spine-rigc 0.4.0 → 0.6.0

package/cli.ts

@@ -31,13 +31,35 @@
  * Its paths resolve against the cuts.json file itself, so the table travels
  * with the project that owns the art rather than with this repository.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
 import { compile, CompileError, type CompileOptions } from './src/compile.ts';
 import { diffLines, diffSkeletons, sectionFigures, type DiffReport } from './src/diff.ts';
+import { copyAtlasImages } from './src/emit.ts';
+import { parseJsonWithPosition } from './src/json-position.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
-import { DEFAULT_PROFILE, reportLines, validate, VALIDATE_PROFILES, type ValidateProfile } from './src/validate.ts';
+import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
+import {
+  atlasPageNames,
+  BACKGROUND,
+  contactSheet,
+  FRAMES_SIDECAR,
+  FRAMES_SPEC,
+  framingViewport,
+  loadPosable,
+  PROTOCOL_FPS,
+  renderFrame,
+  sampleAll,
+  sampleAnimation,
+  SETUP_POSE_DIR,
+  SHEET_FILE,
+  SHEET_TILE,
+  type Frame,
+  type FramesSidecar,
+  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';
 
 /**
@@ -61,6 +83,40 @@ export type CutTable = Record<string, CutEntry>;
 
 class UsageError extends Error {}
 
+// ---------------------------------------------------------------------------
+// package metadata — the installed version and repository, for `--version`
+// and for naming a remedy `bench` can only give from a repo checkout.
+// ---------------------------------------------------------------------------
+
+interface PackageMeta {
+  version?: string;
+  repository?: string | { url?: string };
+}
+
+let packageMeta: PackageMeta | null | undefined;
+
+/** `package.json` sits next to this file both in the repo and once installed. */
+function readPackageMeta(): PackageMeta | null {
+  if (packageMeta === undefined) {
+    try {
+      packageMeta = JSON.parse(readFileSync(join(import.meta.dir, 'package.json'), 'utf8')) as PackageMeta;
+    } catch {
+      packageMeta = null;
+    }
+  }
+  return packageMeta;
+}
+
+function readVersion(): string {
+  return readPackageMeta()?.version ?? 'unknown';
+}
+
+function repositoryUrl(): string {
+  const repo = readPackageMeta()?.repository;
+  const url = typeof repo === 'string' ? repo : repo?.url;
+  return (url ?? 'https://github.com/firejune/rigc').replace(/^git\+/, '').replace(/\.git$/, '');
+}
+
 // ---------------------------------------------------------------------------
 // argument parsing
 // ---------------------------------------------------------------------------
@@ -72,7 +128,7 @@ class UsageError extends Error {}
  * flag": inferring it would turn `--out --json report.json` — a real typo, a
  * missing value — into a silently accepted switch plus a stray positional.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'help', 'copy-images']);
 
 /** `--flag value` pairs plus the leftover positionals, in order. */
 function parseArgs(argv: string[]): { flags: Record<string, string>; positional: string[] } {
@@ -99,6 +155,21 @@ function parseArgs(argv: string[]): { flags: Record<string, string>; positional:
   return { flags, positional };
 }
 
+/**
+ * Read and parse a JSON file the caller named on the command line — a cuts
+ * table, a candidate or reference skeleton to `diff`. A parse failure names the
+ * file and, best-effort, where inside it the syntax broke (see
+ * `parseJsonWithPosition`); left as a raw `JSON.parse`, it would surface as an
+ * unhandled `SyntaxError` with a stack trace instead of a usage error.
+ */
+function readJsonFile(path: string): unknown {
+  try {
+    return parseJsonWithPosition(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new UsageError(`cannot read ${path}: ${(err as Error).message}`);
+  }
+}
+
 /**
  * Read a cuts.json and resolve its three paths against the file's own
  * directory. Anchoring on the table rather than on the process cwd is what lets
@@ -107,7 +178,7 @@ function parseArgs(argv: string[]): { flags: Record<string, string>; positional:
 function readCutTable(cutsPath: string): { dir: string; table: CutTable } {
   const abs = resolve(cutsPath);
   if (!existsSync(abs)) throw new UsageError(`no cuts file at ${abs}`);
-  const parsed: unknown = JSON.parse(readFileSync(abs, 'utf8'));
+  const parsed = readJsonFile(abs);
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
     throw new UsageError(`${abs}: expected an object of cut name -> { manifest, motion, out }`);
   }
@@ -168,14 +239,17 @@ function resolveCut(flags: Record<string, string>): { label: string; opts: Compi
 // ---------------------------------------------------------------------------
 
 /**
- * Read `--profile`, defaulting to the profile every caller had before the flag
- * existed. An unknown name is a usage error rather than a silent fallback: the
- * fallback would be `spine-html`, so a typo would quietly re-apply the strictest
- * rulebook to data the caller was trying to exempt.
+ * Read `--profile`, defaulting to `spine` — see `CLI_DEFAULT_PROFILE`.
+ *
+ * An unknown name is a usage error rather than a silent fallback, and that
+ * matters in both directions: a typo used to re-apply the strictest rulebook to
+ * data the caller was trying to exempt, and it would now drop the policy layer
+ * from a caller who typed `--profile spine-htlm` and believes they asked for it.
+ * Neither is something to discover from a green.
  */
 function readProfile(flags: Record<string, string>): ValidateProfile {
   const raw = flags.profile;
-  if (raw === undefined) return DEFAULT_PROFILE;
+  if (raw === undefined) return CLI_DEFAULT_PROFILE;
   const found = VALIDATE_PROFILES.find((p) => p === raw);
   if (!found) throw new UsageError(`--profile ${JSON.stringify(raw)}; known profiles: ${VALIDATE_PROFILES.join(', ')}`);
   return found;
@@ -206,6 +280,12 @@ function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
   console.log(`rigc build ${label}`);
+  // Named explicitly and on their own lines rather than folded into the header
+  // above: with two input files, a header that names only one of them (the rig,
+  // historically) reads as though it were the one at fault whenever the error
+  // that follows actually comes from the other.
+  console.log(`  ..    rig    ${opts.rigPath}`);
+  console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
 
   console.log(`  ..    ${result.images.length} part page(s):`);
@@ -241,8 +321,25 @@ function cmdBuild(flags: Record<string, string>): void {
   }
 
   mkdirSync(opts.outDir, { recursive: true });
+
+  // `--copy-images`: `--out` is otherwise NOT self-contained — a page's default
+  // path is relative to the source art (often `../parts/foo.png`), which is
+  // correct for a build sitting beside the project it came from and breaks the
+  // moment the directory is zipped, committed or moved on its own (issue #217).
+  // Opt-in only: the default stays exactly what it has always been.
+  let atlasText = result.atlasText;
+  if (flags['copy-images'] !== undefined) {
+    const copied = copyAtlasImages(result.images, opts.outDir);
+    atlasText = copied.atlasText;
+    console.log(`  ..    copy-images: ${copied.pages.length} page(s) copied into ${opts.outDir}`);
+    for (const p of copied.pages) {
+      const note = p.to === basename(p.from) ? '' : `  (renamed from ${basename(p.from)} — basename collision)`;
+      console.log(`  ..      ${p.region.padEnd(24)} <- ${p.to}${note}`);
+    }
+  }
+
   writeFileSync(join(opts.outDir, 'skeleton.json'), result.skeletonText);
-  writeFileSync(join(opts.outDir, 'skeleton.atlas'), result.atlasText);
+  writeFileSync(join(opts.outDir, 'skeleton.atlas'), atlasText);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.atlas')}`);
 }
@@ -325,10 +422,7 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
   for (const path of [candidatePath, referencePath]) {
     if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
   }
-  const report = diffSkeletons(
-    JSON.parse(readFileSync(candidatePath, 'utf8')),
-    JSON.parse(readFileSync(referencePath, 'utf8')),
-  );
+  const report = diffSkeletons(readJsonFile(candidatePath), readJsonFile(referencePath));
   console.log('rigc diff');
   for (const line of diffLines(report, { candidate: candidatePath, reference: referencePath })) console.log(line);
   if (flags.json !== undefined) {
@@ -411,14 +505,235 @@ function writeJson(target: string, body: unknown): void {
   console.log(`rigc: wrote ${out}`);
 }
 
+// ---------------------------------------------------------------------------
+// seeing the result — render and preview
+// ---------------------------------------------------------------------------
+//
+// ⭐ Why two commands exist for one question. `validate` says the artifact is
+// valid, `check` says how close it is to reference frames — and a first user has
+// neither a reference nor any way to look at what they built. A rig whose head
+// sits visibly off its torso passes the gate, loads in `spine-core` and steps
+// cleanly, because the offsets are the ones the spec asked for. The only remedy
+// is looking (issue #216).
+//
+// `render` looks with OUR rasteriser: PNGs on disk, no browser, no network, and
+// the same frame geometry `check` compares against — so its output is a frame set
+// like any other, sidecar included. `preview` looks with ESOTERIC'S, in one HTML
+// file, which is the stronger statement of the two: a rig that plays there has
+// been played by the reference implementation rather than by ours (issue #151).
+//
+// Both take a COMPILED artifact rather than a rig and motion spec. That is what
+// `check`, `bench` and `validate` all take, it is what `build --out` leaves
+// behind, and it keeps `--out` meaning one thing per command instead of naming
+// the build directory on the way in and the pictures on the way out.
+
+/** Both commands' shared front door: which artifact, and what is in it. */
+function resolveViewable(flags: Record<string, string>): {
+  skeletonPath: string;
+  atlasPath: string;
+  atlasDir: string;
+} {
+  if (flags.candidate === undefined) {
+    throw new UsageError('needs --candidate <dir | skeleton.json> — the directory `build --out` wrote');
+  }
+  const { skeletonPath, atlasPath } = resolveArtifacts(flags.candidate, flags.atlas);
+  for (const path of [skeletonPath, atlasPath]) {
+    if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
+  }
+  return { skeletonPath, atlasPath, atlasDir: dirname(atlasPath) };
+}
+
+/** `--animation`, checked against what the skeleton actually carries. */
+function readAnimationFlag(flags: Record<string, string>, available: string[]): string | undefined {
+  const name = flags.animation;
+  if (name === undefined) return undefined;
+  if (!available.includes(name)) {
+    throw new UsageError(
+      `no animation ${JSON.stringify(name)} in this skeleton; it has [${available.join(', ') || 'none'}]`,
+    );
+  }
+  return name;
+}
+
+function readPositiveNumber(flags: Record<string, string>, key: string, fallback: number, least: number): number {
+  const raw = flags[key];
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < least) throw new UsageError(`--${key} must be a number of at least ${least}`);
+  return value;
+}
+
+/**
+ * render — the frame series, drawn by the same rasteriser `check` measures with.
+ *
+ * The framing is measured across EVERY animation at `FRAMING_FPS` and not across
+ * the one being written, which is `src/render.ts`'s own invariant: the viewport is
+ * a property of the shot, so two animations of one rig — and the same animation at
+ * two rates — land on one pixel grid and stay comparable.
+ */
+function cmdRender(flags: Record<string, string>): void {
+  const { skeletonPath, atlasPath, atlasDir } = resolveViewable(flags);
+  const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
+  const maxSide = readPositiveNumber(flags, 'max', 256, 16);
+  const outRoot = resolve(flags.out ?? 'render');
+
+  console.log('rigc render');
+  console.log(`  ..    skeleton ${skeletonPath}`);
+  console.log(`  ..    atlas    ${atlasPath}`);
+  const { data, pages } = loadPosable(skeletonPath, atlasPath, atlasDir);
+  const only = readAnimationFlag(flags, data.animations.map((a) => a.name));
+
+  const viewport = framingViewport(data, maxSide);
+  if (!viewport) {
+    throw new UsageError(
+      `${skeletonPath} posed no drawable attachment in any animation or in its setup pose — there is nothing to draw`,
+    );
+  }
+
+  // `sampleAll` covers the skeleton with no animation at all, which files its one
+  // setup-pose frame under the reserved name. Narrowing to one animation reuses
+  // the same sampler rather than a second path through it.
+  const sampled: Map<string, Frame[]> =
+    only === undefined ? sampleAll(data, fps) : new Map([[only, sampleAnimation(data, only, fps)]]);
+  console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
+
+  mkdirSync(outRoot, { recursive: true });
+  const sets: FrameSet[] = [];
+  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 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
+    // are indistinguishable from real ones.
+    if (existsSync(dir)) rmSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true });
+    for (let i = 0; i < frames.length; i++) {
+      renderFrame(frames[i], pages, viewport, BACKGROUND).writePng(join(dir, `f${String(i).padStart(4, '0')}.png`));
+    }
+    // One frame has nothing to compare itself against, so it gets no sheet — it
+    // would be the same picture with a border and a "0" on it.
+    const sheet = frames.length > 1;
+    if (sheet) contactSheet(frames, pages, viewport, SHEET_TILE).writePng(join(dir, SHEET_FILE));
+    const duration = frames[frames.length - 1].time;
+    sets.push({
+      dir: dirName,
+      animation: name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name,
+      fps,
+      sampled: frames.length,
+      written: frames.length,
+      stride: 1,
+      duration,
+    });
+    const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
+    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${sheet ? ` + ${SHEET_FILE}` : ''} -> ${dir}`);
+  }
+
+  // The sidecar is what makes this a frame SET rather than a pile of pictures:
+  // the world box every frame is a picture of, so a distance measured in pixels
+  // converts back to the units the rig is authored in — and so `rigc check` can
+  // render something else into the same grid later.
+  const sidecar: FramesSidecar = {
+    spec: FRAMES_SPEC,
+    background: BACKGROUND,
+    viewport: {
+      x: viewport.minX,
+      y: viewport.minY,
+      width: viewport.maxX - viewport.minX,
+      height: viewport.maxY - viewport.minY,
+      scale: viewport.scale,
+      pixelWidth: viewport.width,
+      pixelHeight: viewport.height,
+    },
+    sets: [...sets].sort((a, b) => a.dir.localeCompare(b.dir)),
+  };
+  writeFileSync(join(outRoot, FRAMES_SIDECAR), `${JSON.stringify(sidecar, null, 2)}\n`);
+  console.log(`rigc: wrote ${join(outRoot, FRAMES_SIDECAR)}`);
+}
+
+/** The animation names an emitted skeleton carries, in the order it lists them. */
+function skeletonAnimationNames(skeletonText: string, path: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = parseJsonWithPosition(skeletonText);
+  } catch (err) {
+    throw new UsageError(`cannot read ${path}: ${(err as Error).message}`);
+  }
+  if (typeof parsed !== 'object' || parsed === null) throw new UsageError(`${path} is not a skeleton object`);
+  const animations = (parsed as { animations?: unknown }).animations;
+  if (animations === undefined) return [];
+  if (typeof animations !== 'object' || animations === null || Array.isArray(animations)) {
+    throw new UsageError(`${path} has an "animations" field that is not an object`);
+  }
+  return Object.keys(animations);
+}
+
+/**
+ * preview — the artifact playing in Esoteric's own web player, as one file.
+ *
+ * ⚠️ Nothing is rasterised here and nothing is decoded. The pages go into the
+ * page as the bytes they are on disk, so a preview works for any PNG a BROWSER
+ * can draw rather than for the ones our own decoder reads — which is the right
+ * direction for the command whose whole job is "just show me".
+ */
+function cmdPreview(flags: Record<string, string>): void {
+  const { skeletonPath, atlasPath, atlasDir } = resolveViewable(flags);
+  const skeletonText = readFileSync(skeletonPath, 'utf8');
+  const atlasText = readFileSync(atlasPath, 'utf8');
+  const animations = skeletonAnimationNames(skeletonText, skeletonPath);
+  const chosen = readAnimationFlag(flags, animations);
+
+  // A directory for --out is taken as "put the default name in here", because
+  // `--out render/` is what the sibling command means by the same flag and a
+  // preview written OVER a directory is not a recoverable mistake.
+  const target = resolve(flags.out ?? 'preview.html');
+  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, 'preview.html') : target;
+
+  console.log('rigc preview');
+  console.log(`  ..    skeleton ${skeletonPath}`);
+  console.log(`  ..    atlas    ${atlasPath}`);
+
+  const pages: PreviewPage[] = atlasPageNames(atlasText).map((name) => {
+    const path = join(atlasDir, name);
+    if (!existsSync(path)) {
+      throw new UsageError(
+        `the atlas declares page "${name}", which resolves to ${path} and is not there — ` +
+          'a page a preview cannot embed is a page the player could not have loaded either',
+      );
+    }
+    return { name, bytes: readFileSync(path) };
+  });
+  for (const page of pages) {
+    console.log(`  ..    page     ${page.name.padEnd(28)} ${(page.bytes.length / 1024).toFixed(1)} KiB`);
+  }
+
+  const html = buildPreview({
+    skeletonText,
+    atlasText,
+    pages,
+    animation: chosen ?? animations[0] ?? null,
+    animations,
+    label: skeletonPath,
+    version: readVersion(),
+  });
+  mkdirSync(dirname(out), { recursive: true });
+  writeFileSync(out, html);
+  console.log(
+    `  ..    embedded ${pages.length} page(s) + the skeleton and atlas as data URIs; ` +
+      `the player itself loads from unpkg (@${PLAYER_LINE}), so the first open needs a network`,
+  );
+  console.log(`rigc: wrote ${out}  (${(html.length / 1024).toFixed(1)} KiB — open it in a browser)`);
+}
+
 /**
  * bench — run one rung of the benchmark ladder against a candidate rig.
  *
  * Two questions, asked in this order and never merged:
  *
  *   1. Is the candidate valid Spine at all? That is `validate --profile spine`,
- *      and it is the only part with a pass/fail. `spine-html` is not the default
- *      here (it is everywhere else): the thing being reproduced is an editor
+ *      and it is the only part with a pass/fail. The profile is pinned here, not
+ *      inherited from the CLI default: the thing being reproduced is an editor
  *      export, and holding it to this project's renderer policy would fail rungs
  *      for reasons the rung is not about.
  *   2. How close is it, structurally, to the reference? That is `diff`, and it
@@ -438,13 +753,22 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
   if (!rung) throw new UsageError(`unknown rung ${JSON.stringify(rungId)}; known: ${RUNG_IDS.join(', ')}`);
   if (flags.candidate === undefined) throw new UsageError('bench needs --candidate <dir | skeleton.json>');
 
-  // bench judges a reproduction of editor output, so `spine` is the default.
-  const profile = flags.profile === undefined ? 'spine' : readProfile(flags);
+  // bench judges a reproduction of editor output, so `spine` is PINNED here
+  // rather than inherited. It reads the same as the CLI default today (#221) and
+  // is kept as its own statement anyway: the ladder's stage-1 gate is defined by
+  // `docs/GATE.md` as `validate --profile spine`, and a bench run must go on
+  // meaning that whatever a later release decides the default should be.
+  const profile: ValidateProfile = flags.profile === undefined ? 'spine' : readProfile(flags);
   const exportDir = resolve(import.meta.dir, 'examples', rung.example, 'export');
   if (!existsSync(exportDir)) {
-    throw new UsageError(
-      `no example corpus at ${exportDir} — run \`bun run fetch-examples\` first (examples/ is gitignored, not shipped)`,
-    );
+    // `bun run fetch-examples` runs `scripts/fetch-examples.sh`, and `scripts/`
+    // is not in package.json's `files` — an npm install has no such script to
+    // run. Its presence is what tells the two contexts apart, so the remedy
+    // named here is one that actually exists in whichever context this is.
+    const remedy = existsSync(resolve(import.meta.dir, 'scripts', 'fetch-examples.sh'))
+      ? 'run `bun run fetch-examples` first'
+      : `bench needs a checkout of ${repositoryUrl()} — its \`fetch-examples\` script is not part of the installed package`;
+    throw new UsageError(`no example corpus at ${exportDir} — ${remedy} (examples/ is gitignored, not shipped)`);
   }
 
   const { skeletonPath, atlasPath } = resolveArtifacts(flags.candidate, flags.atlas);
