spine-rigc 1.6.2 → 1.7.0

package/src/render_core.ts

@@ -2,8 +2,10 @@
  * The render's second poser (issue #968, step 3d of issue #380): the posing
  * seam of `src/render.ts` (`Poser` / `Posed`) implemented over rigc's own
  * core — the compiled model document (`skeleton.model.json`) posed by
- * `src/core/`, and the atlas the render samples read by rigc's own reader
- * (`src/atlas.ts`). Nothing here links spine-core, and nothing here is reached
+ * `src/core/`, each drawn region placed on its page by the document's own
+ * `pages` section (issue #1016; a `rigc-compiled/1` document, which has none,
+ * by the atlas beside it, read by rigc's own reader `src/atlas.ts`). Nothing
+ * here links spine-core, and nothing here is reached
  * from `src/core/`: the core stays pure, and this module is the adapter from
  * its raw entry to the renderer's shapes.
  *
@@ -32,7 +34,11 @@
  *   region a drawn attachment samples (`drawnRegions` over the pose's `shown`
  *   records and draw order), a region's four UVs (`regionPageUvs`) and a
  *   mesh's (`meshPageUvs`), each held to `sequence.getUVs(index)` at
- *   tolerance 0 on every corpus by `core_gate`'s `uvs` blocks.
+ *   tolerance 0 on every corpus by `core_gate`'s `uvs` blocks. Where each
+ *   region sits — its page, `x`, `y`, turn and the page's size — is the
+ *   document's `pages` section (issue #1016, `placementOf`), the atlas `build`
+ *   wrote spelled into the document, so a build draws with its `.atlas`
+ *   removed.
  * - **The tint** is the slot's light colour times the attachment's colour,
  *   channel by channel, as `src/render.ts`'s `tintOf` forms it; the dark
  *   colour is the slot's, absent where the slot carries none.
@@ -80,15 +86,16 @@ import type {
   PoseOptions,
   Posed,
   Poser,
+  SkinRoster,
   SlotSubset,
 } from './render.ts';
-import { atlasRegionLookup, parseAtlasText, type AtlasRegion } from './atlas.ts';
-import { spineFileSha256 } from './model.ts';
+import { atlasRegionLookup, parseAtlasText } from './atlas.ts';
+import { pagesOfAtlas, spineFileSha256, type ModelPage } from './model.ts';
 import { clipThrough, type ClipShape, type ShapeClipper } from './core/clipping.ts';
-import { CoreInputError, readModel, sourceOfDoc, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
+import { activeBones, CoreInputError, readModel, sourceOfDoc, underSkin, type CompiledDocument, type CoreSlotRow } from './core/index.ts';
 import { poseRawAnimation, poseRawSetup, type RawDrawn, type RawPose } from './core/raw.ts';
 import { CORE_ALL_SKINS, CORE_DEFAULT_SKIN, lookupSkins } from './core/skins.ts';
-import { drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvSource } from './core/uvs.ts';
+import { documentPageLookup, drawnRegions, meshPageUvs, readUvSequences, regionPageUvs, type DrawnRegion, type UvRegion, type UvSource } from './core/uvs.ts';
 import { regionCorners, worldVertices } from './core/vertices.ts';
 import type { CoreWorld } from './core/world.ts';
 
@@ -256,12 +263,15 @@ export function clipSourceOf(
 /** The runtime's own triangulation of a region's quad — `src/render.ts`'s `QUAD_TRIANGLES`. */
 const QUAD_TRIANGLES: readonly number[] = [0, 1, 2, 2, 3, 0];
 
-/** Everything a core pose reads besides the pose: the document under one skin, and the atlas. */
+/** A region as texture substitution reads it: the page-UV rules' numbers, and the name and `index:` its key is made of (`regionKey`). */
+type TextureRegion = UvRegion & { name: string; index: number };
+
+/** Everything a core pose reads besides the pose: the document under one skin, and where each region sits on its page. */
 interface CoreInput {
   doc: CompiledDocument;
   source: UvSource;
-  /** The atlas region a name draws, as rigc's reader holds it — what an original-art UV reads its trim from. */
-  region: (name: string) => AtlasRegion | null;
+  /** The region a name draws — the document's `pages`, or for a `/1` document the atlas's — what an original-art UV reads its trim from. */
+  region: (name: string) => TextureRegion | null;
 }
 
 /**
@@ -300,12 +310,12 @@ function worldOf(pose: RawPose): Map<string, CoreWorld> {
 }
 
 /** `regionKey` in `src/render.ts`: the trimmed name and the sequence index — the key a substitution matches on. */
-function regionKey(region: AtlasRegion): string {
+function regionKey(region: TextureRegion): string {
   return `${region.name.trim()}#${region.index}`;
 }
 
 /** `artUvsOf` in `src/render.ts`, over rigc's atlas reader: a mesh's own UVs, a region's kept rectangle in the drawing's space. */
-function artUvsOf(drawn: RawDrawn, region: AtlasRegion): PieceTexture | undefined {
+function artUvsOf(drawn: RawDrawn, region: TextureRegion): PieceTexture | undefined {
   if (drawn.kind === 'mesh') return { region: regionKey(region), artUvs: [...drawn.uvs] };
   if (region.degrees !== 0) return undefined;
   const ow = region.originalWidth;
@@ -515,9 +525,70 @@ function restOf(view: CompiledDocument, setup: RawPose, shown: readonly Attachme
 }
 
 /**
- * `Poser` over rigc's own core: `modelText` a `rigc-compiled/1` document
- * (`skeleton.model.json`), `atlasText` the atlas the render samples — the one
- * `build` wrote beside it. With `skeleton`, the Spine file beside the document
+ * The first place two `pages` sections differ, by path, or `null` when they
+ * are the same — the page count, a page's name or size, a region count, or a
+ * region's name or one of its numbers.
+ */
+export function firstPageDifference(stated: readonly ModelPage[], found: readonly ModelPage[]): string | null {
+  if (stated.length !== found.length) return `the document states ${stated.length} page(s), the atlas has ${found.length}`;
+  for (let i = 0; i < stated.length; i++) {
+    const a = stated[i];
+    const b = found[i];
+    for (const key of ['name', 'width', 'height'] as const) {
+      if (a[key] !== b[key]) return `pages[${i}].${key} is ${JSON.stringify(a[key])} in the document and ${JSON.stringify(b[key])} in the atlas`;
+    }
+    if (a.regions.length !== b.regions.length) return `pages[${i}] "${a.name}" holds ${a.regions.length} region(s) in the document and ${b.regions.length} in the atlas`;
+    for (let j = 0; j < a.regions.length; j++) {
+      const r = a.regions[j];
+      const q = b.regions[j];
+      for (const key of Object.keys(r) as Array<keyof typeof r>) {
+        if (r[key] !== q[key]) return `pages[${i}] "${a.name}" region ${JSON.stringify(r.name)}: ${key} is ${JSON.stringify(r[key])} in the document and ${JSON.stringify(q[key])} in the atlas`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Where each region a core pose draws sits on its page, read from the
+ * document's `pages` section (issue #1016) — or, for a `rigc-compiled/1`
+ * document, which has none, from `atlasText` as before. With both, the atlas
+ * must be the one the document was written beside: a page or region that
+ * differs is refused naming the first difference, so the core never draws the
+ * build's placement over another atlas's pages while spine-core, reading that
+ * atlas, would draw another picture.
+ */
+function placementOf(doc: CompiledDocument, atlasText: string, where: string): { lookup: UvSource['lookup']; region: CoreInput['region'] } {
+  if (doc.pages !== null) {
+    if (atlasText !== '') {
+      const differs = firstPageDifference(doc.pages, pagesOfAtlas(atlasText));
+      if (differs !== null) {
+        throw new CoreInputError(
+          `the atlas beside ${where} is not the one it was written beside: ${differs} — ` +
+            'the core would draw the build\'s placement over pages the atlas has rearranged',
+        );
+      }
+    }
+    const lookup = documentPageLookup(doc.pages);
+    return { lookup, region: (name) => lookup(name)?.region ?? null };
+  }
+  if (atlasText === '') {
+    throw new CoreInputError(
+      `${where} is a ${doc.spec} document, which does not state where each region sits on its page (the pages section, issue #1016), ` +
+        'and no atlas was given to read it from — rebuild it to carry them, or pose it beside the atlas it was built with',
+    );
+  }
+  const lookup = atlasRegionLookup(parseAtlasText(atlasText));
+  return { lookup, region: (name) => lookup(name)?.region ?? null };
+}
+
+/**
+ * `Poser` over rigc's own core: `modelText` a `rigc-compiled/2` document
+ * (`skeleton.model.json`), which states where each region sits on its page
+ * (`pages`, issue #1016), so `atlasText` may be `''`; given, it is held to
+ * the document's `pages` (`placementOf`). A `rigc-compiled/1` document states
+ * no placement and is drawn through `atlasText`, the atlas `build` wrote
+ * beside it, as before; with none given it is refused by name. With `skeleton`, the Spine file beside the document
  * is held to the digest the document records (`spine.sha256`, issue #968) and
  * refused, naming both digests, when it is not that build's. Refused by
  * `CoreInputError`, naming why, where the document or the atlas cannot be read; a pose the core leaves a block of out
@@ -542,8 +613,7 @@ export function corePoser(modelText: string, atlasText: string, where = 'skeleto
     throw new CoreInputError(`${where}: not JSON — ${(err as Error).message}`);
   }
   const sequences = readUvSequences(parsed);
-  const atlas = parseAtlasText(atlasText);
-  const lookup = atlasRegionLookup(atlas);
+  const { lookup, region } = placementOf(doc, atlasText, where);
   const views = new Map<string, CompiledDocument>();
   const inputOf = (skin: string | undefined): CoreInput => {
     const key = skin === undefined ? '' : `=${skin}`;
@@ -552,7 +622,7 @@ export function corePoser(modelText: string, atlasText: string, where = 'skeleto
       view = skin === undefined ? noSkinView(doc) : underSkin(doc, skin);
       views.set(key, view);
     }
-    return { doc: view, source: { lookup, sequences }, region: (name) => lookup(name)?.region ?? null };
+    return { doc: view, source: { lookup, sequences }, region };
   };
   const roster: SubsetRoster = {
     declared: doc.slots.map((s) => s.name),
@@ -580,3 +650,30 @@ export function corePoser(modelText: string, atlasText: string, where = 'skeleto
     },
   };
 }
+
+/**
+ * The skin roster behind the core poser (`SkinRoster` in `src/render.ts`,
+ * issue #1014): the bones each skin leaves unposed, read off the model
+ * document — `unposedBones` over `activeBones` of the skin's view, the
+ * predicate the raw pose flags its bones with, and under no skin the view the
+ * core poses with no skin set (`noSkinView`, refused by `CoreInputError` where
+ * it refuses to pose). `skins` is the Spine file's own list, in its order, which
+ * the document does not hold (`resolveSkinView`'s note in `./core/index.ts`).
+ *
+ * Measured against the runtime's reading (`skinRosterOf`, a fresh skeleton's
+ * `active` under each skin and under none) on every rigc build the tree
+ * carries: the same bones, under every skin. The document is read on the first
+ * question, so a render that frames nothing under a skin never parses it twice.
+ */
+export function coreSkinRoster(modelText: string, where: string, skins: readonly string[]): SkinRoster {
+  let doc: CompiledDocument | null = null;
+  return {
+    skins,
+    unposedUnder: (skin) => {
+      doc ??= readModel(modelText, where);
+      const view = skin === undefined ? noSkinView(doc) : underSkin(doc, skin);
+      const active = activeBones(view);
+      return unposedBones(view.bones.map((b) => ({ name: b.name, parent: b.parent ?? null, active: active.has(b.name) })));
+    },
+  };
+}

package/src/transform.ts

@@ -11,7 +11,7 @@
  * measured polygon. That is why the old code refused rotation instead of ignoring
  * it, and why this file exists rather than a relaxed assertion.
  *
- * The composition mirrors spine-core exactly (`Bone.updateWorldTransform`):
+ * The composition, for a bone with a parent in the `normal` mode:
  *
  *   la = cos(rot)      lb = cos(rot + 90) = -sin(rot)
  *   lc = sin(rot)      ld = sin(rot + 90) =  cos(rot)
@@ -28,9 +28,19 @@
  * at scale 2 measured **0.752×** the runtime's own `PathConstraint.curves` on the
  * build's posed geometry, and a production rig's weighted path 2.35×. The
  * weights were blended all along; the matrices they were blended through were
- * wrong. `computeWorldTransforms` below is `BonePose.updateWorldTransform`
- * (spine-core 4.3.13, `BonePose.js:110-216`) at setup, with a skeleton scale of 1.
+ * wrong.
+ *
+ * ⭐ **`computeWorldTransforms` is the core's evaluator** (`worldTransforms` in
+ * [`src/core/world.ts`](core/world.ts), issue #1015), whose every rule — the five
+ * inherit modes, the collapsed parent axis, the operation orders — was measured
+ * against the runtime's pose dump and is held there by the core suite. This file
+ * hands it the compiler's arithmetic (`COMPILER_ARITHMETIC`, below) and keeps
+ * what is the compiler's own: the coordinate contract, the refusals by name, the
+ * world rotation a region cancels, and the inverses.
  */
+import type { ModelBone } from './model.ts';
+import { modeMatrix, worldTransforms, type CoreWorld, type WorldArithmetic } from './core/world.ts';
+
 /**
  * What `computeWorldTransforms` reads off a bone — a structural type, so both a
  * Spine bone (`SpineBone`, what spine-parts and every skeleton reader hold) and
@@ -70,6 +80,24 @@ export class TransformError extends Error {}
 
 const DEG = Math.PI / 180;
 
+/**
+ * The arithmetic every figure rigc emits was computed with, handed to the core's
+ * evaluator (issue #1015). It differs from the runtime's in the last bit and in
+ * no matrix: degrees to radians with `Math.PI` rather than the runtime's
+ * 3.1415927, radians back to degrees by dividing by that factor, and a bone with
+ * the default scale and no shear framed as `lb = -sin`, `ld = cos` rather than
+ * `cos`/`sin` of `rot + 90°`. One bit can move a float32 spelling in the file, so
+ * this is a parameter and not a rewrite: measured with the runtime's arithmetic
+ * instead, 2 of the 19 public recipes moved by at most 4e-5. Whether the compiler
+ * should bind with the runtime's constant is a question of its own, not settled
+ * here.
+ */
+const COMPILER_ARITHMETIC: WorldArithmetic = {
+  radiansPerDegree: DEG,
+  degreesOf: (radians) => radians / DEG,
+  rotationOnlyFrame: true,
+};
+
 /**
  * Crop pixels (y down, origin top-left) -> Spine world (y up, origin at the
  * bottom-left of the crop).
@@ -92,69 +120,46 @@ export function cropToSpineY(cropY: number, cropHeight: number): number {
  * requires (it resolves `parent` by name against the bones already read), so a
  * violation here is a violation there.
  *
- * 🔒 **A bone with the default scale and no shear takes the exact arithmetic
- * this function always used** — `lb = -sin`, `ld = cos` rather than the
- * runtime's `cos(rot + 90°)`/`sin(rot + 90°)`, which can differ in the last bit.
- * Every figure rigc emitted off an unscaled rig was computed that way, and one
- * bit there can move a float32 spelling in the file, so the general local matrix
- * is taken only where the old one was wrong: nothing an unscaled, normally
- * inheriting rig emits moves by a byte. The five `inherit` cases are the
- * runtime's, transcribed.
+ * The matrices and origins are the core's (`worldTransforms`, under
+ * `COMPILER_ARITHMETIC`). What is decided here is what the core does not say:
+ * an undeclared parent and an `inherit` no mode answers to are refused by name
+ * as `TransformError`, a bone whose `parent` is empty is a root as it always was
+ * here, and `worldRotation` is read off the matrix — a root with the default
+ * scale and no shear keeps its stated rotation, unwrapped.
  */
 export function computeWorldTransforms(bones: readonly PosableBone[]): Map<string, BoneTransform> {
-  const out = new Map<string, BoneTransform>();
+  const model: ModelBone[] = [];
+  const declared = new Set<string>();
   for (const bone of bones) {
-    const rotation = bone.rotation ?? 0;
-    const scaleX = bone.scaleX ?? 1;
-    const scaleY = bone.scaleY ?? 1;
-    const shearX = bone.shearX ?? 0;
-    const shearY = bone.shearY ?? 0;
-    const plain = scaleX === 1 && scaleY === 1 && shearX === 0 && shearY === 0;
-    let la: number;
-    let lb: number;
-    let lc: number;
-    let ld: number;
-    if (plain) {
-      const cos = Math.cos(rotation * DEG);
-      const sin = Math.sin(rotation * DEG);
-      la = cos;
-      lb = -sin;
-      lc = sin;
-      ld = cos;
-    } else {
-      const rx = (rotation + shearX) * DEG;
-      const ry = (rotation + 90 + shearY) * DEG;
-      la = Math.cos(rx) * scaleX;
-      lb = Math.cos(ry) * scaleY;
-      lc = Math.sin(rx) * scaleX;
-      ld = Math.sin(ry) * scaleY;
-    }
-    const x = bone.x ?? 0;
-    const y = bone.y ?? 0;
-    if (!bone.parent) {
-      const worldRotation = plain ? rotation : (Math.atan2(lc, la) / DEG + 360) % 360;
-      out.set(bone.name, { a: la, b: lb, c: lc, d: ld, worldX: x, worldY: y, worldRotation });
-      continue;
+    const parent = bone.parent ? bone.parent : undefined;
+    if (parent !== undefined && !declared.has(parent)) {
+      throw new TransformError(`bone "${bone.name}" names parent "${parent}", which is not declared before it`);
     }
-    const p = out.get(bone.parent);
-    if (!p) throw new TransformError(`bone "${bone.name}" names parent "${bone.parent}", which is not declared before it`);
-    const [a, b, c, d] = inheritedMatrix(inheritMode(bone), p, [la, lb, lc, ld], rotation, scaleX, scaleY, shearX, shearY);
-    out.set(bone.name, {
-      a,
-      b,
-      c,
-      d,
-      worldX: p.a * x + p.b * y + p.worldX,
-      worldY: p.c * x + p.d * y + p.worldY,
-      worldRotation: (Math.atan2(c, a) / DEG + 360) % 360,
+    model.push({
+      name: bone.name,
+      parent,
+      x: bone.x,
+      y: bone.y,
+      rotation: bone.rotation,
+      scaleX: bone.scaleX,
+      scaleY: bone.scaleY,
+      shearX: bone.shearX,
+      shearY: bone.shearY,
+      inheritMode: parent === undefined ? undefined : inheritMode(bone),
     });
+    declared.add(bone.name);
+  }
+  const worlds = worldTransforms(model, null, modeMatrix, COMPILER_ARITHMETIC);
+  const out = new Map<string, BoneTransform>();
+  for (const bone of model) {
+    const w = worlds.get(bone.name) as CoreWorld;
+    const plain = (bone.scaleX ?? 1) === 1 && (bone.scaleY ?? 1) === 1 && (bone.shearX ?? 0) === 0 && (bone.shearY ?? 0) === 0;
+    const worldRotation = bone.parent === undefined && plain ? (bone.rotation ?? 0) : (Math.atan2(w.c, w.a) / DEG + 360) % 360;
+    out.set(bone.name, { a: w.a, b: w.b, c: w.c, d: w.d, worldX: w.worldX, worldY: w.worldY, worldRotation });
   }
   return out;
 }
 
-/** `MathUtils.epsilon2` — the threshold `noRotationOrReflection` tests a degenerate parent against. */
-const EPSILON2 = 0.00001 * 0.00001;
-
 type InheritMode = 'normal' | 'onlyTranslation' | 'noRotationOrReflection' | 'noScale' | 'noScaleOrReflection';
 
 const INHERIT_MODES: readonly InheritMode[] = ['normal', 'onlyTranslation', 'noRotationOrReflection', 'noScale', 'noScaleOrReflection'];
@@ -177,75 +182,6 @@ function inheritMode(bone: PosableBone): InheritMode {
   return mode;
 }
 
-/**
- * `BonePose.updateWorldTransform`'s switch (`BonePose.js:136-215`) for a bone
- * with a parent, at a skeleton scale of 1 — so every `sx`/`sy` factor there is 1
- * and is left out rather than multiplied in.
- */
-function inheritedMatrix(
-  inherit: InheritMode,
-  p: BoneTransform,
-  local: [number, number, number, number],
-  rotation: number,
-  scaleX: number,
-  scaleY: number,
-  shearX: number,
-  shearY: number,
-): [number, number, number, number] {
-  const [la, lb, lc, ld] = local;
-  if (inherit === 'normal') {
-    return [p.a * la + p.b * lc, p.a * lb + p.b * ld, p.c * la + p.d * lc, p.c * lb + p.d * ld];
-  }
-  if (inherit === 'onlyTranslation') return [la, lb, lc, ld];
-  if (inherit === 'noRotationOrReflection') {
-    let pa = p.a;
-    let pb = p.b;
-    let pc = p.c;
-    let pd = p.d;
-    let s = pa * pa + pc * pc;
-    let r: number;
-    if (s > EPSILON2) {
-      s = Math.abs(pa * pd - pb * pc) / s;
-      pb = pc * s;
-      pd = pa * s;
-      r = rotation - Math.atan2(pc, pa) / DEG;
-    } else {
-      pa = 0;
-      pc = 0;
-      r = rotation - 90 + Math.atan2(pd, pb) / DEG;
-    }
-    const rx = (r + shearX) * DEG;
-    const ry = (r + shearY + 90) * DEG;
-    const ra = Math.cos(rx) * scaleX;
-    const rb = Math.cos(ry) * scaleY;
-    const rc = Math.sin(rx) * scaleX;
-    const rd = Math.sin(ry) * scaleY;
-    return [pa * ra - pb * rc, pa * rb - pb * rd, pc * ra + pd * rc, pc * rb + pd * rd];
-  }
-  // noScale / noScaleOrReflection
-  const r = rotation * DEG;
-  const cos = Math.cos(r);
-  const sin = Math.sin(r);
-  let za = p.a * cos + p.b * sin;
-  let zc = p.c * cos + p.d * sin;
-  const s = 1 / Math.sqrt(za * za + zc * zc);
-  za *= s;
-  zc *= s;
-  let zb = -zc;
-  let zd = za;
-  if (inherit === 'noScale' && p.a * p.d - p.b * p.c < 0) {
-    zb = -zb;
-    zd = -zd;
-  }
-  const rx = shearX * DEG;
-  const ry = (90 + shearY) * DEG;
-  const ra = Math.cos(rx) * scaleX;
-  const rb = Math.cos(ry) * scaleY;
-  const rc = Math.sin(rx) * scaleX;
-  const rd = Math.sin(ry) * scaleY;
-  return [za * ra + zb * rc, za * rb + zb * rd, zc * ra + zd * rc, zc * rb + zd * rd];
-}
-
 /**
  * World point -> the bone's local space. Used for bind coordinates and offsets.
  *

package/src/types.ts

@@ -1098,11 +1098,12 @@ export interface SpineClippingAttachment {
  * is re-parameterised by the trip rather than corrupted by it.
  *
  * ⇒ **rigc emits that computation, not a sampler aimed at it** (issue #560).
- * `pathCurveLengths` in [`compile.ts`](compile.ts) is `PathConstraint.js:301-320`
- * transcribed, down to `Math.sqrt(dx * dx + dy * dy)` rather than `Math.hypot`
- * and `0.16666667` rather than `1 / 6`; `PS67`, `PS68` and `PS187` in `selftest.ts` hold it
- * there by requiring it to reproduce a real `PathConstraint.curves` array **bit
- * for bit** on the runtime's own posed chain. Measured after the change, all
+ * `pathCurveLengths` in [`compile.ts`](compile.ts) measures with the core's
+ * curve table (`curveLengthTable` in `src/core/constraints_path.ts`, issue
+ * #1015), down to `Math.sqrt(dx * dx + dy * dy)` rather than `Math.hypot` and
+ * `0.16666667` rather than `1 / 6`; `PS67`, `PS68` and `PS186` in `selftest.ts`
+ * hold it there by requiring it to reproduce a real `PathConstraint.curves`
+ * array **bit for bit** on the runtime's own posed chain. Measured after the change, all
  * seven entries of both editor exports above come back at the precision the
  * editor prints them.
  *

package/src/validate.ts

@@ -65,6 +65,7 @@ import {
 // rectangle on a shared page.
 import { readPlate } from '../tools/plate.ts';
 import { pageFootprint, pageGridSentence } from './atlas.ts';
+import { frameRegionName } from './core/uvs.ts';
 import {
   BEZIER_POINTS,
   curveStorage,
@@ -613,6 +614,9 @@ function setupBasisSays(rule: PhysicsPoseRule, poseValue: number): string {
   return arm === undefined ? physicsOutsideSays(rule, poseValue) : physicsBasisSays(arm);
 }
 
+/** `physicsTimelineNames`' table, once it has been built. */
+let physicsTimelineNamesTable: Record<number, string> | null = null;
+
 /**
  * The skeleton-JSON name of each physics timeline, keyed by the runtime's own
  * `Property` id.
@@ -624,16 +628,25 @@ function setupBasisSays(rule: PhysicsPoseRule, poseValue: number): string {
  * on the right are the ones `SkeletonJson`'s physics branch reads
  * (`SkeletonJson.js:1063-1094`), which is also what a motion spec's `property`
  * says.
+ *
+ * ⚠️ Built on first use, not while the module loads (issue #1014): the
+ * computed keys read the runtime's `Property` enum, and seven reads of it at
+ * load time were the only spine-core access a module made before a command
+ * ran — so `--help`, `render` and `check` on a rigc build all touched the
+ * runtime for a table only the gate's physics rules consult.
  */
-export const PHYSICS_TIMELINE_NAMES: Record<number, string> = {
-  [Property.physicsConstraintInertia]: 'inertia',
-  [Property.physicsConstraintStrength]: 'strength',
-  [Property.physicsConstraintDamping]: 'damping',
-  [Property.physicsConstraintMass]: 'mass',
-  [Property.physicsConstraintWind]: 'wind',
-  [Property.physicsConstraintGravity]: 'gravity',
-  [Property.physicsConstraintMix]: 'mix',
-};
+export function physicsTimelineNames(): Record<number, string> {
+  physicsTimelineNamesTable ??= {
+    [Property.physicsConstraintInertia]: 'inertia',
+    [Property.physicsConstraintStrength]: 'strength',
+    [Property.physicsConstraintDamping]: 'damping',
+    [Property.physicsConstraintMass]: 'mass',
+    [Property.physicsConstraintWind]: 'wind',
+    [Property.physicsConstraintGravity]: 'gravity',
+    [Property.physicsConstraintMix]: 'mix',
+  };
+  return physicsTimelineNamesTable;
+}
 
 /**
  * Which physics constraints a physics timeline that names NO constraint writes
@@ -733,20 +746,23 @@ function atStoredKey(time: number): number {
  * The atlas region names one raw skin entry will make the loader look up — or
  * `null` when the file states a sequence this walk cannot predict.
  *
- * ⚠️ Transcribed from the loader rather than reasoned out, because a join that
+ * ⚠️ Measured against the loader rather than reasoned out, because a join that
  * merely looks right is the thing A08 exists to refuse. `readSequence`
  * (`dist/SkeletonJson.js:641-649`) turns an absent or null `sequence` into
  * `new Sequence(1, false)` — one lookup, at the bare path — and a present one
  * into `new Sequence(count ?? 0, true)`, so a sequence map with no `count`
- * looks up nothing at all. `Sequence.getPath` (`dist/Sequence.js:124-132`)
- * appends `start + i`, left-padded with zeros to `digits`.
+ * looks up nothing at all. Each frame's name is the core's `frameRegionName`
+ * (`src/core/uvs.ts`): `start + i`, left-padded with zeros to `digits`, after
+ * the path (issue #1015). `PS127` records what the loader asks for and compares,
+ * and the core suite holds the frame names to `Sequence.getPath` over 7,680
+ * cases.
  *
  * Nothing in `examples/` carries a `sequence` (measured: 0 occurrences across
  * all twelve editor exports), so without this the assertion would have read a
  * sequence's base path as a region name and refused correct foreign data —
  * `A21_MESH_RIM_PINNED`'s old `|| 'ring'` default, one file over.
  */
-function attachmentRegionLookups(sequence: unknown, path: string): string[] | null {
+export function attachmentRegionLookups(sequence: unknown, path: string): string[] | null {
   if (sequence === undefined || sequence === null) return [path];
   if (!isObj(sequence)) return null;
   const whole = (value: unknown, fallback: number): number | null => {
@@ -757,11 +773,9 @@ function attachmentRegionLookups(sequence: unknown, path: string): string[] | nu
   const start = whole(sequence.start, 1);
   const digits = whole(sequence.digits, 0);
   if (count === null || start === null || digits === null || count < 0) return null;
+  const series = { count, start, digits, setup: 0 };
   const lookups: string[] = [];
-  for (let i = 0; i < count; i++) {
-    const frame = String(start + i);
-    lookups.push(`${path}${'0'.repeat(Math.max(0, digits - frame.length))}${frame}`);
-  }
+  for (let i = 0; i < count; i++) lookups.push(frameRegionName(path, series, i));
   return lookups;
 }
 
@@ -870,11 +884,11 @@ interface RawLinkedMesh {
  * `"<skin>\0<slot>\0<placeholder>" -> source` for every linked mesh the raw
  * skeleton declares, with what the file says about each one (issues #691, #710).
  *
- * 🔑 The test is the parser's own and it is not `type`: `type: "mesh"` and
- * `type: "linkedmesh"` share one branch and a truthy `source` is what decides
- * between them (`SkeletonJson.js:568-569`, `:582`). An empty `source` is falsy
- * there, so it is not a link here either — that map is read as an ordinary mesh,
- * which is exactly what the runtime does with it.
+ * 🔑 The format decides it, and not by `type`: `type: "mesh"` and
+ * `type: "linkedmesh"` share one branch of the reader and a truthy `source` is
+ * what decides between them (`SkeletonJson.js:568-569`, `:582`). An empty
+ * `source` is falsy there, so it is not a link here either — that map is read
+ * as an ordinary mesh, which is exactly what the runtime does with it.
  */
 function rawLinkedMeshes(raw: unknown): Map<string, RawLinkedMesh> {
   const links = new Map<string, RawLinkedMesh>();
@@ -3305,7 +3319,7 @@ export function validate(input: ValidateInput): ValidateReport {
         const reached = keyedLive(
           (timeline): timeline is PhysicsConstraintTimeline =>
             timeline instanceof PhysicsConstraintTimeline &&
-            PHYSICS_TIMELINE_NAMES[Number(timeline.getPropertyIds()[0].split('|')[0])] === rule.timeline,
+            physicsTimelineNames()[Number(timeline.getPropertyIds()[0].split('|')[0])] === rule.timeline,
           (timeline, value) => {
             timeline.set(raised, value);
             return rule.poseOk(raised[rule.field]);
@@ -3388,7 +3402,7 @@ export function validate(input: ValidateInput): ValidateReport {
           // `ConstraintTimeline1` encodes its propertyId as `<Property>|<index>`,
           // so the name comes from the runtime's own enum rather than from a
           // table of strings this file would have to keep in step.
-          const name = PHYSICS_TIMELINE_NAMES[Number(timeline.getPropertyIds()[0].split('|')[0])];
+          const name = physicsTimelineNames()[Number(timeline.getPropertyIds()[0].split('|')[0])];
           if (name === undefined) continue;
           const rule = physicsRuleFor(name);
           // -1 is the global form: the timeline drives every physics constraint
@@ -5029,9 +5043,9 @@ export function validate(input: ValidateInput): ValidateReport {
     // reads each of those off the FILE and names the value. The second POSES
     // every key at sampled times — mid-frame, so a float32 key time cannot land
     // a sample on a frame boundary — and compares the region the slot shows
-    // against the one the file's own statement gives: the frame arithmetic of
-    // `SequenceTimeline.applyToSlot` transcribed here, and the frame names of
-    // `Sequence.getPath` transcribed in `attachmentRegionLookups`. Neither is
+    // against the one the file's own statement gives: the frame the key's mode,
+    // index and delay give (`frameOf` below), and the frame names
+    // `attachmentRegionLookups` derives (the core's `frameRegionName`). Neither is
     // read off the loaded timeline, so the check is not the runtime agreeing
     // with itself.
     //
@@ -5099,7 +5113,15 @@ export function validate(input: ValidateInput): ValidateReport {
         }
       }
 
-      /** The frame `SequenceTimeline.applyToSlot` shows — transcribed, not called. */
+      /**
+       * The frame the file's statement gives for one key at one elapsed time —
+       * A46's prediction, not a call into the runtime. What holds it is the
+       * comparison it feeds: every sample sets it against the frame the posed
+       * slot shows, so a reading that disagreed with the runtime would fail A46
+       * on a correct file. A46 passing with samples posed on the selftest's
+       * series probes is that measurement for the modes they key; `M73` is its
+       * red half.
+       */
       const frameOf = (mode: string, index: number, elapsed: number, delay: number, count: number): number => {
         if (mode === 'hold') return index;
         let i = index + Math.trunc(elapsed / delay + 0.00001);
@@ -5436,7 +5458,7 @@ export function validate(input: ValidateInput): ValidateReport {
     // is about rigc's own packer never turning a region, which is a statement
     // about what rigc WRITES. It stopped being a statement about what rigc can
     // read in issue #570 — `extractRegion` now lifts a rotated region back off
-    // its page as a transcription of `MeshAttachment.computeUVs` — and the two
+    // its page, measured against `MeshAttachment.computeUVs` (`PKR02`) — and the two
     // must not be re-merged: an artifact under the renderer's own rulebook that
     // rigc did not pack is still a foreign artifact, whatever rigc can measure.
     const regionsPerPage = new Map<string, TextureAtlasRegion[]>();