spine-rigc 1.6.2 → 1.8.0

package/cli.ts

@@ -82,7 +82,8 @@ import { writeCheckPictures } from './src/checkpics.ts';
 import { compile, CompileError, droppedStateReason, relativeImagesPath, type CompileOptions } from './src/compile.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from './src/model.ts';
 import { deformReportBlock } from './src/deformreport.ts';
-import { surveyOfBuild } from './src/deformmeasure.ts';
+import { surveyOfBuild, type DeformSurvey } from './src/deformmeasure.ts';
+import { CoreInputError } from './src/core/index.ts';
 import {
   diffLines,
   diffSkeletons,
@@ -93,7 +94,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 +142,9 @@ import {
   GEOMETRY_FILE,
   GeometryError,
   UnframeablePoseError,
-  skinRosterOf,
   geometryFileOf,
   geometryText,
-  loadPosable,
+  loadCandidate,
   PROTOCOL_FPS,
   renderFrame,
   sampleAll,
@@ -154,17 +154,17 @@ import {
   SHEET_TILE,
   sidecarViewport,
   SlotSubsetError,
-  slotSubsetOf,
-  candidatePosers,
   POSER_NAMES,
   PoserChoiceError,
+  refuseUnchosen,
+  CandidateAtlasError,
+  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 +456,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 +472,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,
   });
@@ -860,11 +865,20 @@ function memberReportLines(result: CompileResult): string[] {
  * an author who came here asking whether their deform broke the coverage
  * deserves the answer rather than a silence. What does move is the stretch.
  */
-function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>): 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');
+function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>, poser: PoserName | undefined, label: string): string[] {
+  // Read and posed through rigc's own core over the model document the build carries (issues #969, #1019) —
+  // spine-core is not touched — and through spine-core under `--poser spine` or when the core refuses the
+  // document, which the block then names; `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 reader's survey.
+  const input = { skeletonText: result.skeletonText, atlasText: result.atlasText, modelText: modelDocument(result.model, result.skeletonText, result.atlasText), label: `the deform survey of ${label}` };
+  let survey: DeformSurvey;
+  try {
+    survey = surveyOfBuild(input, new Set(), poser === undefined ? 'auto' : poser === 'core' ? 'model' : 'spine-core');
+  } catch (err) {
+    // `--poser core` on a build the core refuses: a refusal of the invocation, as `render` and `check` give it.
+    if (poser === 'core' && err instanceof CoreInputError) throw new ExplainError(`--poser core: the core refused to pose the deform survey's model document — ${err.message}`);
+    throw err;
+  }
   return deformReportBlock(survey, result.deformTransforms, exempt);
 }
 
