spine-rigc 1.7.0 → 1.9.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,
@@ -156,6 +157,7 @@ import {
   POSER_NAMES,
   PoserChoiceError,
   refuseUnchosen,
+  CandidateAtlasError,
   SpineRuntimeError,
   throughPoser,
   type Frame,
@@ -863,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, result.atlasText) }, 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);
 }
 
@@ -1226,7 +1237,7 @@ 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/2`, issue #922;
+  // rigc's own record of the compiled rig (`rigc-compiled/3`, 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).
@@ -1463,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),
@@ -1576,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 or /3 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;
@@ -1720,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');
@@ -1745,13 +1797,14 @@ function cmdRender(flags: Record<string, string>): void {
 
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
-  console.log(`  ..    atlas    ${atlasPath}`);
+  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.
+  // 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: readFileSync(atlasPath, 'utf8'), atlasDir, label: skeletonPath },
+    { skeletonText: readFileSync(skeletonPath, 'utf8'), atlasText, atlasDir, label: skeletonPath },
     { skeleton: skeletonPath, atlas: atlasPath },
     posersAsked(flags),
   );
@@ -2747,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:
@@ -2820,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
@@ -3075,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)');
@@ -3591,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 ' +
@@ -3806,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',
@@ -4316,6 +4376,13 @@ try {
   // 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);

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/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** |
+| `--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/3`: the stage the header declares, or `null`; the bones, slots, skins, constraints, events and animations the Spine files were emitted from, in the spec's order, and `editorOrder`, the order `skeleton.json` lists the skins, each skin's slot keys and the animations in; the rest of what posing them takes; then `pages`, every page of the `skeleton.atlas` written beside it, its `pma` and its `scale:` line (`null` where it states none), 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/2` document (rigc 1.7) states no stage, editor order, `pma` or `scale`, and is still read: `render` and `check` then read those off `skeleton.json` and the atlas, and the `poser` line names both files. A `rigc-compiled/1` document (rigc 1.6) has no `pages` either 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` or `/3` 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/3` or `/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` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `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. 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`) |
+| `--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; so do the order its animations and skins are listed in, its stage and its pages' `scale:` lines, on a `rigc-compiled/3` document (`editorOrder`, `stage`, `pages`) — a `/2` or `/1` document states none of those, so they come off its own `skeleton.json` and atlas, and the `poser` line then says `a rigc-compiled/2 document, which does not state the order its skins and animations are listed in or its stage, read from` and names both files; 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 |
@@ -933,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.
@@ -5753,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:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "1.7.0",
+  "version": "1.9.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`);
+    }
+  }
+}

package/src/assertions/bodies/a04.ts

