spine-rigc 0.5.0 → 0.6.0

package/src/json-position.ts

@@ -0,0 +1,253 @@
+/**
+ * Best-effort line/column for a `JSON.parse` failure.
+ *
+ * Bun's `JSON.parse` (JavaScriptCore) names the fault — `JSON Parse error:
+ * Property name must be a string literal` — and never a position, so a caller
+ * only ever learns which file was bad, not where inside it. This module fills
+ * that gap without a dependency: it re-walks the text through a minimal,
+ * hand-written JSON grammar and stops at the first place that grammar
+ * disagrees with the text.
+ *
+ * ⚠️ This is not a JSON parser used to parse anything — `JSON.parse` still owns
+ * every successful parse and every error MESSAGE. `locateJsonError` only ever
+ * runs after `JSON.parse` has already thrown, purely to attribute a position to
+ * the failure it already found. That is why it does not have to be a complete,
+ * spec-perfect grammar: for the ordinary mistakes (an unquoted key, a trailing
+ * comma, a missing colon, an unterminated string) the two parsers diverge at
+ * the same character, so the position is exact. Wherever this scanner is
+ * looser or stricter than `JSON.parse` in some corner, the position can be
+ * early rather than exactly the runtime's own stopping point — which is why
+ * it is documented, and named, as best-effort rather than exact.
+ */
+
+export interface JsonPosition {
+  /** 1-based, like every editor and every compiler diagnostic. */
+  line: number;
+  column: number;
+}
+
+/** Thrown internally the moment the grammar walk disagrees with the text. */
+class ScanStopped {
+  constructor(readonly position: JsonPosition) {}
+}
+
+class Cursor {
+  private i = 0;
+  private line = 1;
+  private column = 1;
+
+  constructor(private readonly text: string) {}
+
+  get done(): boolean {
+    return this.i >= this.text.length;
+  }
+
+  peek(): string | undefined {
+    return this.text[this.i];
+  }
+
+  startsWith(s: string): boolean {
+    return this.text.startsWith(s, this.i);
+  }
+
+  advance(): void {
+    if (this.text[this.i] === '\n') {
+      this.line++;
+      this.column = 1;
+    } else {
+      this.column++;
+    }
+    this.i++;
+  }
+
+  position(): JsonPosition {
+    return { line: this.line, column: this.column };
+  }
+}
+
+function isDigit(c: string | undefined): boolean {
+  return c !== undefined && c >= '0' && c <= '9';
+}
+
+function isHexDigit(c: string | undefined): boolean {
+  return c !== undefined && ((c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F'));
+}
+
+function isWhitespace(c: string | undefined): boolean {
+  return c === ' ' || c === '\t' || c === '\n' || c === '\r';
+}
+
+function stop(cur: Cursor): never {
+  throw new ScanStopped(cur.position());
+}
+
+function skipWhitespace(cur: Cursor): void {
+  while (!cur.done && isWhitespace(cur.peek())) cur.advance();
+}
+
+function skipLiteral(cur: Cursor, length: number): void {
+  for (let k = 0; k < length; k++) cur.advance();
+}
+
+const STRING_ESCAPES = new Set(['"', '\\', '/', 'b', 'f', 'n', 'r', 't']);
+
+function scanString(cur: Cursor): void {
+  cur.advance(); // opening quote
+  for (;;) {
+    if (cur.done) stop(cur);
+    const c = cur.peek()!;
+    if (c === '"') {
+      cur.advance();
+      return;
+    }
+    if (c === '\\') {
+      cur.advance();
+      const esc = cur.peek();
+      if (esc !== undefined && STRING_ESCAPES.has(esc)) {
+        cur.advance();
+        continue;
+      }
+      if (esc === 'u') {
+        cur.advance();
+        for (let k = 0; k < 4; k++) {
+          if (!isHexDigit(cur.peek())) stop(cur);
+          cur.advance();
+        }
+        continue;
+      }
+      stop(cur); // unknown escape
+    }
+    if (c.charCodeAt(0) < 0x20) stop(cur); // raw control character in a string
+    cur.advance();
+  }
+}
+
+function scanNumber(cur: Cursor): void {
+  if (cur.peek() === '-') cur.advance();
+  if (cur.peek() === '0') {
+    cur.advance();
+  } else if (isDigit(cur.peek())) {
+    while (isDigit(cur.peek())) cur.advance();
+  } else {
+    stop(cur);
+  }
+  if (cur.peek() === '.') {
+    cur.advance();
+    if (!isDigit(cur.peek())) stop(cur);
+    while (isDigit(cur.peek())) cur.advance();
+  }
+  if (cur.peek() === 'e' || cur.peek() === 'E') {
+    cur.advance();
+    if (cur.peek() === '+' || cur.peek() === '-') cur.advance();
+    if (!isDigit(cur.peek())) stop(cur);
+    while (isDigit(cur.peek())) cur.advance();
+  }
+}
+
+function scanValue(cur: Cursor): void {
+  skipWhitespace(cur);
+  if (cur.done) stop(cur);
+  const c = cur.peek();
+  if (c === '{') return scanObject(cur);
+  if (c === '[') return scanArray(cur);
+  if (c === '"') return scanString(cur);
+  if (c === '-' || isDigit(c)) return scanNumber(cur);
+  if (cur.startsWith('true')) return skipLiteral(cur, 4);
+  if (cur.startsWith('false')) return skipLiteral(cur, 5);
+  if (cur.startsWith('null')) return skipLiteral(cur, 4);
+  stop(cur);
+}
+
+function scanObject(cur: Cursor): void {
+  cur.advance(); // '{'
+  skipWhitespace(cur);
+  if (cur.peek() === '}') {
+    cur.advance();
+    return;
+  }
+  for (;;) {
+    skipWhitespace(cur);
+    // The classic unquoted-key mistake stops here — this is
+    // "Property name must be a string literal" in JavaScriptCore's own words.
+    if (cur.peek() !== '"') stop(cur);
+    scanString(cur);
+    skipWhitespace(cur);
+    if (cur.peek() !== ':') stop(cur);
+    cur.advance();
+    scanValue(cur);
+    skipWhitespace(cur);
+    const c = cur.peek();
+    if (c === ',') {
+      cur.advance();
+      continue;
+    }
+    if (c === '}') {
+      cur.advance();
+      return;
+    }
+    stop(cur);
+  }
+}
+
+function scanArray(cur: Cursor): void {
+  cur.advance(); // '['
+  skipWhitespace(cur);
+  if (cur.peek() === ']') {
+    cur.advance();
+    return;
+  }
+  for (;;) {
+    scanValue(cur);
+    skipWhitespace(cur);
+    const c = cur.peek();
+    if (c === ',') {
+      cur.advance();
+      skipWhitespace(cur);
+      continue;
+    }
+    if (c === ']') {
+      cur.advance();
+      return;
+    }
+    stop(cur);
+  }
+}
+
+/**
+ * Where, in `text`, a strict JSON parse first disagrees with it. Best-effort:
+ * see the module doc for what that means and why.
+ */
+export function locateJsonError(text: string): JsonPosition {
+  const cur = new Cursor(text);
+  try {
+    scanValue(cur);
+    skipWhitespace(cur);
+    if (!cur.done) stop(cur); // trailing content after the one top-level value
+  } catch (err) {
+    if (err instanceof ScanStopped) return err.position;
+    throw err;
+  }
+  // The grammar walk above found nothing wrong, even though `JSON.parse` did —
+  // this scanner is looser than the runtime parser in whatever way this file's
+  // fault is. Rather than claim a location it did not actually find, it points
+  // at the end of the file.
+  return cur.position();
+}
+
+/**
+ * `JSON.parse`, with a `(line N, column N)` suffix appended to the message
+ * whenever it throws a `SyntaxError` — the runtime's own message, positioned.
+ * Any other error (a non-JSON exception `JSON.parse` never actually throws,
+ * kept here only for type safety) passes through unchanged.
+ */
+export function parseJsonWithPosition(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      const { line, column } = locateJsonError(text);
+      throw new SyntaxError(`${err.message} (line ${line}, column ${column})`);
+    }
+    throw err;
+  }
+}

