spine-rigc 2.55.0 → 2.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.55.0",
+  "version": "2.57.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/skills/rigc/SKILL.md

@@ -100,7 +100,10 @@ row for each.
    parts were not kept, and writes only after every region and the skeleton are
    shown unchanged (`--accept-skeleton-differences` writes a rebuild whose skeleton
    differs, every difference printed; `--stage-box <slot>` reads a build's stage box)
-   — AUTHORING §0.4.
+   — AUTHORING §0.4. A mesh refused because its triangles are several pieces that
+   share no vertex: `rigc split --rig … --motion … --slot <slot> --out <dir>` writes
+   both specs back with one mesh per piece and every deform key renumbered — build
+   that — AUTHORING §3.4.11.
 7. Every finished unit ends with `rigc preview --candidate <out>`, and the report
    names the `.html` it wrote. The hand-off to a person is part of the work.
 

package/src/anglerange.ts

@@ -0,0 +1,190 @@
+/**
+ * How far one bone turns against another over an animation — the reading behind
+ * `rigc render --angle-range <bone>:<relative-to>[,…]` (issue #1414).
+ *
+ * ⭐ **A reading, not a gate**, as `--folds` and `--pass-through` are. A physics
+ * value has no scale an author can see: §4.6 lists `inertia`, `strength` and the
+ * rest with their bounds, and nothing said what `inertia` 0.5 does to a 54-unit
+ * chain under a hip swing — the first try on a real rig was four times too big.
+ * The answer is a number the pose already holds: how far the link turned against
+ * the bone it hangs from. So this reads it off the frames `render` draws and
+ * decides nothing.
+ *
+ * ## What the range is
+ *
+ * At each frame the bones are posed by whichever poser draws the frames, and each
+ * bone's **world direction** is that poser's own `rotationX` — the direction its x
+ * axis points, degrees counter-clockwise, y up (`BoneSnapshot`), never a second
+ * opinion recomputed from the matrix here. The relative angle is
+ *
+ *     rotationX(bone) − rotationX(relative-to)
+ *
+ * taken into (−180, 180] on the first frame read, and then **followed**: each
+ * later frame's difference is moved by whole turns to within half a turn of the
+ * frame before it. So a link that sweeps 200° reads 200°, not −160°, and one that
+ * sways through ±180° does not read a jump of a whole turn. Following assumes no
+ * two consecutive frames are half a turn or more apart, which a frame grid that
+ * coarse could not show anyway.
+ *
+ * ⚠️ It is the angle **drawn**, not the bone's local `rotation`. The two agree for
+ * a child of the other bone when the parent carries no non-uniform scale or shear;
+ * otherwise they differ, and the drawn one is what a viewer sees.
+ *
+ * The range is over the frames on the render's own grid — `--fps`, from t = 0 to
+ * the animation's last frame — so a peak between two frames is not read. A bone
+ * the posed skin leaves unposed, or one scaled to nothing, has no direction: its
+ * world matrix is zero, and the reading is refused naming the bone and the frame
+ * rather than read as 0°.
+ *
+ * Pure: no clock, no randomness, no runtime. The bone snapshots are handed in by
+ * whichever poser drew the frames.
+ */
+import type { BoneSnapshot } from './render_shared.ts';
+
+/** One pair as the flag names it: the bone whose angle is read, and the bone it is read against. */
+export interface BonePair {
+  bone: string;
+  relativeTo: string;
+}
+
+/** A malformed `--angle-range` value, or a pose the reading has no angle for — said by name. */
+export class AngleRangeError extends Error {}
+
+/**
+ * `--angle-range`'s value — `<bone>:<relative-to>[,<bone>:<relative-to>…]` —
+ * read against the skeleton's bones, or refused naming the entry: an empty
+ * entry, one without exactly one `:`, an empty name, a bone the skeleton does not
+ * have (with the bones it does), a bone read against itself (always 0°), and a
+ * pair named twice.
+ */
+export function readBonePairs(raw: string, bones: readonly string[]): BonePair[] {
+  const form = '<bone>:<relative-to>[,<bone>:<relative-to>…]';
+  const pairs: BonePair[] = [];
+  const entries = raw.split(',');
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i].trim();
+    if (entry === '') throw new AngleRangeError(`--angle-range ${JSON.stringify(raw)}: entry ${i} is empty — it takes ${form}`);
+    const parts = entry.split(':');
+    if (parts.length !== 2) {
+      throw new AngleRangeError(`--angle-range: entry ${i} ${JSON.stringify(entry)} has ${parts.length - 1} ":" — it takes ${form}, one ":" per pair`);
+    }
+    const [bone, relativeTo] = parts.map((p) => p.trim());
+    for (const [role, name] of [['bone', bone], ['relative-to bone', relativeTo]] as const) {
+      if (name === '') throw new AngleRangeError(`--angle-range: entry ${i} ${JSON.stringify(entry)} names no ${role} — it takes ${form}`);
+      if (!bones.includes(name)) {
+        throw new AngleRangeError(`--angle-range: entry ${i} names ${role} ${JSON.stringify(name)}, which this skeleton does not have; its bones are [${bones.join(', ')}]`);
+      }
+    }
+    if (bone === relativeTo) {
+      throw new AngleRangeError(`--angle-range: entry ${i} reads bone ${JSON.stringify(bone)} against itself, which is 0° on every frame — name a second bone`);
+    }
+    const again = pairs.findIndex((p) => p.bone === bone && p.relativeTo === relativeTo);
+    if (again >= 0) throw new AngleRangeError(`--angle-range: entry ${i} names "${bone}:${relativeTo}" again — entry ${again} already reads it`);
+    pairs.push({ bone, relativeTo });
+  }
+  return pairs;
+}
+
+/** One sampled frame: its index, its time, and every bone's world transform. */
+export interface AngleFrame {
+  index: number;
+  time: number;
+  bones: readonly BoneSnapshot[];
+}
+
+/** One extreme of a range: the angle, degrees, and the frame that reached it first. */
+export interface AngleExtreme {
+  degrees: number;
+  index: number;
+  time: number;
+}
+
+/** One pair's reading over one set. */
+export interface AngleRangeReading {
+  bone: string;
+  relativeTo: string;
+  /** Frames read — every frame of the set. */
+  frames: number;
+  low: AngleExtreme;
+  high: AngleExtreme;
+}
+
+/**
+ * Wrong readings the suite plants to see its controls go red (issue #1414):
+ * `worldAngle` reads the bone's own world direction and ignores the bone it is
+ * read against; `noFollow` leaves each frame's difference in (−180, 180] rather
+ * than following it from the frame before.
+ */
+export interface AnglePlant {
+  worldAngle?: true;
+  noFollow?: true;
+}
+
+/** `d` taken into (−180, 180]. */
+function wrapped(d: number): number {
+  let r = d % 360;
+  if (r <= -180) r += 360;
+  if (r > 180) r -= 360;
+  return r;
+}
+
+/** A world matrix with no direction — every entry zero: an unposed bone, or one scaled to nothing. */
+function directionless(b: BoneSnapshot): boolean {
+  return b.a === 0 && b.b === 0 && b.c === 0 && b.d === 0;
+}
+
+/**
+ * Each pair's range over `frames`, in the pairs' order — refused by
+ * `AngleRangeError`, naming the bone and the frame, where a bone has no
+ * direction (`directionless`), and naming the bone where a frame carries no
+ * snapshot of it at all (frames sampled without `{ bones: true }`).
+ */
+export function angleRangesOf(pairs: readonly BonePair[], frames: readonly AngleFrame[], where: string, plant: AnglePlant = {}): AngleRangeReading[] {
+  return pairs.map(({ bone, relativeTo }) => {
+    let previous: number | null = null;
+    let low: AngleExtreme | null = null;
+    let high: AngleExtreme | null = null;
+    for (const frame of frames) {
+      const at = (name: string): BoneSnapshot => {
+        const found = frame.bones.find((b) => b.name === name);
+        if (found === undefined) throw new AngleRangeError(`--angle-range, ${where} frame ${frame.index}: no world transform for bone ${JSON.stringify(name)} was sampled`);
+        if (directionless(found)) {
+          throw new AngleRangeError(
+            `--angle-range, ${where} frame ${frame.index} (t=${frame.time.toFixed(4)}s): bone ${JSON.stringify(name)} has no direction — its world matrix is zero ` +
+              '(a bone the posed skin leaves unposed, or one scaled to nothing), so it has no angle to read',
+          );
+        }
+        return found;
+      };
+      const a = at(bone);
+      const b = at(relativeTo);
+      const difference = plant.worldAngle === true ? a.rotationX : a.rotationX - b.rotationX;
+      let angle = wrapped(difference);
+      if (previous !== null && plant.noFollow !== true) angle += 360 * Math.round((previous - angle) / 360);
+      previous = angle;
+      if (low === null || angle < low.degrees) low = { degrees: angle, index: frame.index, time: frame.time };
+      if (high === null || angle > high.degrees) high = { degrees: angle, index: frame.index, time: frame.time };
+    }
+    if (low === null || high === null) throw new AngleRangeError(`--angle-range, ${where}: no frame was sampled`);
+    return { bone, relativeTo, frames: frames.length, low, high };
+  });
+}
+
+/** Degrees to four places, with a rounding to zero printed as `0.0000` rather than `-0.0000`. */
+export function degreesText(d: number): string {
+  const text = d.toFixed(4);
+  return text === '-0.0000' ? '0.0000' : text;
+}
+
+/**
+ * The printed line: the set, the pair, the low and the high with the frame each
+ * was first reached on, the span, and the grid it was read on.
+ */
+export function angleRangeLine(animation: string | null, fps: number, r: AngleRangeReading): string {
+  const where = animation === null ? 'the setup pose' : JSON.stringify(animation);
+  return (
+    `${where}: bone ${JSON.stringify(r.bone)} against ${JSON.stringify(r.relativeTo)} ranges ${degreesText(r.low.degrees)}° to ${degreesText(r.high.degrees)}° ` +
+    `(a span of ${degreesText(r.high.degrees - r.low.degrees)}°) over ${r.frames} frame(s) at ${fps} fps; ` +
+    `lowest at frame ${r.low.index} (t=${r.low.time.toFixed(4)}s), highest at frame ${r.high.index} (t=${r.high.time.toFixed(4)}s)`
+  );
+}

