spine-rigc 1.6.2 → 1.7.0

package/src/compile.ts

@@ -128,6 +128,8 @@ import {
   type BoneTransform,
 } from './transform.ts';
 import { emitSkeleton, PHYSICS_PARAMS, UNSTATED_REFERENCE_SCALE, type SkeletonHeader } from './emit_spine.ts';
+import { curveLengthTable } from './core/constraints_path.ts';
+import { frameRegionName } from './core/uvs.ts';
 import {
   isModelVertexAttachment,
   type CarriedFromCompileResult,
@@ -1979,8 +1981,9 @@ function resolveFromAtlas(
  * ⭐ *Either way* was not true for a pack that turns a region until issue #570:
  * `extractRegion` refused a `rotate: 90`, so how the art was delivered decided
  * whether a measurement could be taken at all — on a foreign pack, where turning
- * is the norm rather than the exception. It now transcribes the runtime's own
- * mapping for all four rotations, which is what makes the sentence above a
+ * is the norm rather than the exception. It now lifts every rotation, measured
+ * as `extractRegion` states (`PKR02` against the runtime's own sampling, `PK29`
+ * against the packer's fixture), which is what makes the sentence above a
  * description rather than an aspiration.
  */
 function partPlate(img: CompiledImage): Plate {
@@ -3802,10 +3805,12 @@ interface AttachmentContext {
    * Linked meshes whose `source` is still unresolved — `resolveLinkedMeshes`
    * empties it once every skin has been built.
    *
-   * ⭐ Deferred for the reason spine-core defers its own (`this.linkedMeshes`,
-   * `SkeletonJson.js:56` filled at `:581` and drained at `:427-449`): a link may
-   * name a source in a skin or a slot this loop has not reached yet, so resolving
-   * it in place would refuse a correct rig on nothing but declaration order.
+   * ⭐ Deferred because the format resolves a link only once every skin is
+   * read — the reader queues each one (`this.linkedMeshes`, `SkeletonJson.js:56`
+   * filled at `:581`) and resolves the queue after the skins (`:427-449`) — so
+   * a link may name a source in a skin or a slot this loop has not reached yet,
+   * and resolving it in place would refuse a correct rig on nothing but
+   * declaration order.
    */
   links: PendingLink[];
 }
@@ -4195,8 +4200,11 @@ export function pathChain(points: Array<[number, number]>, closed: boolean): Arr
 }
 
 /**
- * Cumulative arc length at the end of each curve of the chain, in world units —
- * **the runtime's own measurement, restated line for line**.
+ * Cumulative length at the end of each curve of the chain, in world units —
+ * **the core's curve table** (`curveLengthTable` in
+ * [`src/core/constraints_path.ts`](core/constraints_path.ts), issue #1015), the
+ * one the core's path constraint walks at constant speed. This function only
+ * flattens the chain and counts its curves.
  *
  * One entry per curve, which is what `lengths[curve]` indexes: the parser walks
  * curves with `if (p > lengths[curve]) continue`, and reads `lengths[curveCount]`
@@ -4206,12 +4214,16 @@ export function pathChain(points: Array<[number, number]>, closed: boolean): Arr
  * fact about the Bezier, it is the number the consumer of the field computes for
  * itself when it is not given one. `PathConstraint.computeWorldPositions`
  * (`PathConstraint.js:289-324` in `@esotericsoftware/spine-core` 4.3.13) measures
- * a `constantSpeed` path with a cubic **forward difference** taken at `t = 1/4`
- * — `0.1875 = 3t²`, `0.09375 = 6t³`, `0.75 = 3t`, `0.16666667` standing in for
- * 1/6 — accumulating four `Math.sqrt` terms per curve into a running
- * `pathLength`, and writing the running value into `curves[i]` at each curve's
- * end. The Spine editor's exported `lengths` are that same computation, and the
- * loop below is a transcription of it, not a sampler that happens to agree.
+ * a `constantSpeed` path for itself, and the Spine editor's exported `lengths`
+ * are the same number. What that number is was measured, not read: the core's
+ * table — four forward-difference steps per curve at `t = 1/4` (`0.1875`,
+ * `0.09375`, `0.75`, `0.16666667`), four `Math.sqrt` terms accumulated into a
+ * running total carried across curves — is the rule its header states with the
+ * readings that missed beside it, and `PS67`, `PS68` and `PS186` in
+ * `selftest.ts` hold this function to `PathConstraint`'s own `curves` array read
+ * off a posed skeleton, **bit for bit**. Since issue #1015 the core suite also
+ * holds the swap: 100,000 seeded chains through this function and through the
+ * arithmetic it replaced, 0 differing.
  *
  * 🚨 **What that computation is fed decides the number, and this comment once
  * claimed more than was measured** (issue #804). It said the loop matched the
@@ -4223,8 +4235,8 @@ export function pathChain(points: Array<[number, number]>, closed: boolean): Arr
  *     vertices. rigc blends weighted vertices through its own setup transforms,
  *     which until #804 ignored bone scale, shear and `inherit` — 2.35× the
  *     runtime's own `curves` on a production rig's weighted path, 0.752× on a
- *     50/50 probe over a bone at scale 2. `computeWorldTransforms` is now the
- *     runtime's, and the gap is gone on both.
+ *     50/50 probe over a bone at scale 2. `computeWorldTransforms` honours all
+ *     three now, and the gap is gone on both.
  *   - **Constraints.** The runtime measures the pose its update order hands the
  *     path constraint at the first `updateWorldTransform`: a transform
  *     constraint on the path's slot bone ordered BEFORE the path constraint
@@ -4232,11 +4244,11 @@ export function pathChain(points: Array<[number, number]>, closed: boolean): Arr
  *     not. A production 4.2 export's four numbers are the constrained pose's to
  *     the digit, and its unconstrained setup measures 76.08 against 76.65 on the
  *     first curve. Reproducing that means solving every constraint type in
- *     update order, which is posing — and `src/compile.ts` does not link the
- *     runtime. ⇒ **An omitted `lengths` is measured on the unconstrained setup
- *     pose**, and a path whose bones a constraint moves at rest gets that
- *     figure. What closes the gap for an editor export is not measuring at all:
- *     a stated `lengths` is carried (`buildRigPath`).
+ *     update order, which is posing — and `src/compile.ts` does not pose. ⇒
+ *     **An omitted `lengths` is measured on the unconstrained setup pose**, and
+ *     a path whose bones a constraint moves at rest gets that figure. What
+ *     closes the gap for an editor export is not measuring at all: a stated
+ *     `lengths` is carried (`buildRigPath`).
  *
  * ⚠️ rigc measured this with a 64-chord sum until issue #560, and the comment
  * that stood here argued the difference was inside anything's tolerance. It was
@@ -4247,46 +4259,17 @@ export function pathChain(points: Array<[number, number]>, closed: boolean): Arr
  * two apart and since issue #716 rigc's own file can only where the two land on
  * either side of a float's boundary. Under the six-decimal rounding that stood
  * until then it could: on both measured rigs the two spellings differed on the
- * LAST curve, where the accumulated difference is largest. `PS67`, `PS68` and `PS186` in `selftest.ts` compare
- * this against `PathConstraint`'s own `curves` array read off a posed skeleton,
- * which is the only oracle that can see that gap.
- *
- * 🔒 The transcription is deliberate down to the spelling: `Math.sqrt(dx * dx +
- * dy * dy)` rather than `Math.hypot`, `0.16666667` rather than `1 / 6`, and the
- * running total carried across curves rather than restarted. Each of those is a
- * place where a more accurate line would emit a different file.
+ * LAST curve, where the accumulated difference is largest.
+ *
+ * 🔒 The spelling is load-bearing: `Math.sqrt(dx * dx + dy * dy)` rather than
+ * `Math.hypot`, `0.16666667` rather than `1 / 6`, and the running total carried
+ * across curves rather than restarted. Each of those is a place where a more
+ * accurate line would emit a different file.
  */
 export function pathCurveLengths(chain: Array<[number, number]>): number[] {
-  const out: number[] = [];
-  let total = 0;
-  for (let c = 0; c + 3 < chain.length; c += 3) {
-    const [x1, y1] = chain[c];
-    const [cx1, cy1] = chain[c + 1];
-    const [cx2, cy2] = chain[c + 2];
-    const [x2, y2] = chain[c + 3];
-    const tmpx = (x1 - cx1 * 2 + cx2) * 0.1875;
-    const tmpy = (y1 - cy1 * 2 + cy2) * 0.1875;
-    const dddfx = ((cx1 - cx2) * 3 - x1 + x2) * 0.09375;
-    const dddfy = ((cy1 - cy2) * 3 - y1 + y2) * 0.09375;
-    let ddfx = tmpx * 2 + dddfx;
-    let ddfy = tmpy * 2 + dddfy;
-    let dfx = (cx1 - x1) * 0.75 + tmpx + dddfx * 0.16666667;
-    let dfy = (cy1 - y1) * 0.75 + tmpy + dddfy * 0.16666667;
-    total += Math.sqrt(dfx * dfx + dfy * dfy);
-    dfx += ddfx;
-    dfy += ddfy;
-    ddfx += dddfx;
-    ddfy += dddfy;
-    total += Math.sqrt(dfx * dfx + dfy * dfy);
-    dfx += ddfx;
-    dfy += ddfy;
-    total += Math.sqrt(dfx * dfx + dfy * dfy);
-    dfx += ddfx + dddfx;
-    dfy += ddfy + dddfy;
-    total += Math.sqrt(dfx * dfx + dfy * dfy);
-    out.push(total);
-  }
-  return out;
+  const flat: number[] = [];
+  for (const [x, y] of chain) flat.push(x, y);
+  return curveLengthTable(flat, Math.max(0, Math.floor((chain.length - 1) / 3)));
 }
 
 /**
@@ -4516,20 +4499,22 @@ function meshTextureKeys(att: { name?: string; path?: string; image?: string; co
 }
 
 /**
- * The atlas region frame `i` of a sequence resolves to — `Sequence.getPath`
- * (`Sequence.js:124-132`) transcribed: the stem, then `start + i` left-padded
- * with zeros to `digits`. `start` and `digits` take the parser's own defaults
- * (`readSequence`: 1 and 0), which are the format's, not a guess.
- *
- * ⚠️ A second transcription of the rule exists in `validate.ts`
- * (`attachmentRegionLookups`, the walk `A08` joins the atlas with), and that is
- * deliberate: this module links no runtime, and the two are held to the loader
- * independently — the one by `A08`, both by `A00`'s round trip, which asks the
- * runtime's own `getPath` for every frame.
+ * The atlas region frame `i` of a sequence resolves to — the core's
+ * `frameRegionName` (`src/core/uvs.ts`, issue #1015): the stem, then `start + i`
+ * left-padded with zeros to `digits`. `start` and `digits` take the parser's
+ * defaults when the spec leaves them out (`readSequence`: 1 and 0).
+ *
+ * ⚠️ The same name is derived in `validate.ts` (`attachmentRegionLookups`, the
+ * walk `A08` joins the atlas with) through the same function. What holds it to
+ * the loader is a measurement, not this sentence: the core suite reads
+ * `Sequence.getPath` and the parser's defaults off spine-core over 7,680 cases
+ * and compares this function, the core's and A08's walk with them, and `A00`'s
+ * round trip asks the runtime's own `getPath` for every frame a build emits.
+ *
+ * Exported for the selftest alone.
  */
-function sequenceFrameRegion(stem: string, seq: RigSequence, i: number): string {
-  const frame = String((seq.start ?? 1) + i);
-  return `${stem}${'0'.repeat(Math.max(0, (seq.digits ?? 0) - frame.length))}${frame}`;
+export function sequenceFrameRegion(stem: string, seq: RigSequence, i: number): string {
+  return frameRegionName(stem, { count: seq.count, start: seq.start ?? 1, digits: seq.digits ?? 0, setup: seq.setup ?? 0 }, i);
 }
 
 /** The model's `sequence` record: the four fields exactly as the spec stated them. */
@@ -4796,8 +4781,8 @@ function bindNamedWeights(weights: RigMeshBinding[][], where: string, ctx: Attac
  * an `image` under `--atlas-in` ENDED the build, by a refusal raised inside a
  * measurement, on 36 of 42 atlases of the pack the card was filed from. The
  * repair was to make the refusal unnecessary rather than to catch it: reading a
- * turned region is a transcription of `MeshAttachment.computeUVs` and is now
- * what `extractRegion` does, so there is no unmeasurable case left for this
+ * turned region is now what `extractRegion` does, measured against
+ * `MeshAttachment.computeUVs` (`PKR02`), so there is no unmeasurable case left for this
  * function to report and no catch here to keep reachable.
  */
 function measureAuthoredFit(

package/src/core/constraints_path.ts

@@ -44,8 +44,9 @@
  *
  * 1. **A table of the curves' lengths**, each curve four forward-difference
  *    steps (`0.1875`, `0.09375`, `0.75` and `0.16666667`, the running total
- *    carried across curves) — `pathCurveLengths` in `src/compile.ts`, the
- *    same arithmetic. A ten-step table missed 460 of the grid's 976. The
+ *    carried across curves) — `curveLengthTable`, which `src/compile.ts`'s
+ *    `pathCurveLengths` also calls (issue #1015). A ten-step table missed
+ *    460 of the grid's 976. The
  *    last entry is the path's length; `percent` multiplies the position by
  *    it. The stated `lengths` are not read: the stated total in their place
  *    missed 680 of 1,000.
@@ -217,6 +218,60 @@ import type { CoreCurve, CoreKey } from './animation.ts';
 import type { CoreConstraintRecord } from './constraints.ts';
 
 const RAD = RUNTIME_PI / 180;
+
+/**
+ * The constant-speed walk's table of the curves' lengths — the header's *The
+ * walk*, step 1: each curve four forward-difference steps (`0.1875`,
+ * `0.09375`, `0.75`, `0.16666667`), the running total carried across curves,
+ * one cumulative entry per curve. `chain` is flat, `x, y` per point, knot
+ * handle handle knot …; `curveCount` curves are read off it.
+ *
+ * Exported because it has a second caller: an omitted `lengths` on a path
+ * attachment is measured by `src/compile.ts` through this function (issue
+ * #1015), so the number rigc writes into a file and the number the core walks
+ * are one computation. Measured as the header states it on the grid (a
+ * ten-step table missed 460 of 976) and held there by the core suite's `CP`
+ * controls.
+ */
+export function curveLengthTable(chain: readonly number[], curveCount: number): number[] {
+  const curveEnds: number[] = [];
+  let total = 0;
+  let x1 = chain[0];
+  let y1 = chain[1];
+  for (let i = 0, w = 2; i < curveCount; i++, w += 6) {
+    const cx1 = chain[w];
+    const cy1 = chain[w + 1];
+    const cx2 = chain[w + 2];
+    const cy2 = chain[w + 3];
+    const x2 = chain[w + 4];
+    const y2 = chain[w + 5];
+    const h2x = (x1 - cx1 * 2 + cx2) * 0.1875;
+    const h2y = (y1 - cy1 * 2 + cy2) * 0.1875;
+    const d3x = ((cx1 - cx2) * 3 - x1 + x2) * 0.09375;
+    const d3y = ((cy1 - cy2) * 3 - y1 + y2) * 0.09375;
+    let d2x = h2x * 2 + d3x;
+    let d2y = h2y * 2 + d3y;
+    let d1x = (cx1 - x1) * 0.75 + h2x + d3x * 0.16666667;
+    let d1y = (cy1 - y1) * 0.75 + h2y + d3y * 0.16666667;
+    total += Math.sqrt(d1x * d1x + d1y * d1y);
+    d1x += d2x;
+    d1y += d2y;
+    d2x += d3x;
+    d2y += d3y;
+    total += Math.sqrt(d1x * d1x + d1y * d1y);
+    d1x += d2x;
+    d1y += d2y;
+    total += Math.sqrt(d1x * d1x + d1y * d1y);
+    d1x += d2x + d3x;
+    d1y += d2y + d3y;
+    total += Math.sqrt(d1x * d1x + d1y * d1y);
+    curveEnds.push(total);
+    x1 = x2;
+    y1 = y2;
+  }
+  return curveEnds;
+}
+
 const EPSILON = 0.00001;
 
 /** The three modes a path constraint names, each as the model spells it once its first letter is lower-cased. */
@@ -556,47 +611,14 @@ function positionsOf(state: PathSolverState, c: CorePathRecord, g: CorePathGeome
     chain.push(...P(0), ...P(1));
   } else for (let k = 1; k < n - 1; k++) chain.push(...P(k));
   const curveCount = closed ? n / 3 : n / 3 - 1;
-  const curveEnds: number[] = [];
-  let total = 0;
-  let x1 = chain[0];
-  let y1 = chain[1];
-  for (let i = 0, w = 2; i < curveCount; i++, w += 6) {
-    const cx1 = chain[w];
-    const cy1 = chain[w + 1];
-    const cx2 = chain[w + 2];
-    const cy2 = chain[w + 3];
-    const x2 = chain[w + 4];
-    const y2 = chain[w + 5];
-    const h2x = (x1 - cx1 * 2 + cx2) * 0.1875;
-    const h2y = (y1 - cy1 * 2 + cy2) * 0.1875;
-    const d3x = ((cx1 - cx2) * 3 - x1 + x2) * 0.09375;
-    const d3y = ((cy1 - cy2) * 3 - y1 + y2) * 0.09375;
-    let d2x = h2x * 2 + d3x;
-    let d2y = h2y * 2 + d3y;
-    let d1x = (cx1 - x1) * 0.75 + h2x + d3x * 0.16666667;
-    let d1y = (cy1 - y1) * 0.75 + h2y + d3y * 0.16666667;
-    total += Math.sqrt(d1x * d1x + d1y * d1y);
-    d1x += d2x;
-    d1y += d2y;
-    d2x += d3x;
-    d2y += d3y;
-    total += Math.sqrt(d1x * d1x + d1y * d1y);
-    d1x += d2x;
-    d1y += d2y;
-    total += Math.sqrt(d1x * d1x + d1y * d1y);
-    d1x += d2x + d3x;
-    d1y += d2y + d3y;
-    total += Math.sqrt(d1x * d1x + d1y * d1y);
-    curveEnds.push(total);
-    x1 = x2;
-    y1 = y2;
-  }
+  const curveEnds = curveLengthTable(chain, curveCount);
+  const total = curveEnds.length > 0 ? curveEnds[curveEnds.length - 1] : 0;
   if (c.positionMode === 'percent') position *= total;
   const spaceScale = c.spacingMode === 'percent' ? total : c.spacingMode === 'proportional' ? total / spaceCount : 1;
   const segmentEnds: number[] = new Array(10).fill(0);
   let curveTotal = 0;
   let lastCurve = -1;
-  let cx1 = 0, cy1 = 0, cx2 = 0, cy2 = 0, x2 = 0, y2 = 0;
+  let x1 = 0, y1 = 0, cx1 = 0, cy1 = 0, cx2 = 0, cy2 = 0, x2 = 0, y2 = 0;
   for (let i = 0, o = 0, curve = 0, segment = 0; i < spaceCount; i++, o += 3) {
     const space = spaces[i] * spaceScale;
     position += space;

package/src/core/constraints_physics.ts

@@ -561,6 +561,27 @@ export function physicsState(ctx: PhysicsStepContext, name: string): PhysicsStat
 const PI2 = RUNTIME_PI * 2;
 const INV_PI2 = 1 / PI2;
 
+/** What a physics constraint's step moves, by its five component fields. */
+export interface PhysicsDrives {
+  x: boolean;
+  y: boolean;
+  /** `rotate` or `shearX` above 0: the two share the angular part of the step. */
+  rotateOrShearX: boolean;
+  scaleX: boolean;
+}
+
+/**
+ * Which parts of the step a constraint drives: a component above 0 drives its
+ * part and nothing else does — the test `stepPhysics` takes before each part
+ * of *The step* above, posed against the runtime with the rest of it. Exported
+ * because `src/ingest.ts` asks the same question of a raw file (a
+ * constraint that drives none of the four moves no bone, issue #731) and
+ * answers it through this function (issue #1015).
+ */
+export function physicsDrives(r: { x: number; y: number; rotate: number; shearX: number; scaleX: number }): PhysicsDrives {
+  return { x: r.x > 0, y: r.y > 0, rotateOrShearX: r.rotate > 0 || r.shearX > 0, scaleX: r.scaleX > 0 };
+}
+
 /**
  * One physics constraint updated on its bone's world transform `w`
  * (mutated), `length` the bone's length — the header's *The step*, every
@@ -572,10 +593,7 @@ export function stepPhysics(r: CorePhysicsRecord, w: CoreWorld, length: number,
   const mix = r.mix;
   if (mix === 0) return false;
   const s = physicsState(ctx, r.name);
-  const x = r.x > 0;
-  const y = r.y > 0;
-  const rotateOrShearX = r.rotate > 0 || r.shearX > 0;
-  const scaleX = r.scaleX > 0;
+  const { x, y, rotateOrShearX, scaleX } = physicsDrives(r);
   const l = length;
   if (ctx.phase === 'reset') resetPhysicsState(s, ctx.time);
   const delta = Math.max(ctx.time - s.lastTime, 0);

package/src/core/index.ts

@@ -1,6 +1,7 @@
 /**
  * rigc's own core: it reads the compiled model as `build` writes it
- * (`rigc-compiled/1`, `skeleton.model.json`) and poses it (issue #925, step 2a
+ * (`rigc-compiled/2`, and `/1` before issue #1016; `skeleton.model.json`)
+ * and poses it (issue #925, step 2a
  * of issue #380). It is the second dumper `tools/pose_oracle.ts` was shaped
  * for: what it poses is written into the same `pose-oracle/2` document the
  * runtime's dump is, and `compare` holds the two to each other.
@@ -168,7 +169,7 @@
  * child process, no file system — `readModel` takes the document's TEXT — and
  * nothing from the Spine runtime package, as a value or as a type.
  */
-import type { ModelAtlasRect, ModelBone, ModelSlot, ModelVertices, SkinTableEntry } from '../model.ts';
+import type { ModelAtlasRect, ModelBone, ModelPage, ModelPageRegion, ModelSlot, ModelVertices, SkinTableEntry } from '../model.ts';
 import { worldTransforms, type CoreWorld } from './world.ts';
 import { readAnimationTimelines, type CoreAnimationTimelines } from './animation.ts';
 import { readEventDefs, type CoreEventDef } from './events.ts';
@@ -183,8 +184,19 @@ import { attachmentStates, type DeformBlender, type DeformEvaluator, type Sequen
 import { drawOrderAt, type DrawOrderEvaluator } from './draw_order.ts';
 import type { EventsFired } from './events.ts';
 
-/** The document spec this reader takes. */
-export const CORE_DOCUMENT_SPEC = 'rigc-compiled/1';
+/**
+ * The document spec `build` writes today, and the one this reader takes with
+ * the `pages` section (issue #1016).
+ */
+export const CORE_DOCUMENT_SPEC = 'rigc-compiled/2';
+
+/**
+ * The spec before issue #1016: the same sections without `pages`. Read as
+ * before — the draw then takes where each region sits from the atlas beside
+ * the document (`corePoser` in `src/render_core.ts` says so by name), because
+ * a `/1` document does not state it.
+ */
+export const CORE_DOCUMENT_SPEC_1 = 'rigc-compiled/1';
 
 /** Who posed a dump the core wrote — the oracle document's `dumper`. */
 export const CORE_DUMPER = 'rigc-core';
@@ -196,10 +208,19 @@ export class CoreInputError extends Error {}
 export const CORE_SECTIONS = [
   'referenceScale', 'bones', 'slots', 'skins', 'constraints', 'events', 'animations',
   'images', 'pageGrids', 'droppedStates', 'absentParts', 'meshBones', 'meshes', 'physics', 'deformTransforms', 'trackDerivations', 'rig',
+  // Issue #1016: where each region sits on its page, in the atlas written beside the document (`pagesOfAtlas` in `src/model.ts`). `/2` only.
+  'pages',
   // Issue #968: the digest of the `skeleton.json` written beside the document (`spineFileSha256` in `src/model.ts`).
   'spine',
 ] as const;
 
+/** The sections of a `rigc-compiled/1` document: `CORE_SECTIONS` without `pages`. */
+export const CORE_SECTIONS_1: readonly string[] = CORE_SECTIONS.filter((key) => key !== 'pages');
+
+/** The fields of a page and of a region in the `pages` section, as the writer lists them (`MODEL_PAGE_FIELDS`, `MODEL_PAGE_REGION_FIELDS` in `src/model.ts`, mirrored). */
+export const CORE_PAGE_FIELDS = ['name', 'width', 'height', 'regions'] as const;
+export const CORE_PAGE_REGION_FIELDS = ['name', 'x', 'y', 'width', 'height', 'offsetX', 'offsetY', 'originalWidth', 'originalHeight', 'degrees', 'index'] as const;
+
 /** The fields a bone record may carry, as the writer lists them. A field outside this list is refused. */
 export const CORE_BONE_FIELDS = ['name', 'parent', 'length', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY', 'inheritMode', 'skinRequired', 'editor'] as const;
 const BONE_NUMBERS = ['length', 'x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY'] as const;
@@ -297,7 +318,7 @@ export interface CoreAnimation {
 }
 
 /**
- * A `rigc-compiled/1` document, read. `bones` and `slots` are checked field by
+ * A `rigc-compiled/2` (or `/1`) document, read. `bones` and `slots` are checked field by
  * field against the writer's own records; skins and constraints are read as
  * far as their names and memberships, and every other section is only
  * required to be present — no construct this card admits reads it.
@@ -319,6 +340,66 @@ export interface CompiledDocument {
   animations: CoreAnimation[];
   /** The digest of the `skeleton.json` `build` wrote beside the document (issue #968) — what a render holds the file beside it to before posing it here. */
   spine: { sha256: string };
+  /**
+   * Every page of the atlas `build` wrote beside the document and every region
+   * on it, in file order (issue #1016) — where each drawing sits, which the
+   * draw's page UVs read. `null` for a `rigc-compiled/1` document, which does
+   * not state it.
+   */
+  pages: ModelPage[] | null;
+}
+
+/**
+ * The `pages` section, checked: a list of pages, each holding exactly
+ * `CORE_PAGE_FIELDS` — a non-empty name, a size of two positive finite
+ * numbers, a list of regions — and each region exactly
+ * `CORE_PAGE_REGION_FIELDS`, a non-empty name and nine finite numbers. Every
+ * fault is named by its path. Nothing is defaulted: a field the writer always
+ * writes is required here.
+ */
+function readPages(value: unknown, problems: string[]): ModelPage[] {
+  if (!Array.isArray(value)) {
+    problems.push(`pages is ${JSON.stringify(value) ?? 'absent'}, not a list of pages`);
+    return [];
+  }
+  const out: ModelPage[] = [];
+  value.forEach((raw, i) => {
+    const where = `pages[${i}]`;
+    if (!isRecord(raw)) {
+      problems.push(`${where} is not an object`);
+      return;
+    }
+    const before = problems.length;
+    const label = typeof raw.name === 'string' ? `${where} "${raw.name}"` : where;
+    unknownFields(raw, CORE_PAGE_FIELDS, label, problems);
+    if (typeof raw.name !== 'string' || raw.name === '') problems.push(`${where}: name is ${JSON.stringify(raw.name) ?? 'absent'}, not a non-empty string`);
+    for (const key of ['width', 'height'] as const) {
+      const v = raw[key];
+      if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) problems.push(`${label}: ${key} is ${JSON.stringify(v) ?? 'absent'}, not a positive finite number — a page UV divides by it`);
+    }
+    const regions: ModelPageRegion[] = [];
+    if (!Array.isArray(raw.regions)) problems.push(`${label}: regions is not a list`);
+    else {
+      raw.regions.forEach((region, j) => {
+        const at = `${label}.regions[${j}]`;
+        if (!isRecord(region)) {
+          problems.push(`${at} is not an object`);
+          return;
+        }
+        const named = typeof region.name === 'string' ? `${at} "${region.name}"` : at;
+        unknownFields(region, CORE_PAGE_REGION_FIELDS, named, problems);
+        if (typeof region.name !== 'string' || region.name === '') problems.push(`${at}: name is ${JSON.stringify(region.name) ?? 'absent'}, not a non-empty string`);
+        for (const key of CORE_PAGE_REGION_FIELDS) {
+          if (key === 'name') continue;
+          const v = region[key];
+          if (typeof v !== 'number' || !Number.isFinite(v)) problems.push(`${named}: ${key} is ${JSON.stringify(v) ?? 'absent'}, not a finite number`);
+        }
+        regions.push(region as unknown as ModelPageRegion);
+      });
+    }
+    if (problems.length === before) out.push({ name: raw.name as string, width: raw.width as number, height: raw.height as number, regions });
+  });
+  return out;
 }
 
 /** The `spine` section's value, checked: `{ "sha256": <64 lowercase hex> }` and nothing else, each fault named by path (issue #968). */
@@ -615,7 +696,8 @@ function readConstraints(value: unknown, animations: readonly CoreAnimation[], b
 }
 
 /**
- * Read a `rigc-compiled/1` document from its text, refusing by name a text
+ * Read a `rigc-compiled/2` document — or a `rigc-compiled/1` one, which has
+ * no `pages` and is read with `pages: null` — from its text, refusing by name a text
  * that is not JSON, a wrong `spec`, a missing section (`referenceScale`
  * among them, issue #958), a section the document does not have, a
  * `referenceScale` that is not a finite number, and — in the records these constructs read (bones, slots,
@@ -633,12 +715,15 @@ export function readModel(text: string, where = 'the model document'): CompiledD
     throw new CoreInputError(`${where}: not JSON — ${(err as Error).message}`);
   }
   if (!isRecord(value)) throw new CoreInputError(`${where}: not a JSON object`);
-  if (value.spec !== CORE_DOCUMENT_SPEC) throw new CoreInputError(`${where}: spec is ${JSON.stringify(value.spec)}, not "${CORE_DOCUMENT_SPEC}"`);
+  if (value.spec !== CORE_DOCUMENT_SPEC && value.spec !== CORE_DOCUMENT_SPEC_1) throw new CoreInputError(`${where}: spec is ${JSON.stringify(value.spec)}, not "${CORE_DOCUMENT_SPEC}" (or "${CORE_DOCUMENT_SPEC_1}", read without its pages)`);
+  const spec = value.spec;
+  const sections: readonly string[] = spec === CORE_DOCUMENT_SPEC ? CORE_SECTIONS : CORE_SECTIONS_1;
   const problems: string[] = [];
-  for (const key of CORE_SECTIONS) if (!(key in value)) problems.push(`section "${key}" is missing`);
+  for (const key of sections) if (!(key in value)) problems.push(`section "${key}" is missing`);
   for (const key of Object.keys(value)) {
-    if (key !== 'spec' && !(CORE_SECTIONS as readonly string[]).includes(key)) problems.push(`section "${key}" is not one a ${CORE_DOCUMENT_SPEC} document has`);
+    if (key !== 'spec' && !sections.includes(key)) problems.push(`section "${key}" is not one a ${spec} document has`);
   }
+  const pages = spec === CORE_DOCUMENT_SPEC && 'pages' in value ? readPages(value.pages, problems) : null;
   // The skeleton's reference scale (issue #958): wind and gravity act over it, so a missing one is the section refusal above, and a value the runtime could not read as a number is refused here by name.
   const referenceScale = typeof value.referenceScale === 'number' && Number.isFinite(value.referenceScale) ? value.referenceScale : NaN;
   if ('referenceScale' in value && Number.isNaN(referenceScale)) problems.push(`referenceScale is ${JSON.stringify(value.referenceScale)}, not a finite number — wind and gravity act over it`);
@@ -666,7 +751,7 @@ export function readModel(text: string, where = 'the model document'): CompiledD
     });
   }
   if (problems.length > 0) throw new CoreInputError(`${where}: ${problems.length} problem(s): ${problems.join('; ')}`);
-  const doc: CompiledDocument = { spec: CORE_DOCUMENT_SPEC, skin: CORE_ALL_SKINS, referenceScale, bones, slots, skins, constraints, animations, spine: { sha256: spine } };
+  const doc: CompiledDocument = { spec, skin: CORE_ALL_SKINS, referenceScale, bones, slots, skins, constraints, animations, spine: { sha256: spine }, pages };
   resolveSkinView(doc);
   return doc;
 }

package/src/core/uvs.ts

@@ -5,12 +5,15 @@
  * and `sequence.getUVs(index)` — and `MeshAttachment.computeUVs`'s job, the
  * mapping texture substitution calls, as pure functions.
  *
- * The model document does not carry the page layout (`ModelAtlasRect`'s 🔸 in
+ * The page layout is not a model record (`ModelAtlasRect`'s 🔸 in
  * `src/model.ts`: the page, `x`, `y` and `rotate` are the packer's
- * arrangement, not the drawing), and this construct does not change that: the
- * atlas is a second input, read by rigc's own reader (`parseAtlasText` and
- * `atlasRegionLookup` in `src/atlas.ts`) and handed in as a lookup
- * (`UvLookup`), so nothing here links the runtime or opens a file.
+ * arrangement, not the drawing). It reaches these rules as a lookup
+ * (`UvLookup`), so nothing here links the runtime or opens a file: since
+ * issue #1016 from the document's own `pages` section, which `build` spells
+ * from the atlas it writes (`documentPageLookup` below); for a
+ * `rigc-compiled/1` document, which has none, from the atlas beside it, read
+ * by rigc's own reader (`parseAtlasText` and `atlasRegionLookup` in
+ * `src/atlas.ts`).
  *
  * ## How every rule below was fixed
  *
@@ -143,6 +146,7 @@ import { applyConstraints } from './constraints.ts';
 import type { SliderApplication } from './constraints_slider.ts';
 import { attachmentStates } from './deform.ts';
 import type { ShownGeometry } from './vertices.ts';
+import type { ModelPage, ModelPageRegion } from '../model.ts';
 import { worldTransforms } from './world.ts';
 
 /** A region as these rules read it — `AtlasRegion` in `src/atlas.ts` is one, and so is spine-core's `TextureAtlasRegion`. */
@@ -168,6 +172,22 @@ export interface UvPage {
 /** The region an atlas draws under a name, and its page — the first of that name, as the header states; `null` when there is none. */
 export type UvLookup = (name: string) => { page: UvPage; region: UvRegion } | null;
 
+/**
+ * The lookup over a document's `pages` section (issue #1016): the first region
+ * of a name in file order, pages in order and regions in each page's order —
+ * the order `pagesOfAtlas` in `src/model.ts` copies from the atlas, so this is
+ * `atlasRegionLookup` over the same text, with no atlas read. The name is
+ * compared as stored, untrimmed, as the header's *Which region* states.
+ */
+export function documentPageLookup(pages: readonly ModelPage[]): (name: string) => { page: UvPage; region: ModelPageRegion } | null {
+  const first = new Map<string, { page: UvPage; region: ModelPageRegion }>();
+  for (const page of pages) {
+    const at: UvPage = { name: page.name, width: page.width, height: page.height };
+    for (const region of page.regions) if (!first.has(region.name)) first.set(region.name, { page: at, region });
+  }
+  return (name) => first.get(name) ?? null;
+}
+
 /**
  * The readings the header's tables rejected, each a switch — what the core
  * suite's `CU` plants pass to show the gate names it. The functions below with