package/src/png.ts

@@ -1,10 +1,18 @@
 /**
  * PNG header reader.
  *
- * The only thing rigc needs from a part PNG is its true pixel size and whether
- * it carries an alpha channel, and both live in the IHDR chunk that every PNG
- * puts first. Parsing 26 bytes keeps the compiler dependency-free: no image
- * library, and nothing on the module path but rigc itself.
+ * The only things rigc needs from a part PNG are its true pixel size and whether
+ * it can draw a transparent pixel. The size is in the IHDR chunk that every PNG
+ * puts first; transparency is in the IHDR's colour type OR in a `tRNS` chunk a
+ * little further in, so the reader walks the file's small leading chunks and
+ * stops at the pixel data. That keeps the compiler dependency-free — no image
+ * library, and nothing on the module path but rigc itself — while still reading
+ * every place the answer can be written down.
+ *
+ * ⚠️ It reads a header, not an image: "can this file draw a transparent pixel",
+ * never "does it". Whether the art actually has a transparent margin is a
+ * question about pixels, and the tools that measure pixels decode the whole file
+ * ([`tools/plate.ts`](../tools/plate.ts)).
  *
  * Measuring instead of trusting is the whole point: an atlas `size:` that
  * disagrees with the file loads clean and collapses the UVs silently.
@@ -13,21 +21,72 @@ import { readFileSync } from 'node:fs';
 
 const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
 
-/** PNG colour types that carry a per-pixel alpha channel. */
+/**
+ * PNG colour types that carry a per-pixel alpha channel.
+ *
+ * ⭐ False here does NOT mean opaque, and reading it that way is what #215 was:
+ * types 0, 2 and 3 can all carry a `tRNS` chunk instead — a palette alpha table
+ * for indexed art, one invisible colour for the other two — and indexed+tRNS is
+ * the ordinary output of ImageMagick, Photoshop's PNG-8 export, GIMP's indexed
+ * mode, aseprite and pngquant. `hasTransparency` is the field to judge art by;
+ * this one answers the narrower question of where the alpha is stored.
+ */
 const COLOUR_TYPE_HAS_ALPHA: Record<number, boolean> = {
   0: false, // greyscale
   2: false, // truecolour
-  3: false, // indexed (may have tRNS, but not a straight alpha channel)
+  3: false, // indexed (transparency, if any, is in tRNS)
   4: true, // greyscale + alpha
   6: true, // truecolour + alpha
 };
 
