spine-rigc 0.5.0 → 0.6.0

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.',
       );
     }
   });

package/tools/plate.ts

@@ -169,7 +169,19 @@ function crc32(buf: Uint8Array): number {
   return (c ^ 0xffffffff) >>> 0;
 }
 
-function chunk(type: string, body: Uint8Array): Uint8Array {
+/** The eight bytes every PNG opens with. */
+export const PNG_SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * One PNG chunk: length, type, body, CRC.
+ *
+ * Exported because this writer only ever emits colour type 6, and the selftest
+ * has to produce the colour types it does NOT — indexed and greyscale, with and
+ * without a `tRNS` chunk — to have anything for `A19` to judge. Building those by
+ * hand needs the CRC table, and a second copy of it in the test would be a second
+ * thing that can be wrong.
+ */
+export function pngChunk(type: string, body: Uint8Array): Uint8Array {
   const out = new Uint8Array(body.length + 12);
   const view = new DataView(out.buffer);
   view.setUint32(0, body.length);
@@ -197,10 +209,10 @@ export function encodePng(width: number, height: number, rgba: Uint8Array): Uint
   ihdr[11] = 0;
   ihdr[12] = 0;
   const parts = [
-    new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    chunk('IHDR', ihdr),
-    chunk('IDAT', new Uint8Array(deflateSync(raw, { level: 9 }))),
-    chunk('IEND', new Uint8Array(0)),
+    PNG_SIGNATURE,
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', new Uint8Array(deflateSync(raw, { level: 9 }))),
+    pngChunk('IEND', new Uint8Array(0)),
   ];
   const total = parts.reduce((n, p) => n + p.length, 0);
   const out = new Uint8Array(total);
@@ -216,48 +228,127 @@ export function encodePng(width: number, height: number, rgba: Uint8Array): Uint
 // PNG decoding
 // ---------------------------------------------------------------------------
 
+/** Samples per pixel for each PNG colour type. Anything else is not a colour type. */
+const CHANNELS: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+/** The bit depths the PNG spec allows for each colour type. */
+const BIT_DEPTHS: Record<number, number[]> = {
+  0: [1, 2, 4, 8, 16],
+  2: [8, 16],
+  3: [1, 2, 4, 8],
+  4: [8, 16],
+  6: [8, 16],
+};
+
+/**
+ * Read one sample out of an unfiltered scanline, at the file's own bit depth.
+ *
+ * Returns the RAW value — 0..1 for a 1-bit file, 0..65535 for a 16-bit one — not
+ * a scaled byte. Two callers need it that way: a palette index IS the raw value,
+ * and a `tRNS` colour is declared at the file's depth and has to be compared
+ * against samples at that depth, not against something already rounded to 8 bits.
+ */
+function sampleAt(line: Uint8Array, index: number, bitDepth: number): number {
+  if (bitDepth === 8) return line[index];
+  if (bitDepth === 16) return (line[index * 2] << 8) | line[index * 2 + 1];
+  const perByte = 8 / bitDepth;
+  const byte = line[Math.floor(index / perByte)];
+  // Sub-byte samples are packed most-significant first.
+  const shift = 8 - bitDepth * ((index % perByte) + 1);
+  return (byte >> shift) & ((1 << bitDepth) - 1);
+}
+
+/** A raw sample scaled to 0..255, the range a `Plate` stores. */
+function toByte(sample: number, bitDepth: number): number {
+  if (bitDepth === 8) return sample;
+  if (bitDepth === 16) return sample >> 8;
+  return Math.round((sample * 255) / ((1 << bitDepth) - 1));
+}
+
 /**
- * Read an 8-bit RGB/RGBA PNG back into a `Plate`.
+ * Read a PNG back into a `Plate`, expanding whatever it is to straight RGBA.
  *
  * `src/png.ts` parses 26 bytes because that is all the COMPILER needs, and it
  * stays that way: the compiler never re-measures art. This
  * decoder is for the measuring tools, which is where art measurement belongs -
  * the same division that puts `mesh.center` in the manifest as a measured number
  * rather than as something the compiler derives at build time.
+ *
+ * ⭐ **Every colour type the gate accepts is decodable here** (issue #226). It
+ * used to read colour types 2 and 6 only, which was the compiler's own old blind
+ * spot rebuilt one step later: `A19` learned in #215 that indexed and greyscale
+ * art carrying a `tRNS` chunk is ordinary transparent art — ImageMagick, PNG-8
+ * export, GIMP indexed, aseprite and pngquant all write it — so such a part
+ * builds and validates green, and would then have been refused by the one command
+ * whose whole job is to show the author what they built. A wall removed at the
+ * gate and rebuilt at the picture is not a wall removed.
+ *
+ * So the expansion happens here, at decode: a palette index becomes its `PLTE`
+ * entry with its `tRNS` alpha, a greyscale sample becomes three equal channels,
+ * and a `tRNS` colour on a type 0 or 2 file becomes alpha 0 on the pixels that
+ * match it. Every caller above this line keeps seeing exactly one thing, RGBA.
+ *
+ * Interlaced files are still refused: Adam7 is a second sample layout rather than
+ * a second sample format, and no tool in the corpus writes one.
  */
 export function decodePng(buf: Uint8Array): Plate {
   const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
   let at = 8;
   let width = 0;
   let height = 0;
+  let bitDepth = 8;
   let colourType = 6;
+  let palette: Uint8Array | null = null;
+  let trns: Uint8Array | null = null;
   const idat: Uint8Array[] = [];
-  while (at < buf.length) {
+  while (at + 8 <= buf.length) {
     const len = view.getUint32(at);
     const type = String.fromCharCode(buf[at + 4], buf[at + 5], buf[at + 6], buf[at + 7]);
     const body = buf.subarray(at + 8, at + 8 + len);
     if (type === 'IHDR') {
       width = view.getUint32(at + 8);
       height = view.getUint32(at + 12);
-      if (body[8] !== 8) throw new Error(`unsupported bit depth ${body[8]}`);
+      bitDepth = body[8];
       colourType = body[9];
       if (body[12] !== 0) throw new Error('interlaced PNG');
-    } else if (type === 'IDAT') idat.push(body);
+    } else if (type === 'PLTE') palette = body.slice();
+    else if (type === 'tRNS') trns = body.slice();
+    else if (type === 'IDAT') idat.push(body);
     at += 12 + len;
   }
-  const bpp = colourType === 6 ? 4 : colourType === 2 ? 3 : 0;
-  if (!bpp) throw new Error(`unsupported colour type ${colourType}`);
+  const channels = CHANNELS[colourType];
+  if (channels === undefined) throw new Error(`unsupported colour type ${colourType}`);
+  if (!BIT_DEPTHS[colourType].includes(bitDepth)) {
+    throw new Error(`bit depth ${bitDepth} is not one PNG allows for colour type ${colourType}`);
+  }
+  if (colourType === 3 && palette === null) throw new Error('indexed PNG with no PLTE chunk');
+  // Const copies so the null checks above narrow inside the per-pixel loop below,
+  // where `palette` and `trns` are still the chunk loop's mutable bindings.
+  const pal = palette ?? new Uint8Array(0);
+  const alphaTable = trns;
+
   const raw = new Uint8Array(inflateSync(Buffer.concat(idat.map((c) => Buffer.from(c)))));
-  const stride = width * bpp + 1;
+  // The filter operates on BYTES, and its "left neighbour" is one whole pixel
+  // back — rounded up to a byte, so sub-byte depths compare against the byte
+  // immediately to the left.
+  const filterUnit = Math.max(1, Math.ceil((channels * bitDepth) / 8));
+  const rowBytes = Math.ceil((width * channels * bitDepth) / 8);
+  const stride = rowBytes + 1;
   const plate = new Plate(width, height);
-  let prev = new Uint8Array(width * bpp);
+  let prev = new Uint8Array(rowBytes);
+  // On a type 0 or 2 file a `tRNS` chunk names ONE invisible colour, one
+  // big-endian 16-bit sample per channel whatever the file's own depth. (For an
+  // indexed file the same chunk is something else entirely: one alpha byte per
+  // palette entry, read directly below.)
+  const trnsSample = (i: number): number =>
+    alphaTable === null ? -1 : (alphaTable[i * 2] << 8) | alphaTable[i * 2 + 1];
   for (let y = 0; y < height; y++) {
     const filter = raw[y * stride];
     const line = raw.slice(y * stride + 1, (y + 1) * stride);
-    for (let x = 0; x < width * bpp; x++) {
-      const a = x >= bpp ? line[x - bpp] : 0;
+    for (let x = 0; x < rowBytes; x++) {
+      const a = x >= filterUnit ? line[x - filterUnit] : 0;
       const b = prev[x];
-      const c = x >= bpp ? prev[x - bpp] : 0;
+      const c = x >= filterUnit ? prev[x - filterUnit] : 0;
       if (filter === 1) line[x] = (line[x] + a) & 255;
       else if (filter === 2) line[x] = (line[x] + b) & 255;
       else if (filter === 3) line[x] = (line[x] + ((a + b) >> 1)) & 255;
@@ -271,16 +362,68 @@ export function decodePng(buf: Uint8Array): Plate {
     }
     for (let x = 0; x < width; x++) {
       const o = (y * width + x) * 4;
-      plate.data[o] = line[x * bpp];
-      plate.data[o + 1] = line[x * bpp + 1];
-      plate.data[o + 2] = line[x * bpp + 2];
-      plate.data[o + 3] = bpp === 4 ? line[x * bpp + 3] : 255;
+      const first = x * channels;
+      if (colourType === 3) {
+        const index = sampleAt(line, first, bitDepth);
+        plate.data[o] = pal[index * 3];
+        plate.data[o + 1] = pal[index * 3 + 1];
+        plate.data[o + 2] = pal[index * 3 + 2];
+        // A tRNS shorter than the palette leaves the entries past its end opaque,
+        // which is what the spec says and what pngquant relies on.
+        plate.data[o + 3] = alphaTable !== null && index < alphaTable.length ? alphaTable[index] : 255;
+        continue;
+      }
+      if (colourType === 0 || colourType === 4) {
+        const grey = sampleAt(line, first, bitDepth);
+        const g = toByte(grey, bitDepth);
+        plate.data[o] = g;
+        plate.data[o + 1] = g;
+        plate.data[o + 2] = g;
+        plate.data[o + 3] =
+          colourType === 4
+            ? toByte(sampleAt(line, first + 1, bitDepth), bitDepth)
+            : alphaTable !== null && alphaTable.length >= 2 && trnsSample(0) === grey
+              ? 0
+              : 255;
+        continue;
+      }
+      const r = sampleAt(line, first, bitDepth);
+      const g = sampleAt(line, first + 1, bitDepth);
+      const b = sampleAt(line, first + 2, bitDepth);
+      plate.data[o] = toByte(r, bitDepth);
+      plate.data[o + 1] = toByte(g, bitDepth);
+      plate.data[o + 2] = toByte(b, bitDepth);
+      plate.data[o + 3] =
+        colourType === 6
+          ? toByte(sampleAt(line, first + 3, bitDepth), bitDepth)
+          : alphaTable !== null &&
+              alphaTable.length >= 6 &&
+              trnsSample(0) === r &&
+              trnsSample(1) === g &&
+              trnsSample(2) === b
+            ? 0
+            : 255;
     }
     prev = line;
   }
   return plate;
 }
 
+/**
+ * Decode the PNG at `path`, naming the file if it cannot be decoded.
+ *
+ * The bare message says what is wrong with the bytes and nothing about which
+ * bytes; a rig has as many pages as it has parts, and "unsupported colour type 5"
+ * with no path is a search rather than a fix.
+ */
 export function readPlate(path: string): Plate {
-  return decodePng(readFileSync(path));
+  // Only the DECODE is wrapped. A missing file already says which one, and
+  // rewording an ENOENT as a decoding problem would mislabel the commonest
+  // failure of all.
+  const buf = readFileSync(path);
+  try {
+    return decodePng(buf);
+  } catch (err) {
+    throw new Error(`cannot decode PNG ${path}: ${(err as Error).message}`);
+  }
 }