@rig-c/core 2.59.0 → 2.61.0

package/src/cli/core_commands.ts

@@ -38,6 +38,7 @@ import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine }
 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 { readSeamPairs, SEAM_FILE, seamFileOf, seamLine, SeamError, type SeamPair, seamsOf, seamText } from '../seam.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, 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';
@@ -45,9 +46,10 @@ import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
 import { GUIDE_FILE, GUIDE_RULE_TABLES_ELSEWHERE, guideAnswer, refusalLine } from '../guide.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
+import { ATLAS_ABSENT, COMMANDS, type CommandRun, DelegateError, modelTextBeside, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, GuideError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson, documentStageBeside } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 
 const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> = {
@@ -561,6 +563,23 @@ function readPassThroughFlag(raw: string | undefined, facts: SkeletonFacts): Pas
   }
 }
 
+/**
+ * `--seam <a>:<b>[,…]` read against the skeleton's slots (issue #1456,
+ * `../seam.ts`), or refused as a usage error before anything is posed: a
+ * malformed list, an empty name, a slot the skeleton does not have, a slot paired
+ * with itself, a pair named twice in either order — each by its entry.
+ * `undefined` without the flag.
+ */
+function readSeamFlag(raw: string | undefined, facts: SkeletonFacts): SeamPair[] | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    return readSeamPairs(raw, facts.slots.map((slot) => slot.name));
+  } catch (err) {
+    if (err instanceof SeamError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
 /**
  * `--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
@@ -685,6 +704,21 @@ export function cmdRender(flags: Record<string, string>): void {
     }
   }
 
+  // The seam reading (issue #1456) is its own flag for --folds' reason, and refused beside a subset for --pass-through's:
+  // it reads the two slots as the whole rig draws them.
+  const seam = flags.seam;
+  if (seam !== undefined) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--seam takes no --${flag}: it reads the two slots as the whole rig draws them, which a subset of the drawn slots ` +
+            `would change. Run \`rigc render --seam\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --seam for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
+
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
   console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
@@ -702,7 +736,10 @@ export function cmdRender(flags: Record<string, string>): void {
   const only = readAnimationFlag(flags, [...facts.animations]);
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
+  // The physics constraints the skeleton declares, off the Spine file both posers read (issue #1467).
+  const physicsDeclared = environmentResponse(skeletonText).declared;
   const passPairs = readPassThroughFlag(passThrough, facts);
+  const seamPairs = readSeamFlag(seam, 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
@@ -774,8 +811,15 @@ export function cmdRender(flags: Record<string, string>): void {
     // the export's grid is this frame set's by construction.
     // 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 wantsGeometry = geometry || folds || passPairs !== undefined || seamPairs !== undefined;
+    // The physics constraints each frame's step stepped ride along whenever the rig declares one (issue #1467): the
+    // `physics:` line and frames.json's `physics` field are read off them.
+    const sampling = {
+      ...pose,
+      ...(wantsBones ? { bones: true } : {}),
+      ...(wantsGeometry ? { geometry: true } : {}),
+      ...(physicsDeclared.length > 0 ? { physics: true } : {}),
+    };
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -828,6 +872,34 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
+    // The seam reading, off the very pieces the frames are drawn from — one per set, every pair the flag names. A pair
+    // whose slot draws on no frame of any set drawn is refused, as --pass-through refuses it, rather than read as a SKIP.
+    const seamReadings = new Map<string, ReturnType<typeof seamFileOf>>();
+    if (seamPairs !== undefined) {
+      const draws = new Set<string>();
+      for (const frames of sampled.values()) for (const frame of frames) for (const piece of frame.pieces) draws.add(piece.slot);
+      for (const pair of seamPairs) {
+        for (const slot of [pair.a, pair.b]) {
+          if (!draws.has(slot)) {
+            throw new UsageError(
+              `--seam: slot ${JSON.stringify(slot)} draws on no frame of [${[...sampled.keys()].join(', ')}]${skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`} ` +
+                '— it shows no region or mesh there, so it has no drawing to read a seam of',
+            );
+          }
+        }
+      }
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const shown = frames.map((frame) => frame.attachments ?? []);
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, pieces: frame.pieces, attachments: frame.attachments ?? [] }));
+        try {
+          seamReadings.set(name, seamFileOf(animation, fps, skin, seamsOf(seamPairs, poser.rest(skin, shown), read, pages)));
+        } catch (err) {
+          if (err instanceof SeamError) throw new UsageError(`--seam, ${JSON.stringify(name)}: ${err.message}`);
+          throw err;
+        }
+      }
+    }
     // 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) {
@@ -841,9 +913,9 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings };
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings };
   });
-  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, seamReadings, angleReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -853,6 +925,8 @@ export function cmdRender(flags: Record<string, string>): void {
     );
   }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
+  // Whether physics ran (issue #1467): said once for a rig with nothing to step, and per set below for one with.
+  if (physicsDeclared.length === 0) console.log(`  ..    ${PHYSICS_NONE_LINE}`);
   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);
@@ -893,7 +967,10 @@ export function cmdRender(flags: Record<string, string>): void {
     if (foldReading !== undefined) writeFileSync(join(dir, FOLDS_FILE), foldsText(foldReading));
     const passReading = passReadings.get(name);
     if (passReading !== undefined) writeFileSync(join(dir, PASS_THROUGH_FILE), passThroughText(passReading));
+    const seamReading = seamReadings.get(name);
+    if (seamReading !== undefined) writeFileSync(join(dir, SEAM_FILE), seamText(seamReading));
     const duration = frames[frames.length - 1].time;
+    const physics = physicsDeclared.length === 0 ? undefined : physicsSteppedOf(frames, fps);
     sets.push({
       dir: dirName,
       animation: name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name,
@@ -902,14 +979,18 @@ export function cmdRender(flags: Record<string, string>): void {
       written: frames.length,
       stride: 1,
       duration,
+      ...(physics === undefined ? {} : { physics: { stepped: physics.stepped.length, fps } }),
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
     const foldNote = foldReading === undefined ? '' : ` + ${FOLDS_FILE} (${folding} of ${foldReading.meshes.length} mesh(es) fold)`;
     const passing = passReading?.pairs.filter((p) => p.frames.length > 0).length ?? 0;
     const passNote = passReading === undefined ? '' : ` + ${PASS_THROUGH_FILE} (${passing} of ${passReading.pairs.length} pair(s) pass through)`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}`;
+    const opening = seamReading?.pairs.filter((p) => p.opens.length > 0).length ?? 0;
+    const seamNote = seamReading === undefined ? '' : ` + ${SEAM_FILE} (${opening} of ${seamReading.pairs.length} pair(s) open)`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}${seamNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
+    if (physics !== undefined) console.log(`  ..    ${physicsLine(physics.stepped, physicsDeclared, fps, frames.length)}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
       const fault = faultsSaid.has(key) ? null : setupFaultLine(mesh);
@@ -922,6 +1003,7 @@ 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 pair of seamReading?.pairs ?? []) console.log(`  ..    seam     ${seamLine(seamReading?.animation ?? null, fps, pair)}`);
     for (const reading of angleReadings.get(name) ?? []) {
       console.log(`  ..    angle    ${angleRangeLine(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, reading)}`);
     }
@@ -954,6 +1036,28 @@ export function cmdRender(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
 }
 
+/** `render`'s line for a rig that declares no physics constraint (issue #1467): nothing was stepped because nothing could be. */
+export const PHYSICS_NONE_LINE = 'physics: none in this rig — it declares no physics constraint, so no frame steps one';
+
+/** The physics constraints any frame of a set stepped (issue #1467), by name in code-unit order. */
+export function physicsSteppedOf(frames: readonly Frame[], fps: number): { stepped: string[]; fps: number } {
+  const names = new Set<string>();
+  for (const frame of frames) for (const name of frame.physics ?? []) names.add(name);
+  return { stepped: [...names].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)), fps };
+}
+
+/**
+ * `render`'s `physics:` line for one set (issue #1467): how many constraints were stepped at the set's rate, and — when
+ * fewer than the rig declares — the ones that took no step, by name, with why a constraint takes none.
+ */
+export function physicsLine(stepped: readonly string[], declared: readonly string[], fps: number, frames: number): string {
+  const head = `physics: ${stepped.length} constraint(s) stepped at ${fps} fps`;
+  const idle = declared.filter((name) => !stepped.includes(name));
+  if (idle.length === 0) return head;
+  const why = frames === 1 ? 'a single pose takes no step' : 'inactive, or a mix of 0, on every frame';
+  return `${head} — ${idle.length} of the ${declared.length} declared took none: ${idle.map((n) => JSON.stringify(n)).join(', ')} (${why})`;
+}
+
 /** Where `inspect` writes when `--out` is not given, and the name it takes inside a directory `--out` names. */
 export const DEFAULT_INSPECT_OUT = 'inspect.png';
 
