spine-rigc 0.4.0 → 0.6.0

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. */

package/src/types.ts

@@ -573,6 +573,14 @@ export interface CompiledImage {
   absPath: string;
   width: number;
   height: number;
+  /**
+   * A per-pixel alpha channel, and only that — colour types 4 and 6.
+   *
+   * ⚠️ Not "this part can be transparent": indexed and greyscale art keeps its
+   * transparency in a `tRNS` chunk and reads `false` here. Anything asking
+   * whether the art can draw a transparent pixel wants `PngInfo.hasTransparency`
+   * ([`src/png.ts`](png.ts)), which is the distinction A19 got wrong (#215).
+   */
   hasAlpha: boolean;
   isBase: boolean;
 }

package/src/validate.ts

@@ -29,7 +29,7 @@ import {
   SkeletonJson,
   TextureAtlas,
 } from '@esotericsoftware/spine-core';
-import { readPngInfo } from './png.ts';
+import { colourTypeName, readPngInfo } from './png.ts';
 import { CHANNELS_BY_KIND, KEY_TIME_EPSILON, walkTimelines } from './timelines.ts';
 import type { RigInfo } from './types.ts';
 
@@ -53,15 +53,31 @@ export interface Failure {
  * - `spine`      — is this valid Spine 4.3 that any runtime will play correctly?
  * - `spine-html` — the above, plus this project's renderer and archetype policy.
  *
- * ⚠️ `spine-html` is the DEFAULT and must stay the default: it is the behaviour
- * every existing caller already has, and a switch that silently loosens a gate
- * for callers who did not ask is worse than no switch at all.
+ * ⚠️ `validate()` has NO default profile — `ValidateInput.profile` is required,
+ * and that is deliberate. A silent default here can only be wrong in one of two
+ * directions: loosen it and a caller who did not ask gets a weaker gate than the
+ * one they think they ran; tighten it and foreign data is refused by a policy the
+ * caller has no stake in. Issue #221 flipped the CLI to `spine` while several
+ * internal callers still wanted `spine-html`, at which point one constant could
+ * no longer honestly serve both — so the choice is made at every call site now,
+ * by the caller who knows which question they are asking.
  */
 export type ValidateProfile = 'spine' | 'spine-html';
 
 export const VALIDATE_PROFILES: readonly ValidateProfile[] = ['spine', 'spine-html'];
 
-export const DEFAULT_PROFILE: ValidateProfile = 'spine-html';
+/**
+ * What the CLI uses when `--profile` is absent — and ONLY the CLI. This is not
+ * `validate()`'s default; that function has none (above).
+ *
+ * `spine` since issue #221. The published package's pitch is "the output imports
+ * into the Spine editor", which is exactly the question `spine` asks, and a
+ * stranger's first build was being judged instead against one renderer's policy
+ * and one project's canvas budget — 14 rules they have no stake in, with the
+ * escape hatch documented only in prose. Defaults beat prose. `spine-html` is
+ * still one flag away, and every report names the profile that judged it.
+ */
+export const CLI_DEFAULT_PROFILE: ValidateProfile = 'spine';
 
 /**
  * What kind of rule each assertion is. Every assertion has an entry, and
@@ -136,8 +152,11 @@ export interface ValidateInput {
    * stats line says `rig=absent` so a green run cannot be mistaken for a full one.
    */
   rig?: RigInfo;
-  /** Which body of rules to apply. Defaults to `spine-html`; see ValidateProfile. */
-  profile?: ValidateProfile;
+  /**
+   * Which body of rules to apply. Required, and deliberately so — there is no
+   * default to fall into. See ValidateProfile.
+   */
+  profile: ValidateProfile;
 }
 
 export interface ValidateReport {
@@ -215,7 +234,7 @@ export function validate(input: ValidateInput): ValidateReport {
   const skipped: ValidateReport['skipped'] = [];
   const profileSkipped: ValidateReport['profileSkipped'] = [];
   const stats: Record<string, number | string> = {};
-  const profile = input.profile ?? DEFAULT_PROFILE;
+  const profile = input.profile;
   /** True when this profile's rulebook includes the policy layer. */
   const policy = profile === 'spine-html';
 
@@ -1297,11 +1316,25 @@ export function validate(input: ValidateInput): ValidateReport {
       }
     }
   });
-  // An overlay part must carry an alpha channel or it cannot be an overlay: it
-  // would paint an opaque rectangle over the untouched base, and an overlay
-  // formation's whole claim is that the still frame has no seam. The base
+  // An overlay part must be able to draw a transparent pixel or it cannot be an
+  // overlay: it would paint a solid rectangle over the untouched base, and an
+  // overlay formation's whole claim is that the still frame has no seam. The base
   // plate itself is the one page allowed to be opaque, and it identifies
   // itself structurally — it is the region that covers the whole stage.
+  //
+  // ⭐ Transparency is not the same thing as an alpha CHANNEL, and this assertion
+  // used to conflate them (#215). Colour types 4 and 6 store alpha per pixel;
+  // types 0, 2 and 3 store it in a `tRNS` chunk instead, and indexed+tRNS is the
+  // ordinary output of ImageMagick, Photoshop's PNG-8 export, GIMP's indexed
+  // mode, aseprite and pngquant. Judging on the colour type alone refused art
+  // that was never broken — seven of one author's nine hand-drawn parts, on their
+  // first build — and told them, untruthfully, that the file held no transparency
+  // at all. That audit is also why the CLI's default is now `spine`, which does
+  // not run this rule at all (#221): a stranger reaches this refusal only by
+  // asking for `spine-html`. It still has to be both TRUE and actionable when it
+  // fires, and it now has to name the profile it belongs to as well as the one
+  // that does not ask — the reader opted in, and the message is where they find
+  // out what they opted into.
   check('A19_OVERLAY_PNGS_HAVE_ALPHA', () => {
     if (!atlas) return;
     const stageW = skeletonData?.width ?? 0;
@@ -1313,15 +1346,27 @@ export function validate(input: ValidateInput): ValidateReport {
         if (region) basePages.add(region.page.name);
       }
     }
+    // The escape hatch is only worth naming when it is reachable: with no stage
+    // size to measure against, `basePages` is empty and no image can qualify, so
+    // pointing at it would send the reader after a door that is not there.
+    const exemption =
+      stageW && stageH
+        ? `Only the one image big enough to cover the whole stage (${stageW}x${stageH}) may be opaque.`
+        : 'The one image that covers the whole stage may be opaque, but this skeleton declares no stage size, so ' +
+          'nothing here qualifies.';
     for (const page of atlas.pages) {
       const abs = resolve(input.atlasDir, page.name);
       if (!existsSync(abs)) continue;
       const info = readPngInfo(abs);
-      if (info.hasAlpha) continue;
+      if (info.hasTransparency) continue;
       if (basePages.has(page.name)) continue; // full-stage base plate: opaque is correct
       fail(
         'A19_OVERLAY_PNGS_HAVE_ALPHA',
-        `overlay page "${page.name}" has colour type ${info.colourType}, which carries no alpha channel`,
+        `part image "${page.name}" cannot be transparent anywhere: it is colour type ${info.colourType} ` +
+          `(${colourTypeName(info.colourType)}) with no tRNS chunk, so it would paint a solid rectangle over ` +
+          'whatever is drawn behind it. Re-export it with transparency — as RGBA, or as an indexed or greyscale ' +
+          `PNG that keeps its tRNS chunk. ${exemption} This is renderer policy, and it belongs to --profile ` +
+          'spine-html: the default --profile spine does not run this check.',
       );
     }
   });