spine-rigc 1.6.2 → 1.7.0

package/cli.ts

@@ -93,7 +93,7 @@ import {
 } from './src/diff.ts';
 import { ingest, IngestError, IngestSpecRefused, INGEST_GUTTERS, type IngestFinding, type IngestStage } from './src/ingest.ts';
 import { NotAPngError } from './src/png.ts';
-import { copyAtlasPages } from './src/emit.ts';
+import { copyAtlasPages, plannedPageCopies } from './src/emit.ts';
 import {
   DEFAULT_PADDING,
   DEFAULT_PAGE_EDGES,
@@ -141,10 +141,9 @@ import {
   GEOMETRY_FILE,
   GeometryError,
   UnframeablePoseError,
-  skinRosterOf,
   geometryFileOf,
   geometryText,
-  loadPosable,
+  loadCandidate,
   PROTOCOL_FPS,
   renderFrame,
   sampleAll,
@@ -154,17 +153,16 @@ import {
   SHEET_TILE,
   sidecarViewport,
   SlotSubsetError,
-  slotSubsetOf,
-  candidatePosers,
   POSER_NAMES,
   PoserChoiceError,
+  refuseUnchosen,
+  SpineRuntimeError,
   throughPoser,
   type Frame,
   type FramesSidecar,
   type FrameSet,
-  type Posable,
-  type PoserChoice,
   type PoserName,
+  type SkeletonFacts,
   type SlotSubset,
 } from './src/render.ts';
 import {
@@ -456,10 +454,15 @@ function runGate(
   modelText: string,
   opts: CompileOptions,
   profile: ValidateProfile,
+  /** The atlas text `build` writes for a compile's own — `--copy-images` renames the pages — which the second compile's document is spelled from, as `modelText` was (issue #1016). */
+  written: (atlasText: string) => string,
   atlas?: AtlasOverride,
 ): number {
   // The determinism check compares a second, independent compile — its model
-  // document included, which is the text `build` writes beside the pair.
+  // document included, which is the text `build` writes beside the pair, and
+  // which states where each region sits in the atlas written with it (`pages`,
+  // issue #1016): so the second document is spelled from the second compile's
+  // atlas as it would be written, or from the second, independent pack.
   const again = compile(opts);
   const report = validate({
     skeletonText: result.skeletonText,
@@ -467,7 +470,7 @@ function runGate(
     atlasDir: opts.outDir,
     declaredDurations: result.declaredDurations,
     modelText,
-    reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText, modelText: modelDocument(again.model, again.skeletonText) },
+    reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText, modelText: modelDocument(again.model, again.skeletonText, atlas ? atlas.again : written(again.atlasText)) },
     rig: result.rig,
     profile,
   });
@@ -864,7 +867,7 @@ function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>):
   // Through rigc's own core over the model document the build carries (issue #969), spine-core when the core
   // refuses it; the survey's record says which (`source`), and `tools/survey_hashes.ts` holds the two to one block.
   // The block itself is `deformReportBlock` (`src/deformreport.ts`), so a control renders it off either poser's survey.
-  const survey = surveyOfBuild({ skeletonText: result.skeletonText, atlasText: result.atlasText, modelText: modelDocument(result.model, result.skeletonText) }, new Set(), 'auto');
+  const survey = surveyOfBuild({ skeletonText: result.skeletonText, atlasText: result.atlasText, modelText: modelDocument(result.model, result.skeletonText, result.atlasText) }, new Set(), 'auto');
   return deformReportBlock(survey, result.deformTransforms, exempt);
 }
 
@@ -1113,10 +1116,17 @@ function cmdBuild(flags: Record<string, string>): void {
 
   // The model's document is spelled before the gate, so the text A18 compares
   // is the text written, and a model the document cannot carry is refused
-  // before anything is (issue #922).
-  const modelText = modelDocument(result.model, result.skeletonText);
+  // before anything is (issue #922). It states where each region sits in the
+  // atlas written beside it (`pages`, issue #1016), so it is spelled from that
+  // atlas: under `--copy-images` the text with the copies' page names, planned
+  // here from the text alone (`plannedPageCopies`) and copied after the gate.
+  // Under `--pack` the pages move again after this gate, and the document
+  // written is the one the packed gate below spells and compares.
+  const copying = flags['copy-images'] !== undefined;
+  const writtenAtlas = (atlasText: string): string => (copying ? plannedPageCopies(atlasText, opts.outDir).atlasText : atlasText);
+  let modelText = modelDocument(result.model, result.skeletonText, writtenAtlas(result.atlasText));
   console.log(`  ..    validate (spine-core round trip + machine assertions, profile ${profile})`);
-  const failures = runGate(result, modelText, opts, profile);
+  const failures = runGate(result, modelText, opts, profile, writtenAtlas);
   if (failures > 0) {
     console.error(`rigc: ${failures} assertion(s) failed — nothing written`);
     process.exit(1);
@@ -1139,6 +1149,10 @@ function cmdBuild(flags: Record<string, string>): void {
   let atlasText = result.atlasText;
   if (flags['copy-images'] !== undefined) {
     const copied = copyAtlasPages(atlasText, opts.outDir);
+    // The document's pages were spelled from the plan; the copy is held to it before anything of the pair is written.
+    if (copied.atlasText !== writtenAtlas(result.atlasText)) {
+      throw new Error(`internal: --copy-images wrote an atlas whose page names are not the ones ${MODEL_DOCUMENT_FILE} was spelled with — nothing of the pair was written`);
+    }
     atlasText = copied.atlasText;
     console.log(`  ..    copy-images: ${copied.pages.length} page(s) copied into ${opts.outDir}`);
     for (const p of copied.pages) {
@@ -1197,7 +1211,10 @@ function cmdBuild(flags: Record<string, string>): void {
       })),
       packOpts,
     );
-    const packFailures = runGate(result, modelText, opts, profile, { text: atlasText, again: packAgain.atlasText });
+    // The document written is spelled from the packed atlas, and this gate's A18 compares it with a
+    // second compile's spelled from the second, independent pack (issue #1016).
+    modelText = modelDocument(result.model, result.skeletonText, atlasText);
+    const packFailures = runGate(result, modelText, opts, profile, (text) => text, { text: atlasText, again: packAgain.atlasText });
     if (packFailures > 0) {
       console.error(
         `rigc: ${packFailures} assertion(s) failed on the PACKED atlas — the pages were written to ` +
@@ -1209,8 +1226,9 @@ function cmdBuild(flags: Record<string, string>): void {
 
   writeFileSync(join(opts.outDir, 'skeleton.json'), result.skeletonText);
   writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
-  // rigc's own record of the compiled rig (`rigc-compiled/1`, issue #922),
-  // written with the pair and only after the same gate. rigc's own posing core
+  // rigc's own record of the compiled rig (`rigc-compiled/2`, issue #922;
+  // its `pages` the atlas just written, issue #1016), written with the pair
+  // and only after the same gate — under `--pack`, the packed one. rigc's own posing core
   // reads it (`readModel`, `src/core/index.ts`, issue #380's step 2).
   writeFileSync(join(opts.outDir, MODEL_DOCUMENT_FILE), modelText);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
@@ -1603,13 +1621,13 @@ function readSkinFlag(flags: Record<string, string>, declared: string[]): string
  */
 function readSlotSubsetFlags(
   flags: Record<string, string>,
-  data: Posable['data'],
+  facts: SkeletonFacts,
   skin: string | undefined,
 ): SlotSubset | undefined {
   const list = (raw: string | undefined): string[] | undefined =>
     raw === undefined ? undefined : raw.split(',').map((name) => name.trim()).filter((name) => name !== '');
   try {
-    return slotSubsetOf(data, { slots: list(flags.slot), hidden: list(flags.hide) }, skin);
+    return facts.subset({ slots: list(flags.slot), hidden: list(flags.hide) }, skin);
   } catch (err) {
     if (err instanceof SlotSubsetError) throw new UsageError(err.message);
     throw err;
@@ -1617,16 +1635,12 @@ function readSlotSubsetFlags(
 }
 
 /**
- * `--poser core|spine`, resolved against the candidate (issue #968): both
- * posers for it, and which one this run asked for. `core` on an input that
- * cannot carry it is refused as a usage error by name; absent, the input's own
- * choice stands — see `candidatePosers`.
+ * `--poser` as spelled, checked against the posers there are — shared by
+ * `render` and `check`. On `render` it is read where its refusal has always
+ * stood, after the candidate's own flags; the candidate is loaded before that
+ * with the spelling as given (`posersAsked`), so a rigc build the core poses
+ * is chosen without loading spine-core (issue #1014).
  */
-function readPoserChoice(flags: Record<string, string>, data: Posable['data'], skeletonPath: string, atlasPath: string): PoserChoice {
-  return candidatePosers(data, skeletonPath, atlasPath, readPoserFlag(flags));
-}
-
-/** `--poser` as spelled, checked against the posers there are — shared by `render` and `check`. */
 function readPoserFlag(flags: Record<string, string>): PoserName | undefined {
   const raw = flags.poser;
   const forced = POSER_NAMES.find((name) => name === raw);
@@ -1636,6 +1650,11 @@ function readPoserFlag(flags: Record<string, string>): PoserName | undefined {
   return forced;
 }
 
+/** `--poser` as the candidate is loaded with: a known spelling, or the input's own choice — the spelling is refused later, by `readPoserFlag`. */
+function posersAsked(flags: Record<string, string>): PoserName | undefined {
+  return POSER_NAMES.find((name) => name === flags.poser);
+}
+
 /** A resolved subset as the one field it is spelled as, in `PoseOptions` and in `frames.json` alike. */
 function subsetFields(subset: SlotSubset | undefined): { slots?: string[]; hidden?: string[] } {
   if (subset === undefined) return {};
@@ -1653,8 +1672,10 @@ function readPositiveNumber(flags: Record<string, string>, key: string, fallback
 /**
  * Does this skeleton declare a setup stage — a numeric width AND height?
  *
- * Read off the loaded `SkeletonData` for `render` and off the file's header for
- * `preview`, which never loads one; both are the same two fields, because
+ * Read off the file's header for `preview`, which never loads one; `render`
+ * reads the same statement off its candidate (`SkeletonFacts.declaresStage`:
+ * the header again on a rigc build the core poses, the loaded `SkeletonData`
+ * on an export). Both are the same two fields, because
  * `SkeletonJson` copies them across unconditionally (`SkeletonJson.js:70-73`),
  * so a header that omits them leaves `undefined` on a field typed `number`.
  */
@@ -1725,10 +1746,18 @@ function cmdRender(flags: Record<string, string>): void {
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
   console.log(`  ..    atlas    ${atlasPath}`);
-  const { data, pages } = loadPosable(skeletonPath, atlasPath, atlasDir);
-  const only = readAnimationFlag(flags, data.animations.map((a) => a.name));
-  const skin = readSkinFlag(flags, data.skins.map((s) => s.name));
-  const subset = readSlotSubsetFlags(flags, data, skin);
+  // Which implementation of the posing seam draws this (issue #968), chosen
+  // before anything is read off the candidate (issue #1014): a rigc build the
+  // core poses — `skeleton.model.json` beside the pair — reads its names, its
+  // subset roster and its pages without loading spine-core at all.
+  const { choice, facts, pages } = loadCandidate(
+    { skeletonText: readFileSync(skeletonPath, 'utf8'), atlasText: readFileSync(atlasPath, 'utf8'), atlasDir, label: skeletonPath },
+    { skeleton: skeletonPath, atlas: atlasPath },
+    posersAsked(flags),
+  );
+  const only = readAnimationFlag(flags, [...facts.animations]);
+  const skin = readSkinFlag(flags, [...facts.skins]);
+  const subset = readSlotSubsetFlags(flags, facts, skin);
   // One object, so the framing and the frames cannot be posed under two
   // different skins — which would frame one shot with another shot's box.
   // Not annotated `PoseOptions`: that name is `src/pose.ts`'s in this file, and
@@ -1742,23 +1771,25 @@ function cmdRender(flags: Record<string, string>): void {
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
 
-  // Which implementation of the posing seam draws this (issue #968): rigc's own
-  // core when the candidate is a rigc build — `skeleton.model.json` beside the
-  // pair — and spine-core otherwise, or where the core refuses the input by
-  // name. Never silently: the `poser` line below says which, and why.
-  const choice = readPoserChoice(flags, data, skeletonPath, atlasPath);
+  // Rigc's own core when the candidate is a rigc build, and spine-core
+  // otherwise, or where the core refuses the input by name. Never silently:
+  // the `poser` line below says which, and why. `--poser` is refused here, where
+  // it always was: a spelling there is no poser for, then `core` on an input
+  // that cannot carry it.
+  readPoserFlag(flags);
+  refuseUnchosen(choice);
 
   // Everything is posed before anything is written, so a core refusal partway
   // re-poses the whole input on spine-core rather than leaving half of a frame
   // set drawn by each.
-  const posed = throughPoser(choice, (poser) => {
+  const posed = throughPoser(choice, (poser, roster) => {
     // `null` is a skeleton that posed no vertex at all. One that posed a vertex
     // it cannot frame — Infinity or NaN — is thrown from the framing as a
     // `GeometryError` naming the number (issue #873), and one whose every vertex
     // sits at one point — every drawn bone unposed by the skin, or collapsed — as
     // an `UnframeablePoseError` (issue #997); neither reaches this. The roster is what
     // lets the second name the skins that pose a bone, whichever poser draws.
-    const viewport = framingViewport(poser, maxSide, pose, skinRosterOf(data));
+    const viewport = framingViewport(poser, maxSide, pose, roster);
     if (!viewport) {
       throw new UsageError(
         `${skeletonPath} posed no drawable attachment in any animation or in its setup pose${
@@ -1784,7 +1815,7 @@ function cmdRender(flags: Record<string, string>): void {
     const geometryTexts = new Map<string, string>();
     if (geometry) {
       for (const [name, frames] of sampled) {
-        const animation = name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name;
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
         geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin)));
       }
     }
@@ -1793,7 +1824,7 @@ function cmdRender(flags: Record<string, string>): void {
   const { viewport, sampled, geometryTexts } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
-  if (!declaresSetupStage(data)) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
+  if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
   mkdirSync(outRoot, { recursive: true });
   const sets: FrameSet[] = [];
@@ -1819,7 +1850,7 @@ function cmdRender(flags: Record<string, string>): void {
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
-      animation: name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name,
+      animation: name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name,
       fps,
       sampled: frames.length,
       written: frames.length,
@@ -4281,6 +4312,14 @@ try {
     console.error(`rigc: ${err.message}`);
     process.exit(1);
   }
+  // An input posed through spine-core — a Spine export, `--poser spine`, a
+  // fallback — on a run where the runtime cannot be used (issue #1014). The
+  // sentence names the input and why it needs the runtime; exit 1, like a file
+  // that is not a PNG: the invocation was fine and the run could not pose it.
+  if (err instanceof SpineRuntimeError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(1);
+  }
   // An install refused before its first write (issue #831): the invocation was
   // fine and an entry on disk was not what this command would write, so exit 1
   // like a file that is not a PNG. The message names every such entry, what is

package/docs/AUTHORING.md

@@ -195,7 +195,7 @@ What the flags mean:
 | --- | --- |
 | `--rig` | the rig spec — skeleton structure |
 | `--motion` | the motion spec — time |
-| `--out` | directory for `skeleton.json` + `skeleton.atlas`, and on `build` `skeleton.model.json` beside them; atlas page paths and `skeleton.images` are written relative to it. `skeleton.model.json` is rigc's own record of the compiled rig (`rigc-compiled/1`: the bones, slots, skins, constraints, events and animations the Spine files were emitted from, in the spec's order, and the rest of what posing them takes), written after the same gate as the pair and ending in `spine.sha256`, the digest of the `skeleton.json` written beside it. It is what rigc's own posing core (`src/core/`) poses: `render` and `check` — and `bench --frames`, which folds `check` in — pose a build through it, and `--poser` below says when they do not. On `check` it is a directory of **pictures** instead: one per frame the table lists (every compared frame under `--all-frames`), reference · candidate · difference · overlay at the comparison grid's native size, as `<dir>/<set>/f####.png` beside a `frames.json` that says what they are pictures of. Each `<dir>/<set>/` is cleared first; a file at `<dir>`, or a directory that is or holds `--frames`, is refused by name — **§9.2.1** |
+| `--out` | directory for `skeleton.json` + `skeleton.atlas`, and on `build` `skeleton.model.json` beside them; atlas page paths and `skeleton.images` are written relative to it. `skeleton.model.json` is rigc's own record of the compiled rig (`rigc-compiled/2`: the bones, slots, skins, constraints, events and animations the Spine files were emitted from, in the spec's order, and the rest of what posing them takes; then `pages`, every page of the `skeleton.atlas` written beside it and where each region sits on it — after `--pack` the packed pages, after `--copy-images` the copies' names), written after the same gate as the pair and ending in `spine.sha256`, the digest of the `skeleton.json` written beside it. A `rigc-compiled/1` document (rigc 1.6) has no `pages` and is still read: the core then takes the placement from the atlas beside it. It is what rigc's own posing core (`src/core/`) poses: `render` and `check` — and `bench --frames`, which folds `check` in — pose a build through it, and `--poser` below says when they do not. On `check` it is a directory of **pictures** instead: one per frame the table lists (every compared frame under `--all-frames`), reference · candidate · difference · overlay at the comparison grid's native size, as `<dir>/<set>/f####.png` beside a `frames.json` that says what they are pictures of. Each `<dir>/<set>/` is cleared first; a file at `<dir>`, or a directory that is or holds `--frames`, is refused by name — **§9.2.1** |
 | `--copy-images` | `build` only: also copies every page **the emitted atlas names** into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own, and points `skeleton.images` at `--out` itself so the editor's import finds the parts beside the skeleton (§3.1 says why it is spelled `../<out>/` and not `./`). Under `--atlas-in` those pages are the pack's, not one per part (**§0.2**). Without it, page paths point at the source art |
 | `--pack` | `build` only: arrange every part onto **shared** atlas page(s), written into `--out` as real PNGs, instead of one page per part. Lossless — nothing is resampled, trimmed or rotated. The default is one page per part — **§0.1** |
 | `--page-size` | `build --pack` only: the largest page edge (default `2048`). A ceiling, not the size: page edges are powers of two and the one written is the smallest that holds the pack — **§0.1** |
@@ -210,7 +210,7 @@ What the flags mean:
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
-| `--poser` | `render` and `check`: `core` or `spine` — which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes, with the atlas beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core. Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `the "default" skin names` (no `--skin`, and the default skin names a skin-required bone or constraint, each named) · `and no "default" one` (no `--skin`, and skins with none named `default` — spine-core draws nothing there either, so the render stops at `there is nothing to draw`, exit 2, and only `--poser core` prints this refusal) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row |
+| `--poser` | `render` and `check`: `core` or `spine` — which implementation poses the frames (on `check`, the candidate's; the reference side is pixels either way). By default a **rigc build** (the `skeleton.model.json` `build` writes, with the atlas beside it) is posed by rigc's own core and a **Spine export** by spine-core; the render prints a `poser` line saying which and why, and so does the check report (`check.json`'s `poser`, and the pictures' `frames.json` under `--out`; `bench --frames` prints the same line). A concave or an inverse clip is posed by the core. Where the input cannot carry the core, or the core refuses it, the render poses it through spine-core and the `poser` line says why, in one of these words: `no skeleton.model.json beside` (a Spine export) · `is not beside` (`--atlas` names an atlas outside the build's directory) · `does not describe` (a model document whose bones, slots or animations are not the skeleton's) · `is not the skeleton.json` (a `skeleton.json` whose SHA-256 is not the `spine.sha256` its model document records — edited or replaced after the build — both digests named) · `the polygon is not simple` (a clip polygon two of whose edges cross or touch, the slot named) · `the "default" skin names` (no `--skin`, and the default skin names a skin-required bone or constraint, each named) · `and no "default" one` (no `--skin`, and skins with none named `default` — spine-core draws nothing there either, so the render stops at `there is nothing to draw`, exit 2, and only `--poser core` prints this refusal) · `depends on the runtime's previous pass` (a constraint moves a posed bone from a bone that a constraint writes into while that bone is inactive, all four named) · `--poser spine` (asked for). Any other refusal of the core's — an unreadable model document among them — reads `the core refused` and then the core's own words. `--poser core` on an input that cannot carry it is refused in the same words (exit 2, nothing written); `--poser spine` forces the runtime. The repository's selftest renders one probe per reason above and holds this list to the lines they print (`RC09`). Both posers draw the same frames, geometry and framing box to the bit on every corpus (issue #968), and `check` through either writes the same report, `check.json` and pictures but for the poser it names on every tree row. A rigc build the core poses reads nothing through spine-core on `render`, `render --geometry` and `check` (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its animation and skin names, slot and skin rosters, stage and bone tree come off its own `skeleton.json` and model document, its pages off rigc's atlas reader. The runtime is loaded for a Spine export, `--poser spine`, a fallback the `poser` line names and `--texture-from`; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`) |
 | `--record` | `vote` only: a saved vote to check against its ballot and append to the ledger, instead of writing a ballot. This is the command's second mode; it takes no `--candidate` |
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
@@ -231,7 +231,9 @@ What the flags mean:
 `render` also takes `--fps <n>` (the rate it samples at, default 12 — the same
 protocol rate the reference frames use) and `--max <px>` (the long side of a
 frame, default 256). A clipping attachment is applied as the runtime applies it —
-spine-core's own `SkeletonClipping`, in spine-webgl's call order — so a slot from
+spine-core's own `SkeletonClipping`, in spine-webgl's call order, on a Spine export,
+and the core's clipper, drawing the same pixels, on a rigc build (the `--poser`
+row) — so a slot from
 the clip's through its `end` slot draws only what falls inside the polygon, in
 `render`, `check` and every other picture rigc's own rasteriser draws (`preview`
 plays in Spine's player, which always clipped); the framing box still counts
@@ -6481,8 +6483,9 @@ Inside `setup` and each frame:
   scale and shear all live in `a b c d`.
 - `attachments` — every slot showing a region or a mesh, in the frame's **draw
   order**: `{ slot, attachment, vertices, color }`. `vertices` are `x, y` per vertex
-  in world units after skinning and deform — the runtime's own
-  `computeWorldVertices` over the **whole** attachment. A region's four are its
+  in world units after skinning and deform, over the **whole** attachment — on a
+  Spine export spine-core's own `computeWorldVertices`, and on a rigc build the
+  core's, the same numbers to the bit (the `--poser` row). A region's four are its
   corners in the order bottom-left, top-left, top-right, bottom-right; a mesh's are
   in the attachment's own order, so vertex `i` is the same vertex in every frame and
   in `rest`. `color` is the slot colour times the attachment colour, straight RGBA
@@ -6501,7 +6504,7 @@ are not numbered like them — so `vertices` are the attachment's own, and the f
 show what the clip left of them. Bounding boxes, points, paths and clipping polygons
 draw nothing and are not listed. Numbers are printed the way every JSON file this
 tool writes prints them — the shortest decimal that reads back as the same double —
-so a vertex in the file *is* the runtime's vertex, not a rounding of it; a pose that
+so a vertex in the file *is* the poser's vertex, not a rounding of it; a pose that
 is not finite is refused rather than written as `null`, naming where — the setup pose,
 `animation "a" frame i at F fps (t=…s)`, or the rest table — and then the bone and
 its world-transform field, or the slot, the attachment and the vertex, with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, round-trips it through spine-core and named assertions, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/atlas.ts

@@ -80,18 +80,20 @@
  *
  * `src/compile.ts` must stay independent of the runtime — that is what keeps the
  * compiler and the gate from checking each other's assumptions — so the importer
- * cannot reach for `TextureAtlas`. The reader below is therefore written straight
- * off `TextureAtlas`'s own field table (`dist/TextureAtlas.js`, the
- * `pageFields` / `regionFields` maps and the loop under them), including the
- * parts that look like mistakes and are not: the page name is trimmed and a
- * region name is the RAW line, a blank line closes a page block, `readEntry`
- * stops at four values, and `originalWidth/Height` fall back to `width/height`
- * only when BOTH are zero.
+ * cannot reach for `TextureAtlas`. The reader below therefore states, for every
+ * field the format has, what the runtime reads it as — the page and region
+ * fields of `dist/TextureAtlas.js` — including the readings that look like
+ * mistakes and are not: the page name is trimmed and a region name is the RAW
+ * line, a blank line closes a page block, an entry holds at most four values,
+ * and `originalWidth/Height` fall back to `width/height` only when BOTH are
+ * zero.
  *
  * A second opinion about a format is a liability, so it is measured rather than
- * asserted: the selftest parses every `.atlas` in the example corpus with both
- * this reader and `spine-core`'s and compares every field of every region. If
- * they ever disagree, that control goes red and this file is wrong.
+ * asserted: `PKR01` parses every `.atlas` in the example corpus with both this
+ * reader and `spine-core`'s `TextureAtlas` and compares every page's name, size
+ * and `pma` and every region's eleven fields — 10 atlas files, 132 regions, 3
+ * of them rotated, 0 fields apart when this was written (issue #1015). If they
+ * ever disagree, that control goes red and this file is wrong.
  */
 import { CompileError } from './errors.ts';
 import { Plate, readPlate } from '../tools/plate.ts';
@@ -272,8 +274,9 @@ function int(text: string | undefined): number {
 /**
  * Read an atlas file's text into pages and regions.
  *
- * A transcription of `TextureAtlas`'s constructor, and deliberately a dull one —
- * every branch below is there because the runtime has it. Two additions, both of
+ * The format as the runtime reads it, field for field, and deliberately a dull
+ * reader — every branch below states a reading `PKR01` holds against
+ * `TextureAtlas`'s parse of the corpus (see the header). Two additions, both of
  * them fields a PLAYER has no use for and an IMPORTER does: `nameLine`, which
  * `rewritePageNames` needs, and the page's `scale:`, which is what turns a
  * region's texels back into the drawing's own size (`AtlasPage.scale`).
@@ -1337,7 +1340,7 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  * a plate's rows run downwards, so the kept rectangle's top row is
  * `originalHeight - offsetY - height`.
  *
- * ## A rotated region is TRANSCRIBED, not guessed at (issue #570)
+ * ## A rotated region is MEASURED, not guessed at (issue #570)
  *
  * This refused a rotated region until 2026-09-17, on the argument that the
  * runtime holds "three opinions" about the mapping. Measurement refutes the
@@ -1348,7 +1351,13 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  *     `dist/attachments/MeshAttachment.js:126-162`) is the one routine that
  *     states where a region's texels are for **all four** `degrees`, and it is
  *     the routine `substituteTexture` in [`src/render.ts`](render.ts) already
- *     goes through. The loop below is its inverse, term for term;
+ *     goes through. The loop below inverts what it samples: `PKR02` asks it,
+ *     for every texel of every region of the corpus atlases, which page texel
+ *     the runtime samples and compares the lift — 132 regions, 2,848,402
+ *     texels, 0 apart, three of them turned (90 twice, 270 once) and each of
+ *     those lifting differently with the turn ignored; `PK29` lifts the
+ *     packer's fixture at each of 0, 90, 180 and 270 back to its PNG byte for
+ *     byte;
  *   * `TextureAtlas`'s `u2`/`v2` (`dist/TextureAtlas.js:164-171`) transpose the
  *     rectangle at 90 and not at 270, so at 270 they describe a rectangle the
  *     page does not have — but `MeshAttachment.computeUVs` never reads them for
@@ -1358,8 +1367,9 @@ export function packAtlas(inputs: PackInput[], opts: PackOptions = {}): PackResu
  *     region-attachment rendering defect (issue #199) and not a statement about
  *     where the drawing sits.
  *
- * Inverting the runtime's own expression on texel centres puts kept-rectangle
- * pixel `(x, y)` — `x` from the drawing's left, `y` down from `top` — at page
+ * On texel centres — at 90 and 270 measured against the runtime's sampling
+ * (`PKR02`), at 180 against the packer fixture's turn (`PK29`) — the mapping
+ * puts kept-rectangle pixel `(x, y)` — `x` from the drawing's left, `y` down from `top` — at page
  * pixel `(X + x, Y + y)` unturned, `(X + y, Y + width - 1 - x)` at 90,
  * `(X + width - 1 - x, Y + height - 1 - y)` at 180 and
  * `(X + height - 1 - y, Y + x)` at 270, writing `X`/`Y` for the region's own

package/src/check.ts

@@ -69,7 +69,7 @@ import {
   BACKGROUND,
   frameGeometry,
   PROTOCOL_FPS,
-  posableFromText,
+  loadCandidate,
   renderFrame,
   sampleAnimation,
   sampleSetupPose,
@@ -83,11 +83,8 @@ import {
   nonFinitePoseOf,
   unframeableSentence,
   UnframeablePoseError,
-  skinRosterOf,
-  candidatePosers,
-  spinePoser,
+  refuseUnchosen,
   throughPoser,
-  PoserChoiceError,
   SHEET_COLUMNS,
   SHEET_FILE,
   SHEET_GAP,
@@ -95,9 +92,10 @@ import {
   type Frame,
   type FramesSidecar,
   type FrameSet,
+  type MakeCorePoser,
+  type Posable,
   type PoseOptions,
   type Poser,
-  type PoserChoice,
   type PoserName,
   type TextureSubstitution,
   type Viewport,
@@ -1062,22 +1060,11 @@ export interface CheckOptions {
    * What builds the core poser — `candidatePosers`' own `make`. The suite's
    * `CH01` passes a planted copy, and nothing else passes any.
    */
-  makeCorePoser?: Parameters<typeof candidatePosers>[4];
+  makeCorePoser?: MakeCorePoser;
 }
 
-/**
- * Both posers for the candidate `check` is handed, and which one it asked for:
- * `candidatePosers` over the candidate's files when the caller named them, and
- * spine-core alone when it handed texts only — there is then no directory to
- * find a model document in, and the reason says so.
- */
-function checkPoserChoice(data: Parameters<typeof spinePoser>[0], options: CheckOptions): PoserChoice {
-  const paths = options.candidatePaths;
-  if (paths !== undefined) return candidatePosers(data, paths.skeleton, paths.atlas, options.poser, options.makeCorePoser);
-  const why = 'the candidate was handed to check as text, with no path to find a skeleton.model.json beside';
-  if (options.poser === 'core') throw new PoserChoiceError(`--poser core: ${why}`);
-  return { forced: options.poser, core: null, why: options.poser === 'spine' ? '--poser spine' : why, spine: spinePoser(data) };
-}
+/** Why a candidate handed to `check` as text alone is posed through spine-core — there is no directory to find a model document in. */
+const UNPLACED_CANDIDATE = 'the candidate was handed to check as text, with no path to find a skeleton.model.json beside';
 
 // ---------------------------------------------------------------------------
 
@@ -1145,14 +1132,27 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   }
   const notes: string[] = [];
 
-  const posable = posableFromText(options.skeletonText, options.atlasText, options.atlasDir);
+  // Which implementation poses the candidate (issue #968), chosen once for the
+  // whole run — every set, the setup pose and the non-finite sentence — so no
+  // two figures in one report can come from two posers: `candidatePaths` over
+  // the candidate's files, as `render` chooses, and spine-core alone when it
+  // was handed texts only. Chosen BEFORE anything is read off the candidate
+  // (issue #1014), so a rigc build the core poses reads its names, its stage,
+  // its bone tree and its pages without loading spine-core.
+  const { choice, facts, pages } = loadCandidate(
+    { skeletonText: options.skeletonText, atlasText: options.atlasText, atlasDir: options.atlasDir, label: options.labels?.skeleton ?? 'the candidate' },
+    options.candidatePaths ?? null,
+    options.poser,
+    { ...(options.makeCorePoser === undefined ? {} : { make: options.makeCorePoser }), unplaced: UNPLACED_CANDIDATE },
+  );
+  const posable: Pick<Posable, 'pages'> = { pages };
   // A candidate that declares no stage is framed exactly as one that does,
   // because no framing here reads a stage: the world box is fitted from what the
   // candidate draws. Said on the one candidate where a reader can ask what box
   // stood in for the absent one (issue #714) — `SkeletonJson` copies the header
   // fields across unconditionally (`SkeletonJson.js:70-73`), so an omitted
-  // extent is `undefined` here, not 0.
-  if (typeof posable.data.width !== 'number' || typeof posable.data.height !== 'number') {
+  // extent is `undefined` there, not 0, and the header says the same.
+  if (!facts.declaresStage) {
     notes.push(
       'the candidate declares no stage (no `skeleton.width`/`height`), and nothing stands in for one: its world ' +
         'box is fitted from the pixels it draws, as it is for every candidate, so the absence moves no figure below.',
@@ -1167,18 +1167,16 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   // The skin is refused here rather than deeper in the sampler, for the reason
   // every miss in this project is refused where the names are: the skeleton is
   // open on this line and the alternatives can be listed.
-  if (options.skin !== undefined && !posable.data.skins.some((s) => s.name === options.skin)) {
+  if (options.skin !== undefined && !facts.skins.includes(options.skin)) {
     throw new CheckError(
       `the candidate declares no skin ${JSON.stringify(options.skin)}; it declares [${
-        posable.data.skins.map((s) => s.name).join(', ') || 'none'
+        facts.skins.join(', ') || 'none'
       }]`,
     );
   }
-  // Which implementation poses the candidate (issue #968), chosen once for the
-  // whole run — every set, the setup pose and the non-finite sentence — so no
-  // two figures in one report can come from two posers. `--poser core` on an
-  // input that cannot carry it is refused here, before anything is posed.
-  const choice = checkPoserChoice(posable.data, options);
+  // `--poser core` on an input that cannot carry it is refused here, before
+  // anything is posed.
+  refuseUnchosen(choice);
   const poseOptions: PoseOptions | undefined =
     substitution || options.skin !== undefined
       ? { ...(substitution ? { texture: true } : {}), ...(options.skin === undefined ? {} : { skin: options.skin }) }
@@ -1220,7 +1218,7 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
     sets = [
       {
         dir,
-        animation: posable.data.animations.length === 0 ? null : animation,
+        animation: facts.animations.length === 0 ? null : animation,
         fps,
         sampled: disk[disk.length - 1].index + 1,
         written: disk.length,
@@ -1292,8 +1290,8 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   // poser runs — the model document lists the spec's order, and a refusal that
   // listed the names in another order would be a byte of the report that
   // depends on the poser.
-  const have = posable.data.animations.map((a) => a.name);
-  const posing = throughPoser(choice, (poser) => {
+  const have = [...facts.animations];
+  const posing = throughPoser(choice, (poser, roster) => {
     const sampled = sets.map((set) => prepareSet(located.root, set, poser, have, options.as, poseOptions));
     // 🔒 A pose that is not finite is refused before anything measures it (issue
     // #873), in the words `render` and the geometry export use for it. Measured
@@ -1325,7 +1323,7 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
       posedSets.map((p) => p.frames),
       poser.slots,
       options.skin,
-      skinRosterOf(posable.data),
+      roster,
     );
     if (unframeable !== null) throw new UnframeablePoseError(unframeable);
     return sampled;
@@ -1433,7 +1431,7 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
     throw new CheckError(
       `no reference frame could be compared, so there is nothing to frame against${nothingToFrameWhy(
         prepared,
-        posable.data.animations.map((a) => a.name),
+        [...facts.animations],
         options.as,
         located.sidecar !== null,
       )}`,
@@ -1574,8 +1572,8 @@ export function checkAgainstFrames(options: CheckOptions): CheckReport {
   // `src/chains.ts`. Reading the CANDIDATE's tree is what keeps this on the right
   // side of the honesty rule: the reference is still nothing but pixels.
   const chains = chainsOf(
-    posable.data.bones.map((bone) => ({ name: bone.name, parent: bone.parent === null ? null : bone.parent.name })),
-    posable.data.slots.map((slot) => ({ name: slot.name, bone: slot.boneData.name })),
+    facts.bones.map(({ name, parent }) => ({ name, parent })),
+    facts.slots.map(({ name, bone }) => ({ name, bone })),
   );
   const chainOfSlot = new Map<string, number>();
   chains.forEach((chain, index) => {
@@ -2629,7 +2627,7 @@ function nothingToFrameWhy(
 function checkOneSet(
   root: string,
   prepared: PreparedSet,
-  posable: ReturnType<typeof posableFromText>,
+  posable: Pick<Posable, 'pages'>,
   framing: SetFraming,
   background: RGBA,
   chains: BoneChain[],
@@ -3310,7 +3308,7 @@ function labelBox(index: number): { width: number; height: number } {
 function checkAgainstSheet(
   root: string,
   prepared: PreparedSet,
-  posable: ReturnType<typeof posableFromText>,
+  posable: Pick<Posable, 'pages'>,
   viewport: Viewport,
   background: RGBA,
 ): { sheet: SheetCheck | null; notes: string[] } {