spine-rigc 1.9.0 → 1.9.2

package/src/nonfinite.ts

@@ -0,0 +1,54 @@
+/**
+ * The one sentence for a pose number that is not finite (issue #882, #873) —
+ * moved here from `src/render.ts` by issue #1025 (cut 4c-5a of step 4c of
+ * #380), unchanged, because it now has a reader that may not link the
+ * runtime: `A10_NO_NAN_AFTER_STEPPING`'s body (`./assertions/bodies/a10.ts`),
+ * which reads it over the poses spine-core gives and over the poses rigc's
+ * core gives. `render` refuses on the same sentence, so the gate and the
+ * renderer still hold one definition of "not finite" — the six terms of a
+ * bone's world transform, then the vertices computed from them.
+ *
+ * Pure: no import at all.
+ */
+
+/** The bone fields a world transform is made of — what `firstNonFinite` reads off a bone. */
+export interface WorldTransform {
+  readonly name: string;
+  readonly a: number;
+  readonly b: number;
+  readonly c: number;
+  readonly d: number;
+  readonly worldX: number;
+  readonly worldY: number;
+}
+
+/** The fields of an attachment entry `firstNonFinite` reads — a frame's posed attachment or a rest entry. */
+export interface PosedVertices {
+  readonly slot: string;
+  readonly attachment: string;
+  readonly vertices: readonly number[];
+}
+
+/**
+ * The sentence for the first number at `where` that is not finite — bones before
+ * vertices, since a bone that overflowed is the cause and its vertices the
+ * symptom — or `null` when every number there is finite.
+ */
+export function firstNonFinite(where: string, entries: readonly PosedVertices[], bones: readonly WorldTransform[]): string | null {
+  for (const bone of bones) {
+    for (const field of ['a', 'b', 'c', 'd', 'worldX', 'worldY'] as const) {
+      if (!Number.isFinite(bone[field])) {
+        return `${where}: bone ${JSON.stringify(bone.name)} has ${field} ${String(bone[field])}; a world transform is finite`;
+      }
+    }
+  }
+  for (const entry of entries) {
+    const bad = entry.vertices.findIndex((value) => !Number.isFinite(value));
+    if (bad === -1) continue;
+    return (
+      `${where}: slot ${JSON.stringify(entry.slot)} attachment ${JSON.stringify(entry.attachment)} vertex ` +
+      `${Math.floor(bad / 2)} has ${bad % 2 === 0 ? 'x' : 'y'} ${String(entry.vertices[bad])}; a posed vertex is finite`
+    );
+  }
+  return null;
+}

package/src/render.ts

@@ -126,6 +126,7 @@ import {
   type SubsetRoster,
 } from './render_core.ts';
 import { walkTimelines } from './timelines.ts';
+import { firstNonFinite, type PosedVertices, type WorldTransform } from './nonfinite.ts';
 
 /** Opaque, and light: both of rung 3's parts are dark slate, so is every ground. */
 export const BACKGROUND: RGBA = [232, 232, 232, 255];
@@ -891,10 +892,20 @@ function skeletonDurations(root: JsonObject): Array<{ name: string; duration: nu
   });
 }
 
-/** Every page named, read from `atlasDir` by that name — the images a candidate the core poses is drawn from. */
-function pagesNamed(names: readonly string[], atlasDir: string): Map<string, Plate> {
+/**
+ * Every page named, read from `atlasDir` by that name — the images a candidate
+ * is drawn from, whichever poser draws it. A page that is not there is
+ * `absent`'s refusal, handed the page's absolute path (issues #1033, #1042):
+ * left to `readPlate`, it surfaced as an ENOENT and a stack. A page that is
+ * there and is not a PNG says so itself (`readPlate`).
+ */
+function pagesAt(names: readonly string[], atlasDir: string, absent: (page: string) => Error): Map<string, Plate> {
   const pages = new Map<string, Plate>();
-  for (const name of names) pages.set(name, readPlate(join(atlasDir, name)));
+  for (const name of names) {
+    const path = join(atlasDir, name);
+    if (!existsSync(path)) throw absent(resolve(path));
+    pages.set(name, readPlate(path));
+  }
   return pages;
 }
 
@@ -945,6 +956,140 @@ function requireSpineRuntime(label: string, why: string): void {
   }
 }
 
