spine-rigc 1.7.0 → 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,
@@ -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);
 }
 
@@ -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 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/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. 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; 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 |
@@ -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.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`);
+    }
+  }
+}

package/src/assertions/bodies/a11.ts

@@ -0,0 +1,15 @@
+/**
+ * A11, the body (issue #1025, step 4c of #380): no clipping attachment — the
+ * renderer skips them silently. A `renderer` rule, so `spine` never runs it.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the count is
+ * a fact (`../facts/skin_entries.ts`).
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SkinEntryFacts } from '../facts/skin_entries.ts';
+
+export function a11NoClippingAttachments({ fail }: Verdicts, { clippingCount }: SkinEntryFacts): void {
+  if (clippingCount > 0) {
+    fail('A11_NO_CLIPPING_ATTACHMENTS', `${clippingCount} clipping attachment(s); the renderer skips them silently`);
+  }
+}

package/src/assertions/bodies/a17.ts

@@ -0,0 +1,26 @@
+/**
+ * A17, the body (issue #1025, step 4c of #380): every page the atlas names is
+ * a file on disk, resolved against the directory the atlas sits in.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the pages are
+ * a fact (`../facts/atlas_pages.ts`), and the directory is the caller's. Why
+ * the guard is a SKIP and never a bare `return` (issues #568, #608) is argued
+ * above the `check` call in `validate()`, which stays there with A06 and A19.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+
+export function a17AtlasPageFilesExist({ fail, skip }: Verdicts, { atlas }: AtlasPageFacts, input: { atlasDir: string }): void {
+  if (!atlas) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS);
+  // The other absence, one ring in (#580): the atlas LOADED and declares no
+  // page, so there is no file to find missing. `!atlas` and "zero pages" print
+  // different reasons because they are different facts about the artifact.
+  if (atlas.pages.length === 0) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS_PAGE);
+  for (const page of atlas.pages) {
+    const abs = resolve(input.atlasDir, page.name);
+    if (!existsSync(abs)) fail('A17_ATLAS_PAGE_FILES_EXIST', `page "${page.name}" is not on disk at ${abs}`);
+  }
+}

package/src/assertions/bodies/a45.ts

@@ -0,0 +1,172 @@
+/**
+ * A45, the body (issue #1025, step 4c of #380): the separable colour timelines
+ * own their channels and pose as written.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads, which is
+ * three facts (`../facts/slot_colour.ts`) where it read the skeleton JSON and
+ * the loaded skeleton: the animations' slot timelines in the file's order, as
+ * the file spells them; whether an animation exists; and a slot's colour posed
+ * at a time on a fresh track, which `validate()` takes from spine-core and the
+ * model side from rigc's core. The `check` call stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { SlotColourFacts } from '../facts/slot_colour.ts';
+import { SKIP_NO_SEPARABLE_COLOR } from '../reasons.ts';
+import { atStoredKey, isObj } from '../values.ts';
+import { SLOT_COLOR_CHANNELS } from '../../timelines.ts';
+
+// ⭐ **Why this is its own rule and not a clause on `A43`.** `rgb` and
+// `alpha` pose no dark colour, so under A43's name a failure would be a
+// verdict saying "two-colour tint" about a file that states one colour —
+// the name would say something other than what it decides (the rule #712
+// applied to A43 itself, against a clause on A10). And the SKIP is the
+// sharper half: a rig with a `dark` and no separable timeline has A43's
+// subject present, so a clause there could only PASS on it, which is a pass
+// for an absent subject.
+//
+// 🚨 **What it decides is what makes `rgb` + `alpha` not `rgba`**, and both
+// clauses are about the file against the runtime:
+//
+//   1. **One channel, one timeline.** Each colour timeline poses its
+//      channels at EVERY time — before its first key it writes the setup
+//      value — so when two of one slot share a channel, the one applied
+//      later (the one the file states later) overwrites the other
+//      everywhere and the first one's keys on it are read by nothing
+//      (`SLOT_COLOR_CHANNELS`). It is the shape a converter that writes a
+//      separable `rgb` as `rgba` leaves beside the `alpha` it kept, and it
+//      loads without a word.
+//   2. **Posed as written.** Stepped to each key's own time, the channels
+//      the timeline writes are the key's: a colour that is not six hex
+//      digits loads as NaN, and a key whose time another key repeats is
+//      read by nothing, and both parse in silence.
+//
+// ⚠️ An `rgb` timeline alone that a converter wrote as `rgba` with the
+// setup alpha is NOT this rule's to see, and nothing that reads only the
+// file can see it: the result is a correct `rgba`, which is also what an
+// author keying the light colour and holding its alpha would write. What
+// differs is what happens UNDER another track that moves the alpha, which
+// is the consumer's composing rather than the object (CLAUDE.md). That
+// file SKIPs here — it keys no `rgb` or `alpha` — and says so.
+//
+// ⚠️ The required values are parsed HERE, as A43's are, and the channel
+// table is `timelines.ts`'s rather than the loaded timelines' property ids:
+// a check that asked the parser what a timeline writes would agree with it
+// whatever it did. A selftest control holds that table to the runtime's ids.
+export function a45SeparableColorTimelinesOwnTheirChannelsAndPoseAsWritten({ fail, skip, stats }: Verdicts, facts: SlotColourFacts): void {
+  const NAME = 'A45_SEPARABLE_COLOR_TIMELINES_OWN_THEIR_CHANNELS_AND_POSE_AS_WRITTEN';
+  /** `rrggbb`, or `rrggbbaa` whose alpha an `rgb` key cannot pose. Null for anything else. */
+  const readRgbHex = (hex: unknown): [number, number, number] | null => {
+    if (typeof hex !== 'string') return null;
+    const body = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (!/^[\da-fA-F]{6}([\da-fA-F]{2})?$/.test(body)) return null;
+    return [0, 2, 4].map((i) => Number.parseInt(body.slice(i, i + 2), 16) / 255) as [number, number, number];
+  };
+  /** Half a byte step for a hex channel; a stored `Float32` for an alpha `value`. */
+  const HEX_STEP = 1 / 510;
+  const FLOAT_STEP = 1e-6;
+  const off = (found: number, want: number, step: number): boolean => !Number.isFinite(found) || Math.abs(found - want) > step;
+  const show = (c: readonly number[]): string => c.map((n) => (Number.isFinite(n) ? n.toFixed(4) : 'NaN')).join(', ');
+
+  // -- the subjects, read off the FILE ---------------------------------
+  const subjects: Array<{ anim: string; slot: string; timelines: Record<string, unknown> }> = [];
+  for (const { animation: animName, slot: slotName, timelines } of facts.slotTimelines) {
+    if (Array.isArray(timelines.rgb) || Array.isArray(timelines.alpha)) {
+      subjects.push({ anim: animName, slot: slotName, timelines });
+    }
+  }
+  if (subjects.length === 0) return skip(NAME, SKIP_NO_SEPARABLE_COLOR);
+  stats.separableColorTimelines = subjects.reduce(
+    (n, s) => n + (Array.isArray(s.timelines.rgb) ? 1 : 0) + (Array.isArray(s.timelines.alpha) ? 1 : 0),
+    0,
+  );
+
+  for (const { anim: animName, slot: slotName, timelines } of subjects) {
+    const at = `animation "${animName}" slot "${slotName}"`;
+    // In FILE order, which is the order `readAnimation` pushes them and so
+    // the order they apply in.
+    const colour = Object.keys(timelines).filter((name) => name in SLOT_COLOR_CHANNELS && Array.isArray(timelines[name]));
+
+    // -- clause 1: one channel, one timeline ---------------------------
+    let shared = false;
+    for (const channel of ['rgb', 'alpha', 'dark'] as const) {
+      const writers = colour.filter((name) => SLOT_COLOR_CHANNELS[name].includes(channel));
+      if (writers.length < 2 || !writers.some((name) => name === 'rgb' || name === 'alpha')) continue;
+      shared = true;
+      const last = writers[writers.length - 1];
+      fail(
+        NAME,
+        `${at}: ${writers.map((name) => `"${name}"`).join(' and ')} ${writers.length === 2 ? 'both' : 'all'} key the ${channel === 'rgb' ? 'light rgb' : channel === 'alpha' ? 'alpha' : 'dark colour'} ` +
+          `— each poses it at every time, its setup value before its first key included, so "${last}", which the ` +
+          `file states last, overwrites ${writers.length === 2 ? `"${writers[0]}"` : 'the others'} everywhere and ` +
+          'those keys are read by nothing. Key each channel once: "rgb" and "alpha" on their own key times, or one "rgba"',
+      );
+    }
+    if (shared) continue;
+
+    // -- clause 2: posed as written ------------------------------------
+    //
+    // ⚠️ Two things this does NOT do, both measured rather than skipped:
+    // it does not read the loaded timeline's CLASS back, and it does not
+    // hold a channel the timeline leaves alone to the setup pose. Against
+    // the linked parser neither can fail — every `rgb` / `alpha` array that
+    // loads at all loads as an `RGBTimeline` / `AlphaTimeline`, and the
+    // three other outcomes (an empty array, a slot the skeleton lacks, a
+    // name outside the switch) throw at `A00` — so either would be a clause
+    // nobody can see fire. The selftest reads both off spine-core directly
+    // (`S82`–`S84`), where they are measurements of the runtime rather than
+    // checks on a file.
+    if (!facts.hasAnimation(animName)) {
+      fail(NAME, `${at}: the loaded skeleton has no animation "${animName}"`);
+      continue;
+    }
+    for (const name of ['rgb', 'alpha'] as const) {
+      const keys = timelines[name];
+      if (!Array.isArray(keys)) continue;
+      const where = `${at} ${name}`;
+      for (const rawKey of keys) {
+        if (!isObj(rawKey)) continue;
+        const time = typeof rawKey.time === 'number' ? rawKey.time : 0;
+        // At the key as the runtime stores it, not one float step before
+        // it — see `atStoredKey` (issue #771).
+        const posed = facts.posedSlot(animName, slotName, atStoredKey(time));
+        if (!posed) {
+          fail(NAME, `${where} (t=${time}): the posed skeleton has no slot "${slotName}" to read`);
+          continue;
+        }
+        const light = [posed.color.r, posed.color.g, posed.color.b, posed.color.a];
+        if (name === 'rgb') {
+          const stated = readRgbHex(rawKey.color);
+          if (stated === null) {
+            fail(
+              NAME,
+              `${where} (t=${time}): the key states color ${JSON.stringify(rawKey.color)} — an rgb key is six hex ` +
+                `digits — and the runtime poses (${show(light.slice(0, 3))})`,
+            );
+          } else if (light.slice(0, 3).some((n, i) => off(n, stated[i], HEX_STEP))) {
+            fail(
+              NAME,
+              `${where} (t=${time}): rgb posed (${show(light.slice(0, 3))}), the key states ` +
+                `${JSON.stringify(rawKey.color)} = (${show(stated)})`,
+            );
+          }
+        } else {
+          // `readTimeline1(…, 0, 1)`: an absent `value` IS 0, and an editor
+          // omits it there, so absence is read the parser's way rather than
+          // as a malformed key.
+          const stated = rawKey.value === undefined ? 0 : rawKey.value;
+          if (typeof stated !== 'number' || off(light[3], stated, FLOAT_STEP)) {
+            fail(
+              NAME,
+              `${where} (t=${time}): alpha posed ${show([light[3]])}, the key states value ${JSON.stringify(rawKey.value)}` +
+                (typeof stated !== 'number'
+                  ? ' — an alpha key\'s value is a number'
+                  : stated < 0 || stated > 1
+                    ? ' — the runtime clamps a posed alpha to 0..1'
+                    : ''),
+            );
+          }
+        }
+      }
+    }
+  }
+}

package/src/assertions/facts/atlas_pages.ts

@@ -0,0 +1,19 @@
+/**
+ * The atlas's pages, as the bodies that read them see them (issue #1025, step
+ * 4c of #380) — the census's F20, without `pma`, which the model document does
+ * not hold and a later cut supplies from the caller.
+ *
+ * Links nothing from the runtime: a spine-core `TextureAtlas` satisfies the
+ * shape structurally, which is how `validate()` supplies it, and the model
+ * side supplies the document's `pages` section (`../model/atlas_pages.ts`).
+ */
+
+/** One page: its name, a path relative to the directory the atlas sits in. */
+export interface AtlasPage {
+  readonly name: string;
+}
+
+/** The atlas, or `null` when there is none to read — the round trip refused it, or the model side read no document. */
+export interface AtlasPageFacts {
+  readonly atlas: { readonly pages: readonly AtlasPage[] } | null;
+}

package/src/assertions/facts/skin_entries.ts

@@ -0,0 +1,35 @@
+/**
+ * The skin entries, as the bodies that walk them read them (issue #1025, step
+ * 4c of #380) — the census's F03, F05 and F06: every skin's attachments, of
+ * which kind each is, and a region's name and size.
+ *
+ * ⭐ **The order is a fact, and it is the file's.** A body that prints one
+ * line per offending entry prints them in the order this list holds them, so a
+ * supplier that walked another order would print the same findings in another
+ * order — a different report about the same rig. The order is the one
+ * spine-core's loaded skins list their entries in: the skins in the file's
+ * order (`default` first, the rest in the editor's order the emitter writes —
+ * `editorSkinOrder` in `src/compile.ts`), and within a skin the entries slot by
+ * slot in the skeleton's slot order, each slot's in the order its table states
+ * them. The model side produces it by calling the emitter's own order, never
+ * by restating it (`../model/skin_entries.ts`); the selftest measures the two
+ * walks equal on every multi-skin build it makes.
+ *
+ * Links nothing from the runtime: a spine-core `RegionAttachment` satisfies
+ * the entry shape structurally, which is how `validate()` supplies it.
+ */
+
+/** One region attachment: the name it loaded under (its `name`, else its placeholder) and its size. */
+export interface RegionEntry {
+  readonly name: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** What the skins hold, for A03 and A11. */
+export interface SkinEntryFacts {
+  /** Every region attachment of every skin, in the file's walk order (the header's ⭐). */
+  readonly regionAttachments: readonly RegionEntry[];
+  /** How many clipping attachments the skins hold, every skin counted. */
+  readonly clippingCount: number;
+}