package/src/cli/core_commands.ts

@@ -21,7 +21,8 @@ import { chainFitLines, type ChainFitOptions, estimateChainFit } from '../chainf
 import { checkLines, CheckPlates } from '../check.ts';
 import { writeCheckPictures } from '../checkpics.ts';
 import { compile, type CompileOptions, droppedStateReason, relativeImagesPath } from '../compile.ts';
-import { CoreInputError } from '../core/index.ts';
+import { CoreInputError, readModel } from '../core/index.ts';
+import { leverFractionWhy, leverHeader, leverLines, leverReading, type LeverReading, type WhirlAnimation, WHIRL_HEADER, whirlLines, whirlReading } from '../whirl.ts';
 import { surveyOfBuild } from '../deformbuild.ts';
 import type { DeformSurvey } from '../deformsurvey.ts';
 import { deformReportBlock } from '../deformreport.ts';
@@ -30,12 +31,16 @@ import { findingLine, ingest, type IngestFinding, IngestSpecRefused, type Ingest
 import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
+import { splitMesh, SplitError } from '../meshsplit.ts';
+import { parseRigSpec } from '../rig.ts';
 import { type InspectCompare, type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readBonePatterns, readShow, readTimes, readZoom } from '../inspect.ts';
 import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine } from '../folds.ts';
