spine-rigc 1.0.2 → 1.2.0

package/src/preview.ts

@@ -83,8 +83,123 @@ export interface PreviewInput {
   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. */
+  /** rigc's own version, for the generated-by line and the header's gate line. */
   version: string;
+  /** What the gate said about this candidate on THIS run — see `PreviewGate`. */
+  gate: PreviewGate;
+}
+
+/**
+ * The gate's reading of a candidate, taken when the page is written (issue #837).
+ *
+ * ⭐ Both strings are the validator's own lines, never a paraphrase: `summary`
+ * is the `N assertions: …` line `rigc validate <dir>` prints last and `refusal`
+ * is its first `FAIL` line, each without the report's gutter. The caller
+ * measures them on the run that writes the page, because a figure carried over
+ * from the build would be a claim about bytes nothing here read — and a bare
+ * directory re-gated is NOT what `build` gated: with no rig spec and no second
+ * compile, `A09` and `A18` report SKIP there, so the two runs print different
+ * counts over the same files and only this one's belongs on this page.
+ *
+ * `refusal` is `null` on green. A refused candidate is still previewed —
+ * looking at a red build is what this command is for — and its header says so
+ * in the gate's words.
+ */
+export interface PreviewGate {
+  summary: string;
+  refusal: string | null;
+}
+
+/** The header's gate line, as one element: which rigc, what ran, and what it said. */
+export function gateLine(gate: PreviewGate, version: string): string {
+  const said =
+    `rigc ${escapeHtml(version)}, re-gated as <code>rigc validate &lt;dir&gt;</code> gates it: ${escapeHtml(gate.summary)}`;
+  return gate.refusal === null
+    ? `<span class="rigc-gate" data-gate="green">${said}</span>`
+    : `<span class="rigc-gate" data-gate="refused" style="opacity: 1; color: #7d1d1d; font-weight: 600">${said} — ` +
+        `refused: ${escapeHtml(gate.refusal)}</span>`;
+}
+
+/** What a header says its player is playing. */
+function playedText(animation: string | null, animations: string[]): string {
+  return animation === null
+    ? 'no animation — the setup pose'
+    : `${escapeHtml(animation)}${animations.length > 1 ? ` (of ${animations.length}; pick another in the controls)` : ''}`;
+}
+
+/** The header over one player: the path, what it plays, and the gate's line. */
+function headerHtml(input: PreviewInput): string {
+  return (
+    `<header><b>${escapeHtml(input.label)}</b> <span>— ${playedText(input.animation, input.animations)}</span>` +
+    `<br>${gateLine(input.gate, input.version)}</header>`
+  );
+}
+
+/**
+ * One player's config. `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.
+ */
+function previewConfig(input: PreviewInput): Record<string, unknown> {
+  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);
+  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;
+  return config;
+}
+
+/**
+ * The licence paragraph, spelled once for the one-candidate page and the page
+ * of panes so the two cannot drift. The ballot keeps its own copy of the same
+ * words: its bytes are held by `vote`'s controls, not moved by this card.
+ */
+const PLAYER_LICENCE = `  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.`;
+
+// ---------------------------------------------------------------------------
+// panes — the layout `vote` built first, shared rather than copied
+// ---------------------------------------------------------------------------
+
+/**
+ * The grid panes sit in, as the style lines the ballot has always carried: one
+ * column per pane, one column on a narrow screen. `buildBallot` calls this too,
+ * so a ballot's bytes are what they were and the two pages cannot drift.
+ */
+export function paneGridCss(count: number): string {
+  return `  #panes { display: grid; grid-template-columns: repeat(${count}, minmax(0, 1fr)); gap: 1px; background: rgba(0, 0, 0, 0.15); }
+  @media (max-width: 720px) { #panes { grid-template-columns: minmax(0, 1fr); } }
+  .pane { background: ${backgroundHex()}; display: flex; flex-direction: column; min-width: 0; }`;
+}
+
+/** The box a pane's player mounts in, as the ballot styles it. */
+export const PANE_STAGE_CSS = '  .stage { height: 52vh; min-height: 260px; }';
+
+/** One pane: a heading the caller writes, over the element its player mounts in. */
+export function paneSection(stageId: string, heading: string): string {
+  return `<section class="pane">
+  ${heading}
+  <div class="stage" id="${stageId}"></div>
+</section>`;
+}
+
+/** The element pane `i` (0-based) mounts its player in, numbered from 1 as the CLI numbers candidates. */
+export function previewPaneId(i: number): string {
+  return `rigc-player-${i + 1}`;
 }
 
 /**
@@ -138,31 +253,8 @@ export function embeddedJson(value: unknown): string {
  * 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 config = previewConfig(input);
   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">
@@ -176,12 +268,7 @@ export function buildPreview(input: PreviewInput): string {
   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.
+${PLAYER_LICENCE}
 -->
 <link rel="stylesheet" href="${PLAYER_STYLE_URL}">
 <style>
@@ -202,7 +289,7 @@ export function buildPreview(input: PreviewInput): string {
 </style>
 </head>
 <body>
-<header><b>${label}</b> <span>— ${played}</span></header>
+${headerHtml(input)}
 <div id="rigc-player"></div>
 <p id="rigc-status">loading the Spine Web Player…</p>
 <script src="${PLAYER_SCRIPT_URL}"></script>
@@ -241,3 +328,107 @@ export function buildPreview(input: PreviewInput): string {
 </html>
 `;
 }
+
+/**
+ * Several candidates on one page, a pane per candidate in the order given
+ * (issue #837).
+ *
+ * ⭐ This page asks nothing, and that is the whole difference from the ballot
+ * whose layout it borrows. A ballot hides where each candidate came from
+ * because a voter who can see it is no longer comparing pictures; here the
+ * question is "show me these", so each pane is headed exactly as a
+ * one-candidate preview is — its path, what it plays, the gate's line for it —
+ * and each player offers every animation its own skeleton has. No manifest, no
+ * digests and no result form: there is no answer to record.
+ *
+ * Each pane plays its own candidate's animation (the one `--animation` names,
+ * or its own first). The ballot refuses two panes playing two animations
+ * because the labels are A and B and nothing would say so; here the header over
+ * each pane names what it plays.
+ */
+export function buildPreviewPanes(inputs: PreviewInput[], version: string): string {
+  const configs = inputs.map((input) => previewConfig(input));
+  const panes = inputs.map((input, i) => paneSection(previewPaneId(i), headerHtml(input))).join('\n');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>rigc preview — ${inputs.length} candidates</title>
+<!--
+  Generated by rigc ${escapeHtml(version)} — https://github.com/firejune/rigc
+
+  Every candidate's skeleton, atlas and atlas pages are embedded in this file as
+  data URIs, so it plays on its own with no server and no sibling files.
+
+${PLAYER_LICENCE}
+-->
+<link rel="stylesheet" href="${PLAYER_STYLE_URL}">
+<style>
+  :root { color-scheme: light dark; }
+  html, body { margin: 0; min-height: 100%; }
+  body {
+    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); overflow-wrap: anywhere; }
+  header b { font-weight: 600; }
+  header span { opacity: 0.65; }
+${paneGridCss(inputs.length)}
+${PANE_STAGE_CSS}
+  #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>
+<div id="panes">
+${panes}
+</div>
+<p id="rigc-status">loading the Spine Web Player…</p>
+<script src="${PLAYER_SCRIPT_URL}"></script>
+<script>
+(function () {
+  var configs = ${embeddedJson(configs)};
+  var status = document.getElementById('rigc-status');
+  var state = { status: 'loading', message: null, players: [], ready: [], failed: [] };
+  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;
+  }
+  for (var i = 0; i < configs.length; i++) {
+    (function (pane, config) {
+      config.success = function (player) {
+        state.players[pane - 1] = player;
+        if (state.ready.indexOf(pane) === -1) state.ready.push(pane);
+        if (state.failed.length === 0 && state.ready.length === configs.length) {
+          say('ready', 'all ' + configs.length + ' panes are playing in Spine Web Player ${PLAYER_LINE} — everything they draw is embedded in this file.');
+        }
+      };
+      config.error = function (player, message) {
+        state.players[pane - 1] = player;
+        state.failed.push('pane ' + pane + ': ' + String(message));
+        say('error', state.failed.join('\\n'));
+      };
+      try {
+        new window.spine.SpinePlayer('rigc-player-' + pane, config);
+      } catch (err) {
+        state.failed.push('pane ' + pane + ': ' + String(err && err.message ? err.message : err));
+        say('error', state.failed.join('\\n'));
+      }
+    })(i + 1, configs[i]);
+  }
+})();
+</script>
+</body>
+</html>
+`;
+}

package/src/render.ts

@@ -198,6 +198,19 @@ export interface FramesSidecar {
    * one it cannot (`skin` absent while the run asked for one).
    */
   skin?: string;
+  /**
+   * The slots these frames draw, when `render --slot` narrowed them to a subset
+   * (issue #835) — in the skeleton's draw order, whatever order they were named in.
+   *
+   * ⭐ Absent on a render of every slot, for the reason `skin` is: that is what
+   * every frame set written before this field existed says too, so the whole-rig
+   * render stays byte-identical and the key's presence is the claim. A frame set
+   * carrying this or `hidden` is a picture of PART of the rig, and `check` refuses
+   * it as a reference by name rather than scoring a whole candidate against it.
+   */
+  slots?: string[];
+  /** The slots these frames leave out, when `render --hide` named them — see `slots`. */
+  hidden?: string[];
   /** The colour the frames were cleared to, straight RGBA 0..255. */
   background: RGBA;
   viewport: {
@@ -329,6 +342,118 @@ export interface PoseOptions {
    * whole flag exists to remove.
    */
   skin?: string;
+  /**
+   * Draw only these slots, by name (issue #835). `hidden` is the same statement
+   * the other way round, and the two together are refused.
+   *
+   * ⭐ **It is a filter on what is DRAWN, never on what is framed.**
+   * `framingViewport` takes both off before it samples, so a frame with `head`
+   * hidden sits on exactly the pixel grid of the frame with it and the two
+   * overlay — which is the whole use of the picture: *which part is this pixel*
+   * is answered by the difference between two frames of one grid, and a subset
+   * re-framed to its own extent would have no second frame to differ from.
+   *
+   * ⚠️ Applied in `piecesOf`, where the pieces are collected, and resolved there
+   * against the posed skeleton's own slots and skin — see `slotSubsetOf` — so a
+   * name that draws nothing is refused by name rather than quietly matching no
+   * piece.
+   */
+  slots?: string[];
+  /** Draw every slot but these — see `slots`. */
+  hidden?: string[];
+}
+
+/**
+ * Why a slot subset cannot be drawn — a `--slot`/`--hide` naming no slot, a slot
+ * whose art only another skin carries, or both flags at once (issue #835).
+ *
+ * A class of its own so `cli.ts` can turn it into a usage refusal (exit 2,
+ * nothing written) without reading a message to decide what kind it is.
+ */
+export class SlotSubsetError extends Error {}
+
+/** The flag spelling each half of a subset is refused under — the UI's, since that is who reads it. */
+const SUBSET_FLAG = { slots: '--slot', hidden: '--hide' } as const;
+
+/**
+ * A slot subset resolved against a skeleton: which half was asked for, and the
+ * names in the skeleton's **draw order** rather than the order they were typed.
+ *
+ * Draw order because the names are a set and the sidecar records them: `--hide
+ * b,a` and `--hide a,b` are one picture, and a sidecar whose bytes depended on
+ * the spelling would make two identical frame sets differ.
+ */
+export interface SlotSubset {
+  mode: 'slots' | 'hidden';
+  names: string[];
+}
+
+/**
+ * Resolve `slots` / `hidden` against `data` as posed under `skin`, or refuse by name.
+ *
+ * `undefined` when neither is set — the whole rig, which is the ordinary case and
+ * costs nothing. Refused, each naming what would have worked:
+ *
+ * - **both at once** — one statement two ways, as `--rig` with `--cut` is;
+ * - **a name the skeleton does not declare** — with every slot it does declare,
+ *   in draw order, and how many;
+ * - **a slot whose attachments live only under skins this pose does not
+ *   resolve through.** Every slot is declared at the skeleton's top level, so
+ *   "a slot only a named skin declares" is not a shape the format has — what a
+ *   skin declares is the slot's ART. A pose resolves an attachment through the
+ *   skin it was set to and then the default skin (`Skeleton.getAttachment`), so
+ *   a slot none of whose attachments is in either of those draws nothing in
+ *   every frame, and `--slot` on it would be a blank picture that looks like an
+ *   answer. The refusal names the skin(s) that do carry it.
+ *
+ * ⚠️ A declared slot with no attachment in ANY skin is accepted: it draws
+ * nothing under every skin, so there is no skin to name and no picture of it
+ * that a different invocation would produce.
+ */
+export function slotSubsetOf(
+  data: SkeletonData,
+  opts: Pick<PoseOptions, 'slots' | 'hidden'> | undefined,
+  skin: string | undefined,
+): SlotSubset | undefined {
+  if (opts?.slots !== undefined && opts.hidden !== undefined) {
+    throw new SlotSubsetError(
+      '--slot and --hide are one statement two ways; name the slots to draw or the slots to hide, not both',
+    );
+  }
+  const mode = opts?.slots !== undefined ? 'slots' : opts?.hidden !== undefined ? 'hidden' : undefined;
+  if (mode === undefined) return undefined;
+  const asked = (mode === 'slots' ? opts?.slots : opts?.hidden) ?? [];
+  const flag = SUBSET_FLAG[mode];
+  const declared = data.slots.map((slot) => slot.name);
+
+  const unknown = asked.filter((name) => data.findSlot(name) === null);
+  if (unknown.length > 0 || asked.length === 0) {
+    const named =
+      unknown.length === 0
+        ? 'was given no slot name'
+        : `${unknown.map((name) => JSON.stringify(name)).join(', ')} ${unknown.length === 1 ? 'names' : 'name'} no slot`;
+    throw new SlotSubsetError(
+      `${flag} ${named}; this skeleton declares, in draw order: ${declared.join(', ') || 'none'} (${declared.length})`,
+    );
+  }
+
+  const resolving = new Set([skin ?? null, data.defaultSkin?.name ?? null]);
+  const underThisPose =
+    skin === undefined ? 'under no skin (the default skin alone)' : `under skin ${JSON.stringify(skin)}`;
+  for (const name of asked) {
+    const index = data.findSlot(name)?.index ?? -1;
+    const carriers = data.skins.filter((s) => s.getAttachments().some((entry) => entry.slotIndex === index));
+    if (carriers.length === 0 || carriers.some((s) => resolving.has(s.name))) continue;
+    const skins = carriers.map((s) => JSON.stringify(s.name));
+    throw new SlotSubsetError(
+      `${flag} ${JSON.stringify(name)} draws nothing ${underThisPose}: its attachments are declared only under ` +
+        `${skins.length === 1 ? 'skin' : 'skins'} ${skins.join(', ')} — pass --skin ${
+          skins.length === 1 ? skins[0] : 'with one of them'
+        }`,
+    );
+  }
+  const chosen = new Set(asked);
+  return { mode, names: declared.filter((name) => chosen.has(name)) };
 }
 
 /**
@@ -646,8 +771,14 @@ export function piecesOf(skeleton: Skeleton, opts?: PoseOptions): Piece[] {
         'skeleton.setSkin(...) and skeleton.setupPose() before this.',
     );
   }
+  // Resolved against the skeleton as it was posed — its own slots and the skin
+  // it was set to — so a name that draws nothing is refused here, where the one
+  // application point is, rather than matching no piece in silence.
+  const subset = slotSubsetOf(skeleton.data, opts, skeleton.skin?.name);
+  const named = subset === undefined ? undefined : new Set(subset.names);
   const pieces: Piece[] = [];
   for (const slot of skeleton.drawOrder.appliedPose) {
+    if (subset !== undefined && named !== undefined && named.has(slot.data.name) !== (subset.mode === 'slots')) continue;
     const pose = slot.appliedPose;
     const attachment = pose.attachment;
     if (!attachment) continue;
@@ -1091,10 +1222,17 @@ export function framingViewport(data: SkeletonData, maxSide: number, opts?: Pose
   // attachments that POSE, and two skins fill a slot with art of different sizes
   // in different places. Framing one skin's shot with another skin's box would
   // put the difference between two skins into every measurement taken in it.
+  //
+  // ⭐ A slot subset is the opposite case, and is taken off (issue #835): what
+  // `--slot`/`--hide` leave out still counts toward the box, so a frame with a
+  // part hidden lands on the pixel grid of the frame with it and the two overlay.
+  // A subset framed to its own extent would move every pixel it kept.
+  const { slots: _drawn, hidden: _hidden, ...whole } = opts ?? {};
+  const framed = opts === undefined ? undefined : whole;
   const sets =
     data.animations.length === 0
-      ? [sampleSetupPose(data, opts)]
-      : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS, opts));
+      ? [sampleSetupPose(data, framed)]
+      : data.animations.map((a) => sampleAnimation(data, a.name, FRAMING_FPS, framed));
   const box = unionBounds(sets);
   if (!Number.isFinite(box.minX)) return null;
   const pad = Math.max(box.maxX - box.minX, box.maxY - box.minY) * PAD;