@@ -1113,10 +1127,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 +1160,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 +1222,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 +1237,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')}`);
@@ -1445,16 +1474,16 @@ function runCheck(
   flags: Record<string, string>,
   plates?: CheckPlates,
 ): CheckReport {
-  const { skeletonPath, atlasPath } = resolveArtifacts(candidate, atlasFlag);
+  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(candidate, atlasFlag);
   // The poser is `render`'s choice, over the same two files (issue #968): the
   // paths are what `candidatePosers` looks beside for `skeleton.model.json`.
   const poser = readPoserFlag(flags);
   return checkAgainstFrames({
     skeletonText: readFileSync(skeletonPath, 'utf8'),
-    atlasText: readFileSync(atlasPath, 'utf8'),
+    atlasText,
     atlasDir: dirname(atlasPath),
     framesDir,
-    labels: { skeleton: skeletonPath, atlas: atlasPath },
+    labels: { skeleton: skeletonPath, atlas: atlasText === null ? `${atlasPath} — not there (${ATLAS_ABSENT})` : atlasPath },
     candidatePaths: { skeleton: skeletonPath, atlas: atlasPath },
     ...(poser === undefined ? {} : { poser }),
     ...readCheckFlags(flags),
@@ -1558,6 +1587,43 @@ function resolveViewable(flags: Record<string, string>): {
   return { skeletonPath, atlasPath, atlasDir: dirname(atlasPath) };
 }
 
+/** What `render` and `check` say where a rigc build's atlas is not there (issue #1020). */
+const ATLAS_ABSENT = 'a build the core poses from a rigc-compiled/2 document needs none';
+
+/**
+ * The candidate `render` and `check` draw, with its atlas text — or `null`
+ * where the atlas file is not there and need not be (issue #1020).
+ *
+ * ⭐ A rigc build is drawn by the core from its `skeleton.model.json`, and a
+ * `rigc-compiled/2` document states where each region sits on its page, so
+ * the build's `skeleton.atlas` is not needed to draw it. Its absence is let
+ * through here only where it can be that case — no `--atlas` named, a model
+ * document beside the skeleton, and no atlas beside it at all — and the poser
+ * choice decides the rest: anything that is read through an atlas after all
+ * (a `rigc-compiled/1` document, a build the core refuses) is refused there
+ * naming the file and why (`CandidateAtlasError`). An atlas that IS there is
+ * read, as it always was: the core holds it to the document's `pages` and
+ * draws through spine-core, saying why, when it is not the one the build
+ * wrote (#1016), and `check` reads its `scale:` lines for the texture note.
+ * Everywhere else this is `resolveViewable`'s refusal, word for word.
+ */
+function resolveDrawable(target: string, atlasFlag: string | undefined): { skeletonPath: string; atlasPath: string; atlasText: string | null } {
+  const abs = resolve(target);
+  if (atlasFlag === undefined && existsSync(abs)) {
+    const directory = statSync(abs).isDirectory();
+    const skeletonPath = directory ? join(abs, 'skeleton.json') : abs;
+    const dir = dirname(skeletonPath);
+    const atlasPath = join(dir, 'skeleton.atlas');
+    const noAtlas = directory ? !existsSync(atlasPath) : abs.endsWith('.json') && !readdirSync(dir).some((f) => f.endsWith('.atlas'));
+    if (noAtlas && existsSync(join(dir, MODEL_DOCUMENT_FILE))) {
+      if (!existsSync(skeletonPath)) throw new UsageError(`nothing at ${skeletonPath}`);
+      return { skeletonPath, atlasPath, atlasText: null };
+    }
+  }
+  const { skeletonPath, atlasPath } = resolveViewable({ candidate: target, ...(atlasFlag === undefined ? {} : { atlas: atlasFlag }) });
+  return { skeletonPath, atlasPath, atlasText: readFileSync(atlasPath, 'utf8') };
+}
+
 /** `--animation`, checked against what the skeleton actually carries. */
 function readAnimationFlag(flags: Record<string, string>, available: string[]): string | undefined {
   const name = flags.animation;
@@ -1603,13 +1669,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 +1683,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 +1698,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 +1720,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`.
  */
@@ -1699,7 +1768,11 @@ const STAGELESS_FRAMING = {
  * two rates — land on one pixel grid and stay comparable.
  */
 function cmdRender(flags: Record<string, string>): void {
-  const { skeletonPath, atlasPath, atlasDir } = resolveViewable(flags);
+  if (flags.candidate === undefined) {
+    throw new UsageError('needs --candidate <dir | skeleton.json> — the directory `build --out` wrote');
+  }
+  const { skeletonPath, atlasPath, atlasText } = resolveDrawable(flags.candidate, flags.atlas);
+  const atlasDir = dirname(atlasPath);
   const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   const outRoot = resolve(flags.out ?? 'render');
@@ -1724,11 +1797,20 @@ 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);
+  console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
+  // 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, and with a
+  // rigc-compiled/2 document without its atlas either (issue #1020).
+  const { choice, facts, pages } = loadCandidate(
+    { skeletonText: readFileSync(skeletonPath, 'utf8'), atlasText, 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 +1824,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 +1868,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 +1877,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 +1903,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,
@@ -2716,9 +2800,12 @@ function cmdBoneDist(flags: Record<string, string>): void {
 /**
  * Refuse a compiled pair whose art `explain` cannot pose through, by name.
  *
- * 🚨 `explain` poses the rig — `deformReportLines` loads the emitted pair through
- * `spine-core` to measure what each deform key did — and a pose resolves EVERY
- * attachment against the atlas, whether or not anything deforms it. On the specs
+ * 🚨 `explain` poses the rig — `deformReportLines` measures what each deform key
+ * did — and spine-core's reading of the pair resolves EVERY attachment against
+ * the atlas, whether or not anything deforms it. (Since issue #1019 a build's
+ * survey is read off its model document and posed by the core, which resolves
+ * nothing against the atlas; spine-core reads it under `--poser spine` and on a
+ * fallback, and this refusal is unchanged and comes before either.) On the specs
  * `ingest --art none` writes there is nothing to resolve against: the entries
  * state a size and name no `image`, so the compile atlases nothing, and the load
  * threw the runtime's own `Region not found in atlas: rear-upper-arm (attachment:
@@ -2789,6 +2876,8 @@ function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
 }
 
 function cmdExplain(flags: Record<string, string>): void {
+  // `--poser` is refused by its spelling before anything compiles (issue #1019): it chooses the deform survey's reader and poser.
+  const poser = readPoserFlag(flags);
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
   // See the identical pair of lines in `cmdBuild` for why both paths are named
@@ -3044,7 +3133,7 @@ function cmdExplain(flags: Record<string, string>): void {
   // The `DEFORM` block goes after the timelines and before the constraints,
   // because it is a measurement OF the deform timelines printed above — the keys
   // it names are the keys the reader has just read, by the same index.
-  for (const line of deformReportLines(result, new Set(result.rig.deformMayFold))) console.log(line);
+  for (const line of deformReportLines(result, new Set(result.rig.deformMayFold), poser, label)) console.log(line);
 
   if (result.physics.length) {
     console.log('\nphysics constraints (4.3 top-level `constraints` array, type per entry)');
@@ -3560,7 +3649,9 @@ const FLAG_MEANINGS: Record<string, string> = {
     "`render` and `check`: which implementation poses the frames (on `check`, the candidate's) — `core` (rigc's own, reading the skeleton.model.json a " +
     'build writes beside the pair) or `spine` (spine-core). Default: `core` when that document and the atlas sit ' +
     "beside the skeleton and the skeleton is the one the document records (spine.sha256), `spine` otherwise and wherever the core refuses the input by name; the `poser` " +
-    'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name',
+    'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name. ' +
+    "`explain`: which reads and poses the DEFORM block's survey — `core` (the model document the compile writes, spine-core untouched) or " +
+    '`spine` (the Spine skeleton parsed and posed by spine-core); default `core`, and `spine` where the core refuses the document, which the block names',
   'texture-from':
     "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
     'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
@@ -3775,11 +3866,11 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'explain',
     usage: [
-      'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>]   (it never gates, and writes nothing)',
+      'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--poser core|spine]   (it never gates, and writes nothing)',
       'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
       'rigc explain --cut <name> --cuts <cuts.json>',
     ],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts'],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts', 'poser'],
     notes: [
       'this line said "the same arguments as build, minus --profile" and was false in both',
       'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
@@ -4281,6 +4372,21 @@ 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.
+  // A candidate with no atlas beside it that has to be read through one (issue
+  // #1020): a refusal of the invocation like a missing atlas on an export, exit
+  // 2 and nothing written, and the message names the file and why it is needed.
+  if (err instanceof CandidateAtlasError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(2);
+  }
+  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, the `poser` line says so, and with no atlas there `render` and `check` refuse it naming the file. A `rigc-compiled/2` build is rendered and checked with its `skeleton.atlas` gone (`--candidate` below). 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** |
@@ -207,10 +207,10 @@ What the flags mean:
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 34 validity rules (**the default**) · `spine-html` = all 49, opt-in |
-| `--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 |
+| `--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. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. With the atlas gone, `check`'s texture note says whether it declares a `scale:` line is not read (the document does not state one), and `check.json`'s `textureFrom.candidateScales` is `null` (`RC13`). **`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`, `check` and `explain`: `core` or `spine` — on `render` and `check`, 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; its atlas, when one is named or present, the one 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`, `--texture-from` included (and the check `bench --frames` folds in; `bench`'s own `validate`, like `build`'s, is the runtime's round trip by design): its bone tree, slot list and slot roster come off its model document; the order its animations and skins are listed in, and its stage, off its own `skeleton.json`, because the document states neither; where each region sits and the page images it draws off the document's `pages` (a `rigc-compiled/1` document's off the atlas beside it, and the `poser` line then says `a rigc-compiled/1 document, which does not state where each region sits on its page: that is read from` and names the atlas); and a `--texture-from` atlas off rigc's own atlas reader. The runtime is loaded for a Spine export, `--poser spine` and a fallback the `poser` line names; a run that cannot load it there is refused naming the input and why it needs the runtime (exit 1; `RC11`, `RC13`). On `explain` the flag chooses the `DEFORM` block's survey (§4.11.2): `core`, the default, reads the skeleton's structure — its deform timelines and their keys, curves and slots, the skin each is keyed under, the sliders — off the model document the compile writes and poses it through the core, and spine-core is not touched (`RC15`); `spine` parses and poses the Spine skeleton through spine-core. The two are the same survey to the byte on every corpus row (`DM12`). Where the core refuses the document, the survey falls back to spine-core and the block says so on a line of its own (`read and posed through spine-core: …`); `--poser core` there is refused instead (exit 2), and a run that cannot load the runtime where it needs it is refused naming the survey and why (exit 1) |
 | `--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
@@ -931,12 +933,16 @@ bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
 
   ⭐ **It reads what `ingest` writes, given the pack** — `--atlas-in <pack.atlas>`,
   with `build`'s meaning (§0.2). That matters more here than it looks: printing the
-  `DEFORM` block means **posing** the rig, a pose resolves *every* attachment
-  against the atlas whether or not anything deforms it, and a spec written by
-  `ingest --art none` states sizes and names no image. So the size-only pair
-  `build --atlas-in` gates green is readable here through the same flag, and
-  without it the pair is refused by name at exit 2 rather than posed
-  (§5.1). ⚠️ `--profile`,
+  `DEFORM` block means **posing** the rig, spine-core's pose resolves *every*
+  attachment against the atlas whether or not anything deforms it, and a spec
+  written by `ingest --art none` states sizes and names no image. So the
+  size-only pair `build --atlas-in` gates green is readable here through the same
+  flag, and without it the pair is refused by name at exit 2 rather than posed
+  (§5.1). ⚠️ Since issue #1019 the block's survey on a build is read off the
+  model document and posed by rigc's own core, which resolves nothing against the
+  atlas (`--poser` in the flag table); the refusal is unchanged and still comes
+  first, so a size-only pair needs `--atlas-in` here whichever reader the survey
+  takes. ⚠️ `--profile`,
   `--pack`, `--page-size`, `--padding`, `--page-edges` and `--copy-images` are
   `build`'s and are not here: five of them decide what is *written*, and this
   command writes nothing.
@@ -5751,9 +5757,11 @@ or the key's position in its own track. These are the frequent ones, verbatim:
 | `skin "S" slot "X" attachment "P": "name" is V, which is not a string. An attachment's name is the runtime's `Attachment.name` …` | §3.4 — write the name as a string, or leave the key out and the attachment is named by its placeholder. It is written verbatim and `path` defaults to it, so a number there would reach the atlas as a region name nobody spelled |
 
 ⚠️ **One refusal in this section is not a `CompileError`, and it is `explain`'s.**
-`explain` prints the `DEFORM` block by **posing** the rig, and a pose resolves every
-attachment against the atlas — so it needs the art `build` needs, reached the same
-two ways (§0.2). A pair whose art it cannot resolve is refused **before a line of
+`explain` prints the `DEFORM` block by **posing** the rig, and spine-core's pose
+resolves every attachment against the atlas — so it needs the art `build` needs,
+reached the same two ways (§0.2). (Since issue #1019 a build's survey is read and
+posed through rigc's own core by default, which reads no atlas; the refusal below
+is unchanged and comes before either.) A pair whose art it cannot resolve is refused **before a line of
 the report**, at **exit 2**, in rigc's own sentence:
 
 ```
@@ -6481,8 +6489,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 +6510,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.8.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/assertions/bodies/a03.ts

@@ -0,0 +1,27 @@
+/**
+ * A03, the body (issue #1025, step 4c of #380): every region attachment has a
+ * finite, positive width and height (case 6c).
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the region
+ * attachments are a fact (`../facts/skin_entries.ts`) rather than the list
+ * `validate()` filled from spine-core's loaded skins, so the same body runs over
+ * the model document. The `check` call — and so where the verdict sits in the
+ * report — stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinEntryFacts } from '../facts/skin_entries.ts';
+import { SKIP_NO_REGION_ATTACHMENT } from '../reasons.ts';
+
+export function a03RegionWidthHeightFinite({ fail, skip }: Verdicts, { regionAttachments }: SkinEntryFacts): void {
+  // ⟨subject⟩_⟨property⟩: with no region there is no size to find non-finite,
+  // and a loop over nothing used to report that as held (#580).
+  if (regionAttachments.length === 0) return skip('A03_REGION_WIDTH_HEIGHT_FINITE', SKIP_NO_REGION_ATTACHMENT);
+  for (const att of regionAttachments) {
+    if (!Number.isFinite(att.width) || !Number.isFinite(att.height)) {
+      fail('A03_REGION_WIDTH_HEIGHT_FINITE', `region "${att.name}" loaded w=${att.width} h=${att.height}`);
+    }
+    if (att.width <= 0 || att.height <= 0) {
+      fail('A03_REGION_WIDTH_HEIGHT_FINITE', `region "${att.name}" has a non-positive size`);
+    }
+  }
+}