+import { AngleRangeError, angleRangeLine, type AngleRangeReading, angleRangesOf, type BonePair, readBonePairs } from '../anglerange.ts';
+import { outsideLine, outsideViewport, pinnedRecord, readViewportBox, viewportOfFramesFile, ViewportError } from '../viewportpin.ts';
 import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
-import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
+import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
@@ -556,6 +561,59 @@ function readPassThroughFlag(raw: string | undefined, facts: SkeletonFacts): Pas
   }
 }
 
+/**
+ * `--angle-range`'s pairs, read against the skeleton's bones (issue #1414,
+ * `../anglerange.ts`), or refused as a usage error before anything is posed: a
+ * malformed list, an empty name, a bone the skeleton does not have, a bone read
+ * against itself, a pair named twice — each by its entry. `undefined` without the flag.
+ */
+function readAngleRangeFlag(raw: string | undefined, facts: SkeletonFacts): BonePair[] | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    return readBonePairs(raw, facts.bones.map((bone) => bone.name));
+  } catch (err) {
+    if (err instanceof AngleRangeError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
+/** A box `render` was given rather than fitting one (issue #1414): the box flag's numbers, or an earlier render's grid. */
+type GivenViewport =
+  | { by: '--viewport'; box: { x: number; y: number; width: number; height: number } }
+  | { by: '--viewport-from'; path: string; viewport: Viewport };
+
+/**
+ * `--viewport` and `--viewport-from`, read before anything is read off the
+ * candidate (`../viewportpin.ts`): the two together are refused, and so is
+ * `--max` beside `--viewport-from`, whose file already fixes the pixel size; a
+ * malformed box, a path with no `frames.json` and a file whose grid is not one
+ * are refused by name. `undefined` without either flag.
+ */
+function readGivenViewport(flags: Record<string, string>): GivenViewport | undefined {
+  const box = flags.viewport;
+  const from = flags['viewport-from'];
+  if (box !== undefined && from !== undefined) {
+    throw new UsageError('--viewport and --viewport-from both give the box the frames are of; give one of them');
+  }
+  try {
+    if (box !== undefined) return { by: '--viewport', box: readViewportBox(box) };
+    if (from === undefined) return undefined;
+    if (flags.max !== undefined) {
+      throw new UsageError(
+        `--viewport-from takes no --max: the frames.json it reads fixes the pixel size as well as the box, so --max ${flags.max} ` +
+          'would put this render on another grid. Give --viewport <x,y,w,h> with --max for a box at another size',
+      );
+    }
+    const given = resolve(from);
+    const path = existsSync(given) && statSync(given).isDirectory() ? join(given, FRAMES_SIDECAR) : given;
+    if (!existsSync(path)) throw new UsageError(`--viewport-from ${from}: no ${FRAMES_SIDECAR} at ${path} — it takes an earlier render's ${FRAMES_SIDECAR}, or the directory \`render --out\` wrote it into`);
+    return { by: '--viewport-from', path, viewport: viewportOfFramesFile(readJsonFile(path), path) };
+  } catch (err) {
+    if (err instanceof ViewportError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
 /**
  * render — the frame series, drawn by the same rasteriser `check` measures with.
  *
@@ -574,6 +632,8 @@ export function cmdRender(flags: Record<string, string>): void {
   // Read before anything is read off the candidate, so a malformed schedule is refused before a line is printed.
   const environment = readEnvironmentFlag(flags);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
+  // A box given rather than fitted (issue #1414), read before a line is printed, so a malformed one is refused first.
+  const given = readGivenViewport(flags);
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
@@ -643,6 +703,8 @@ export function cmdRender(flags: Record<string, string>): void {
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
   const passPairs = readPassThroughFlag(passThrough, facts);
+  // The angle reading (issue #1414) reads bones, which a subset of the drawn slots does not change, so it takes --slot/--hide.
+  const anglePairs = readAngleRangeFlag(flags['angle-range'], facts);
   // One object, so the framing and the frames cannot be posed under two
   // different skins — which would frame one shot with another shot's box.
   // Not annotated `PoseOptions`: that name is `src/pose.ts`'s in this file, and
@@ -686,14 +748,22 @@ export function cmdRender(flags: Record<string, string>): void {
     // 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, roster);
-    if (!viewport) {
+    const fitted = framingViewport(poser, maxSide, pose, roster);
+    if (!fitted) {
       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`,
       );
     }
+    // ⭐ A given box replaces the fitted one, and the framing still runs: it is what refuses a pose with nothing to draw,
+    // one that is not finite and one with no extent, and a box given over such a pose would draw it in silence.
+    const viewport =
+      given === undefined
+        ? fitted
+        : given.by === '--viewport'
+          ? viewportFor(given.box.x, given.box.y, given.box.x + given.box.width, given.box.y + given.box.height, maxSide)
+          : given.viewport;
 
     // `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
@@ -702,7 +772,10 @@ export function cmdRender(flags: Record<string, string>): void {
     // `--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 } : folds || passPairs !== undefined ? { ...pose, geometry: true } : pose;
+    // The bones ride along for --geometry and --angle-range, the whole attachments for --geometry and the two readings off them.
+    const wantsBones = geometry || anglePairs !== undefined;
+    const wantsGeometry = geometry || folds || passPairs !== undefined;
+    const sampling = !wantsBones && !wantsGeometry ? pose : { ...pose, ...(wantsBones ? { bones: true } : {}), ...(wantsGeometry ? { geometry: true } : {}) };
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -755,9 +828,22 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, sampled, geometryTexts, foldReadings, passReadings };
+    // The angle reading, off the very bones the frames were posed with — one per set, every pair the flag names.
+    const angleReadings = new Map<string, AngleRangeReading[]>();
+    if (anglePairs !== undefined) {
+      for (const [name, frames] of sampled) {
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, bones: frame.bones ?? [] }));
+        try {
+          angleReadings.set(name, angleRangesOf(anglePairs, read, JSON.stringify(name)));
+        } catch (err) {
+          if (err instanceof AngleRangeError) throw new UsageError(err.message);
+          throw err;
+        }
+      }
+    }
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings };
   });
-  const { viewport, sampled, geometryTexts, foldReadings, passReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -768,6 +854,17 @@ export function cmdRender(flags: Record<string, string>): void {
   }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
+  // A given box (issue #1414): said with the box it replaced, and every slot it leaves part of out, by set and frame.
+  const outside = given === undefined ? [] : outsideViewport(sampled, viewport);
+  if (given !== undefined) {
+    const f = (n: number): string => String(Number(n.toFixed(4)));
+    const box = (v: Viewport): string => `world x ${f(v.minX)}..${f(v.maxX)}, y ${f(v.minY)}..${f(v.maxY)}`;
+    console.log(
+      `  ..    viewport given by ${given.by}${given.by === '--viewport-from' ? ` ${given.path}` : ''}: ${box(viewport)} at ${f(viewport.scale)} px per unit, y up ` +
+        `(fitted, the box would be ${box(fitted)}) — ${outside.length === 0 ? 'every drawn piece of every frame is inside it' : `${outside.length} slot(s) reach past it, named below`}`,
+    );
+    for (const reading of outside) console.log(`  ..    outside  ${outsideLine(reading, fps)}`);
+  }
 
   mkdirSync(outRoot, { recursive: true });
   const sets: FrameSet[] = [];
@@ -776,7 +873,7 @@ export function cmdRender(flags: Record<string, string>): void {
   for (const [name, frames] of sampled) {
     // Same naming as a reference render: the protocol rate says nothing, any
     // other rate says itself, so two rates of one animation sit side by side.
-    const dirName = fps === PROTOCOL_FPS ? name : `${name}@${fps}fps`;
+    const dirName = frameSetDir(name, fps);
     const dir = join(outRoot, dirName);
     // Cleared rather than written over: a shorter animation would otherwise leave
     // the tail of a longer previous run on disk, and stale frames in a frame set
@@ -825,6 +922,9 @@ export function cmdRender(flags: Record<string, string>): void {
       console.log(`  ..    pass     ${passSummaryLine(passReading?.animation ?? null, fps, pair)}`);
       for (const frame of pair.frames) console.log(`  ..    pass     ${passFrameLine(passReading?.animation ?? null, pair, frame)}`);
     }
+    for (const reading of angleReadings.get(name) ?? []) {
+      console.log(`  ..    angle    ${angleRangeLine(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, reading)}`);
+    }
   }
 
   // The sidecar is what makes this a frame SET rather than a pile of pictures:
@@ -842,6 +942,8 @@ export function cmdRender(flags: Record<string, string>): void {
     ...subsetFields(subset),
     // Written only when a schedule was given (issue #1416): a render without one says nothing and stays the bytes it was.
     ...(environment === undefined ? {} : { environment: environment.steps }),
+    // Written only when the box was given (issue #1414): a fitted render says nothing and stays the bytes it was.
+    ...(given === undefined ? {} : { pinned: pinnedRecord(given.by, outside) }),
     background: BACKGROUND,
     // The one spelling `geometry.json` repeats, so the two files cannot state
     // two boxes for one grid.
@@ -895,12 +997,12 @@ export function cmdInspect(flags: Record<string, string>): void {
   let frame: InspectFrame = { kind: 'shot' };
   if (flags.zoom !== undefined) frame = { kind: 'zoom', ...readZoom(flags.zoom) };
   if (flags.viewport !== undefined) {
-    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
-    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
-      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+    try {
+      frame = { kind: 'viewport', ...readViewportBox(flags.viewport) };
+    } catch (err) {
+      if (err instanceof ViewportError) throw new UsageError(err.message);
+      throw err;
     }
-    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
-    frame = { kind: 'viewport', x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   const target = resolve(flags.out ?? DEFAULT_INSPECT_OUT);
   const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_INSPECT_OUT) : target;
@@ -1176,6 +1278,11 @@ function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
 export 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);
+  // `--lever-fold` is refused by its value before anything compiles, too (issue #1427): the fraction is the caller's and
+  // has no default, so a value that is not one is a usage error rather than a reading taken at a guess.
+  const leverFold = flags['lever-fold'] === undefined ? null : Number(flags['lever-fold']);
+  const leverWhy = leverFold === null ? null : leverFractionWhy(leverFold);
+  if (leverWhy !== null) throw new UsageError(`--lever-fold ${JSON.stringify(flags['lever-fold'])}: ${leverWhy}`);
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
   // See the identical pair of lines in `cmdBuild` for why both paths are named
@@ -1372,6 +1479,24 @@ export function cmdExplain(flags: Record<string, string>): void {
               console.log(`               transform ${gen.kind}  ${gen.stated}`);
               console.log(`               ${gen.formula}`);
               for (const line of gen.derived) console.log(`                 ${line}`);
+              // The envelope's weights, one per vertex, because they are half
+              // of every number below (issue #1413): each offset is
+              // round(w × the un-enveloped offset), and a reader holding these
+              // and the model reproduces the run without a second evaluation.
+              if (gen.envelope !== undefined) {
+                const env = gen.envelope;
+                console.log(`               envelope  ${env.stated}`);
+                console.log(`               ${env.formula}`);
+                console.log(
+                  `                 each offset below is round(w × the un-enveloped offset): ${env.zero} vertex(es) at w 0, ` +
+                    `${env.full} at 1, ${gen.vertexCount - env.zero - env.full} between`,
+                );
+                for (let v = 0; v < env.weights.length; v += 8) {
+                  const ws: string[] = [];
+                  for (let k = v; k < Math.min(v + 8, env.weights.length); k++) ws.push(`v${String(k).padStart(3)} ${env.weights[k]}`);
+                  console.log(`                 w  ${ws.join('  ')}`);
+                }
+              }
               console.log(
                 `               ${gen.vertexCount} vertices, largest offset ${gen.maxOffset}px at vertex ${gen.maxOffsetVertex}`,
               );
@@ -1436,6 +1561,36 @@ export function cmdExplain(flags: Record<string, string>): void {
     for (const ph of result.physics) {
       console.log(`  ${ph.name.padEnd(12)} bone=${ph.bone.padEnd(14)} components=[${ph.components.join(', ')}] mix=${ph.mix} drivesMesh=${ph.drivesMesh}`);
     }
+    // The whirl reading (issue #1423): how far each constraint's bone turns in one step, walked by the core from the
+    // setup pose — `src/whirl.ts` says why that walk and not render's. It decides nothing, so it sits in the report
+    // rather than in the gate, and explain's exit is the same whatever it prints.
+    console.log(`\n${WHIRL_HEADER}`);
+    let reading: WhirlAnimation[] | null = null;
+    try {
+      reading = whirlReading(readModel(modelDocument(result.model, result.skeletonText, result.atlasText), `the whirl reading of ${label}`));
+    } catch (err) {
+      if (!(err instanceof CoreInputError)) throw err;
+      console.log(`  ..    turn     not read — the core refused the model document: ${err.message}`);
+    }
+    if (reading !== null && reading.length === 0) console.log('  ..    turn     not read — the skeleton declares no animation to walk');
+    for (const line of whirlLines(reading ?? [])) console.log(`  ..    turn     ${line}`);
+    // The lever reading (issue #1427): on the same walk, the steps a scaleX drive's inertia lever divides by a collapsed
+    // divisor, and the steps its scale factor jumps. Only when asked for, because its fraction has no default —
+    // and said so when not asked, rather than left out in silence.
+    if (leverFold === null) {
+      console.log('\n  ..    lever    not read — `--lever-fold <fraction>` states the fraction of its setup divisor a scaleX lever is named for dividing below, and it has no default');
+    } else {
+      console.log(`\n${leverHeader(leverFold)}`);
+      let levers: LeverReading | null = null;
+      try {
+        levers = leverReading(readModel(modelDocument(result.model, result.skeletonText, result.atlasText), `the lever reading of ${label}`), leverFold);
+      } catch (err) {
+        if (!(err instanceof CoreInputError)) throw err;
+        console.log(`  ..    lever    not read — the core refused the model document: ${err.message}`);
+      }
+      if (levers !== null && levers.animations.length === 0 && levers.unread.length < result.physics.length) console.log('  ..    lever    not read — the skeleton declares no animation to walk');
+      for (const line of levers === null ? [] : leverLines(levers)) console.log(`  ..    lever    ${line}`);
+    }
   }
 
   // Path constraints, with the curve each one follows MEASURED — its length and
@@ -1947,6 +2102,55 @@ export const MODEL_AND_TEXT_GATE: BuildGate = {
   look: (outDir) => `rigc: look at it: rigc render --candidate ${outDir}`,
 };
 
+/**
+ * split — one authored mesh's pieces, proposed as one mesh each (issue #1414).
+ *
+ * Reads the two spec files and nothing else: a mesh of several pieces does not
+ * compile, so there is no build to read. Writes the proposal — both specs and
+ * `split.json` — into an `--out` that is absent or empty, which is the whole of
+ * how it never overwrites anything: there is no in-place flag, because the
+ * specs it read are the only statement of what the proposal must reproduce,
+ * and a proposal nobody has built yet is not something to put over them.
+ */
+function cmdSplit(flags: Record<string, string>): void {
+  for (const flag of ['rig', 'motion', 'slot', 'out'] as const) {
+    if (flags[flag] === undefined) throw new UsageError(`split needs --${flag}`);
+  }
+  const rigPath = resolve(flags.rig);
+  const motionPath = resolve(flags.motion);
+  const outDir = resolve(flags.out);
+  for (const [flag, path] of [['rig', rigPath], ['motion', motionPath]] as const) {
+    if (!existsSync(path) || !statSync(path).isFile()) throw new SplitError(`--${flag} ${path}: no file there`, 2);
+  }
+  if (existsSync(outDir) && (!statSync(outDir).isDirectory() || readdirSync(outDir).length > 0)) {
+    throw new SplitError(
+      `--out ${outDir} ${statSync(outDir).isDirectory() ? `holds ${readdirSync(outDir).length} entr${readdirSync(outDir).length === 1 ? 'y' : 'ies'}` : 'is a file'}; ` +
+        'the proposal is written into an absent or empty directory only, so it never lands on top of a file — the specs it read included',
+      2,
+    );
+  }
+  const rig = parseRigSpec(readJsonFile(rigPath), rigPath);
+  const motion = parseMotionSpec(readJsonFile(motionPath), motionPath);
+  // The rig spec's `images` is relative to the rig file, and the proposal is written somewhere else: restate it from
+  // there, so every `image` resolves to the file it resolved to before.
+  const imagesDir = resolve(dirname(rigPath), rig.images ?? '.');
+  const images = relativeImagesPath(outDir, imagesDir);
+  console.log(`rigc split ${rigPath}`);
+  console.log(`  ..    motion   ${motionPath}`);
+  const result = splitMesh({ rig, motion, slot: flags.slot, ...(flags.attachment === undefined ? {} : { attachment: flags.attachment }), ...(flags.skin === undefined ? {} : { skin: flags.skin }), images });
+  if (result.kind === 'whole') {
+    console.log(`rigc split: ${result.line}`);
+    return;
+  }
+  for (const line of result.lines) console.log(`  ..    ${line}`);
+  console.log(`  ..    images   ${images}  (the rig spec's own, restated from ${outDir} — it resolves to ${imagesDir})`);
+  mkdirSync(outDir, { recursive: true });
+  writeJson(join(outDir, 'rig.json'), result.rig);
+  writeJson(join(outDir, 'motion.json'), result.motion);
+  writeJson(join(outDir, 'split.json'), result.record);
+  console.log(`rigc: build it with  rigc build --rig ${join(outDir, 'rig.json')} --motion ${join(outDir, 'motion.json')} --out <dir>`);
+}
+
 /**
  * The bodies the second entry runs under a name whose full-entry body is the
  * runtime's (`runtime.core` in `COMMANDS`, issue #1060) — registered by
@@ -1968,6 +2172,7 @@ export const CORE_ENTRY_RUNS: Readonly<Record<string, CommandRun>> = {
 export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   explain: ({ flags }) => cmdExplain(flags),
   ingest: ({ flags, positional }) => cmdIngest(flags, positional),
+  split: ({ flags }) => cmdSplit(flags),
   diff: ({ flags, lists, positional }) => cmdDiff(flags, lists, positional),
   check: ({ flags }) => cmdCheck(flags),
   render: ({ flags }) => cmdRender(flags),