spine-rigc 0.13.0 → 0.14.1

package/README.md

@@ -386,7 +386,7 @@ limits: [AUTHORING.md §11](docs/AUTHORING.md). The parts it refuses because
 something is drawn over them are `rigc chainfit`'s, once a candidate exists —
 [§12](docs/AUTHORING.md).
 
-## The gallery — four complete rigs over art that ships with them
+## The gallery — five complete rigs over art that ships with them
 
 Each directory in [`gallery/`](https://github.com/firejune/rigc/tree/main/gallery) is
 one rig spec, one motion spec and the PNGs they name, small enough to read in one
@@ -398,9 +398,20 @@ was verified, and what writing it cost. Repository material: a clone and
 | Example | Stars | What it is |
 | --- | --- | --- |
 | [`gallery/walk`](https://github.com/firejune/rigc/tree/main/gallery/walk) | `ik` constraints + **`ik` timelines** | Two two-bone leg chains solved to foot targets — the planted leg nailed down, the swinging one let go at the top of its lift |
-| [`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash) | **`deform` timelines** | A ball squashed about its contact point and stretched along its travel, from two affine transforms written out in the README |
+| [`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash) | **`deform` timelines** | A ball squashed about its contact point and stretched along its travel, from two affine transforms the keys state rather than tabulate |
 | [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex) | **`contour` meshes** | A swallow-tailed banner and a serrated leaf: four meshes traced off their own alpha, waved by bone timelines and rippled by a `deform` |
 | [`gallery/ride`](https://github.com/firejune/rigc/tree/main/gallery/ride) | `path` attachments + **path constraints** | A trolley coasting down a drawn rail and rolling back, driven by a `position` timeline, with `groups` + `stagger` keying the wheels and the ears |
+| [`gallery/portrait`](https://github.com/firejune/rigc/tree/main/gallery/portrait) | **deform `transform`** + `derive` group tracks | A 2.5D head turn: two meshes and six feature bones all keyed from one stated expression, `dx = x(cos t − 1) − z·sin t`, with the depths in the spec rather than a README |
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/rigc-scene.gif" alt="A portrait rig breathing, glancing aside, then turning its head in 2.5D — hair and features sliding at different depths" width="600" />
+</p>
+
+<p align="center"><em>The portrait rig playing its three animations in one take — the turn is
+the shot: both silhouette edges move apart, which a flat slide cannot do, because every
+feature carries its own depth. Scene direction of this kind was Live2D's territory; the
+split was authoring cost, and the cost is now one stated expression per key. Compiled and
+rendered entirely by the published package.</em></p>
 
 ## Commands
 
@@ -419,7 +430,7 @@ commands take it and what its default is.
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
-| `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies |
+| `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies. A bone with two or more anchored descendants is **determined** rather than searched, and the residual that over-determination leaves is reported |
 | `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
 | `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
@@ -447,6 +458,7 @@ the art. Its shape is under
 | Document | For |
 | --- | --- |
 | 📘 **[docs/AUTHORING.md](docs/AUTHORING.md)** | **the format guide, and the one to read before writing a spec.** Both input files field by field with a complete minimal example each, every field with its Spine meaning, the rules that decide what is emitted, the build → read the report → fix → repeat loop, the map from every named failure to the file that has to change, and the features rigc refuses by name so you do not spend a loop discovering them. It travels **inside the npm package**, at `node_modules/spine-rigc/docs/AUTHORING.md` |
+| 🦴 **[docs/RIGGING.md](docs/RIGGING.md)** | **authoring the hierarchy.** Where a bone goes and why the art is pushed out on an offset, why a pivot in the wrong place looks like a search failure and what identifies one, moving a pivot and the child row that gets forgotten, gauges, siblings-not-a-chain, what a chain can reach and how many links it needs, why a local key is not a world key, duplicate art at mirrored pivots, and constraints as structure. Every section is a stumble the run records hold more than once, ranked by how often. Ships in the package too |
 | 🎞️ **[docs/MOTION.md](docs/MOTION.md)** | **the key-pose recipe.** How to get two poses, what a pair of poses does and does not fix, the in-betweening rules and where each comes from, and how to spread candidates so a ballot informs. Ships in the package too |
 | 🙂 **[docs/FACE.md](docs/FACE.md)** | **authoring a face.** A blink, a gaze and a 2.5D head turn on plain Spine data: the one line of yaw arithmetic every number in a turn comes from, depth as the parameter you are actually authoring, where to put a grid's columns and the angle at which any grid folds, what foreshortens and what does not, channel allocation before the first key, and the three cliffs with their angles. Also the deform audit gap, demonstrated — a folded mesh gates green — and the differential check that works today |
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
@@ -491,7 +503,7 @@ that an agent authors a spineboy-scale rig from the brief alone in one run: the
 ladder has not demonstrated that, and each row records which of the two it is.
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 39 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 40 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).

package/cli.ts

@@ -58,10 +58,17 @@ import {
 } from './src/bonedist.ts';
 import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
 import { compile, CompileError, type CompileOptions } from './src/compile.ts';
+import {
+  skeletonDataFromText,
+  surveyDeformKeys,
+  type DeformExtreme,
+  type DeformKeyMeasure,
+} from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
 import { copyAtlasImages } from './src/emit.ts';
 import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
+import { KEY_TIME_EPSILON } from './src/timelines.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
 import {
   DEFAULT_MAX_RESIDUAL,
@@ -79,6 +86,7 @@ import {
   ChainFitError,
   DEFAULT_HINGE_MAX,
   DEFAULT_HINGE_MIN,
+  DEFAULT_MIN_LEVER_PX,
   DEFAULT_MIN_VISIBLE,
   DEFAULT_PASSES,
   estimateChainFit,
@@ -105,7 +113,8 @@ import {
   type FrameSet,
 } from './src/render.ts';
 import { CLI_DEFAULT_PROFILE, reportLines, validate, VALIDATE_PROFILES, type ValidateProfile } from './src/validate.ts';
-import type { CompileResult, MotionSpec } from './src/types.ts';
+import { parseMotionSpec } from './src/motion.ts';
+import type { CompileResult } from './src/types.ts';
 
 /**
  * One entry of a cuts.json, every path relative to the cuts.json file.
@@ -172,8 +181,19 @@ function repositoryUrl(): string {
  * Listed by name rather than inferred from "the next argument looks like a
  * flag": inferring it would turn `--out --json report.json` — a real typo, a
  * missing value — into a silently accepted switch plus a stray positional.
+ *
+ * ⚠️ This set and `FLAG_VALUES` are two halves of one statement, and they are
+ * the halves a reader and the parser read separately: a flag absent from
+ * `FLAG_VALUES` is printed bare in every usage line and flag table, and a flag
+ * present here is the only kind the parser will accept bare. `all-bones` was in
+ * one half and not the other for two releases — documented bare in `bonedist`'s
+ * usage line, in the shared flag table, and in the hint `src/bonedist.ts` prints
+ * under a truncated bone table, while the parser fell through to the value
+ * branch and answered the caller who followed that hint with `rigc: --all-bones
+ * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
+ * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'help', 'copy-images', 'again', 'pack']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -431,6 +451,264 @@ 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).
+ *
+ * ## Why side by side is the whole point
+ *
+ * The complaint that filed #295 was not the line count. `gallery/portrait`'s
+ * held yaw put six sibling bones' `translatex` in six separate tracks, and the
+ * reason that is bad is that **nobody can see a wrong sign in a column that is
+ * eighty lines from its neighbours.** FACE §3 makes the same argument from the
+ * other side: a residual is 1–6 units where a total is 30–40, and the split is
+ * *an auditing decision before it is a rigging one*. So the report's job is to
+ * put the numbers in the arrangement the audit needs — one row per member, one
+ * block per key — which is exactly the arrangement the emitted format cannot
+ * have, because Spine keys one bone per timeline.
+ *
+ * ## It quotes; it does not re-derive
+ *
+ * The same rule as the `DEFORM` block. Every value here is the one the compiler
+ * **emitted**, carried on `result.trackDerivations`, so the block and the
+ * artifact cannot disagree. `derived` and `formula` are the model's own strings
+ * from `src/trackgen.ts`, so the block names the closed form the spec stated
+ * rather than a second reading of it.
+ *
+ * ## What it deliberately does not print
+ *
+ * **Tracks whose members all share one value** — the ordinary `groups` entry.
+ * There is one number there and the timelines above already show it on every
+ * member; a table of six identical rows would be a tautology, and the block
+ * exists to make a *difference* visible. `look_l`/`look_r` in the worked example
+ * are exactly that case and they are right to be absent from here.
+ *
+ * **`stagger`.** A per-member time offset is printed as it always was — on each
+ * member's own timeline, where the shifted key times are. Repeating it here
+ * would put one lag in two places.
+ */
+function memberReportLines(result: CompileResult): string[] {
+  if (result.trackDerivations.length === 0) return [];
+  const out: string[] = [
+    '',
+    'group members  (the per-member values of one track, side by side — issue #295)',
+    '  ..    a row per member and a block per key, because a wrong sign is visible in a column of six and',
+    '  ..    invisible in six tracks. Values are the EMITTED ones, so this and the artifact cannot disagree',
+    '  ..    a group whose members all share one value is not here: there is one number and the timelines',
+    '  ..    above already carry it. `stagger` is not here either — the shifted key times are on those timelines',
+  ];
+  for (const entry of result.trackDerivations) {
+    const states =
+      entry.model === null
+        ? 'stated per member'
+        : `derive ${entry.model.kind}  ${entry.model.stated}  -> ${entry.model.projection === 'shift' ? 'the displacement' : 'the narrowing'}`;
+    out.push(
+      `  MEMBER  ${entry.animation}  ${entry.targetKind} "${entry.target}".${entry.property}  ` +
+        `t=${entry.time.toFixed(6)}  ${entry.members.length} member(s)  ${states}`,
+    );
+    if (entry.model !== null) {
+      out.push(`          ${entry.model.formula}`);
+      for (const line of entry.model.derived) out.push(`            ${line}`);
+    }
+    const width = Math.max(6, ...entry.members.map((m) => m.member.length));
+    for (let i = 0; i < entry.members.length; i++) {
+      const m = entry.members[i];
+      const value = Array.isArray(m.value) ? m.value.join(', ') : JSON.stringify(m.value);
+      // The model's own row carries the two inputs that produced the value — the
+      // coordinate it read off the rig and the depth the spec stated — because
+      // "5.513" alone is a number a reader can only take on trust, and `−62` and
+      // `150` beside it are a claim they can check.
+      const from = entry.model === null ? '' : `  <- ${entry.model.members[i].at >= 0 ? ' ' : ''}${entry.model.members[i].at} at depth ${entry.model.members[i].depth}`;
+      out.push(`            ${m.member.padEnd(width)}  ${value.padStart(12)}${from}`);
+    }
+  }
+  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 the compiler's own key-time grid plus one float32 ulp at this magnitude,
+ * which is narrower than any key spacing the format can hold and wide enough for
+ * both roundings.
+ */
+function sameKeyTime(specTime: number, loaded: number): boolean {
+  return Math.abs(specTime - loaded) <= KEY_TIME_EPSILON + Math.abs(loaded) * 2 ** -23;
+}
+
+/**
+ * The `DEFORM` report block — what each deform key does to the geometry, per key
+ * and then per animation (issue #316).
+ *
+ * ## Why this is a report and not an assertion
+ *
+ * Because a 3× stretch is a real thing to author, for the same reason issue #277
+ * settled mesh coverage as a printed figure on authored geometry rather than a
+ * bar. The one deformed-geometry fault that has no legitimate counter-example is
+ * the fold, and that one already IS an assertion —
+ * `A39_DEFORM_KEEPS_TRIANGLE_WINDING`. What this block adds is **the approach to
+ * that wall**: FACE §4.2's table of ratios down to the fold at 31.37° was
+ * measured by rendering seven variants of `gallery/portrait` and looking at them,
+ * and `0.637` was a number an author derived from the closed form rather than one
+ * the tool printed.
+ *
+ * ## It quotes; it does not re-derive
+ *
+ * - the reversal and collapse counts are the **survey's**, which is A39's own
+ *   survey ([`src/deformmeasure.ts`](src/deformmeasure.ts)) — one measurement,
+ *   two readers, so the block and the gate cannot disagree about a fold;
+ * - a key's model is the **compiler's** `transform` report (§4.11.1), so the
+ *   block names the same `kind` and parameters the spec stated;
+ * - the fold ANGLE is nowhere here. It is A39's, derived at run time from the
+ *   grid, and a second copy of it printed beside a ratio would be a number that
+ *   goes stale when somebody moves a column.
+ *
+ * ## And what it deliberately does not print
+ *
+ * **Deformed coverage**, which #296 asked for. The coverage figure is rasterised
+ * from the attachment's **uvs** against the part's alpha, and a deform moves
+ * positions and never uvs — so it is identical at every key by construction, and
+ * a `coverage 100.00% (setup 100.00%)` line would be a tautology wearing a
+ * measurement's clothes. The header line says so and points at `meshes`, because
+ * 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[] {
+  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',
+      '  ..    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}`,
+    );
+    // 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
+      ? 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 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.
+  for (const animation of [...new Set(survey.keys.map((k) => k.animation))]) {
+    const keys = survey.keys.filter((k) => k.animation === animation);
+    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);
+    out.push(
+      `  WORST   ${animation}  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(animation.length)}  reversed ${reversed}, collapsed ${collapsed}, over ` +
+        `${keys.length} key(s) and ${samples} triangle sample(s)  <- A39 reads the same two counts`,
+    );
+  }
+  return out;
+}
+
 /**
  * Read one non-negative integer flag, or its default.
  *
@@ -1141,6 +1419,11 @@ function cmdChainFit(flags: Record<string, string>): void {
     if (!Number.isInteger(value) || value < 1 || value > 8) throw new UsageError('--passes must be a whole number in 1..8');
     options.passes = value;
   }
+  if (flags['inward-lever'] !== undefined) {
+    const value = Number(flags['inward-lever']);
+    if (!Number.isFinite(value) || value < 0) throw new UsageError('--inward-lever must be a number of frame pixels, 0 or more');
+    options.minLeverPx = value;
+  }
   if (flags['anchor-residual'] !== undefined) {
     const value = Number(flags['anchor-residual']);
     if (!Number.isFinite(value) || value <= 0 || value > 1) throw new UsageError('--anchor-residual must be a number in (0, 1]');
@@ -1693,7 +1976,10 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  ..    rig    ${opts.rigPath}`);
   console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
-  const motion = readJsonFile(opts.motionPath) as MotionSpec;
+  // `compile` has already parsed this file, so the read below cannot fail — but
+  // it goes through the same parser rather than a cast, because the cast was the
+  // last one in the repository and issue #307 was about exactly that.
+  const motion = parseMotionSpec(readJsonFile(opts.motionPath), opts.motionPath);
 
   console.log(`\nstage  ${result.skeleton.skeleton.width} x ${result.skeleton.skeleton.height}  (spine ${result.skeleton.skeleton.spine})`);
 
@@ -1813,6 +2099,30 @@ function cmdExplain(flags: Record<string, string>): void {
                 : 'back to the setup pose';
               const curve = Array.isArray(key.curve) ? `bezier[${key.curve.length}]` : key.curve === 'stepped' ? 'stepped' : 'linear';
               console.log(`      t=${String(key.time).padEnd(7)} ${span.padEnd(46)} ${curve}`);
+              // A generated key prints its MODEL and then every offset the model
+              // produced (issue #294). Both halves are the point: the model is
+              // what a reviewer checks a claim against, and the offsets are what
+              // reaches the file — printing only the first would ask a reader to
+              // trust an evaluation they cannot see, which is the gap FACE §9.3
+              // records. The numbers are the emitted ones, not a second
+              // evaluation, so this block and the artifact cannot disagree.
+              const gen = result.deformTransforms.find(
+                (g) => g.animation === animName && g.skin === skinName && g.slot === slotName && g.attachment === attName && g.time === key.time,
+              );
+              if (gen === undefined) continue;
+              console.log(`               transform ${gen.kind}  ${gen.stated}`);
+              console.log(`               ${gen.formula}`);
+              for (const line of gen.derived) console.log(`                 ${line}`);
+              console.log(
+                `               ${gen.vertexCount} vertices, largest offset ${gen.maxOffset}px at vertex ${gen.maxOffsetVertex}`,
+              );
+              for (let v = 0; v < gen.vertexCount; v += 4) {
+                const pairs: string[] = [];
+                for (let k = v; k < Math.min(v + 4, gen.vertexCount); k++) {
+                  pairs.push(`v${String(k).padStart(3)} (${gen.offsets[2 * k]}, ${gen.offsets[2 * k + 1]})`);
+                }
+                console.log(`                 ${pairs.join('  ')}`);
+              }
             }
           }
         }
@@ -1834,6 +2144,16 @@ function cmdExplain(flags: Record<string, string>): void {
     }
   }
 
+  // The `MEMBER` block sits beside the `DEFORM` one and for the same reason:
+  // both re-print timelines the reader has just read, in the arrangement the
+  // question needs rather than the one the format has.
+  for (const line of memberReportLines(result)) console.log(line);
+
+  // 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);
+
   if (result.physics.length) {
     console.log('\nphysics constraints (4.3 top-level `constraints` array, type per entry)');
     for (const ph of result.physics) {
@@ -1997,6 +2317,10 @@ const FLAG_MEANINGS: Record<string, string> = {
   'anchor-residual':
     `the residual a \`pose\` placement must be within to anchor a chain (default ${ANCHOR_MAX_RESIDUAL}, with ` +
     `unexplained ≤ ${ANCHOR_MAX_UNEXPLAINED} and unambiguous — the 2026-09-03 measurement run's own clean-frame criterion)`,
+  'inward-lever':
+    `how far apart, in frame pixels, two anchored descendants have to sit before the rotation they determine is ` +
+    `printed (default ${DEFAULT_MIN_LEVER_PX}); below it the bone is refused \`no-bracket\` naming the measured ` +
+    'lever, because an angle read across a short lever turns a half-pixel anchor error into several degrees',
   animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
   max: 'longest side of a rendered frame, in pixels (default 256)',
   record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
@@ -2041,6 +2365,7 @@ const FLAG_VALUES: Record<string, string> = {
   'min-visible': '<0..1>',
   passes: '<n>',
   'anchor-residual': '<0..1>',
+  'inward-lever': '<px>',
   animation: '<name>',
   max: '<px>',
   record: '<result.json>',
@@ -2193,6 +2518,7 @@ const COMMANDS: CommandDoc[] = [
       'max-residual',
       'passes',
       'anchor-residual',
+      'inward-lever',
       'scale',
       'rotation',
       'out',