@@ -1283,7 +1387,7 @@ export function cmdExplain(flags: Record<string, string>): void {
   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);
+  const { label, opts } = resolveCut(flags, 'explain');
   console.log(`rigc explain ${label}`);
   // See the identical pair of lines in `cmdBuild` for why both paths are named
   // here rather than only the one the header's `label` happens to carry.
@@ -2103,6 +2207,72 @@ export const MODEL_AND_TEXT_GATE: BuildGate = {
   look: (outDir) => `rigc: look at it: rigc render --candidate ${outDir}`,
 };
 
+/**
+ * Where a delegated package's `package.json` resolves, or `null` (issue #1457).
+ *
+ * ⚖️ Node's `node_modules` lookup — `<dir>/node_modules/<package>` for the
+ * directory and then each of its ancestors, nearest first — from two places in
+ * this order, the first answer winning:
+ *
+ *   1. the working directory — the project `npm i -D <package>` installed it
+ *      into, which is what the refusal tells a caller to run, so a project's
+ *      own install is the one its command line reaches;
+ *   2. this package's root — where an install of rig-c sits beside it in the
+ *      same `node_modules` and the command was run from somewhere else.
+ *
+ * 🚨 Walked here rather than asked of the runtime's resolver: Bun's resolves a
+ * package it cannot find, from a directory with no `node_modules` above it, by
+ * installing it on demand into its global cache — measured, a directory with
+ * none resolved `@rig-c/review` there — so "not installed" would never be
+ * refused, and asking would reach the network. `NODE_PATH` and the global
+ * folders are not read: what the refusal tells a caller to run never puts a
+ * package there. The bin is read off the `package.json` found, not resolved.
+ */
+function resolveDelegate(name: string): string | null {
+  for (const from of [process.cwd(), PACKAGE_ROOT]) {
+    for (let dir = resolve(from); ; dir = dirname(dir)) {
+      const manifest = join(dir, 'node_modules', name, 'package.json');
+      if (existsSync(manifest)) return manifest;
+      if (dirname(dir) === dir) break;
+    }
+  }
+  return null;
+}
+
+/**
+ * A delegating command's body (`CommandDoc.delegate`, issue #1457): resolve the
+ * package's bin and run it under the Bun running this — the bin is a Bun script
+ * — with every argument untouched and stdio inherited, then exit with its code,
+ * or die by its signal the way `bin/rigc.cjs` does, so a caller reads what it
+ * would have read running the bin itself. Not installed, it is refused by name
+ * with the one command that installs it, exit 2, and nothing else is printed.
+ */
+function cmdDelegate(command: string, raw: readonly string[]): void {
+  const delegate = COMMANDS.find((c) => c.name === command)?.delegate;
+  if (delegate === undefined) throw new Error(`internal: ${command} names no delegate`);
+  const manifest = resolveDelegate(delegate.package);
+  if (manifest === null) throw new DelegateError(`${delegate.package} is not installed — npm i -D ${delegate.package}`, 2);
+  const bins = (readJsonFile(manifest) as { bin?: unknown }).bin;
+  const relativeBin = typeof bins === 'object' && bins !== null ? (bins as Record<string, unknown>)[delegate.bin] : undefined;
+  const bin = typeof relativeBin === 'string' ? join(dirname(manifest), relativeBin) : null;
+  if (bin === null || !existsSync(bin)) {
+    throw new DelegateError(
+      `${delegate.package} at ${dirname(manifest)} ${bin === null ? `declares no "${delegate.bin}" bin` : `declares the "${delegate.bin}" bin ${String(relativeBin)}, which is not there`} — npm i -D ${delegate.package}`,
+      2,
+    );
+  }
+  const ran = spawnSync(process.execPath, [bin, ...raw], { stdio: 'inherit' });
+  // ⚠️ The exit and the signal are read before `error`: Bun 1.2.0 — the declared minimum — sets `error` on every
+  // child that exits non-zero, so reading it first refused review's own exit 7 as "could not run". `error` is a
+  // launch that failed only where the child left neither a status nor a signal.
+  if (typeof ran.status === 'number') process.exit(ran.status);
+  if (ran.signal !== null) {
+    process.kill(process.pid, ran.signal);
+    return;
+  }
+  throw new DelegateError(`could not run ${bin}: ${ran.error?.message ?? 'it left no exit status and no signal'}`, 1);
+}
+
 /**
  * split — one authored mesh's pieces, proposed as one mesh each (issue #1414).
  *
@@ -2182,4 +2352,5 @@ export const CORE_COMMAND_RUNS: Readonly<Record<string, CommandRun>> = {
   chainfit: ({ flags }) => cmdChainFit(flags),
   guide: ({ flags, positional }) => cmdGuide(flags, positional),
   skills: ({ flags, positional }) => cmdSkills(flags, positional),
+  review: ({ raw }) => cmdDelegate('review', raw),
 };

package/src/cli/shared.ts

@@ -38,7 +38,8 @@ import { checkAgainstFrames, type CheckOptions, CheckPlates, type CheckReport }
 import { compile, CompileError, droppedStateReason, headerBoundsOf, type CompileOptions } from '../compile.ts';
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { FOLDS_FILE } from '../folds.ts';
-import { PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
+import { DRAWN_ALPHA, PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
+import { SEAM_FILE } from '../seam.ts';
 import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
@@ -93,6 +94,19 @@ export type CutTable = Record<string, CutEntry>;
 
 export class UsageError extends Error {}
 
+/**
+ * A usage error that is one required flag missing from a spelled-out cut —
+ * printed as its one line and exit 2, without the usage block under it (issue
+ * #1466). The catalogue under `--out is required` buried the only line that
+ * said what to add, which is `PoseError`'s reason for printing alone. Still a
+ * `UsageError`, so every reader that asks whether an invocation was refused
+ * reads it as one.
+ */
+export class MissingFlagError extends UsageError {}
+
+/** The `<value>` each flag of a spelled-out cut takes, for the line that names a missing one. */
+const CUT_FLAG_VALUES = { rig: '<rig.json>', motion: '<motion.json>', out: '<dir>' } as const;
+
 /**
  * `explain` refusing a pair it cannot pose — a usage error in kind, printed
  * without the usage block for `PoseError`'s and `IngestError`'s reason: the
@@ -263,7 +277,7 @@ function entryToOptions(dir: string, name: string, entry: CutEntry): CompileOpti
  * Resolve the cut a command was pointed at, either spelled out on the command
  * line or looked up by name in a cuts.json.
  */