@@ -0,0 +1,40 @@
+/**
+ * A04, the body (issue #1025, step 4c of #380): every mesh has triangles, in
+ * threes, each an index into its own vertices (case 6f).
+ *
+ * Moved out of `src/validate.ts` clause by clause. The three clauses about
+ * the triangles are about the rig — a document's mesh states its triangles
+ * and its vertices, so the same wrongness has a place to live there (where
+ * the reader refuses two of the three by the record's name) — and moved. The
+ * two about the vertex run — a weighted run whose length is not a multiple of
+ * three, an unweighted array of another length than the `uvs` — are about
+ * the encoding: the document states the weighted form outright, and the flat
+ * run is written by the emitter. They stay with the round trip, which hands
+ * their findings in as each mesh's `encoding`, printed where the body always
+ * printed them.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+
+export function a04MeshTrianglesAndEncoding({ fail, skip }: Verdicts, { meshes }: MeshFacts): void {
+  if (meshes.length === 0) return skip('A04_MESH_TRIANGLES_AND_ENCODING', SKIP_NO_MESH_ATTACHMENT);
+  for (const mesh of meshes) {
+    if (!mesh.triangles || mesh.triangles.length === 0) {
+      fail('A04_MESH_TRIANGLES_AND_ENCODING', `mesh "${mesh.name}" has no triangles`);
+      continue;
+    }
+    if (mesh.triangles.length % 3 !== 0) {
+      fail('A04_MESH_TRIANGLES_AND_ENCODING', `mesh "${mesh.name}" triangle count is not a multiple of 3`);
+    }
+    const vertexCount = mesh.worldVerticesLength / 2;
+    for (const idx of mesh.triangles) {
+      if (idx < 0 || idx >= vertexCount) {
+        fail('A04_MESH_TRIANGLES_AND_ENCODING', `mesh "${mesh.name}" index ${idx} is outside 0..${vertexCount - 1}`);
+        break;
+      }
+    }
+    // The encoding's own clauses, kept with the round trip (the header).
+    for (const detail of mesh.encoding) fail('A04_MESH_TRIANGLES_AND_ENCODING', detail);
+  }
+}

package/src/assertions/bodies/a06.ts

@@ -0,0 +1,195 @@
+/**
+ * A06, the body (issue #1025, step 4c of #380): every page the atlas names is
+ * the size its PNG is, every region lies inside its page, and — under
+ * `spine-html` — no page claims premultiplied alpha, no two regions on one page
+ * overlap and no region is turned.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the pages and
+ * regions are a fact (`../facts/atlas_regions.ts`), the directory is the
+ * caller's, and the profile's policy switch is passed in. The `check` call —
+ * and the argument for the SKIP guards it shares with A17 and A19 (#568, #608)
+ * — stays in `validate()`.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasRegionEntry, AtlasRegionFacts } from '../facts/atlas_regions.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+import { pageFootprint, pageGridSentence } from '../../atlas.ts';
+import { readPngHeader } from '../../png.ts';
+
+export function a06AtlasPageSizeMatchesPng({ fail, skip }: Verdicts, { atlas }: AtlasRegionFacts, input: { atlasDir: string }, policy: boolean): void {
+  if (!atlas) return skip('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', SKIP_NO_ATLAS);
+  if (atlas.pages.length === 0) return skip('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', SKIP_NO_ATLAS_PAGE);
+  for (const page of atlas.pages) {
+    const abs = resolve(input.atlasDir, page.name);
+    if (!existsSync(abs)) continue; // A17 owns this
+    // 🔒 **A page that is not a PNG is a named failure, not a throw** (issue
+    // #732). The reader's throw used to reach this rule's catch and print as
+    // `threw: not a PNG (bad signature)`: the verdict right, the sentence a
+    // stack message that named neither what the file was nor what rigc reads.
+    // `pngProblem` ([`src/png.ts`](png.ts)) is the one sentence every reader
+    // of a page states; this rule prefixes the size the atlas declares, the
+    // value the file would have had to carry.
+    //
+    // ⚠️ No size is read off a file rigc cannot decode, deliberately. A WebP
+    // header carries its dimensions in a fixed field, and reading them would
+    // print a number no oracle in this tree has checked (rigc links no WebP
+    // reader to compare a parse against), about a page that is refused here
+    // either way — and measured, the variant that PASSED a WebP page whose
+    // size agreed built green under the default profile and wrote a
+    // directory that `render` then refused.
+    const header = readPngHeader(abs);
+    if (header.problem !== null) {
+      fail(
+        'A06_ATLAS_PAGE_SIZE_MATCHES_PNG',
+        `page "${page.name}" declares ${page.width}x${page.height} and its file cannot be read as PNG, so the ` +
+          `size was not measured: ${header.problem}`,
+      );
+    }
+    const info = header.info;
+    const onPage = atlas.regions.filter((region) => region.page.name === page.name);
+    const gridSaid = info === null ? null : pageGridSentence(page, info, onPage);
+    if (gridSaid !== null) {
+      // 🔒 **Still validity, and now for a measured reason rather than an
+      // inherited one** (issue #715). The card that opened this expected the
+      // clause to move behind the profile switch once the runtime's mapping
+      // was measured — it is declared-size-relative, so a rescaled page
+      // draws. What settles it the other way is that the sentence below can
+      // name a repair the FORMAT already provides (`scale:`), and that two of
+      // the three readers a wrong grid breaks are rigc's own and run under
+      // both profiles. The sentence, and the one derivation of the ratio under
+      // it, is `pageGridSentence` in [`src/atlas.ts`](atlas.ts): the compiler's
+      // region lift states the same one when it is asked for texels on such a
+      // page (issue #750), so the two cannot come to describe one page two ways.
+      fail('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', gridSaid);
+    }
+    // 📐 PROFILE, from here down. `pma: false` and no rotation are rigc's atlas
+    // CONVENTION, not the atlas format's rules — a packed page with
+    // `rotate: 90` is what the Spine packer produces and every official example
+    // ships one. Under `spine` an atlas is judged only on whether its declared
+    // size matches the file it names.
+    if (policy && page.pma) {
+      fail('A06_ATLAS_PAGE_SIZE_MATCHES_PNG', `page "${page.name}" claims premultiplied alpha; parts are straight alpha`);
+    }
+  }
+  // 🔒 **A region's rectangle lies inside the page it names, and that is
+  // VALIDITY** (issue #694). The clause is not new — it has read the same four
+  // numbers since issue #266 — but it stood inside the policy half below, and
+  // behind a guard that skipped any page carrying one region that covered it.
+  // Both fences were wrong for it. A rectangle that leaves its page is not a
+  // convention somebody else may hold differently: `u2 > 1` samples whatever
+  // the wrap mode returns, which is never the drawing the pack was made of, so
+  // the part draws garbage or nothing at all. Measured on a pack shaped like
+  // the two production atlases that found this — a page declaring 2048x256
+  // with regions at `2274,0 980x200` and `0,252 100x258` — every atlas
+  // assertion passed under the default profile and the first of the two parts
+  // drew 0 of the 10,517 pixels it draws when the same rig is built loose.
+  //
+  // ⭐ The tool's other half already said so, which is what settles where the
+  // clause belongs. `resolveFromAtlas` ([`src/compile.ts`](compile.ts)) refuses
+  // exactly this rectangle as a `CompileError` under every profile when a pack
+  // arrives through `--atlas-in`, so while it was policy here the compiler and
+  // the gate disagreed about the same four numbers — and the gate is the only
+  // half that a skeleton and a pack somebody else made ever reach.
+  //
+  // ⚠️ It is stated over `atlas.regions` rather than per page group, because
+  // the question is about one region and its own page and needs no neighbour:
+  // a page carrying a single full-page region is measured too, and answers
+  // trivially. The rectangle is `pageFootprint`'s and nobody else's here
+  // (issue #579): what `TextureAtlas` transposes at 90 and not at 270 is
+  // `u2`/`v2`, a UV pair `MeshAttachment.computeUVs` never reads for an atlas
+  // region, and the page rectangle is a different quantity — transposed at
+  // BOTH quarter turns. A region that fits only *because* it is turned is
+  // inside its page, and this clause says so.
+  for (const region of atlas.regions) {
+    const foot = pageFootprint(region);
+    if (
+      region.x < 0 ||
+      region.y < 0 ||
+      region.x + foot.width > region.page.width ||
+      region.y + foot.height > region.page.height
+    ) {
+      fail(
+        'A06_ATLAS_PAGE_SIZE_MATCHES_PNG',
+        `region "${region.name}" occupies ${region.x},${region.y} ${foot.width}x${foot.height} of page ` +
+          `"${region.page.name}", which is ${region.page.width}x${region.page.height} — a region that runs off ` +
+          'its page samples texels that are not there',
+      );
+    }
+  }
+  if (!policy) return;
+  // ⭐ **One part per page OR a tiling page** (issue #266, follow-up 2). This
+  // clause used to be the first alternative alone — every region's UVs
+  // `(0,0)-(1,1)` — which is rigc's *unpacked* convention and exactly what
+  // `build --pack` stops being true, so `--pack --profile spine-html` had to be
+  // a named CLI refusal. A pack is not a defect, and refusing it under this
+  // profile meant the one shape that exercises the renderer's shared-page
+  // sampling could never be gated by the renderer's own rulebook.
+  //
+  // What the first alternative bought was the attachment -> region -> file
+  // chain being checkable exactly, and `A27` already owns that half and already
+  // stands down on a multi-region page. What is left to check on a *tiling*
+  // page is what makes shared-page sampling well defined at all: no two regions
+  // on one page overlapping. A foreign pack can fail that while loading clean,
+  // and two overlapping rectangles put one drawing inside another's.
+  //
+  // ⚠️ Its sibling — every region inside the page it names — moved above and
+  // out of this profile in issue #694, and the two are not symmetrical. That
+  // one is broken for every consumer; this one is a statement about what a
+  // pack MEANS, and the corpus is the evidence rather than the taste:
+  // measured over the ten atlases in `examples/`, 0 of 132 regions are off
+  // their page and 49 pairs on four of those pages overlap, editor-exported
+  // and correct. A rule that called those files broken would be one
+  // consumer's convention refusing everybody else's data, which is the thing
+  // the profile split exists to prevent.
+  //
+  // ⚠️ Rotation stays refused either way, and that is not the same clause: it
+  // is about rigc's own packer never turning a region, which is a statement
+  // about what rigc WRITES. It stopped being a statement about what rigc can
+  // read in issue #570 — `extractRegion` now lifts a rotated region back off
+  // its page, measured against `MeshAttachment.computeUVs` (`PKR02`) — and the two
+  // must not be re-merged: an artifact under the renderer's own rulebook that
+  // rigc did not pack is still a foreign artifact, whatever rigc can measure.
+  const regionsPerPage = new Map<string, AtlasRegionEntry[]>();
+  for (const region of atlas.regions) {
+    const on = regionsPerPage.get(region.page.name);
+    if (on) on.push(region);
+    else regionsPerPage.set(region.page.name, [region]);
+  }
+  for (const [pageName, on] of regionsPerPage) {
+    // The `onePartPerPage` guard that stood here went with the clause it was
+    // written for: with only the pair check left, a page carrying one region
+    // has no pair and the loop below does nothing on it anyway. Nothing reads
+    // `u`/`v`/`u2`/`v2` in this assertion any more, which is the point of
+    // #579 kept rather than restated.
+    const rects = on.map((region) => {
+      const foot = pageFootprint(region);
+      return { name: region.name, x: region.x, y: region.y, width: foot.width, height: foot.height };
+    });
+    for (let i = 0; i < rects.length; i++) {
+      for (let j = i + 1; j < rects.length; j++) {
+        const a = rects[i];
+        const b = rects[j];
+        if (a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height) {
+          fail(
+            'A06_ATLAS_PAGE_SIZE_MATCHES_PNG',
+            `regions "${a.name}" (${a.x},${a.y} ${a.width}x${a.height}) and "${b.name}" (${b.x},${b.y} ` +
+              `${b.width}x${b.height}) overlap on page "${pageName}"; a page is one part covering it exactly or ` +
+              'a tiling of regions that do not, and two rectangles over the same texels put one drawing inside ' +
+              "the other's",
+          );
+        }
+      }
+    }
+  }
+  for (const region of atlas.regions) {
+    if (region.degrees !== 0) {
+      fail(
+        'A06_ATLAS_PAGE_SIZE_MATCHES_PNG',
+        `region "${region.name}" is rotated; rigc's own packer never turns a region (see PACK_NO_ROTATE in ` +
+          'src/atlas.ts), so this atlas came from somewhere else',
+      );
+    }
+  }
+}