spine-rigc 1.5.3 → 1.6.2

package/cli.ts

@@ -80,14 +80,9 @@ import {
 } from './src/check.ts';
 import { writeCheckPictures } from './src/checkpics.ts';
 import { compile, CompileError, droppedStateReason, relativeImagesPath, type CompileOptions } from './src/compile.ts';
-import {
-  skeletonDataFromText,
-  surveyDeformKeys,
-  unreachableWhy,
-  type DeformExtreme,
-  type DeformKeyMeasure,
-  type DeformSpan,
-} from './src/deformmeasure.ts';
+import { MODEL_DOCUMENT_FILE, modelDocument } from './src/model.ts';
+import { deformReportBlock } from './src/deformreport.ts';
+import { surveyOfBuild } from './src/deformmeasure.ts';
 import {
   diffLines,
   diffSkeletons,
@@ -112,7 +107,6 @@ import {
 } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { PARSER_DEFAULTS, parserReading } from './src/keyorder.ts';
-import { float32Step } from './src/timelines.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
 import {
   DEFAULT_MAX_RESIDUAL,
@@ -146,6 +140,8 @@ import {
   framingViewport,
   GEOMETRY_FILE,
   GeometryError,
+  UnframeablePoseError,
+  skinRosterOf,
   geometryFileOf,
   geometryText,
   loadPosable,
@@ -159,10 +155,16 @@ import {
   sidecarViewport,
   SlotSubsetError,
   slotSubsetOf,
+  candidatePosers,
+  POSER_NAMES,
+  PoserChoiceError,
+  throughPoser,
   type Frame,
   type FramesSidecar,
   type FrameSet,
   type Posable,
+  type PoserChoice,
+  type PoserName,
   type SlotSubset,
 } from './src/render.ts';
 import {
@@ -451,18 +453,21 @@ interface AtlasOverride {
 
 function runGate(
   result: CompileResult,
+  modelText: string,
   opts: CompileOptions,
   profile: ValidateProfile,
   atlas?: AtlasOverride,
 ): number {
-  // The determinism check compares a second, independent compile.
+  // The determinism check compares a second, independent compile — its model
+  // document included, which is the text `build` writes beside the pair.
   const again = compile(opts);
   const report = validate({
     skeletonText: result.skeletonText,
     atlasText: atlas ? atlas.text : result.atlasText,
     atlasDir: opts.outDir,
     declaredDurations: result.declaredDurations,
-    reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText },
+    modelText,
+    reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText, modelText: modelDocument(again.model, again.skeletonText) },
     rig: result.rig,
     profile,
   });
@@ -728,18 +733,6 @@ function meshBudget(rig: CompileResult['rig']): string {
   return rig.meshTriangleBudget === null ? '(no budget declared)' : `(budget ${rig.meshTriangleBudget})`;
 }
 
-/**
- * One extreme, as `x0.637306 tri 0`, or an em dash when no triangle on the key
- * could carry the quantity.
- *
- * A dash rather than `x1.000000`: a key over a mesh whose every triangle is a
- * hair has no ratio and no map, and printing the identity there would report a
- * measurement that was never taken — this repository's favourite false green.
- */
-function deformExtreme(extreme: DeformExtreme | null): string {
-  return extreme === null ? '—'.padEnd(9) : `x${extreme.value.toFixed(6)} tri ${extreme.triangle}`;
-}
-
 /**
  * The `MEMBER` report block — a group track's per-member values, side by side
  * (issue #295).
@@ -814,28 +807,6 @@ function memberReportLines(result: CompileResult): string[] {
   return out;
 }
 
-/** `head/head key 1`, which is how A39's own message names a key. */
-function deformKeyName(key: DeformKeyMeasure): string {
-  return `${key.slot}/${key.attachment} key ${key.key}`;
-}
-
-/**
- * Does this compiled `transform` report belong to this loaded key?
- *
- * ⚠️ The two times are not the same number and cannot be compared with `===`.
- * The report's is the spec's own `t`; the survey's came back through
- * `Float32Array`, because that is what `spine-core` reads a timeline's frames
- * into — a key written `0.62` arrives as `0.6200000047683716`. So the tolerance
- * is one float32 step at this magnitude (`float32Step`): the compiler emits a
- * key time as a float's name — the spec's own time when it names one, the float
- * below it when it does not (issue #716) — so the loaded float is within one
- * step of the spec's `t` either way, which is narrower than any key spacing the
- * format can hold.
- */
-function sameKeyTime(specTime: number, loaded: number): boolean {
-  return Math.abs(specTime - loaded) <= float32Step(loaded);
-}
-
 /**
  * The `DEFORM` report block — what each deform key does to the geometry, per key
  * and then per animation (issue #316).
@@ -890,327 +861,11 @@ function sameKeyTime(specTime: number, loaded: number): boolean {
  * deserves the answer rather than a silence. What does move is the stretch.
  */
 function deformReportLines(result: CompileResult, exempt: ReadonlySet<string>): string[] {
-  const survey = surveyDeformKeys(skeletonDataFromText(result.skeletonText, result.atlasText));
-  if (survey.timelines === 0) return [];
-  const out: string[] = ['', 'deform  (what each key does to the geometry — figures with names, never a bar; issue #316)'];
-  // The legend costs six lines and is worth them exactly once — on a report that
-  // has figures in it. A bounding box or a clipping polygon deformed and nothing
-  // else gets the reason it has no figures and no essay about them.
-  if (survey.keys.length) {
-    out.push(
-      '  ..    every key measured at its OWN time against the same pose with the deform CLEARED, so the',
-      '  ..    denominator is 1.000 by definition and a NEGATIVE area ratio IS a reversed triangle',
-      '  ..    the FRAME is on each key line: on a track, or the slider that applies the animation with the',
-      '  ..    dial value its mapping was inverted to — a slider picks the time, so the key\'s time IS it',
-      '  ..    stretch is the two singular values of the map from the cleared triangle to the deformed one —',
-      '  ..    the worst stretch and the worst squash the drawing takes there; their product is |area ratio|',
-      '  ..    coverage is NOT here: it is rasterised from the uvs, which no deform moves, so the figure on',
-      '  ..    the `meshes` line below is already the deformed one',
-    );
-  }
-  if (survey.notAMesh.length) {
-    out.push(`  ..    ${survey.notAMesh.join(', ')} deform an attachment with no triangles — nothing to measure`);
-  }
-  for (const key of survey.keys) {
-    const model = result.deformTransforms.find(
-      (g) =>
-        g.animation === key.animation &&
-        g.skin === key.skin &&
-        g.slot === key.slot &&
-        g.attachment === key.placeholder &&
-        sameKeyTime(g.time, key.time),
-    );
-    // A stated model is quoted rather than reduced to its results: `yaw
-    // radius=170 degrees=12` is what a reviewer checks the ratios against, and an
-    // authored table says so instead of saying nothing, because "no model here"
-    // is itself the thing a reader of a wrong ratio needs to know.
-    const states = model === undefined ? 'authored table' : `transform ${model.kind}  ${model.stated}`;
-    out.push(
-      `  DEFORM  ${key.animation}  ${key.skin}/${key.slot}/${key.placeholder}  key ${key.key}  ` +
-        `t=${key.time.toFixed(6)}  ${states}`,
-    );
-    // 🔒 The frame, on every key, because the derivation is shared with A39 and
-    // this block is where a reader finds out which one it was (issue #407). A
-    // track frame says so in three words; a slider frame names the dial value
-    // its own mapping inverts this time to, which is the number an author sets.
-    out.push(
-      `          frame      ${key.reach.label}` +
-        (key.dial === null
-          ? ''
-          : `, dial ${key.dial.value.toFixed(6)}` +
-            // ⚠️ `reach.drive` names the field when it is NOT the one `property`
-            // names, which happens under `local: false` on a rotated parent — a
-            // bare figure there would read as a value of the wrong field (#419).
-            (key.reach.local || key.dial.driven === key.dial.value
-              ? ''
-              : ` (bone local ${key.reach.drive === null ? '' : `${key.reach.drive} `}${key.dial.driven.toFixed(6)})`) +
-            ` -> t=${key.dial.applied.toFixed(6)}`),
-    );
-    // A key at a time no dial selects: the figures below are the frame the
-    // runtime DOES land on, which is some other time's geometry, so the line
-    // that says so comes before them and the gate reads none of them.
-    if (key.dial?.unreachable === true) {
-      out.push(
-        `          unreachable A39 gates nothing here: ${unreachableWhy(key)}. Every figure below is that other ` +
-          "frame's, not this key's",
-      );
-    }
-    // ⚠️ An exemption nobody can see is how a gate comes to look kept while
-    // checking nothing (issue #401). A key the gate passed over because the mesh
-    // draws no pixels there says so on its own line, in the survey's own words,
-    // whether or not it folds.
-    if (key.draw.blank !== null) {
-      out.push(
-        `          skipped    A39 reads no winding off this key: ${key.draw.blank} — a triangle that draws no ` +
-          'pixels cannot draw them backwards',
-      );
-    }
-    // And when the slot shows something else, the figures below would be a
-    // second falsehood rather than a caveat: the runtime applies no deform to a
-    // slot that is not showing the mesh (`DeformTimeline.applyToSlot`), so every
-    // figure would be the identity and `moved 0` would read as "this key is the
-    // setup pose" — which is exactly what the key is NOT.
-    if (!key.draw.showsThisMesh) {
-      out.push(
-        `          ..         the slot shows ${key.draw.shown === null ? 'no attachment' : `"${key.draw.shown}"`} ` +
-          'here, so the runtime applied no deform and there is no posed geometry to measure' +
-          (key.draw.blank === null
-            ? ' — but the mesh IS drawn in another slot this deform reaches (timelineSlots), so nothing here is exempt'
-            : ''),
-      );
-      continue;
-    }
-    // A key that moves nothing gets one line and no figures. `{ "t": 2.2 }` with
-    // no run is the format's own way of writing "back to the setup pose" (§4.11),
-    // and its geometry is bit-identical to the cleared pose it would be measured
-    // against — so `x1.000000` there is the definition and not a measurement, and
-    // four lines of it on every loop's opening and closing key is the noise that
-    // stops the block being read. It is still counted in the rollup below,
-    // because A39 measures it too.
-    if (key.moved === 0) {
-      out.push(
-        `          moved      0 of ${key.vertices} vertices — this key IS the setup pose, so every ` +
-          `figure is the identity (${key.triangles} triangles, all kept)`,
-      );
-      continue;
-    }
-    out.push(
-      `          moved      ${key.moved} of ${key.vertices} vertices, ` +
-        `worst ${key.maxDisplacement.toFixed(4)}px at v${key.maxDisplacementVertex}`,
-    );
-    out.push(
-      `          area       min ${deformExtreme(key.areaRatioMin)}   max ${deformExtreme(key.areaRatioMax)}   ` +
-        `(${key.triangles} triangles, ${key.degenerate} with no area at the cleared pose, band ${key.band.toFixed(6)}px²)`,
-    );
-    out.push(
-      `          stretch    max ${deformExtreme(key.stretchMax)}   min ${deformExtreme(key.stretchMin)}`,
-    );
-    // The marker has to know about the exemption, or it says the false half of
-    // the truth on the one build where it matters: a declared fold IS a fold and
-    // A39 does not refuse it — it SKIPs the slot entirely.
-    const exempted = exempt.has(key.slot);
-    const fold = key.reversed.length
-      ? key.draw.blank !== null
-        ? '  <- a fold, and nothing gates it: this key draws no pixels (see above)'
-        : exempted
-          ? '  <- a fold, and A39 does not gate it — see below'
-          : '  <- a fold: A39 refuses this key by name'
-      : '';
-    out.push(
-      `          winding    ${key.triangles - key.reversed.length} of ${key.triangles} kept, ` +
-        `${key.collapsed} collapsed${fold}`,
-    );
-    if (exempted) {
-      out.push(
-        `          ..         A39 is exempt on "${key.slot}" (invariants.deformMayFold), so nothing here is gated`,
-      );
-    }
-  }
-  // The folds at times no key lands on (issue #403), printed after the keys they
-  // lie between rather than interleaved: they are a different measurement — the
-  // closed form named the time and the runtime was posed there — and a reader
-  // needs to be able to tell the two apart at a glance.
-  for (const span of survey.spans) {
-    if (span.fold === null) continue;
-    const at = span.fold;
-    out.push(
-      `  BETWEEN ${span.animation}${span.reach.kind === 'slider' ? ` via ${span.reach.slider}` : ''}  ` +
-        `${span.skin}/${span.slot}/${span.placeholder}  key ${span.fromKey} -> ` +
-        `${span.toKey}  t=${at.time.toFixed(6)}  ${span.curve}` +
-        (span.curve === 'stepped' ? '  (held, not interpolated)' : `  ${(at.percent * 100).toFixed(1)}% of the way`),
-    );
-    out.push(
-      `          winding    ${at.measure.triangles - at.measure.reversed.length} of ${at.measure.triangles} kept, ` +
-        `${at.measure.collapsed} collapsed  <- a fold at a time no key lands on` +
-        (at.measure.draw.blank !== null
-          ? ', and nothing gates it: nothing is drawn there'
-          : exempt.has(span.slot)
-            ? ', and A39 does not gate it (invariants.deformMayFold)'
-            : `: A39 refuses this span by name, at alpha ${at.measure.draw.alpha.toFixed(4)}`),
-    );
-  }
-  // The rollup, per animation: the worst key by each quantity. A timeline's own
-  // eight keys are eight blocks above, and "which of them is the one to look at"
-  // is the question the sweep in issue #313's landing comment answered by hand.
-  //
-  // ⚠️ Per animation AND per frame (issue #407). Two sliders applying one
-  // animation are two frames and two rollups: merging them would average a fold
-  // one dial reaches into a run of keys another one is clean over, which is the
-  // hiding the two frames exist to prevent.
-  // 🔒 ONE derivation of a rollup's identity, read by every filter below.
-  //
-  // ⚠️ It was spelled three times and one of them drifted. The two key filters
-  // separate animation from slider with a NUL; the span filter used a SPACE, so
-  // its `=== id` never matched on any rig and `spans` was always empty — the
-  // "N span(s) … scanned" line silently stopped printing everywhere, taking with
-  // it the one thing issue #403 added it to say: that the scan RAN and found
-  // nothing, as opposed to never having run. A dead branch is the same silence
-  // this tool exists to convert into a named failure, and it survived because
-  // the identity was a literal at each site rather than a derivation (#440).
-  const rollupId = (animation: string, slider: string | null): string => `${animation}\u0000${slider ?? ''}`;
-  /**
-   * The readings A39 puts on its stats line for the three things this rollup
-   * reports — each spelled ONCE here and nowhere else in this file.
-   *
-   * 🔒 Checked rather than derived, and the difference is forced: `src/validate.ts`
-   * sets these on a `Record<string, number | string>`, so there is no type to take
-   * a name off and no constant to import. So they are spelled here and a control
-   * compiles a rig that triggers each one, then asserts the breadcrumb names a
-   * reading A39 really printed — two independent derivations compared, which is
-   * the shape `CUR07` uses for the same reason.
-   */
-  const A39_COUNTS = {
-    notDrawn: 'deformKeysNotDrawn',
-    unreachable: 'deformKeysUnreachable',
-    dialsDisagreed: 'deformDialsDisagreed',
-    dialDisagreed: 'deformDialDisagreed',
-  } as const;
-  const rollups = new Map<string, { animation: string; label: string }>();
-  for (const key of survey.keys) {
-    rollups.set(rollupId(key.animation, key.reach.slider), {
-      animation: key.animation,
-      label: key.reach.kind === 'slider' ? `${key.animation} via ${key.reach.slider}` : key.animation,
-    });
-  }
-  for (const [id, { animation, label }] of rollups) {
-    // Only the keys the gate ran on, because the line ends by claiming A39 reads
-    // the same two counts and A39 reads none of a key that draws nothing, nor of
-    // one at a time no dial selects. The ones it left out get their own line
-    // rather than a silence (issues #401, #407).
-    const mine = survey.keys.filter((k) => rollupId(k.animation, k.reach.slider) === id);
-    const unreachable = mine.filter((k) => k.dial?.unreachable === true);
-    const keys = mine.filter((k) => k.dial?.unreachable !== true && k.draw.blank === null);
-    const blank = mine.filter((k) => k.dial?.unreachable !== true && k.draw.blank !== null);
-    const worst = (
-      pick: (key: DeformKeyMeasure) => DeformExtreme | null,
-      better: (a: number, b: number) => boolean,
-    ): string => {
-      let best: { key: DeformKeyMeasure; extreme: DeformExtreme } | null = null;
-      for (const key of keys) {
-        const extreme = pick(key);
-        if (extreme === null) continue;
-        if (best === null || better(extreme.value, best.extreme.value)) best = { key, extreme };
-      }
-      return best === null ? '—' : `x${best.extreme.value.toFixed(6)} (${deformKeyName(best.key)} tri ${best.extreme.triangle})`;
-    };
-    const reversed = keys.reduce((n, k) => n + k.reversed.length, 0);
-    const collapsed = keys.reduce((n, k) => n + k.collapsed, 0);
-    const samples = keys.reduce((n, k) => n + k.triangles, 0);
-    if (keys.length) {
-      out.push(
-        `  WORST   ${label}  area ${worst((k) => k.areaRatioMin, (a, b) => a < b)}  ` +
-          `stretch ${worst((k) => k.stretchMax, (a, b) => a > b)}  ` +
-          `squash ${worst((k) => k.stretchMin, (a, b) => a < b)}`,
-      );
-      out.push(
-        `  ..      ${''.padEnd(label.length)}  reversed ${reversed}, collapsed ${collapsed}, over ` +
-          `${keys.length} key(s) and ${samples} triangle sample(s)  <- A39 reads the same two counts`,
-      );
-    }
-    if (blank.length) {
-      out.push(
-        `  ..      ${keys.length ? ''.padEnd(label.length) : label}  ${blank.length} key(s) draw no pixels ` +
-          `at their own time and are read for no winding, carrying ` +
-          `${blank.reduce((n, k) => n + k.reversed.length, 0)} reversed triangle(s) nothing gates  <- A39 counts ` +
-          `them as ${A39_COUNTS.notDrawn}`,
-      );
-    }
-    if (unreachable.length) {
-      out.push(
-        `  ..      ${keys.length || blank.length ? ''.padEnd(label.length) : label}  ${unreachable.length} key(s) ` +
-          'at a time no dial selects, measured in the frame the runtime lands on instead and read for no winding, ' +
-          `carrying ${unreachable.reduce((n, k) => n + k.reversed.length, 0)} reversed triangle(s) nothing gates ` +
-          ` <- A39 counts them as ${A39_COUNTS.unreachable}`,
-      );
-    }
-    // ⚠️ The dial rigc's two halves disagree about (issues #427, #440). It is a
-    // property of the SLIDER and not of any one key, so it is placed by the
-    // rollup's own identity rather than by a key filter — and it is REPORTED,
-    // never gated: A39 refuses nothing for it, because a disagreement can pose
-    // every frame correctly. Both readings are named because they differ by one
-    // letter, and a breadcrumb that named only one of `deformDialsDisagreed` /
-    // `deformDialDisagreed` would send a reader to grep for the other.
-    const disputes = survey.dialDisputes.filter((dispute) => rollupId(animation, dispute.slider) === id);
-    if (disputes.length) {
-      out.push(
-        `  ..      ${keys.length || blank.length || unreachable.length ? ''.padEnd(label.length) : label}  ` +
-          `${disputes.length} dial(s) the skeleton and the probe disagree about: ` +
-          disputes
-            .map(
-              (dispute) =>
-                `the skeleton reads ${dispute.bone}.${dispute.stated} and the probe drives ` +
-                `${dispute.bone}.${dispute.drive}, ` +
-                (dispute.outside.length === 0
-                  ? 'and both answers pose the same frames'
-                  : `${dispute.outside.length} key time(s) outside what the skeleton's own field reaches`),
-            )
-            .join('; ') +
-          `  <- A39 counts them as ${A39_COUNTS.dialsDisagreed} and spells them out as ${A39_COUNTS.dialDisagreed}`,
-      );
-    }
-    // ⚠️ Printed on a clean animation too. "The scan ran and found nothing" and
-    // "the scan never ran" are the two things a gate must never say the same
-    // way, and this line is the only place an author can tell them apart
-    // (issue #403).
-    const spans = survey.spans.filter((s) => rollupId(s.animation, s.reach.slider) === id);
-    if (spans.length) {
-      out.push(
-        `  ..      ${keys.length || blank.length || unreachable.length || disputes.length ? ''.padEnd(label.length) : label}  ` +
-          `${spans.length} span(s) between consecutive keys scanned for a fold no key lands on: ` +
-          `${spanTally(spans)}  <- A39 reads the same scan`,
-      );
-    }
-  }
-  // ⚠️ And the spans that were NOT scanned, once, because a scan that did not
-  // run has to be distinguishable from one that ran and found nothing — the same
-  // rule the line above keeps, on the other side of it (issue #407).
-  if (survey.spansNotScanned) {
-    out.push(
-      `  ..      ${survey.spansNotScanned} span(s) NOT scanned: one of the two keys bounding each is at a time no ` +
-        'dial selects, so the interpolation between them is between two poses of some other time',
-    );
-  }
-  return out;
-}
-
-/** What the between-keys scan found, in one clause (issue #403). */
-function spanTally(spans: readonly DeformSpan[]): string {
-  const folds = spans.filter((s) => s.fold !== null).length;
-  const notDrawn = spans.filter((s) => s.notDrawn > 0).length;
-  const unconfirmed = spans.filter((s) => s.unconfirmed).length;
-  const probes = spans.reduce((n, s) => n + s.probed.length, 0);
-  if (folds === 0 && notDrawn === 0 && unconfirmed === 0) {
-    return `none folds (the closed form flagged nothing, so no span cost a posed measurement)`;
-  }
-  return (
-    [
-      folds ? `${folds} fold(s)` : '',
-      notDrawn ? `${notDrawn} folding only where nothing is drawn` : '',
-      unconfirmed ? `${unconfirmed} predicted a fold no probe reproduced` : '',
-    ]
-      .filter(Boolean)
-      .join(', ') + `, at a cost of ${probes} posed measurement(s)`
-  );
+  // Through rigc's own core over the model document the build carries (issue #969), spine-core when the core
+  // refuses it; the survey's record says which (`source`), and `tools/survey_hashes.ts` holds the two to one block.
+  // The block itself is `deformReportBlock` (`src/deformreport.ts`), so a control renders it off either poser's survey.
+  const survey = surveyOfBuild({ skeletonText: result.skeletonText, atlasText: result.atlasText, modelText: modelDocument(result.model, result.skeletonText) }, new Set(), 'auto');
+  return deformReportBlock(survey, result.deformTransforms, exempt);
 }
 
 /**
@@ -1456,8 +1111,12 @@ function cmdBuild(flags: Record<string, string>): void {
     );
   }
 
+  // The model's document is spelled before the gate, so the text A18 compares
+  // is the text written, and a model the document cannot carry is refused
+  // before anything is (issue #922).
+  const modelText = modelDocument(result.model, result.skeletonText);
   console.log(`  ..    validate (spine-core round trip + machine assertions, profile ${profile})`);
-  const failures = runGate(result, opts, profile);
+  const failures = runGate(result, modelText, opts, profile);
   if (failures > 0) {
     console.error(`rigc: ${failures} assertion(s) failed — nothing written`);
     process.exit(1);
@@ -1538,7 +1197,7 @@ function cmdBuild(flags: Record<string, string>): void {
       })),
       packOpts,
     );
-    const packFailures = runGate(result, opts, profile, { text: atlasText, again: packAgain.atlasText });
+    const packFailures = runGate(result, modelText, opts, profile, { text: atlasText, again: packAgain.atlasText });
     if (packFailures > 0) {
       console.error(
         `rigc: ${packFailures} assertion(s) failed on the PACKED atlas — the pages were written to ` +
@@ -1550,8 +1209,13 @@ function cmdBuild(flags: Record<string, string>): void {
 
   writeFileSync(join(opts.outDir, 'skeleton.json'), result.skeletonText);
   writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
+  // rigc's own record of the compiled rig (`rigc-compiled/1`, issue #922),
+  // written with the pair and only after the same gate. rigc's own posing core
+  // reads it (`readModel`, `src/core/index.ts`, issue #380's step 2).
+  writeFileSync(join(opts.outDir, MODEL_DOCUMENT_FILE), modelText);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.atlas')}`);
+  console.log(`rigc: wrote ${join(opts.outDir, MODEL_DOCUMENT_FILE)}`);
   // The next command is part of the message (issue #837). A green build is the
   // moment somebody wants to see what came out, and the one page rigc writes
   // for that is `preview` of exactly this directory — so the line names it,
@@ -1782,12 +1446,17 @@ function runCheck(
   plates?: CheckPlates,
 ): CheckReport {
   const { skeletonPath, atlasPath } = resolveArtifacts(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'),
     atlasDir: dirname(atlasPath),
     framesDir,
     labels: { skeleton: skeletonPath, atlas: atlasPath },
+    candidatePaths: { skeleton: skeletonPath, atlas: atlasPath },
+    ...(poser === undefined ? {} : { poser }),
     ...readCheckFlags(flags),
     ...(plates === undefined ? {} : { plates }),
   });
@@ -1947,6 +1616,26 @@ function readSlotSubsetFlags(
   }
 }
 
+/**
+ * `--poser core|spine`, resolved against the candidate (issue #968): both
+ * posers for it, and which one this run asked for. `core` on an input that
+ * cannot carry it is refused as a usage error by name; absent, the input's own
+ * choice stands — see `candidatePosers`.
+ */
+function readPoserChoice(flags: Record<string, string>, data: Posable['data'], skeletonPath: string, atlasPath: string): PoserChoice {
+  return candidatePosers(data, skeletonPath, atlasPath, readPoserFlag(flags));
+}
+
+/** `--poser` as spelled, checked against the posers there are — shared by `render` and `check`. */
+function readPoserFlag(flags: Record<string, string>): PoserName | undefined {
+  const raw = flags.poser;
+  const forced = POSER_NAMES.find((name) => name === raw);
+  if (raw !== undefined && forced === undefined) {
+    throw new UsageError(`--poser ${JSON.stringify(raw)}: known posers are ${POSER_NAMES.join(', ')}`);
+  }
+  return forced;
+}
+
 /** A resolved subset as the one field it is spelled as, in `PoseOptions` and in `frames.json` alike. */
 function subsetFields(subset: SlotSubset | undefined): { slots?: string[]; hidden?: string[] } {
   if (subset === undefined) return {};
@@ -2053,39 +1742,56 @@ function cmdRender(flags: Record<string, string>): void {
   if (skin !== undefined) console.log(`  ..    skin     ${skin}`);
   if (subset !== undefined) console.log(`  ..    ${subset.mode.padEnd(8)} ${subset.names.join(', ')}`);
 
-  // `null` is a skeleton that posed no vertex at all. One that posed a vertex
-  // it cannot frame — Infinity or NaN — is thrown from the framing as a
-  // `GeometryError` naming the number (issue #873), and never reaches this.
-  const viewport = framingViewport(data, maxSide, pose);
-  if (!viewport) {
-    throw new UsageError(
-      `${skeletonPath} posed no drawable attachment in any animation or in its setup pose${
-        skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`
-      } — there is nothing to draw`,
-    );
-  }
+  // Which implementation of the posing seam draws this (issue #968): rigc's own
+  // core when the candidate is a rigc build — `skeleton.model.json` beside the
+  // pair — and spine-core otherwise, or where the core refuses the input by
+  // name. Never silently: the `poser` line below says which, and why.
+  const choice = readPoserChoice(flags, data, skeletonPath, atlasPath);
+
+  // Everything is posed before anything is written, so a core refusal partway
+  // re-poses the whole input on spine-core rather than leaving half of a frame
+  // set drawn by each.
+  const posed = throughPoser(choice, (poser) => {
+    // `null` is a skeleton that posed no vertex at all. One that posed a vertex
+    // it cannot frame — Infinity or NaN — is thrown from the framing as a
+    // `GeometryError` naming the number (issue #873), and one whose every vertex
+    // sits at one point — every drawn bone unposed by the skin, or collapsed — as
+    // an `UnframeablePoseError` (issue #997); neither reaches this. The roster is what
+    // lets the second name the skins that pose a bone, whichever poser draws.
+    const viewport = framingViewport(poser, maxSide, pose, skinRosterOf(data));
+    if (!viewport) {
+      throw new UsageError(
+        `${skeletonPath} posed no drawable attachment in any animation or in its setup pose${
+          skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`
+        } — there is nothing to draw`,
+      );
+    }
 
-  // `sampleAll` covers the skeleton with no animation at all, which files its one
-  // setup-pose frame under the reserved name. Narrowing to one animation reuses
-  // the same sampler rather than a second path through it.
-  //
-  // `--geometry` rides on the SAME call (issue #864): the bones and the whole
-  // attachments are read off the skeleton at the step that drew each frame, so
-  // the export's grid is this frame set's by construction.
-  const sampling = geometry ? { ...pose, bones: true, geometry: true } : pose;
-  const sampled: Map<string, Frame[]> =
-    only === undefined
-      ? sampleAll(data, fps, sampling)
-      : new Map([[only, sampleAnimation(data, only, fps, sampling)]]);
-  // Every file's text before the first write, so a refused number leaves the
-  // output directory as it was rather than half of a frame set behind it.
-  const geometryTexts = new Map<string, string>();
-  if (geometry) {
-    for (const [name, frames] of sampled) {
-      const animation = name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name;
-      geometryTexts.set(name, geometryText(geometryFileOf(data, animation, fps, frames, viewport, skin)));
+    // `sampleAll` covers the skeleton with no animation at all, which files its one
+    // setup-pose frame under the reserved name. Narrowing to one animation reuses
+    // the same sampler rather than a second path through it.
+    //
+    // `--geometry` rides on the SAME call (issue #864): the bones and the whole
+    // attachments are read off the skeleton at the step that drew each frame, so
+    // the export's grid is this frame set's by construction.
+    const sampling = geometry ? { ...pose, bones: true, geometry: true } : pose;
+    const sampled: Map<string, Frame[]> =
+      only === undefined
+        ? sampleAll(poser, fps, sampling)
+        : new Map([[only, sampleAnimation(poser, only, fps, sampling)]]);
+    // Every file's text before the first write, so a refused number leaves the
+    // output directory as it was rather than half of a frame set behind it.
+    const geometryTexts = new Map<string, string>();
+    if (geometry) {
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name;
+        geometryTexts.set(name, geometryText(geometryFileOf(poser, animation, fps, frames, viewport, skin)));
+      }
     }
-  }
+    return { viewport, sampled, geometryTexts };
+  });
+  const { viewport, sampled, geometryTexts } = posed.value;
+  console.log(`  ..    poser    ${posed.note}`);
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!declaresSetupStage(data)) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
@@ -3812,7 +3518,7 @@ function cmdSkills(flags: Record<string, string>, positional: string[]): void {
 const FLAG_MEANINGS: Record<string, string> = {
   rig: 'the rig spec — skeleton structure',
   motion: 'the motion spec — time',
-  out: 'directory for skeleton.json + skeleton.atlas; atlas page paths and skeleton.images are written relative to it',
+  out: 'directory for skeleton.json + skeleton.atlas (and, from build, skeleton.model.json); atlas page paths and skeleton.images are written relative to it',
   images: "override the rig spec's own images directory (relative to your working directory)",
   manifest: 'a cut manifest, for a rig with measured art behind it; a foreign skeleton has none',
   'copy-images':
@@ -3850,6 +3556,11 @@ const FLAG_MEANINGS: Record<string, string> = {
     `also write ${GEOMETRY_FILE} 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 — on the " +
     'frames\' own grid and viewport. Not with --slot/--hide: the geometry is the whole pose whatever is drawn',
+  poser:
+    "`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',
   '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 ' +
@@ -3954,6 +3665,7 @@ const FLAG_VALUES: Record<string, string> = {
   padding: '<px>',
   'page-edges': 'pot|free',
   'texture-from': '<path>',
+  poser: 'core|spine',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
   bones: `<correspondence.json|${IDENTITY_CORRESPONDENCE}>`,
@@ -4130,7 +3842,7 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'check',
     usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
-    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'all-frames', 'json', 'out'],
+    flags: ['candidate', 'frames', 'atlas', 'texture-from', 'fps', 'viewport', 'framing', 'as', 'skin', 'poser', 'all-frames', 'json', 'out'],
     overrides: {
       skin: {
         meaning:
@@ -4190,10 +3902,10 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'render',
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
@@ -4545,10 +4257,26 @@ try {
   // the skeleton posed a NaN or an infinity, so exit 1 like a file that is not
   // a PNG. Raised by the geometry export and by the framing — the one sentence
   // naming the bone or vertex and its value — before the first file is written.
+  // A pose whose every drawn vertex sits at one point (issue #997), from
+  // `render` or `check`: exit 2 like *nothing to draw*, the other framing
+  // refusal, because the usual fix is the invocation's — `--skin` — and nothing
+  // was written. A `GeometryError` in kind, so it is caught before that.
+  if (err instanceof UnframeablePoseError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof GeometryError) {
     console.error(`rigc render: ${err.message}`);
     process.exit(1);
   }
+  // `--poser core` on an input the core cannot carry (issue #968): a refusal of
+  // the invocation, nothing written, and the message names the input and why —
+  // the usage under it would bury that. Without the flag the same refusal is a
+  // fallback to spine-core, named on the render's `poser` line instead.
+  if (err instanceof PoserChoiceError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof NotAPngError) {
     console.error(`rigc: ${err.message}`);
     process.exit(1);