+/**
+ * A candidate whose skeleton spine-core cannot load against the atlas beside
+ * it — refused naming both files, why the runtime was drawing them, and what
+ * the runtime could not resolve, in its own words (issue #1033).
+ *
+ * On a rigc build this is a directory whose files are not one build: a
+ * `skeleton.json` or a `skeleton.atlas` from another build put beside this
+ * one's `skeleton.model.json`. The core refuses the pair first (the digest, or
+ * the atlas's pages, on the poser line's reason), the fallback hands it to
+ * spine-core, and the runtime stops at the first name it cannot resolve —
+ * which surfaced as its own uncaught error and a stack. A class of its own so
+ * `cli.ts` refuses it as an invocation (exit 2, nothing written), as it
+ * refuses a missing atlas on an export: the files the command was pointed at
+ * have to change, not the rig.
+ *
+ * Since issue #1042 it is also `bonedist`'s (and `bench --bones`'), on either
+ * side (`loadPosedSkeleton`), and the refusal for a page a candidate is drawn
+ * from that is not there on every poser's path — the core's included, where a
+ * build moved whole away from where it was built died on `readPlate`'s ENOENT.
+ */
+export class CandidatePairError extends Error {}
+
+/** Where a candidate's files sit, as the refusals below name them: the atlas, and the directory when it holds a model document. */
+function pairPlace(paths: { skeleton: string; atlas: string } | null): { atlas: string; build: string | null } {
+  const dir = paths === null ? null : dirname(resolve(paths.skeleton));
+  return { atlas: paths === null ? 'the atlas handed over with it' : resolve(paths.atlas), build: dir !== null && existsSync(join(dir, MODEL_DOCUMENT_FILE)) ? dir : null };
+}
+
+/** What a directory whose files are not one build is told to do. */
+function notOneBuild(dir: string): string {
+  return (
+    `${dir} is not one build: ${MODEL_DOCUMENT_FILE}, skeleton.json and skeleton.atlas are written together by one \`rigc build\`, ` +
+    "and these are not one build's — build it again, or put that build's own files back beside each other"
+  );
+}
+
+/**
+ * The refusal for a skeleton the runtime could not load against its atlas:
+ * `runtime` is the runtime's own message, and `does` what spine-core was
+ * loading it to do — `draws` for `render` and `check`, `poses` for a command
+ * that reads the posed bones and draws nothing (`bonedist`, issue #1042).
+ */
+function pairRefusal(
+  label: string,
+  paths: { skeleton: string; atlas: string } | null,
+  why: string,
+  runtime: string,
+  does: 'draws' | 'poses' = 'draws',
+): CandidatePairError {
+  const { atlas, build } = pairPlace(paths);
+  const head = `${label} does not load against ${atlas}: spine-core ${does} this pair (${why}) and could not resolve it — ${JSON.stringify(runtime)}. `;
+  return new CandidatePairError(head + (build === null ? 'The skeleton and the atlas are not one pair: the atlas has to be the one the skeleton was exported or built with' : notOneBuild(build)));
+}
+
+/**
+ * The refusal for a page a candidate is drawn from that is not there — the
+ * page's path is relative to the directory of the file that names it, so the
+ * file was written somewhere else. What the last clause may claim depends on
+ * what is known about the directory:
+ *
+ * - an export (no model document): only that the page has to be there;
+ * - a rigc build whose files the core REFUSED (issue #1033): an atlas copied
+ *   from another build's directory, and the directory is not one build — the
+ *   core's own reason, on the poser line's words, says so;
+ * - a rigc build the core ACCEPTED, or one `--poser spine` never asked the
+ *   core about (issue #1042): the build was moved or copied away from where it
+ *   was built. "Not one build" would be a guess there, and on a build moved
+ *   whole — measured — a false one.
+ *
+ * `by` is the file that names the page (`null`: the atlas), `draws` what is
+ * drawn from it.
+ */
+function pageRefusal(
+  page: string,
+  paths: { skeleton: string; atlas: string } | null,
+  why: string,
+  reading: { by: string | null; draws: string; refusedBuild: boolean },
+): CandidatePairError {
+  const { atlas, build } = pairPlace(paths);
+  // The poser line's reason, unless it is only the document's path — which the sentence has just named.
+  const because = why === reading.by ? '' : ` (${why})`;
+  const head =
+    `nothing at ${page}: ${reading.by ?? atlas} names it as a page, and ${reading.draws}${because}. ` +
+    `A page path is relative to the ${reading.by === null ? "atlas's own" : "build's"} directory`;
+  const tail =
+    build === null
+      ? ', and the page has to be there'
+      : reading.refusedBuild
+        ? `, so an atlas copied from another build's directory names pages that are not here. ${notOneBuild(build)}`
+        : `, so a build moved or copied away from the directory it was built in names pages that are not here — ` +
+          'build it again where it is, or build it with --copy-images, which writes its pages beside it';
+  return new CandidatePairError(head + tail);
+}
+
+/**
+ * The one place a candidate's skeleton is handed to the runtime's parser
+ * against its atlas (issues #1033, #1042): a pair it cannot load is `refuse`'s
+ * refusal, given the runtime's own message, rather than the runtime's throw
+ * and a stack. The JSON is parsed outside the catch: a file that is not JSON
+ * is not something the runtime said, and the CLI refuses it by name before it
+ * gets here (`readSkeletonText`).
+ */
+function spineSkeletonData(skeletonText: string, atlasText: string, refuse: (runtime: string) => Error): SkeletonData {
+  const json = JSON.parse(skeletonText);
+  const reader = new SkeletonJson(new AtlasAttachmentLoader(new TextureAtlas(atlasText)));
+  try {
+    return reader.readSkeletonData(json);
+  } catch (err) {
+    throw refuse(err instanceof Error ? err.message : String(err));
+  }
+}
+
+/**
+ * A skeleton a user named, posed through spine-core for what its bones do —
+ * `bonedist`'s two sides (issue #1042). A pair that does not load is refused
+ * by name (`CandidatePairError`, `pairRefusal` with `poses`), `why` saying
+ * which side and what the pose is read for.
+ *
+ * ⭐ The skeleton data alone, and no page: `bonedist` reads bone world
+ * transforms and samples no pixel, and the atlas's regions — which the
+ * runtime resolves every attachment against — are in the atlas text. Reading
+ * the page PNGs as `loadPosable` does made a pair whose pages are elsewhere
+ * die on an ENOENT for images the command never looks at; the figures are the
+ * same with or without them (the PR of #1042 measures it).
+ *
+ * `loadPosable` and `posableFromText` stay the unguarded loaders, for pairs
+ * the caller wrote itself (the tools and the selftest), where the runtime's
+ * own message is what the caller reads.
+ */
+export function loadPosedSkeleton(skeletonPath: string, atlasPath: string, why: string): SkeletonData {
+  const paths = { skeleton: skeletonPath, atlas: atlasPath };
+  return spineSkeletonData(readFileSync(skeletonPath, 'utf8'), readFileSync(atlasPath, 'utf8'), (runtime) => pairRefusal(skeletonPath, paths, why, runtime, 'poses'));
+}
+
 /** A candidate as `render` and `check` read it: the posers, the facts and the pages (issue #1014). */
 export interface Candidate {
   choice: PoserChoice;
@@ -983,12 +1128,21 @@ export function loadCandidate(
     if (input.atlasText === null) throw atlasAbsent(paths?.atlas ?? '(no atlas)', input.label, why);
     return input.atlasText;
   };
+  // A pair the runtime cannot load — a skeleton.json or an atlas from another build beside this one's document — is
+  // refused by name rather than surfacing the runtime's own throw and stack (issue #1033); `spineSkeletonData` is
+  // where the catch is.
+  // Under `--poser core` the runtime is loaded only for the facts the flags are checked against, and nothing would be
+  // drawn through it: the refusal that is true there is the flag's, the one `refuseUnchosen` would have said next.
+  const refusing = (refusal: CandidatePairError): Error =>
+    forced === 'core' && choice !== null && choice.core === null ? new PoserChoiceError(`--poser core: ${choice.why}`) : refusal;
+  const spineLoad = (text: string, why: string): SkeletonData =>
+    spineSkeletonData(input.skeletonText, text, (runtime) => refusing(pairRefusal(input.label, paths, why, runtime)));
   const spineData = (): SkeletonData => {
     if (data === null) {
       const why = choice === null || choice.core !== null ? 'a fallback from the core poser' : choice.why;
       const text = atlasText(why);
       requireSpineRuntime(input.label, why);
-      data = new SkeletonJson(new AtlasAttachmentLoader(new TextureAtlas(text))).readSkeletonData(JSON.parse(input.skeletonText));
+      data = spineLoad(text, why);
     }
     return data;
   };
@@ -999,14 +1153,31 @@ export function loadCandidate(
   choice = chosen.choice;
   if (choice.core !== null && chosen.document !== null) {
     // A rigc-compiled/2 document names its pages; a /1 document is posed only with its atlas beside it, which names them (`choosePosers`).
-    const names = chosen.document.pageNames ?? parseAtlasText(atlasText(choice.why)).pages.map((page) => page.name);
-    return { choice, facts: coreFacts(input.skeletonText, input.atlasText, choice.core, chosen.document), pages: pagesNamed(names, input.atlasDir) };
+    const named = chosen.document.pageNames;
+    const names = named ?? parseAtlasText(atlasText(choice.why)).pages.map((page) => page.name);
+    // A page the build names that is not here is a build moved away from where it was built (issue #1042): the
+    // core accepted these files as one build, so the refusal does not say they are not one.
+    const by = named === null || paths === null ? null : join(dirname(resolve(paths.skeleton)), MODEL_DOCUMENT_FILE);
+    const reading = { by, draws: 'the core draws this build from it', refusedBuild: false };
+    const accepted = choice.why;
+    const pages = pagesAt(names, input.atlasDir, (page) => pageRefusal(page, paths, accepted, reading));
+    return { choice, facts: coreFacts(input.skeletonText, input.atlasText, choice.core, chosen.document), pages };
   }
   const text = atlasText(choice.why);
   requireSpineRuntime(input.label, choice.why);
-  const posable = posableFromText(input.skeletonText, text, input.atlasDir);
-  data = posable.data;
-  return { choice, facts: spineFacts(posable.data, text), pages: posable.pages };
+  // `posableFromText`'s two steps, in its order — every page the atlas declares, then the skeleton — each refusing
+  // by name where the pair is not one: a page that is not there (`pageRefusal`), a skeleton the runtime cannot load
+  // against the atlas (`spineLoad`). The directory is called "not one build" only where the core refused its files —
+  // `--poser spine` never asked the core, and a build moved whole is one build whose pages are elsewhere.
+  const reading = { by: null, draws: 'spine-core draws this pair through that atlas', refusedBuild: forced !== 'spine' };
+  const why = choice.why;
+  const pages = pagesAt(
+    new TextureAtlas(text).pages.map((page) => page.name),
+    input.atlasDir,
+    (page) => refusing(pageRefusal(page, paths, why, reading)),
+  );
+  data = spineLoad(text, choice.why);
+  return { choice, facts: spineFacts(data, text), pages };
 }
 
 /**
@@ -1066,8 +1237,8 @@ function coreFacts(skeletonText: string, atlasText: string | null, poser: Poser,
 // 🔒 What stays spine-core's and outside the seam, deliberately: an export's
 // atlas (`posableFromText`'s pages, and `substituteTexture`'s region lookup on
 // anything spine-core poses — a rigc build the core poses reads both through
-// rigc's own reader since issue #1020) and `nonFiniteOfPosed`, which `validate.ts` calls on a spine-core
-// skeleton it stepped itself (A10), so the round trip keeps its spine-core
+// rigc's own reader since issue #1020) and `posedNumbersOf`, which `validate.ts` calls on a spine-core
+// skeleton it stepped itself (A10's runtime supplier), so the round trip keeps its spine-core
 // entry whatever poses the renders.
 
 /** What a sampler hands a posed frame's draw walk — `PoseOptions` with the subset already resolved. */
@@ -1979,66 +2150,36 @@ function restOf(data: SkeletonData, skin: string | undefined, shown: readonly At
   return out;
 }
 
-/** The bone fields a world transform is made of — what `firstNonFinite` reads off a bone. */
-type WorldTransform = Pick<GeometryBone, 'name' | 'a' | 'b' | 'c' | 'd' | 'worldX' | 'worldY'>;
-
-/** The fields of an attachment entry `firstNonFinite` reads — a frame's `AttachmentPose` or a rest entry. */
-type PosedVertices = Pick<AttachmentPose, 'slot' | 'attachment' | 'vertices'>;
-
 /**
- * The sentence for the first number at `where` that is not finite — bones before
- * vertices, since a bone that overflowed is the cause and its vertices the
- * symptom — or `null` when every number there is finite.
- */
-function firstNonFinite(where: string, entries: readonly PosedVertices[], bones: readonly WorldTransform[]): string | null {
-  for (const bone of bones) {
-    for (const field of ['a', 'b', 'c', 'd', 'worldX', 'worldY'] as const) {
-      if (!Number.isFinite(bone[field])) {
-        return `${where}: bone ${JSON.stringify(bone.name)} has ${field} ${String(bone[field])}; a world transform is finite`;
-      }
-    }
-  }
-  for (const entry of entries) {
-    const bad = entry.vertices.findIndex((value) => !Number.isFinite(value));
-    if (bad === -1) continue;
-    return (
-      `${where}: slot ${JSON.stringify(entry.slot)} attachment ${JSON.stringify(entry.attachment)} vertex ` +
-      `${Math.floor(bad / 2)} has ${bad % 2 === 0 ? 'x' : 'y'} ${String(entry.vertices[bad])}; a posed vertex is finite`
-    );
-  }
-  return null;
-}
-
-/**
- * The same sentence for one skeleton as it stands posed now — its bones, then
- * the vertices of every region and mesh its slots show, in draw order — or
- * `null` when every one of those numbers is finite.
+ * One skeleton as it stands posed now, as the numbers `firstNonFinite`
+ * (`./nonfinite.ts`) reads: every bone's six world-transform terms, in skeleton
+ * order, then the world vertices of every region and mesh its slots show, in
+ * draw order — the runtime's reading of each (`worldVerticesOf`).
  *
- * ⭐ This is how `A10_NO_NAN_AFTER_STEPPING` reads each pose it steps (issue
- * #882), so the gate and the renderer hold one definition of "not finite": the
- * six terms `firstNonFinite` reads off a bone, and the vertices the runtime
- * computes from them. Before it A10 read the world POSITION alone, and a bone at
- * `rotation: 1e309` — finite position, NaN `a`, `b`, `c`, `d` — was gated green
- * and then refused here. The vertices are read too because a bone can be finite
- * and still carry one that is not: a two-bone `scaleX` chain of 1e154 × 1e154
+ * ⭐ This is how `A10_NO_NAN_AFTER_STEPPING` reads each pose spine-core steps
+ * (issue #882; its runtime supplier in `validate.ts` since issue #1025), so the
+ * gate and the renderer hold one definition of "not finite": the six terms
+ * `firstNonFinite` reads off a bone, and the vertices the runtime computes from
+ * them. Before #882 A10 read the world POSITION alone, and a bone at `rotation:
+ * 1e309` — finite position, NaN `a`, `b`, `c`, `d` — was gated green and then
+ * refused here. The vertices are read too because a bone can be finite and
+ * still carry one that is not: a two-bone `scaleX` chain of 1e154 × 1e154
  * leaves the child's `a` at 1e308, finite, and every vertex of its attachment
- * past the largest double. Only computed once every bone is finite, so a
- * broken bone is named as the cause rather than through its vertices.
+ * past the largest double. `firstNonFinite` reads the bones first, so a broken
+ * bone is named as the cause rather than through its vertices.
  */
-export function nonFiniteOfPosed(where: string, skeleton: Skeleton): string | null {
+export function posedNumbersOf(skeleton: Skeleton): { bones: WorldTransform[]; drawn: PosedVertices[] } {
   const bones: WorldTransform[] = skeleton.bones.map((bone) => {
     const { a, b, c, d, worldX, worldY } = bone.appliedPose;
     return { name: bone.data.name, a, b, c, d, worldX, worldY };
   });
-  const found = firstNonFinite(where, [], bones);
-  if (found !== null) return found;
-  const entries: PosedVertices[] = [];
+  const drawn: PosedVertices[] = [];
   for (const slot of skeleton.drawOrder.appliedPose) {
     const attachment = slot.appliedPose.attachment;
     if (!(attachment instanceof MeshAttachment) && !(attachment instanceof RegionAttachment)) continue;
-    entries.push({ slot: slot.data.name, attachment: attachment.name, vertices: worldVerticesOf(skeleton, slot, attachment) });
+    drawn.push({ slot: slot.data.name, attachment: attachment.name, vertices: worldVerticesOf(skeleton, slot, attachment) });
   }
-  return firstNonFinite(where, entries, []);
+  return { bones, drawn };
 }
 
 /**

package/src/render_core.ts

@@ -282,6 +282,11 @@ interface CoreInput {
  * Exported for the model side of the validator (issue #1025), which poses a
  * slot the way `validate()` does — a fresh skeleton, no skin set — and must
  * resolve that state by this rule rather than by a copy of it.
+ *
+ * ⚠️ The first refusal — skins declared and none of them `default` — is issue
+ * #1051: the model side's A10, which always poses, fails such a rig the round
+ * trip passes; `tools/verdict_gate.ts` and the selftest's `VF02` count those
+ * line sets apart as this documented class rather than as a difference.
  */
 export function noSkinView(doc: CompiledDocument): CompiledDocument {
   if (doc.skins.length === 0) return underSkin(doc, CORE_ALL_SKINS);