@hegemonart/get-design-done 1.21.0 → 1.23.0

package/scripts/lib/visual-baseline/diff.cjs

@@ -0,0 +1,137 @@
+/**
+ * visual-baseline/diff.cjs — pixel-diff primitive (Plan 23-07).
+ *
+ * Compares two PNG buffers. With `pngjs` installed (probeOptional),
+ * decodes both and counts pixels whose R/G/B/A channels differ beyond
+ * the tolerance. Without `pngjs`, falls back to bytewise equality
+ * (SHA-256 hash compare) — ratio is `equal ? 0 : 1`.
+ *
+ * Dimension mismatch in pixel mode → ratio=1, drifted=true,
+ * reason='dimension-mismatch'. Never throws on shape mismatch.
+ */
+
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { probeOptional } = require('../probe-optional.cjs');
+
+const _pngjs = probeOptional('pngjs');
+
+const DEFAULT_THRESHOLD = 0.005;
+const DEFAULT_TOLERANCE = 4;
+
+/**
+ * @typedef {Object} DiffResult
+ * @property {boolean} drifted
+ * @property {number} ratio
+ * @property {number} diffPixels
+ * @property {number} totalPixels
+ * @property {'pixel'|'bytewise'} mode
+ * @property {string} [reason]
+ */
+
+function bytewiseDiff(a, b, threshold) {
+  const ha = createHash('sha256').update(a).digest('hex');
+  const hb = createHash('sha256').update(b).digest('hex');
+  const equal = ha === hb;
+  const ratio = equal ? 0 : 1;
+  return {
+    drifted: ratio > threshold,
+    ratio,
+    diffPixels: equal ? 0 : 1,
+    totalPixels: 1,
+    mode: 'bytewise',
+    reason: 'pngjs-not-available',
+  };
+}
+
+function pixelDiff(a, b, threshold, tolerance) {
+  const { PNG } = _pngjs;
+  let pa;
+  let pb;
+  try {
+    pa = PNG.sync.read(a);
+  } catch (err) {
+    return {
+      drifted: true,
+      ratio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      mode: 'pixel',
+      reason: `decode-a-failed: ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+  try {
+    pb = PNG.sync.read(b);
+  } catch (err) {
+    return {
+      drifted: true,
+      ratio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      mode: 'pixel',
+      reason: `decode-b-failed: ${err && err.message ? err.message : String(err)}`,
+    };
+  }
+  if (pa.width !== pb.width || pa.height !== pb.height) {
+    return {
+      drifted: true,
+      ratio: 1,
+      diffPixels: 0,
+      totalPixels: 0,
+      mode: 'pixel',
+      reason: 'dimension-mismatch',
+    };
+  }
+  const total = pa.width * pa.height;
+  const A = pa.data;
+  const B = pb.data;
+  let diffPx = 0;
+  for (let i = 0; i < A.length; i += 4) {
+    const dr = Math.abs(A[i] - B[i]);
+    const dg = Math.abs(A[i + 1] - B[i + 1]);
+    const db = Math.abs(A[i + 2] - B[i + 2]);
+    const da = Math.abs(A[i + 3] - B[i + 3]);
+    if (dr > tolerance || dg > tolerance || db > tolerance || da > tolerance) {
+      diffPx += 1;
+    }
+  }
+  const ratio = total > 0 ? diffPx / total : 0;
+  return {
+    drifted: ratio > threshold,
+    ratio,
+    diffPixels: diffPx,
+    totalPixels: total,
+    mode: 'pixel',
+  };
+}
+
+/**
+ * Compare two PNG buffers.
+ *
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @param {{threshold?: number, tolerance?: number}} [opts]
+ * @returns {DiffResult}
+ */
+function diff(a, b, opts = {}) {
+  if (!Buffer.isBuffer(a) || !Buffer.isBuffer(b)) {
+    throw new TypeError('visual-baseline/diff: both inputs must be Buffers');
+  }
+  const threshold = typeof opts.threshold === 'number' ? opts.threshold : DEFAULT_THRESHOLD;
+  const tolerance = typeof opts.tolerance === 'number' ? opts.tolerance : DEFAULT_TOLERANCE;
+  if (!_pngjs) return bytewiseDiff(a, b, threshold);
+  return pixelDiff(a, b, threshold, tolerance);
+}
+
+/** Test-only: report whether pngjs is available. */
+function pngjsAvailable() {
+  return _pngjs !== null && _pngjs !== undefined;
+}
+
+module.exports = {
+  diff,
+  pngjsAvailable,
+  DEFAULT_THRESHOLD,
+  DEFAULT_TOLERANCE,
+};

package/scripts/lib/visual-baseline/index.cjs

@@ -0,0 +1,139 @@
+/**
+ * visual-baseline/index.cjs — baseline manager for PNG drift checks
+ * (Plan 23-07).
+ *
+ * Reads/writes `.design/baselines/<key>.png`. Compare delegates to
+ * `./diff.cjs#diff`. Atomic write via `.tmp` sibling + rename.
+ *
+ * Defers Playwright/Preview MCP screenshot capture orchestration to a
+ * later phase — this module only handles "given a PNG buffer, compare it
+ * / save it as the baseline".
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { diff, DEFAULT_THRESHOLD, DEFAULT_TOLERANCE } = require('./diff.cjs');
+
+const DEFAULT_BASELINE_DIR = '.design/baselines';
+const SAFE_KEY_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/i;
+
+/**
+ * @typedef {Object} CompareOutcome
+ * @property {boolean} drifted
+ * @property {number} ratio
+ * @property {boolean} baselineExists
+ * @property {string} baselinePath
+ * @property {'pixel'|'bytewise'|'absent'} mode
+ * @property {number} [diffPixels]
+ * @property {number} [totalPixels]
+ * @property {string} [reason]
+ */
+
+/**
+ * Validate a baseline key. Rejects path separators, '..', and unsafe
+ * characters that could traverse outside the baseline dir.
+ *
+ * @param {string} key
+ * @returns {string}
+ */
+function validateKey(key) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError('visual-baseline: key must be a non-empty string');
+  }
+  if (key.includes('..') || key.includes('/') || key.includes('\\')) {
+    throw new RangeError(
+      `visual-baseline: key "${key}" contains illegal characters (/, \\, ..)`,
+    );
+  }
+  if (!SAFE_KEY_RE.test(key)) {
+    throw new RangeError(
+      `visual-baseline: key "${key}" must match /^[a-z0-9][a-z0-9._-]{0,127}$/i`,
+    );
+  }
+  return key;
+}
+
+/**
+ * Resolve baseline file path.
+ *
+ * @param {string} key
+ * @param {{cwd?: string, baselineDir?: string}} [opts]
+ * @returns {string}
+ */
+function baselinePathFor(key, opts = {}) {
+  validateKey(key);
+  const cwd = opts.cwd ?? process.cwd();
+  const dir = opts.baselineDir ?? DEFAULT_BASELINE_DIR;
+  const root = path.isAbsolute(dir) ? dir : path.join(cwd, dir);
+  return path.join(root, `${key}.png`);
+}
+
+/**
+ * Compare a PNG buffer to the on-disk baseline.
+ *
+ * @param {string} key
+ * @param {Buffer} pngBuffer
+ * @param {{cwd?: string, threshold?: number, tolerance?: number, baselineDir?: string}} [opts]
+ * @returns {CompareOutcome}
+ */
+function compareToBaseline(key, pngBuffer, opts = {}) {
+  if (!Buffer.isBuffer(pngBuffer)) {
+    throw new TypeError('visual-baseline: pngBuffer must be a Buffer');
+  }
+  const baselinePath = baselinePathFor(key, opts);
+  if (!fs.existsSync(baselinePath)) {
+    return {
+      drifted: true,
+      ratio: NaN,
+      baselineExists: false,
+      baselinePath,
+      mode: 'absent',
+      reason: 'baseline-not-found',
+    };
+  }
+  const a = fs.readFileSync(baselinePath);
+  const r = diff(a, pngBuffer, opts);
+  return {
+    drifted: r.drifted,
+    ratio: r.ratio,
+    baselineExists: true,
+    baselinePath,
+    mode: r.mode,
+    diffPixels: r.diffPixels,
+    totalPixels: r.totalPixels,
+    reason: r.reason,
+  };
+}
+
+/**
+ * Persist a PNG buffer as the baseline. Atomic write (.tmp + rename).
+ *
+ * @param {string} key
+ * @param {Buffer} pngBuffer
+ * @param {{cwd?: string, baselineDir?: string}} [opts]
+ * @returns {string} absolute path written
+ */
+function applyBaseline(key, pngBuffer, opts = {}) {
+  if (!Buffer.isBuffer(pngBuffer)) {
+    throw new TypeError('visual-baseline: pngBuffer must be a Buffer');
+  }
+  const out = baselinePathFor(key, opts);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  const tmp = out + '.tmp';
+  fs.writeFileSync(tmp, pngBuffer);
+  fs.renameSync(tmp, out);
+  return out;
+}
+
+module.exports = {
+  compareToBaseline,
+  applyBaseline,
+  baselinePathFor,
+  validateKey,
+  DEFAULT_BASELINE_DIR,
+  DEFAULT_THRESHOLD,
+  DEFAULT_TOLERANCE,
+};