-export function resolveCut(flags: Record<string, string>): { label: string; opts: CompileOptions } {
+export function resolveCut(flags: Record<string, string>, command: 'build' | 'explain' | 'validate'): { label: string; opts: CompileOptions } {
   const explicit =
     flags.rig !== undefined || flags.manifest !== undefined || flags.motion !== undefined || flags.out !== undefined;
   if (explicit) {
@@ -271,7 +285,7 @@ export function resolveCut(flags: Record<string, string>): { label: string; opts
       throw new UsageError('--rig/--motion/--out and --cut/--cuts are two ways to say the same thing; pick one');
     }
     for (const key of ['rig', 'motion', 'out'] as const) {
-      if (flags[key] === undefined) throw new UsageError(`--${key} is required when the cut is spelled out`);
+      if (flags[key] === undefined) throw new MissingFlagError(`${command} needs --${key} ${CUT_FLAG_VALUES[key]} (or --cut <name> --cuts <cuts.json>)`);
     }
     const opts: CompileOptions = {
       rigPath: resolve(flags.rig),
@@ -955,6 +969,21 @@ export class SkillsInstallError extends Error {}
 /** `guide` asked for a rule or a section the guide does not have (issue #1397): a refusal by `GUIDE_RULE_KNOWN` or `GUIDE_SECTION_KNOWN`, whose message is the whole line. Exit 1. */
 export class GuideError extends Error {}
 
+/**
+ * A delegating command (`CommandDoc.delegate`, issue #1457) that could not hand
+ * over: the package it delegates to does not resolve, or resolves without the
+ * bin it names. Nothing ran, so the exit is `status` (2) and the message is the
+ * whole of what is printed after `rigc <command>: `.
+ */
+export class DelegateError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // usage / per-command help
 // ---------------------------------------------------------------------------
@@ -1023,6 +1052,13 @@ const FLAG_MEANINGS: Record<string, string> = {
     'world units, one texel of the coarser drawing to a step — each with the depth and the world box. One line per pair, and one per frame that passes through. ' +
     'The order is the declaration: the first name must draw over the second for a frame to be read. A reading, not a gate. ' +
     'An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name. Not with --slot/--hide',
+  seam:
+    `also read, for each <slot>:<slot> pair, where the two drawings stop meeting, and write ${SEAM_FILE} into each frame directory: ` +
+    'per pair, the frames with a gap — background inside the hull of the band the two drawings share at the setup pose, carried to the frame by both — ' +
+    'and the frames with a ghost — the band of one drawing showing where, from its partner\'s point of view, nothing was drawn at the setup pose — each with ' +
+    `its cell count, area and world box. Cells are one texel of the coarser drawing, drawn at ${DRAWN_ALPHA} of 255 or more. One line per pair; a pair whose ` +
+    'drawings share no cell at the setup pose is a SKIP. A reading, not a gate: the exit status never moves. An unknown slot, a slot with itself, ' +
+    'a slot that draws on no frame, a malformed list and a pair named twice in either order are refused by name. Not with --slot/--hide',
   'angle-range':
     'also read, for each <bone>:<relative-to> pair, the range of the first bone\'s world direction against the second\'s over each set\'s ' +
     'frames — its rotationX less the other\'s, followed from frame to frame so a sweep past ±180° reads as itself — and print one line per ' +
@@ -1234,6 +1270,7 @@ const FLAG_VALUES: Record<string, string> = {
   poser: 'core|spine',
   environment: '<schedule.json>',
   'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
+  seam: '<slot>:<slot>[,<slot>:<slot>…]',
   'angle-range': '<bone>:<relative-to>[,…]',
   'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
@@ -1365,6 +1402,15 @@ interface CommandDoc {
    * `diff`) can be moved to another side in one place.
    */
   spineFormat: boolean;
+  /**
+   * A command whose body is another package's bin (issue #1457): the dispatch
+   * hands it every argument after the name untouched — nothing is parsed as a
+   * flag, `--help` included, so its page is the delegate's own — and the
+   * delegate's exit code is the command's. `flags` is empty for that reason:
+   * rigc documents no flag of a program it does not own. A control that reads
+   * a command's flag table off `--help` reads it off the commands without this.
+   */
+  delegate?: { package: string; bin: string };
 }
 
 export const COMMANDS: CommandDoc[] = [
@@ -1686,10 +1732,11 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
       'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
+      'rigc render … --seam <slot>:<slot>[,…]   (the frames where two slots that meet open a gap or show a ghost)',
       'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
       'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'angle-range', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'seam', 'angle-range', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: {
@@ -1891,6 +1938,16 @@ export const COMMANDS: CommandDoc[] = [
       '"Install it into your agent").',
     ],
   },
+  {
+    name: 'review',
+    runtime: false,
+    spineFormat: false,
+    delegate: { package: '@rig-c/review', bin: 'rig-review' },
+    usage: [
+      "rigc review <dir> [...]      (@rig-c/review's rig-review, installed beside: every argument handed over untouched, its exit code returned — `rigc review open <dir>` prints a loopback URL to give a person, `rigc review --help` is rig-review's own usage)",
+    ],
+    flags: [],
+  },
 ];
 
 /** Every command's name, in the order the usage lists them — what the full entry dispatches over. */
@@ -2247,7 +2304,7 @@ function pageRectangle(region: AtlasRegion): string {
  * alone (`./core_commands.ts`). Moved here unchanged from `cmdBuild`.
  */
 export function readBuildInvocation(flags: Record<string, string>): { label: string; opts: CompileOptions; profile: AssertionProfile; packing: boolean } {
-  const { label, opts } = resolveCut(flags);
+  const { label, opts } = resolveCut(flags, 'build');
   const profile = readProfile(flags);
   const packing = flags.pack !== undefined;
   // Two combinations are refused rather than silently resolved, because in each
@@ -2731,6 +2788,8 @@ export interface CommandArgs {
   flags: Record<string, string>;
   lists: Record<string, string[]>;
   positional: string[];
+  /** Every argument after the command's name, as given — what a delegating command (`CommandDoc.delegate`) hands over. */
+  raw: readonly string[];
 }
 
 /** One command's body, as an entry registers it. */
@@ -2931,13 +2990,18 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
       if (elsewhere !== undefined) throw commandNeedsRuntime(elsewhere, known, rest);
       throw new UsageError(`unknown command: ${command}`);
     }
+    // A delegating command reads nothing here: not a flag, not `--help` (issue #1457).
+    if (docs.find((doc) => doc.name === command)?.delegate !== undefined) {
+      entry.runs[command]({ flags: {}, lists: {}, positional: [], raw: rest });
+      return;
+    }
 
     const { flags, lists, positional } = parseArgs([...rest], REPEATABLE_FLAGS[command]);
     if (flags.help !== undefined) {
       console.log(commandHelp(command, docs));
       process.exit(0);
     }
-    entry.runs[command]({ flags, lists, positional });
+    entry.runs[command]({ flags, lists, positional, raw: rest });
   } catch (err) {
     refuse(err, command, USAGE, entry);
   }
@@ -2950,6 +3014,10 @@ export function runCli(entry: CliEntry, argv: readonly string[]): void {
  * (`CliEntry.refusals`). Anything else is not a refusal and is thrown on.
  */
 function refuse(err: unknown, command: string | undefined, USAGE: string, entry: CliEntry): never {
+  if (err instanceof MissingFlagError) {
+    console.error(`rigc: ${err.message}`);
+    process.exit(2);
+  }
   if (err instanceof UsageError) {
     console.error(`rigc: ${err.message}\n\n${USAGE}`);
     process.exit(2);
@@ -3107,5 +3175,11 @@ function refuse(err: unknown, command: string | undefined, USAGE: string, entry:
     console.error(err.message);
     process.exit(1);
   }
+  // A delegate that could not be handed the run (issue #1457): one line naming the package and what to run, nothing else —
+  // the usage under it would bury the one command that fixes it.
+  if (err instanceof DelegateError) {
+    console.error(`rigc ${command}: ${err.message}`);
+    process.exit(err.status);
+  }
   throw err;
 }

package/src/cli/spine_commands.ts

@@ -76,7 +76,7 @@ export function cmdValidate(flags: Record<string, string>, positional: string[])
   // a directory alone cannot supply — and the report says which it had.
   const named = flags.cut !== undefined || flags.rig !== undefined;
   const profile = readProfile(flags);
-  const derivedOpts = named ? resolveCut(flags).opts : null;
+  const derivedOpts = named ? resolveCut(flags, 'validate').opts : null;
   // Both files there before the first line, from the one statement of a build (issue #1046): a directory without them
   // read the skeleton unguarded and died on an ENOENT and a stack.
   const { skeletonPath, atlasPath } = spinePairOf(resolveBuild(derivedOpts ? derivedOpts.outDir : (positional[0] ?? '.'), flags.atlas));

package/src/compile.ts

@@ -18,7 +18,7 @@
  * the two emits byte for byte (assertion A18).
  */
 import { basename, dirname, join, relative, resolve } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { readPngHeader, readPngInfo } from './png.ts';
 import {
   DEPTH_TONE_IDENTITY,
@@ -1649,8 +1649,62 @@ function easingCurve(
 // inputs
 // ---------------------------------------------------------------------------
 
-function readJson<T>(path: string): T {
+/**
+ * Which input a JSON path was given as, for the refusal a directory gets: the
+ * flag that named it, the file it wants, and whether a file's contents read as
+ * one (`null` where no parser exists here — the manifest is cast, not parsed).
+ */
+interface JsonInputRole {
+  flag: '--rig' | '--motion' | '--manifest';
+  wants: string;
+  reads: ((raw: unknown, where: string) => unknown) | null;
+}
+
+const RIG_INPUT: JsonInputRole = { flag: '--rig', wants: 'the rig spec file', reads: parseRigSpec };
+const MOTION_INPUT: JsonInputRole = { flag: '--motion', wants: 'the motion spec file', reads: parseMotionSpec };
+const MANIFEST_INPUT: JsonInputRole = { flag: '--manifest', wants: 'the cut manifest file', reads: null };
+
+/** The most `.json` names a directory refusal lists before it says how many there are. */
+const LISTED_JSON_NAMES = 8;
+
+/**
+ * The refusal for an input flag that names a directory (issue #1466): what the
+ * flag wants, and what the directory holds — the one file there that reads as
+ * that input, named by its path, or every `.json` there when that is not
+ * exactly one. Nothing is accepted on the strength of it: the caller is told
+ * the path, and the compile still reads only what it was given. The names are
+ * sorted, so the sentence is the same on every machine.
+ */
+function directoryInputRefusal(dir: string, role: JsonInputRole): string {
+  const head = `${role.flag} names a directory; it wants ${role.wants} —`;
+  const names = readdirSync(dir)
+    .filter((name) => name.endsWith('.json') && statSync(join(dir, name)).isFile())
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (names.length === 0) return `${head} ${dir} holds no .json file`;
+  const reading = names.filter((name) => {
+    if (role.reads === null) return true;
+    const file = join(dir, name);
+    try {
+      role.reads(parseJsonWithPosition(readFileSync(file, 'utf8')), file);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (reading.length === 1) return `${head} ${join(dir, reading[0])} exists there`;
+  const listed = (list: string[]): string =>
+    list.slice(0, LISTED_JSON_NAMES).join(', ') + (list.length > LISTED_JSON_NAMES ? `, … ${list.length} in all` : '');
+  if (reading.length === 0) {
+    return `${head} ${dir} holds ${names.length} .json file(s) and none reads as one: ${listed(names)}`;
+  }
+  return `${head} ${reading.length} .json files in ${dir} read as one, so name it: ${listed(reading)}`;
+}
+
+function readJson<T>(path: string, role: JsonInputRole): T {
   let text: string;
+  if (existsSync(path) && statSync(path).isDirectory()) {
+    throw new CompileError(directoryInputRefusal(path, role), 'CE_COMPILE_JSON_READ_FAILED');
+  }
   try {
     text = readFileSync(path, 'utf8');
   } catch (err) {
@@ -2309,11 +2363,11 @@ function compileInto(opts: CompileOptions, droppedStates: DroppedState[]): Compi
   const manifestPath = opts.manifestPath === undefined ? null : resolve(opts.manifestPath);
   const manifestDir = manifestPath === null ? null : dirname(manifestPath);
 
-  const rig = parseRigSpec(readJson<unknown>(rigPath), rigPath);
+  const rig = parseRigSpec(readJson<unknown>(rigPath, RIG_INPUT), rigPath);
   // Parsed, not cast, since issue #307 — `src/motion.ts` states what it proves
   // and which refusals it deliberately leaves in this file.
-  const motion = parseMotionSpec(readJson<unknown>(motionPath), motionPath);
-  const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath);
+  const motion = parseMotionSpec(readJson<unknown>(motionPath, MOTION_INPUT), motionPath);
+  const manifest = manifestPath === null ? null : readJson<FaceManifest>(manifestPath, MANIFEST_INPUT);
   // The manifest is the record of what was measured, and its numbers become
   // bone positions and the stage: a `crop.h` of 1e309 built as `"height": null`
   // before issue #881. The rig spec's walk is `parseRigSpec`'s; this is the

package/src/passthrough.ts

@@ -238,7 +238,7 @@ export function texelSize(piece: Piece, vertices: ArrayLike<number>, page: Plate
 }
 
 /** The cells `piece` draws at half opacity or more over `viewport`, row major, 1 where drawn. */
-function drawnCells(piece: Piece, page: Plate, viewport: Viewport): Uint8Array {
+export function drawnCells(piece: Piece, page: Plate, viewport: Viewport): Uint8Array {
   const cells = new Uint8Array(viewport.width * viewport.height);
   rasterisePiece(page, piece, projector(viewport), viewport, (px, py, _r, _g, _b, a) => {
     if (a >= DRAWN_ALPHA) cells[py * viewport.width + px] = 1;
@@ -251,7 +251,7 @@ function drawnCells(piece: Piece, page: Plate, viewport: Viewport): Uint8Array {
  * renderer's own traversal over a one-cell grid centred on the point, so the
  * test is the frame's pixel test and nothing re-derived beside it.
  */
-function drawsAt(piece: Piece, page: Plate, x: number, y: number, cell: number): boolean {
+export function drawsAt(piece: Piece, page: Plate, x: number, y: number, cell: number): boolean {
   const viewport: Viewport = { minX: x - cell / 2, minY: y - cell / 2, maxX: x + cell / 2, maxY: y + cell / 2, scale: 1 / cell, width: 1, height: 1 };
   let drawn = false;
   rasterisePiece(page, piece, projector(viewport), viewport, (_px, _py, _r, _g, _b, a) => {
@@ -427,7 +427,7 @@ function runsAt(
 const restKey = (slot: string, attachment: string): string => `${slot}\u0000${attachment}`;
 
 /** Whether two vertex lists are the same numbers — a piece drawn from its attachment whole, not cut by a clip. */
-function sameVertices(a: ArrayLike<number>, b: ArrayLike<number>): boolean {
+export function sameVertices(a: ArrayLike<number>, b: ArrayLike<number>): boolean {
   if (a.length !== b.length) return false;
   for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
   return true;

package/src/render.ts

@@ -549,9 +549,25 @@ function spinePosed(skeleton: Skeleton): Posed {
     pieces: (draw) => drawPieces(skeleton, draw),
     bones: () => boneSnapshots(skeleton),
     attachments: () => attachmentsOf(skeleton),
+    physics: () => steppedPhysicsOf(skeleton),
   };
 }
 
+/**
+ * `Posed.physics` on spine-core (issue #1467): every physics constraint whose
+ * `lastTime` reads the skeleton's `time` after a step that moved it — which
+ * `PhysicsConstraint.update` sets under `Physics.update` and `Physics.reset`,
+ * and which an inactive constraint, a mix of 0 or `Physics.none` leaves where
+ * it was. The setup pose and frame 0 sit at time 0 and step none.
+ */
+function steppedPhysicsOf(skeleton: Skeleton): string[] {
+  if (!(skeleton.time > 0)) return [];
+  return skeleton.physics
+    .filter((c) => c.lastTime === skeleton.time)
+    .map((c) => c.data.name)
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
 /**
  * A fresh skeleton under `skin`, stepped into its setup pose — the one recipe
  * `sampleSetupPose` and the geometry export's `rest` table both pose from, so