+/** The spec's name for each colour type, for messages that have to name one. */
+const COLOUR_TYPE_NAMES: Record<number, string> = {
+  0: 'greyscale',
+  2: 'truecolour',
+  3: 'indexed',
+  4: 'greyscale + alpha',
+  6: 'truecolour + alpha',
+};
+
+/** How to say a colour type out loud. Unknown types print as themselves. */
+export function colourTypeName(colourType: number): string {
+  return COLOUR_TYPE_NAMES[colourType] ?? 'unrecognised';
+}
+
 export interface PngInfo {
   width: number;
   height: number;
   bitDepth: number;
   colourType: number;
+  /** A per-pixel alpha channel in the pixel data: colour types 4 and 6, and only those. */
   hasAlpha: boolean;
+  /** A `tRNS` chunk: a palette alpha table (type 3), or one invisible colour (types 0 and 2). */
+  hasTrns: boolean;
+  /** Either of the above — the file is able to draw a transparent pixel. */
+  hasTransparency: boolean;
+}
+
+/**
+ * Walk the chunk list looking for `tRNS`, stopping where it can no longer appear.
+ *
+ * The spec orders `tRNS` after `PLTE` and before the first `IDAT`, so this reads
+ * only the file's small leading chunks and never touches the compressed bulk. A
+ * length that would run past the end of the file ends the walk rather than
+ * throwing: a truncated PNG is A17 and A06's business, and answering "no tRNS"
+ * about a file nobody can open is the same answer either way.
+ */
+function scanForTrns(buf: Buffer): boolean {
+  let at = 8; // past the signature; the first chunk is IHDR
+  while (at + 8 <= buf.length) {
+    const length = buf.readUInt32BE(at);
+    const type = buf.toString('latin1', at + 4, at + 8);
+    if (type === 'tRNS') return true;
+    if (type === 'IDAT' || type === 'IEND') return false;
+    const next = at + 12 + length; // 4 length + 4 type + body + 4 CRC
+    if (next <= at || next > buf.length) return false;
+    at = next;
+  }
+  return false;
 }
 
 export function readPngInfo(path: string): PngInfo {
@@ -40,11 +99,17 @@ export function readPngInfo(path: string): PngInfo {
     throw new Error(`PNG does not start with IHDR: ${path}`);
   }
   const colourType = buf.readUInt8(25);
+  const hasAlpha = COLOUR_TYPE_HAS_ALPHA[colourType] ?? false;
+  // A file with an alpha channel cannot also carry tRNS, so the scan is skipped
+  // for the types that already answered — which is every PNG rigc itself writes.
+  const hasTrns = hasAlpha ? false : scanForTrns(buf);
   return {
     width: buf.readUInt32BE(16),
     height: buf.readUInt32BE(20),
     bitDepth: buf.readUInt8(24),
     colourType,
-    hasAlpha: COLOUR_TYPE_HAS_ALPHA[colourType] ?? false,
+    hasAlpha,
+    hasTrns,
+    hasTransparency: hasAlpha || hasTrns,
   };
 }

