spine-rigc 1.6.1 → 1.7.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

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