@@ -615,10 +939,14 @@ function cmdBench(flags: Record<string, string>, positional: string[]): void {
 
 function cmdExplain(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
+  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.
+  console.log(`  ..    rig    ${opts.rigPath}`);
+  console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
-  const motion = JSON.parse(readFileSync(opts.motionPath, 'utf8')) as MotionSpec;
+  const motion = readJsonFile(opts.motionPath) as MotionSpec;
 
-  console.log(`rigc explain ${label}`);
   console.log(`\nstage  ${result.skeleton.skeleton.width} x ${result.skeleton.skeleton.height}  (spine ${result.skeleton.skeleton.spine})`);
 
   // The crop note describes where the numbers CAME from, and without a manifest
@@ -725,35 +1053,198 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  default=${motion.mix?.default ?? 0} pairs=${JSON.stringify(motion.mix?.pairs ?? [])}`);
 }
 
+// ---------------------------------------------------------------------------
+// usage / per-command help
+// ---------------------------------------------------------------------------
+
+/**
+ * One meaning per flag name, shared by every command that takes it — the
+ * single place this project states what a flag means. AUTHORING.md §0 quotes
+ * this table for `build`'s `--rig`/`--motion`/`--out`/`--images`/`--manifest`/
+ * `--profile`; if the two ever disagree, this is the one the code runs.
+ */
+const FLAG_MEANINGS: Record<string, string> = {
+  rig: 'the rig spec — skeleton structure',
+  motion: 'the motion spec — time',
+  out: 'directory for skeleton.json + skeleton.atlas; atlas page paths are written relative to it',
+  images: "override the rig spec's own images directory (relative to your working directory)",
+  manifest: 'a cut manifest, for a rig with measured art behind it; a foreign skeleton has none',
+  'copy-images':
+    'also copy every referenced page PNG into --out and rewrite the atlas to the copies, so the directory is ' +
+    'self-contained enough to zip or commit on its own (default: page paths still point at the source art)',
+  cut: 'look up a named cut in --cuts <cuts.json>, instead of --rig/--motion/--out',
+  cuts: 'the cuts.json --cut names',
+  profile:
+    'which rulebook to check against (default: spine) — spine = valid Spine 4.3 that any runtime plays ' +
+    "correctly; spine-html = also this project's renderer/archetype policy",
+  atlas: "the candidate's atlas, when it is not beside the skeleton",
+  candidate: 'a compiled skeleton: a directory holding skeleton.json + skeleton.atlas, or a skeleton.json path',
+  frames: 'a rendered reference frame set (a skeleton root, or one animation directory)',
+  fps: 'frame rate, only for a frame set with no frames.json sidecar',
+  viewport: "pin the candidate's world box, y up, instead of fitting it",
+  framing: 'fit each frame set on its own (default) or once across all of them',
+  as: 'the candidate animation to play, when it is named differently from the frame set',
+  'all-frames': 'print every frame, not just the worst by MAE',
+  json: 'also write the whole report to this path',
+  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)',
+  help: "show this command's flags and exit",
+};
+
+/** The `<value>` a flag takes, for its column in a command's flag table. Absent for a boolean switch. */
+const FLAG_VALUES: Record<string, string> = {
+  rig: '<path>',
+  motion: '<path>',
+  out: '<dir>',
+  images: '<dir>',
+  manifest: '<path>',
+  cut: '<name>',
+  cuts: '<path>',
+  profile: 'spine|spine-html',
+  atlas: '<path>',
+  candidate: '<dir|skeleton.json>',
+  frames: '<dir>',
+  fps: '<n>',
+  viewport: '<x,y,w,h>',
+  framing: 'per-shot|shared',
+  as: '<name>',
+  json: '<out>',
+  animation: '<name>',
+  max: '<px>',
+};
+
+interface CommandDoc {
+  name: string;
+  /** One or more invocation forms, each already spelling the command name. */
+  usage: string[];
+  /** Flag names (into FLAG_MEANINGS/FLAG_VALUES), in display order. `--help` is appended automatically. */
+  flags: string[];
+  /**
+   * Per-command wording for a flag whose value or meaning genuinely differs here.
+   *
+   * ⚠️ The default above it — one meaning per flag name, everywhere — is the rule
+   * and this is the named exception to it, not a second table. Two flags earn it:
+   * `--out` is a directory of artifacts to `build`, a directory of pictures to
+   * `render` and one file to `preview`; `--fps` is the rate a frame set was
+   * RECORDED at to `check`, which reads it off a sidecar, and the rate to SAMPLE
+   * at to `render`, which is choosing it. Writing either as one sentence covering
+   * every command would leave every command's own help less true than it is now.
+   */
+  overrides?: Record<string, { value?: string; meaning?: string }>;
+}
+
+const COMMANDS: CommandDoc[] = [
+  {
+    name: 'build',
+    usage: [
+      'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
+      'rigc build --cut <name> --cuts <cuts.json>',
+    ],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'copy-images', 'cut', 'cuts', 'profile'],
+  },
+  {
+    name: 'explain',
+    usage: ['rigc explain  (same arguments as build, minus --profile — it never gates)'],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'cut', 'cuts'],
+  },
+  {
+    name: 'validate',
+    usage: [
+      'rigc validate <dir | skeleton.json> [--atlas <path>] [--profile spine|spine-html]',
+      'rigc validate --cut <name> --cuts <cuts.json>   (also re-derives declared durations)',
+    ],
+    flags: ['atlas', 'profile', 'cut', 'cuts', 'rig', 'motion', 'out', 'manifest', 'images'],
+  },
+  {
+    name: 'diff',
+    usage: ['rigc diff <candidate.json> <reference.json> [--json <out>]'],
+    flags: ['json'],
+  },
+  {
+    name: 'check',
+    usage: ['rigc check --candidate <dir | skeleton.json> --frames <dir> [flags]'],
+    flags: ['candidate', 'frames', 'atlas', 'fps', 'viewport', 'framing', 'as', 'all-frames', 'json'],
+  },
+  {
+    name: 'bench',
+    usage: [`rigc bench <${RUNG_IDS.join(' | ')}> --candidate <dir | skeleton.json> [--frames <dir>] [flags]`],
+    flags: ['candidate', 'atlas', 'frames', 'profile', 'all-frames', 'json'],
+  },
+  {
+    name: 'render',
+    usage: [
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--fps 12] [--max 256] [--out render/]',
+    ],
+    flags: ['candidate', 'atlas', 'animation', 'fps', 'max', 'out'],
+    overrides: {
+      out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
+      fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
+    },
+  },
+  {
+    name: 'preview',
+    usage: ['rigc preview --candidate <dir | skeleton.json> [--animation <name>] [--out preview.html]'],
+    flags: ['candidate', 'atlas', 'animation', 'out'],
+    overrides: {
+      out: {
+        value: '<file>',
+        meaning: 'the .html file to write (default `preview.html`); a directory means "the default name in here"',
+      },
+    },
+  },
+];
+
+const KNOWN_COMMANDS = COMMANDS.map((c) => c.name);
+
+/** `rigc <command> --help`: that command's own usage line(s) and flag table. */
+function commandHelp(name: string): string {
+  const doc = COMMANDS.find((c) => c.name === name);
+  if (!doc) throw new Error(`internal: no help text for command "${name}"`);
+  const keys = [...doc.flags, 'help'];
+  const value = (key: string): string | undefined => doc.overrides?.[key]?.value ?? FLAG_VALUES[key];
+  const meaning = (key: string): string => doc.overrides?.[key]?.meaning ?? FLAG_MEANINGS[key];
+  const labels = keys.map((key) => `--${key}${value(key) ? ` ${value(key)}` : ''}`);
+  const width = Math.max(...labels.map((l) => l.length)) + 2;
+  return ['usage:', ...doc.usage.map((u) => `  ${u}`), '', 'flags:', ...keys.map((key, i) => `  ${labels[i].padEnd(width)}${meaning(key)}`)].join(
+    '\n',
+  );
+}
+
 const USAGE = [
+  'rigc — the rig compiler',
+  '',
+  '(from a source checkout: `bun cli.ts <command>` is the same as `rigc <command>`)',
+  '',
   'usage:',
-  '  bun cli.ts build    --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>]',
-  '  bun cli.ts build    --cut <name> --cuts <cuts.json>',
-  '  bun cli.ts explain  (same arguments as build)',
-  '  bun cli.ts validate <dir | skeleton.json> [--atlas <path>]',
-  '  bun cli.ts diff     <candidate.json> <reference.json> [--json <out>]',
-  '  bun cli.ts check    --candidate <dir | skeleton.json> --frames <dir>',
-  `  bun cli.ts bench    <${RUNG_IDS.join(' | ')}> --candidate <dir | skeleton.json> [--frames <dir>]`,
+  ...COMMANDS.flatMap((c) => c.usage.map((u) => `  ${u}`)),
   '',
-  'build and validate take --profile spine|spine-html (default spine-html):',
+  '  rigc <command> --help    that command\'s own flag table',
+  '  rigc --version           print the installed version (-v works too)',
+  '',
+  'build, validate and bench take --profile spine|spine-html:',
   '  spine       is this valid Spine 4.3 that any runtime plays correctly?',
-  '  spine-html  the above, plus this project\'s renderer and archetype policy.',
+  '              THE DEFAULT — 20 rules, and the question the output answers when',
+  '              you import it into the Spine editor.',
+  '  spine-html  the above, plus this project\'s renderer and archetype policy:',
+  '              all 34 rules, opt-in. Those extra 14 fire on real, correct,',
+  '              editor-produced Spine data, so they are somebody\'s policy rather',
+  '              than anybody\'s validity.',
+  '',
+  'Every report names the profile that judged it and lists, on PROF lines, the',
+  'rules that profile left out.',
   '',
   'check renders the candidate onto the reference frames\' own pixel grid, fitting it',
   'there by its own drawn pixels, and compares. It reads the frames and never the',
   'reference skeleton, so it belongs INSIDE an authoring loop — the validator cannot',
-  'see a wrong animation and this can:',
-  '  --frames <dir>        a rendered frame set (a skeleton root, or one animation dir)',
-  '  --atlas <path>        the candidate\'s atlas, when it is not beside the skeleton',
-  '  --fps <n>             only for a frame set with no frames.json sidecar',
-  '  --viewport x,y,w,h    pin the candidate\'s world box, y up, instead of fitting it',
-  '  --framing per-shot|shared   decide the framing per frame set (default), or once',
-  '                        across all of them. Per set, a set whose own pixels land in',
-  '                        frames.json\'s box is measured there; on a multi-shot root that',
-  '                        is worth 15-25 MAE against one shared fit for every set',
-  '  --as <name>           the candidate animation to play, when it is named differently',
-  '  --all-frames          print every frame, not just the worst by MAE',
-  '  --json <out>          the whole per-frame, per-slot report',
+  'see a wrong animation and this can. See `rigc check --help` for its flags.',
+  '',
+  'render and preview are how you LOOK at a build, and they need no reference at all:',
+  '  rigc render  --candidate <the dir build --out wrote>    PNG frames + a contact sheet',
+  '  rigc preview --candidate <the same dir>                 one .html file that plays it',
+  'A rig with its head off its torso passes the gate and steps cleanly — the offsets',
+  'are the ones you asked for — so looking is the only thing that catches it. render',
+  'draws with rigc\'s own rasteriser; preview embeds the artifact in a page that plays',
+  'it in the official Spine Web Player, which is also the interop proof.',
   '',
   'a cuts.json is { "<name>": { "rig": "...", "motion": "...", "out": "...",',
   '                             "manifest": "..." (optional) } }, with every path',
@@ -762,17 +1253,35 @@ const USAGE = [
 
 const [command, ...rest] = process.argv.slice(2);
 try {
+  if (command === undefined) {
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (command === '--version' || command === '-v') {
+    console.log(readVersion());
+    process.exit(0);
+  }
+  if (command === '--help' || command === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!KNOWN_COMMANDS.includes(command)) {
+    throw new UsageError(`unknown command: ${command}`);
+  }
+
   const { flags, positional } = parseArgs(rest);
+  if (flags.help !== undefined) {
+    console.log(commandHelp(command));
+    process.exit(0);
+  }
   if (command === 'build') cmdBuild(flags);
   else if (command === 'validate') cmdValidate(flags, positional);
   else if (command === 'explain') cmdExplain(flags);
   else if (command === 'diff') cmdDiff(flags, positional);
   else if (command === 'check') cmdCheck(flags);
   else if (command === 'bench') cmdBench(flags, positional);
-  else {
-    console.error(USAGE);
-    process.exit(2);
-  }
+  else if (command === 'render') cmdRender(flags);
+  else if (command === 'preview') cmdPreview(flags);
 } catch (err) {
   if (err instanceof UsageError) {
     console.error(`rigc: ${err.message}\n\n${USAGE}`);