@oim-media/spec 1.27.8 → 1.27.10

package/tools/parity-core.mjs

@@ -1,122 +1,122 @@
-// Copyright (c) 2026 Xue Studios LLC
-// SPDX-License-Identifier: Apache-2.0
-// Visual conformance metric (CANONICAL_SPEC.md, "Visual conformance"). Zero dependencies.
-import zlib from 'node:zlib';
-
-export const CHANNEL_TOLERANCE = 40;
-// Calibrated 2026-11-07: passing text noise reaches 0.265 %, a unitless letterSpacing bug 0.509 %.
-export const MAX_AREA = 0.004;
-export const MAX_BLOB = 24 * 24;
-
-const SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
-
-const paeth = (a, b, c) => {
-  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
-  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
-};
-
-/** Decodes an 8-bit, non-interlaced RGB or RGBA PNG to RGBA. */
-export const decodePng = (buf) => {
-  if (!buf.subarray(0, 8).equals(SIGNATURE)) throw new Error('unsupported PNG: bad signature');
-  let pos = 8, width = 0, height = 0, type = 0;
-  const idat = [];
-  while (pos < buf.length) {
-    const len = buf.readUInt32BE(pos), kind = buf.toString('latin1', pos + 4, pos + 8);
-    const data = buf.subarray(pos + 8, pos + 8 + len);
-    if (kind === 'IHDR') {
-      width = data.readUInt32BE(0); height = data.readUInt32BE(4); type = data[9];
-      if (data[8] !== 8 || (type !== 2 && type !== 6) || data[12] !== 0)
-        throw new Error(`unsupported PNG: bit depth ${data[8]}, colour type ${type}, interlace ${data[12]}`);
-    } else if (kind === 'IDAT') idat.push(data);
-    else if (kind === 'IEND') break;
-    pos += 12 + len;
-  }
-  const raw = zlib.inflateSync(Buffer.concat(idat));
-  const bpp = type === 6 ? 4 : 3, stride = width * bpp;
-  const out = Buffer.alloc(stride * height);
-  for (let y = 0; y < height; y++) {
-    const f = raw[y * (stride + 1)], src = y * (stride + 1) + 1, row = y * stride;
-    for (let i = 0; i < stride; i++) {
-      const a = i >= bpp ? out[row + i - bpp] : 0, b = y ? out[row - stride + i] : 0;
-      const c = i >= bpp && y ? out[row - stride + i - bpp] : 0;
-      const pred = f === 0 ? 0 : f === 1 ? a : f === 2 ? b : f === 3 ? (a + b) >> 1 : f === 4 ? paeth(a, b, c) : NaN;
-      if (Number.isNaN(pred)) throw new Error(`unsupported PNG: filter ${f}`);
-      out[row + i] = (raw[src + i] + pred) & 255;
-    }
-  }
-  const rgba = new Uint8Array(width * height * 4);
-  for (let p = 0; p < width * height; p++) {
-    rgba[p * 4] = out[p * bpp]; rgba[p * 4 + 1] = out[p * bpp + 1]; rgba[p * 4 + 2] = out[p * bpp + 2];
-    rgba[p * 4 + 3] = bpp === 4 ? out[p * bpp + 3] : 255;
-  }
-  return { width, height, rgba };
-};
-
-const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
-  let c = n;
-  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
-  return c >>> 0;
-});
-const crc32 = (buf) => {
-  let c = 0xffffffff;
-  for (const byte of buf) c = CRC_TABLE[(c ^ byte) & 255] ^ (c >>> 8);
-  return (c ^ 0xffffffff) >>> 0;
-};
-const chunk = (kind, data) => {
-  const head = Buffer.alloc(8); head.writeUInt32BE(data.length); head.write(kind, 4, 'latin1');
-  const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])));
-  return Buffer.concat([head, data, crc]);
-};
-
-/** Encodes RGBA as an 8-bit RGBA PNG (filter 0). */
-export const encodePng = ({ width, height, rgba }) => {
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(width); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 6;
-  const raw = Buffer.alloc((width * 4 + 1) * height);
-  for (let y = 0; y < height; y++) raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1);
-  return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
-};
-
-// Composite over white: a transparent render is a blank page, not black.
-const onWhite = (rgba, i) => {
-  const a = rgba[i + 3] / 255;
-  return [0, 1, 2].map((k) => rgba[i + k] * a + 255 * (1 - a));
-};
-
-/** Compares a render against a golden under the visual conformance metric. */
-export const compare = (golden, render) => {
-  const { width: w, height: h } = golden;
-  if (w !== render.width || h !== render.height)
-    return { ok: false, reason: `size ${render.width}x${render.height}, expected ${w}x${h}`, area: 1, largestBlob: 0, mask: new Uint8Array(0) };
-  const diff = new Uint8Array(w * h);
-  for (let p = 0; p < w * h; p++) {
-    const g = onWhite(golden.rgba, p * 4), r = onWhite(render.rgba, p * 4);
-    diff[p] = g.some((v, k) => Math.abs(Math.round(v) - Math.round(r[k])) > CHANNEL_TOLERANCE) ? 1 : 0;
-  }
-  // 3x3 erosion: antialiasing and hinting leave 1-2 px lines; a defect is an area.
-  const mask = new Uint8Array(w * h);
-  let count = 0;
-  for (let y = 1; y < h - 1; y++)
-    for (let x = 1; x < w - 1; x++) {
-      let all = 1;
-      for (let dy = -1; dy <= 1 && all; dy++) for (let dx = -1; dx <= 1 && all; dx++) all = diff[(y + dy) * w + x + dx];
-      if (all) { mask[y * w + x] = 1; count++; }
-    }
-  let largestBlob = 0;
-  const seen = new Uint8Array(w * h), stack = [];
-  for (let p = 0; p < w * h; p++) {
-    if (!mask[p] || seen[p]) continue;
-    let size = 0;
-    stack.push(p); seen[p] = 1;
-    while (stack.length) {
-      const q = stack.pop(), x = q % w;
-      size++;
-      for (const n of [q - w, q + w, x > 0 ? q - 1 : -1, x < w - 1 ? q + 1 : -1])
-        if (n >= 0 && n < w * h && mask[n] && !seen[n]) { seen[n] = 1; stack.push(n); }
-    }
-    largestBlob = Math.max(largestBlob, size);
-  }
-  const area = count / (w * h);
-  const ok = area <= MAX_AREA && largestBlob <= MAX_BLOB;
-  return { ok, reason: ok ? undefined : `area ${(area * 100).toFixed(3)}%, largest blob ${largestBlob}px`, area, largestBlob, mask };
-};
+// Copyright (c) 2026 Xue Studios LLC
+// SPDX-License-Identifier: Apache-2.0
+// Visual conformance metric (CANONICAL_SPEC.md, "Visual conformance"). Zero dependencies.
+import zlib from 'node:zlib';
+
+export const CHANNEL_TOLERANCE = 40;
+// Calibrated 2026-11-07: passing text noise reaches 0.265 %, a unitless letterSpacing bug 0.509 %.
+export const MAX_AREA = 0.004;
+export const MAX_BLOB = 24 * 24;
+
+const SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+const paeth = (a, b, c) => {
+  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+};
+
+/** Decodes an 8-bit, non-interlaced RGB or RGBA PNG to RGBA. */
+export const decodePng = (buf) => {
+  if (!buf.subarray(0, 8).equals(SIGNATURE)) throw new Error('unsupported PNG: bad signature');
+  let pos = 8, width = 0, height = 0, type = 0;
+  const idat = [];
+  while (pos < buf.length) {
+    const len = buf.readUInt32BE(pos), kind = buf.toString('latin1', pos + 4, pos + 8);
+    const data = buf.subarray(pos + 8, pos + 8 + len);
+    if (kind === 'IHDR') {
+      width = data.readUInt32BE(0); height = data.readUInt32BE(4); type = data[9];
+      if (data[8] !== 8 || (type !== 2 && type !== 6) || data[12] !== 0)
+        throw new Error(`unsupported PNG: bit depth ${data[8]}, colour type ${type}, interlace ${data[12]}`);
+    } else if (kind === 'IDAT') idat.push(data);
+    else if (kind === 'IEND') break;
+    pos += 12 + len;
+  }
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const bpp = type === 6 ? 4 : 3, stride = width * bpp;
+  const out = Buffer.alloc(stride * height);
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)], src = y * (stride + 1) + 1, row = y * stride;
+    for (let i = 0; i < stride; i++) {
+      const a = i >= bpp ? out[row + i - bpp] : 0, b = y ? out[row - stride + i] : 0;
+      const c = i >= bpp && y ? out[row - stride + i - bpp] : 0;
+      const pred = f === 0 ? 0 : f === 1 ? a : f === 2 ? b : f === 3 ? (a + b) >> 1 : f === 4 ? paeth(a, b, c) : NaN;
+      if (Number.isNaN(pred)) throw new Error(`unsupported PNG: filter ${f}`);
+      out[row + i] = (raw[src + i] + pred) & 255;
+    }
+  }
+  const rgba = new Uint8Array(width * height * 4);
+  for (let p = 0; p < width * height; p++) {
+    rgba[p * 4] = out[p * bpp]; rgba[p * 4 + 1] = out[p * bpp + 1]; rgba[p * 4 + 2] = out[p * bpp + 2];
+    rgba[p * 4 + 3] = bpp === 4 ? out[p * bpp + 3] : 255;
+  }
+  return { width, height, rgba };
+};
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+const crc32 = (buf) => {
+  let c = 0xffffffff;
+  for (const byte of buf) c = CRC_TABLE[(c ^ byte) & 255] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+};
+const chunk = (kind, data) => {
+  const head = Buffer.alloc(8); head.writeUInt32BE(data.length); head.write(kind, 4, 'latin1');
+  const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])));
+  return Buffer.concat([head, data, crc]);
+};
+
+/** Encodes RGBA as an 8-bit RGBA PNG (filter 0). */
+export const encodePng = ({ width, height, rgba }) => {
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 6;
+  const raw = Buffer.alloc((width * 4 + 1) * height);
+  for (let y = 0; y < height; y++) raw.set(rgba.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1);
+  return Buffer.concat([SIGNATURE, chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+};
+
+// Composite over white: a transparent render is a blank page, not black.
+const onWhite = (rgba, i) => {
+  const a = rgba[i + 3] / 255;
+  return [0, 1, 2].map((k) => rgba[i + k] * a + 255 * (1 - a));
+};
+
+/** Compares a render against a golden under the visual conformance metric. */
+export const compare = (golden, render) => {
+  const { width: w, height: h } = golden;
+  if (w !== render.width || h !== render.height)
+    return { ok: false, reason: `size ${render.width}x${render.height}, expected ${w}x${h}`, area: 1, largestBlob: 0, mask: new Uint8Array(0) };
+  const diff = new Uint8Array(w * h);
+  for (let p = 0; p < w * h; p++) {
+    const g = onWhite(golden.rgba, p * 4), r = onWhite(render.rgba, p * 4);
+    diff[p] = g.some((v, k) => Math.abs(Math.round(v) - Math.round(r[k])) > CHANNEL_TOLERANCE) ? 1 : 0;
+  }
+  // 3x3 erosion: antialiasing and hinting leave 1-2 px lines; a defect is an area.
+  const mask = new Uint8Array(w * h);
+  let count = 0;
+  for (let y = 1; y < h - 1; y++)
+    for (let x = 1; x < w - 1; x++) {
+      let all = 1;
+      for (let dy = -1; dy <= 1 && all; dy++) for (let dx = -1; dx <= 1 && all; dx++) all = diff[(y + dy) * w + x + dx];
+      if (all) { mask[y * w + x] = 1; count++; }
+    }
+  let largestBlob = 0;
+  const seen = new Uint8Array(w * h), stack = [];
+  for (let p = 0; p < w * h; p++) {
+    if (!mask[p] || seen[p]) continue;
+    let size = 0;
+    stack.push(p); seen[p] = 1;
+    while (stack.length) {
+      const q = stack.pop(), x = q % w;
+      size++;
+      for (const n of [q - w, q + w, x > 0 ? q - 1 : -1, x < w - 1 ? q + 1 : -1])
+        if (n >= 0 && n < w * h && mask[n] && !seen[n]) { seen[n] = 1; stack.push(n); }
+    }
+    largestBlob = Math.max(largestBlob, size);
+  }
+  const area = count / (w * h);
+  const ok = area <= MAX_AREA && largestBlob <= MAX_BLOB;
+  return { ok, reason: ok ? undefined : `area ${(area * 100).toFixed(3)}%, largest blob ${largestBlob}px`, area, largestBlob, mask };
+};

package/tools/parity.mjs

@@ -1,86 +1,86 @@
-#!/usr/bin/env node
-// Copyright (c) 2026 Xue Studios LLC
-// SPDX-License-Identifier: Apache-2.0
-// Visual conformance: compares a renderer's PNGs against the web goldens.
-// Usage: node parity.mjs <renders-dir> --renderer <name> [--out <diff-dir>]
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { decodePng, encodePng, compare } from './parity-core.mjs';
-
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-
-const names = (dir, suffix) =>
-  fs.readdirSync(dir).filter((f) => f.endsWith(suffix)).map((f) => f.slice(0, -suffix.length)).sort();
-
-const diffImage = (golden, mask) => {
-  const rgba = new Uint8Array(golden.rgba.length);
-  for (let p = 0; p < mask.length; p++) {
-    const i = p * 4;
-    if (mask[p]) rgba.set([255, 0, 0, 255], i);
-    else rgba.set([golden.rgba[i] * 0.3, golden.rgba[i + 1] * 0.3, golden.rgba[i + 2] * 0.3, 255], i);
-  }
-  return { width: golden.width, height: golden.height, rgba };
-};
-
-export const runParity = ({
-  rendersDir,
-  renderer,
-  outDir,
-  goldenDir = path.join(HERE, '..', 'vectors', 'golden'),
-  vectorsDir = path.join(HERE, '..', 'vectors'),
-}) => {
-  const failures = [], lines = [];
-  const vectors = names(vectorsDir, '.oim.png');
-  const goldens = names(goldenDir, '.web.png');
-  const exceptionsFile = path.join(goldenDir, 'exceptions.json');
-  const exceptions = (fs.existsSync(exceptionsFile) ? JSON.parse(fs.readFileSync(exceptionsFile, 'utf8')) : {})[renderer] ?? {};
-
-  for (const v of vectors) if (!goldens.includes(v)) failures.push(`${v}: no golden for this vector, regenerate the goldens`);
-  for (const g of goldens) if (!vectors.includes(g)) failures.push(`${g}: orphan golden, no vector`);
-  for (const e of Object.keys(exceptions)) if (!vectors.includes(e)) failures.push(`${e}: unknown vector in exceptions`);
-  if (outDir) fs.mkdirSync(outDir, { recursive: true });
-
-  for (const name of goldens.filter((g) => vectors.includes(g))) {
-    const renderPath = path.join(rendersDir, `${name}.png`);
-    const excepted = name in exceptions;
-    // `broken`: no comparison happened (missing, unreadable or wrong-size render). An exception never covers it.
-    let verdict, detail = '', broken = false;
-    if (!fs.existsSync(renderPath)) {
-      verdict = 'FAIL'; detail = 'missing render'; broken = true;
-    } else {
-      let golden, r;
-      try {
-        golden = decodePng(fs.readFileSync(path.join(goldenDir, `${name}.web.png`)));
-        r = compare(golden, decodePng(fs.readFileSync(renderPath)));
-      } catch (err) {
-        r = { ok: false, reason: err.message, area: 1, largestBlob: 0 };
-      }
-      broken = !r.ok && !r.mask?.length;
-      detail = r.reason ?? `area=${(r.area * 100).toFixed(3)}% blob=${r.largestBlob}px`;
-      verdict = r.ok ? 'PASS' : 'FAIL';
-      if (!r.ok && outDir && r.mask?.length) fs.writeFileSync(path.join(outDir, `${name}.diff.png`), encodePng(diffImage(golden, r.mask)));
-    }
-    if (excepted && verdict === 'PASS') failures.push(`${name}: passes, remove the exception for ${renderer}`);
-    else if (excepted && !broken) verdict = 'EXCEPTED';
-    else if (verdict === 'FAIL') failures.push(`${name}: ${detail}`);
-    lines.push(`${name.padEnd(32)} ${verdict.padEnd(8)} ${detail}`);
-  }
-  if (!lines.length) failures.push('no vectors compared: check the vectors and goldens directories');
-  return { failures, lines };
-};
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
-  const args = process.argv.slice(2);
-  const flag = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
-  const rendersDir = args[0], renderer = flag('--renderer');
-  if (!rendersDir || !renderer) {
-    console.error('usage: parity.mjs <renders-dir> --renderer <name> [--out <diff-dir>]');
-    process.exit(2);
-  }
-  const { failures, lines } = runParity({ rendersDir, renderer, outDir: flag('--out') });
-  lines.forEach((l) => console.log(l));
-  failures.forEach((f) => console.error(`✖ ${f}`));
-  console.log(failures.length ? `\n${failures.length} failure(s)` : '\nvisual parity: OK');
-  process.exit(failures.length ? 1 : 0);
-}
+#!/usr/bin/env node
+// Copyright (c) 2026 Xue Studios LLC
+// SPDX-License-Identifier: Apache-2.0
+// Visual conformance: compares a renderer's PNGs against the web goldens.
+// Usage: node parity.mjs <renders-dir> --renderer <name> [--out <diff-dir>]
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { decodePng, encodePng, compare } from './parity-core.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+const names = (dir, suffix) =>
+  fs.readdirSync(dir).filter((f) => f.endsWith(suffix)).map((f) => f.slice(0, -suffix.length)).sort();
+
+const diffImage = (golden, mask) => {
+  const rgba = new Uint8Array(golden.rgba.length);
+  for (let p = 0; p < mask.length; p++) {
+    const i = p * 4;
+    if (mask[p]) rgba.set([255, 0, 0, 255], i);
+    else rgba.set([golden.rgba[i] * 0.3, golden.rgba[i + 1] * 0.3, golden.rgba[i + 2] * 0.3, 255], i);
+  }
+  return { width: golden.width, height: golden.height, rgba };
+};
+
+export const runParity = ({
+  rendersDir,
+  renderer,
+  outDir,
+  goldenDir = path.join(HERE, '..', 'vectors', 'golden'),
+  vectorsDir = path.join(HERE, '..', 'vectors'),
+}) => {
+  const failures = [], lines = [];
+  const vectors = names(vectorsDir, '.oim.png');
+  const goldens = names(goldenDir, '.web.png');
+  const exceptionsFile = path.join(goldenDir, 'exceptions.json');
+  const exceptions = (fs.existsSync(exceptionsFile) ? JSON.parse(fs.readFileSync(exceptionsFile, 'utf8')) : {})[renderer] ?? {};
+
+  for (const v of vectors) if (!goldens.includes(v)) failures.push(`${v}: no golden for this vector, regenerate the goldens`);
+  for (const g of goldens) if (!vectors.includes(g)) failures.push(`${g}: orphan golden, no vector`);
+  for (const e of Object.keys(exceptions)) if (!vectors.includes(e)) failures.push(`${e}: unknown vector in exceptions`);
+  if (outDir) fs.mkdirSync(outDir, { recursive: true });
+
+  for (const name of goldens.filter((g) => vectors.includes(g))) {
+    const renderPath = path.join(rendersDir, `${name}.png`);
+    const excepted = name in exceptions;
+    // `broken`: no comparison happened (missing, unreadable or wrong-size render). An exception never covers it.
+    let verdict, detail = '', broken = false;
+    if (!fs.existsSync(renderPath)) {
+      verdict = 'FAIL'; detail = 'missing render'; broken = true;
+    } else {
+      let golden, r;
+      try {
+        golden = decodePng(fs.readFileSync(path.join(goldenDir, `${name}.web.png`)));
+        r = compare(golden, decodePng(fs.readFileSync(renderPath)));
+      } catch (err) {
+        r = { ok: false, reason: err.message, area: 1, largestBlob: 0 };
+      }
+      broken = !r.ok && !r.mask?.length;
+      detail = r.reason ?? `area=${(r.area * 100).toFixed(3)}% blob=${r.largestBlob}px`;
+      verdict = r.ok ? 'PASS' : 'FAIL';
+      if (!r.ok && outDir && r.mask?.length) fs.writeFileSync(path.join(outDir, `${name}.diff.png`), encodePng(diffImage(golden, r.mask)));
+    }
+    if (excepted && verdict === 'PASS') failures.push(`${name}: passes, remove the exception for ${renderer}`);
+    else if (excepted && !broken) verdict = 'EXCEPTED';
+    else if (verdict === 'FAIL') failures.push(`${name}: ${detail}`);
+    lines.push(`${name.padEnd(32)} ${verdict.padEnd(8)} ${detail}`);
+  }
+  if (!lines.length) failures.push('no vectors compared: check the vectors and goldens directories');
+  return { failures, lines };
+};
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  const args = process.argv.slice(2);
+  const flag = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+  const rendersDir = args[0], renderer = flag('--renderer');
+  if (!rendersDir || !renderer) {
+    console.error('usage: parity.mjs <renders-dir> --renderer <name> [--out <diff-dir>]');
+    process.exit(2);
+  }
+  const { failures, lines } = runParity({ rendersDir, renderer, outDir: flag('--out') });
+  lines.forEach((l) => console.log(l));
+  failures.forEach((f) => console.error(`✖ ${f}`));
+  console.log(failures.length ? `\n${failures.length} failure(s)` : '\nvisual parity: OK');
+  process.exit(failures.length ? 1 : 0);
+}