package/src/preview.ts

@@ -0,0 +1,243 @@
+/**
+ * The single-file preview — a compiled artifact playing in Esoteric Software's
+ * own web player, with nothing beside it.
+ *
+ * ⭐ Why this exists at all. `validate` answers "is this valid Spine", `check`
+ * answers "does it match these frames", and neither of them can answer the
+ * question a first user actually has: *does it look right?* A rig whose head sits
+ * visibly off its torso compiles green, loads in `spine-core` and steps
+ * numerically clean — the offsets are the ones the spec asked for. The only
+ * remedy for that class of error is looking, and until this command the package
+ * offered no way to look (issue #216).
+ *
+ * ## Why the official player, and not our own renderer
+ *
+ * There is a rasteriser in [`render.ts`](render.ts) already, and `rigc render`
+ * uses it. This is deliberately the other thing: `SpinePlayer` is the runtime
+ * Esoteric ships, so a rig that plays here has been played by the reference
+ * implementation rather than by ours. Every picture our own code draws is, at
+ * some level, rigc checking its own work — this one is not, which is why issue
+ * #151 settled on it as the surface a human votes on.
+ *
+ * ## Why one file, and what `rawDataURIs` is doing
+ *
+ * `SpinePlayer` normally fetches its skeleton, atlas and pages over HTTP, which
+ * would make a preview a directory plus a web server — a thing to set up rather
+ * than a thing to open. Its `rawDataURIs` option maps each of those paths to a
+ * `data:` URI instead, and the player's downloader takes the mapping in
+ * preference to the network. So the whole artifact — skeleton JSON, atlas text
+ * and every page's PNG bytes — is embedded, and the result is one `.html` file
+ * that plays when double-clicked and can be attached to a message.
+ *
+ * ⚠️ The keys are the paths the player asks for, and they must match exactly.
+ * `config.atlas` has no directory part, so the player's own texture resolution
+ * (`parentPath + pageName`) asks for each page under **the name the atlas spells**
+ * — `../parts/torso.png` and all. That is why the atlas text is embedded verbatim
+ * rather than rewritten to flat names: the file that plays is the file that was
+ * built, which is the entire value of the interop proof.
+ *
+ * ## The player is referenced, never vendored
+ *
+ * The `<script>` and `<link>` point at unpkg. Nothing Esoteric owns is copied
+ * into this repository or into the published package — see [NOTICE.md](../NOTICE.md)
+ * — and the generated page belongs to whoever ran the command. The cost is that
+ * the file needs the network the first time it is opened, which the page says out
+ * loud when the script does not arrive.
+ */
+import { SPINE_VERSION } from './compile.ts';
+import { BACKGROUND } from './render.ts';
+
+/**
+ * The Spine Web Player line the generated page loads.
+ *
+ * Derived from the runtime line the compiler emits rather than written down
+ * twice: a page playing 4.2 data in a 4.3 player (or the reverse) is a failure
+ * mode nobody would look for, and this makes the two impossible to edit apart.
+ *
+ * The **patch** is deliberately a wildcard where `SPINE_VERSION` is exact. Data
+ * compatibility is a property of the minor line, and pinning a patch would break
+ * every generated page on the day spine-core ships a version the player did not.
+ */
+export const PLAYER_LINE = `${SPINE_VERSION.split('.').slice(0, 2).join('.')}.*`;
+export const PLAYER_SCRIPT_URL = `https://unpkg.com/@esotericsoftware/spine-player@${PLAYER_LINE}/dist/iife/spine-player.js`;
+export const PLAYER_STYLE_URL = `https://unpkg.com/@esotericsoftware/spine-player@${PLAYER_LINE}/dist/spine-player.css`;
+
+/** The name the embedded skeleton and atlas are asked for under, inside the page. */
+export const SKELETON_KEY = 'skeleton.json';
+export const ATLAS_KEY = 'skeleton.atlas';
+
+/** One atlas page, named exactly as the atlas spells it, with its bytes. */
+export interface PreviewPage {
+  /** The page name from the atlas text — a path, quite possibly a relative one. */
+  name: string;
+  bytes: Uint8Array;
+}
+
+export interface PreviewInput {
+  skeletonText: string;
+  atlasText: string;
+  pages: PreviewPage[];
+  /** The animation to autoplay and loop, or `null` for a skeleton with none. */
+  animation: string | null;
+  /** Every animation the page offers in its picker. */
+  animations: string[];
+  /** What the page calls itself — the skeleton's path, for the tab and the header. */
+  label: string;
+  /** rigc's own version, for the generated-by line. */
+  version: string;
+}
+
+/**
+ * A `data:` URI the player's downloader will take the fast path on.
+ *
+ * ⚠️ Base64 for the text assets too, not only for the PNGs. The downloader
+ * decides a value is a data URI rather than an alias by asking whether it
+ * contains a `.` — and a percent-encoded skeleton JSON is full of them, so the
+ * un-encoded form would be handed to `XMLHttpRequest` as a URL instead. Base64's
+ * alphabet has no `.` in it, so this always lands on the branch that decodes.
+ */
+export function dataUri(mime: string, body: string | Uint8Array): string {
+  const base64 = (typeof body === 'string' ? Buffer.from(body, 'utf8') : Buffer.from(body)).toString('base64');
+  return `data:${mime};base64,${base64}`;
+}
+
+/** `#rrggbb` for the player's background, so a preview and `rigc render` agree. */
+function backgroundHex(): string {
+  return `#${BACKGROUND.slice(0, 3)
+    .map((c) => c.toString(16).padStart(2, '0'))
+    .join('')}`;
+}
+
+/** The five characters that can end an element or an attribute early. */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * JSON for embedding inside a `<script>` element.
+ *
+ * The escape is on `<` alone and it is enough: an HTML parser ends a script at
+ * `</script`, and it cannot see one if no `<` survives. `<` is the same
+ * string to a JSON reader, so nothing about the value changes. Page names come
+ * out of a file somebody else wrote, which is exactly why this is not optional.
+ */
+function embeddedJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+/**
+ * The whole page, as text.
+ *
+ * There is no template file and no build step: this is a `.ts` string, so the
+ * published package carries it the way it carries every other module, and the
+ * page it produces has no dependency of its own except the player URL above.
+ */
+export function buildPreview(input: PreviewInput): string {
+  const rawDataURIs: Record<string, string> = {
+    [SKELETON_KEY]: dataUri('application/json', input.skeletonText),
+    [ATLAS_KEY]: dataUri('text/plain', input.atlasText),
+  };
+  for (const page of input.pages) rawDataURIs[page.name] = dataUri('image/png', page.bytes);
+
+  // `animation` is left off a skeleton with none rather than set to null: the
+  // player checks for the key's presence, and the setup pose held still is the
+  // honest picture of a rig that has no animation to play.
+  const config: Record<string, unknown> = {
+    skeleton: SKELETON_KEY,
+    atlas: ATLAS_KEY,
+    rawDataURIs,
+    animations: input.animations,
+    showControls: true,
+    alpha: false,
+    backgroundColor: backgroundHex(),
+  };
+  if (input.animation !== null) config.animation = input.animation;
+
+  const label = escapeHtml(input.label);
+  const played =
+    input.animation === null
+      ? 'no animation — the setup pose'
+      : `${escapeHtml(input.animation)}${input.animations.length > 1 ? ` (of ${input.animations.length}; pick another in the controls)` : ''}`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>rigc preview — ${label}</title>
+<!--
+  Generated by rigc ${escapeHtml(input.version)} — https://github.com/firejune/rigc
+
+  The skeleton, the atlas and every atlas page are embedded in this file as data
+  URIs, so it plays on its own with no server and no sibling files.
+
+  It plays them in the Spine Web Player, which is NOT embedded: the script and
+  stylesheet below are loaded from unpkg. The Spine Runtimes are Copyright (c)
+  2013-2025 Esoteric Software LLC and are licensed under the Spine Runtimes
+  License Agreement — https://esotericsoftware.com/spine-runtimes-license — which
+  requires each user of a product integrating them to hold a Spine Editor
+  license. Nothing owned by Esoteric Software is redistributed by rigc.
+-->
+<link rel="stylesheet" href="${PLAYER_STYLE_URL}">
+<style>
+  :root { color-scheme: light dark; }
+  html, body { margin: 0; height: 100%; }
+  body {
+    display: flex; flex-direction: column;
+    background: ${backgroundHex()};
+    color: #1a1a1a;
+    font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+  header { padding: 10px 14px; border-bottom: 1px solid rgba(0, 0, 0, 0.15); }
+  header b { font-weight: 600; }
+  header span { opacity: 0.65; }
+  #rigc-player { flex: 1 1 auto; min-height: 0; }
+  #rigc-status { margin: 0; padding: 10px 14px; border-top: 1px solid rgba(0, 0, 0, 0.15); white-space: pre-wrap; }
+  #rigc-status[data-state="error"] { background: #7d1d1d; color: #fff; }
+</style>
+</head>
+<body>
+<header><b>${label}</b> <span>— ${played}</span></header>
+<div id="rigc-player"></div>
+<p id="rigc-status">loading the Spine Web Player…</p>
+<script src="${PLAYER_SCRIPT_URL}"></script>
+<script>
+(function () {
+  var status = document.getElementById('rigc-status');
+  var state = { status: 'loading', message: null, player: null };
+  window.rigcPreview = state;
+  function say(kind, message) {
+    state.status = kind;
+    state.message = message;
+    status.textContent = message;
+    status.setAttribute('data-state', kind);
+  }
+  if (typeof window.spine === 'undefined' || typeof window.spine.SpinePlayer !== 'function') {
+    say('error', 'The Spine Web Player did not load from ${PLAYER_SCRIPT_URL} — this page needs a network connection the first time it is opened.');
+    return;
+  }
+  var config = ${embeddedJson(config)};
+  config.success = function (player) {
+    state.player = player;
+    say('ready', 'playing in Spine Web Player ${PLAYER_LINE} — everything it is drawing is embedded in this file.');
+  };
+  config.error = function (player, message) {
+    state.player = player;
+    say('error', String(message));
+  };
+  try {
+    new window.spine.SpinePlayer('rigc-player', config);
+  } catch (err) {
+    say('error', String(err && err.message ? err.message : err));
+  }
+})();
+</script>
+</body>
+</html>
+`;
+}

package/src/render.ts

@@ -144,6 +144,11 @@ export const SHEET_COLUMNS = 8;
 export const SHEET_FILE = 'contact.png';
 /** One pixel of rule between tiles, and one around the outside. */
 export const SHEET_GAP = 1;
+/** Default long side of one contact-sheet tile, in pixels. */
+export const SHEET_TILE = 128;
+/** The rule between tiles, and the frame number drawn in each. */
+export const SHEET_RULE: RGBA = [176, 176, 176, 255];
+export const SHEET_LABEL: RGBA = [96, 96, 96, 255];
 
 /** One rendered frame directory: which animation, at what rate, and what is on disk. */
 export interface FrameSet {
@@ -285,6 +290,19 @@ export function loadPosable(skeletonPath: string, atlasPath: string, atlasDir: s
   return posableFromText(readFileSync(skeletonPath, 'utf8'), readFileSync(atlasPath, 'utf8'), atlasDir);
 }
 
+/**
+ * The page names an atlas declares, in the order it declares them.
+ *
+ * Through `TextureAtlas` rather than by reading the lines: a page name and a
+ * region name are both unindented in the atlas format, so anything that told them
+ * apart here would be a second opinion about the file's syntax — and the one
+ * caller that needs this list (`rigc preview`, embedding each page) has to agree
+ * exactly with the player that will ask for them by name.
+ */
+export function atlasPageNames(atlasText: string): string[] {
+  return new TextureAtlas(atlasText).pages.map((page) => page.name);
+}
+
 /** Same, for artifacts held in memory rather than on disk. */
 export function posableFromText(skeletonText: string, atlasText: string, atlasDir: string): Posable {
   const atlas = new TextureAtlas(atlasText);
@@ -911,6 +929,46 @@ export function renderFrame(frame: Frame, pages: Map<string, Plate>, viewport: V
   return plate;
 }
 
+/**
+ * Every frame of one animation as one labelled grid, row major.
+ *
+ * Not decoration: rung 3's subject is *spacing* — how far a thing travels
+ * between two consecutive frames — and that is a comparison across frames. A
+ * reader flipping through 65 separate files is comparing against memory.
+ *
+ * ⭐ It lives here rather than beside either caller because the layout is a
+ * CONTRACT: `bench/render_reference.ts` writes the grid, `rigc render` writes the
+ * same grid for a user's own build, and `src/check.ts` reads a sheet's tiles back
+ * out of it (issue #36). Three programs reading one geometry is one definition or
+ * it is a bug waiting for the day two of them are edited apart.
+ */
+export function contactSheet(frames: Frame[], pages: Map<string, Plate>, viewport: Viewport, tile: number): Plate {
+  const tileScale = tile / Math.max(viewport.width, viewport.height);
+  const tileW = Math.max(1, Math.round(viewport.width * tileScale));
+  const tileH = Math.max(1, Math.round(viewport.height * tileScale));
+  const columns = Math.min(SHEET_COLUMNS, frames.length);
+  const rows = Math.ceil(frames.length / columns);
+  const sheet = new Plate(columns * (tileW + SHEET_GAP) + SHEET_GAP, rows * (tileH + SHEET_GAP) + SHEET_GAP);
+  fill(sheet, SHEET_RULE);
+  const base = projector(viewport);
+  frames.forEach((frame, i) => {
+    const col = i % columns;
+    const row = Math.floor(i / columns);
+    const ox = col * (tileW + SHEET_GAP) + SHEET_GAP;
+    const oy = row * (tileH + SHEET_GAP) + SHEET_GAP;
+    const plate = new Plate(tileW, tileH);
+    fill(plate, BACKGROUND);
+    const project = (wx: number, wy: number): [number, number] => {
+      const [px, py] = base(wx, wy);
+      return [px * tileScale, py * tileScale];
+    };
+    for (const piece of frame.pieces) blitPiece(plate, pageFor(pages, piece), piece, project);
+    plate.text(String(i), 2, 2, 1, SHEET_LABEL);
+    for (let y = 0; y < tileH; y++) for (let x = 0; x < tileW; x++) sheet.set(ox + x, oy + y, plate.get(x, y));
+  });
+  return sheet;
+}
+
 /** Where one thing landed in a frame, in frame pixels. */
 export interface Footprint {
   /** Alpha-weighted count of covered pixels. 0 means nothing was drawn. */