CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

diff-report.mjsskills/replica/scripts/

#!/usr/bin/env node
/**
 * skills/replica/scripts/diff-report.mjs
 *
 * Where are the differences? pixel-compare's 500 px bands say WHERE on the page, never WHICH block; its diff image is
 * 8–15k px tall. This reads a gate round's evidence (live.png, build.png and a diff PNG in one gate dir), loads the
 * BUILD page once at the same width to read its block boxes, and reports the differing-pixel share per block —
 * the block a fix belongs to — plus a self-contained HTML report: the table, a live | build | diff overview (the three
 * captures scaled side by side) and live / build / diff crops of the hottest blocks.
 *
 * Blocks: `[data-block-name]` elements plus each `.default-content-wrapper` ("default content (section N)") when the
 * build has them (an EDS page), else `main > .section`, else the children of `main` (a prototype), or `--blocks <css>`.
 * A block inside another picked block is folded into the outermost one (named "<outer> (+N nested)"), so no pixel
 * counts twice. Rows outside every block are one "outside blocks" row (chrome, gaps). The diff's red pixels are
 * pixel-compare's own count (anti-aliased yellow excluded). pixel-compare diffs only the shorter capture's height:
 * when live and build heights differ a warning is printed, a block below the compared height is "not compared" and
 * one straddling it is "partial" (its share is over the compared rows only).
 *
 * Usage:
 *   node skills/replica/scripts/diff-report.mjs <gateDir> <buildURL> [options]
 *     --width <px>     viewport width of the round              (default: the PNG's width)
 *     --diff <file>    diff PNG, relative to <gateDir> or absolute (default: the newest diff-*.png; gate.sh writes
 *                      diff-<label>.png, label default iter)
 *     --blocks <css>   block selector on the build              (default: auto, see above)
 *     --top <n>        crops for the n hottest blocks           (default 4)
 *     --out <dir>      report dir                               (default <gateDir>/report)
 *     --json           the table as JSON on stdout
 *
 * Writes <out>/report.html, <out>/overview.png and <out>/crop-<n>-{live,build,diff}.png. Exit: 0 written, 1 error.
 * Requires playwright and pngjs (project devDependencies; imported lazily, so --help and the pure test need neither).
 */
/* eslint-disable no-await-in-loop, max-len */
import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
import { basename, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

// browser.mjs lives in the master skill's scripts dir: the plugin tree (skills/replica/scripts ↔ skills/stardust/scripts)
// or the project copy (scripts/replica ↔ scripts/stardust). Resolved in main, so the pure exports need no browser.
const BROWSER = ['../../stardust/scripts/browser.mjs', '../stardust/browser.mjs']
  .map((p) => new URL(p, import.meta.url)).find((u) => existsSync(u));

export const HELP = readFileSync(new URL(import.meta.url), 'utf8').match(/\/\*\*([\s\S]*?)\*\//)[1].replace(/^\s*\* ?/gm, '').trim();

export function parseArgs(argv) {
  const rest = argv.slice(2);
  const opts = { width: null, diff: null, blocks: null, top: 4, out: null, json: false };
  const pos = [];
  for (let i = 0; i < rest.length; i += 1) {
    const a = rest[i];
    if (a === '--width') opts.width = Number(rest[i += 1]);
    else if (a === '--diff') opts.diff = rest[i += 1];
    else if (a === '--blocks') opts.blocks = rest[i += 1];
    else if (a === '--top') opts.top = Number(rest[i += 1]);
    else if (a === '--out') opts.out = rest[i += 1];
    else if (a === '--json') opts.json = true;
    else if (a.startsWith('--')) throw new Error(`unknown flag ${a}`);
    else pos.push(a);
  }
  const [dir, build] = pos;
  if (!dir || !build) throw new Error('need <gateDir> and <buildURL>');
  return { dir, build, opts };
}

// The diff PNG a round left: --diff (relative to the gate dir, or absolute), else the newest diff-*.png
// (gate.sh writes diff-<label>.png, label default iter).
export function pickDiff(dir, explicit) {
  if (explicit) return resolve(dir, explicit);
  const all = readdirSync(dir).filter((f) => /^diff-.*\.png$/.test(f)).sort((a, b) => statSync(join(dir, b)).mtimeMs - statSync(join(dir, a)).mtimeMs);
  if (!all.length) throw new Error(`no diff-*.png in ${dir} — run a gate round first`);
  return join(dir, all[0]);
}

const red = (d, i) => d[i] === 255 && d[i + 1] < 100;

// Pure: differing-pixel share per block ({ name, x, y, w, h } in page coordinates) over a diff image
// ({ width, height, data }), plus the rows outside every block. The diff covers only the shorter capture's height, so
// a block is clipped to the image: `compared` is 'full', 'partial' (y0..y1 is the compared part of top..bottom) or
// 'none' (wholly below the diff — pct null, never a false 0 %). The outside row counts every pixel no block covers.
export function blockTable(diff, blocks) {
  const { width: W, height: H, data } = diff;
  const covered = new Uint8Array(W * H);
  const rows = blocks.map((b, k) => {
    const top = Math.max(0, Math.floor(b.y)); const bottom = Math.ceil(b.y + b.h);
    const x0 = Math.max(0, Math.floor(b.x)); const x1 = Math.min(W, Math.ceil(b.x + b.w));
    const y0 = Math.min(top, H); const y1 = Math.min(H, bottom);
    const compared = y1 <= y0 ? 'none' : (bottom > H ? 'partial' : 'full');
    let px = 0; let hit = 0;
    for (let y = y0; y < y1; y += 1) {
      for (let x = x0; x < x1; x += 1) {
        const p = y * W + x;
        covered[p] = 1; px += 1;
        if (red(data, p * 4)) hit += 1;
      }
    }
    return { k, name: b.name, top, bottom, y0, y1, compared, px, differing: hit, pct: compared === 'none' ? null : (px ? (100 * hit) / px : 0) };
  });
  let px = 0; let hit = 0;
  for (let p = 0; p < W * H; p += 1) if (!covered[p]) { px += 1; if (red(data, p * 4)) hit += 1; }
  return { blocks: rows, outside: { name: 'outside blocks', px, differing: hit, pct: px ? (100 * hit) / px : 0 } };
}

// Pure: fold nested blocks into the outermost picked ancestor so no pixel counts twice. Each box carries
// `parent` — the index (in the same list) of its nearest picked ancestor, or -1 (readBlocks sets it).
export function foldNested(boxes) {
  const root = (i) => { let j = i; while (boxes[j].parent >= 0 && boxes[j].parent !== j) j = boxes[j].parent; return j; };
  const nested = boxes.map(() => 0);
  boxes.forEach((b, i) => { if (b.parent >= 0) nested[root(i)] += 1; });
  return boxes.flatMap((b, i) => (b.parent >= 0 ? [] : [{ name: nested[i] ? `${b.name} (+${nested[i]} nested)` : b.name, x: b.x, y: b.y, w: b.w, h: b.h }]));
}

// Pure: one table row as text — "not compared" / "(partial, compared y a–b)" instead of a false share.
export function rowText(r) {
  const head = `  #${String(r.k + 1).padStart(2)} ${r.name.padEnd(24)} y ${String(r.top).padStart(6)}–${String(r.bottom).padEnd(6)}`;
  if (r.compared === 'none') return `${head}    not compared (below the compared height)`;
  return `${head} ${r.pct.toFixed(2).padStart(6)} %${r.compared === 'partial' ? ` (partial, compared y ${r.y0}–${r.y1})` : ''}${r.pct >= 10 ? '  ◄◄' : ''}`;
}

// Pure: the warning when the two captures differ in height (pixel-compare diffs the shorter height only), else ''.
export function heightWarning(liveH, buildH, diffH) {
  if (liveH === buildH) return '';
  return `warning: live is ${liveH}px tall, build ${buildH}px — only y 0–${diffH} was compared; blocks below it are "not compared"`;
}

// Pure: nearest-neighbour scale of an RGBA image to width w (the overview strip).
export function scaleTo(img, w) {
  const f = img.width / w; const h = Math.max(1, Math.round(img.height / f));
  const data = Buffer.alloc(w * h * 4);
  for (let y = 0; y < h; y += 1) {
    const sy = Math.min(img.height - 1, Math.floor(y * f));
    for (let x = 0; x < w; x += 1) img.data.copy(data, (y * w + x) * 4, (sy * img.width + Math.min(img.width - 1, Math.floor(x * f))) * 4, (sy * img.width + Math.min(img.width - 1, Math.floor(x * f))) * 4 + 4);
  }
  return { width: w, height: h, data };
}

// Pure: rows y0..y1 of an RGBA image (clipped).
export function cropRows(img, y0, y1) {
  const a = Math.max(0, y0); const b = Math.min(img.height, y1);
  const h = Math.max(1, b - a);
  const data = Buffer.alloc(img.width * h * 4);
  if (b > a) img.data.copy(data, 0, a * img.width * 4, b * img.width * 4);
  return { width: img.width, height: h, data };
}

const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;');
export function reportHtml({ dir, build, width, diffFile, table, crops, warning = '' }) {
  const share = (r) => (r.compared === 'none' ? 'not compared' : `${r.pct.toFixed(2)} %${r.compared === 'partial' ? ` (partial, y ${r.y0}–${r.y1})` : ''}`);
  const row = (r, i) => `<tr class="${r.pct >= 20 ? 'hot' : r.pct >= 10 ? 'warm' : ''}"><td>${i}</td><td>${esc(r.name)}</td><td>${r.top}–${r.bottom}</td><td>${share(r)}</td><td>${r.compared === 'none' ? '' : r.differing}</td></tr>`;
  return `<!doctype html><html lang="en"><meta charset="utf-8"><title>diff report — ${esc(basename(dir))}</title>
<style>body{font:14px/1.5 -apple-system,Helvetica,Arial,sans-serif;margin:24px;color:#1c1c1c}table{border-collapse:collapse}td,th{border:1px solid #ddd;padding:4px 8px;text-align:left}tr.hot td{background:#ffe5e8}tr.warm td{background:#fff4d6}.crop{display:flex;gap:8px;margin:8px 0 24px}.crop img{width:32%;border:1px solid #ccc}img.ov{max-width:100%;border:1px solid #ccc}</style>
<h1>Where the differences are — ${esc(basename(dir))}</h1>
<p>build ${esc(build)} @ ${width}px · diff ${esc(basename(diffFile))}</p>${warning ? `<p><strong>${esc(warning)}</strong></p>` : ''}
<table><tr><th>#</th><th>block</th><th>rows</th><th>differing</th><th>px</th></tr>${table.blocks.map((r) => row(r, r.k + 1)).join('')}<tr><td></td><td>${table.outside.name}</td><td></td><td>${table.outside.pct.toFixed(2)} %</td><td>${table.outside.differing}</td></tr></table>
<h2>Overview — live | build | diff</h2><img class="ov" src="overview.png" alt="live, build and diff side by side">
<h2>Hottest blocks</h2>${crops.map((c) => `<h3>#${c.k + 1} ${esc(c.name)} — ${c.pct.toFixed(2)} %</h3><div class="crop"><img src="${c.files[0]}" alt="live"><img src="${c.files[1]}" alt="build"><img src="${c.files[2]}" alt="diff"></div>`).join('')}
</html>`;
}

// In the build page: block boxes in page coordinates (EDS default content as one unit per wrapper), each with
// `parent` = the index of its nearest picked ancestor (-1 if none) for foldNested.
/* eslint-disable no-undef */
function readBlocks(sel) {
  const eds = !sel && document.querySelector('[data-block-name]');
  const pick = sel ? [...document.querySelectorAll(sel)]
    : (eds ? [...document.querySelectorAll('[data-block-name], .default-content-wrapper')]
      : (document.querySelector('main > .section') ? [...document.querySelectorAll('main > .section')] : [...document.querySelectorAll('main > *')]));
  const sections = [...document.querySelectorAll('main > div')];
  const boxes = pick.map((el) => {
    const r = el.getBoundingClientRect();
    const sec = el.closest('main > div');
    const name = (eds && el.matches('.default-content-wrapper:not([data-block-name])'))
      ? `default content (section ${sections.indexOf(sec) + 1})`
      : (el.getAttribute('data-block-name') || [...el.classList].filter((c) => c !== 'block' && c !== 'section').slice(0, 2).join('.') || el.tagName.toLowerCase());
    let up = el.parentElement; while (up && !pick.includes(up)) up = up.parentElement;
    return { name, x: r.left + window.scrollX, y: r.top + window.scrollY, w: r.width, h: r.height, parent: up ? pick.indexOf(up) : -1 };
  });
  // drop zero-size boxes; a parent index then points at the nearest kept ancestor
  const keep = boxes.map((b) => b.w > 0 && b.h > 0);
  const lift = (i) => { let j = i; while (j >= 0 && !keep[j]) j = boxes[j].parent; return j; };
  const idx = []; let n = 0; keep.forEach((k, i) => { if (k) { idx[i] = n; n += 1; } });
  return boxes.flatMap((b, i) => { if (!keep[i]) return []; const p = lift(b.parent); return [{ ...b, parent: p >= 0 ? idx[p] : -1 }]; });
}
/* eslint-enable no-undef */

async function main() {
  if (process.argv.includes('--help') || process.argv.includes('-h')) { console.log(HELP); return; }
  const { dir, build, opts } = parseArgs(process.argv);
  if (!BROWSER) throw new Error('diff-report: browser.mjs not found (looked in ../../stardust/scripts/ and ../stardust/). Copy the master skill\'s scripts dir to stardust/scripts/stardust/ (skills/stardust/SKILL.md § Setup).');
  const { goto, loadPlaywright, newPage, openBrowser } = await import(BROWSER.href);
  await loadPlaywright();
  let PNG;
  try { ({ PNG } = await import('pngjs')); } catch (e) { throw new Error(`pngjs is not importable (${e.code || e.message}) — from the project root run: npm i -D pngjs --legacy-peer-deps`); }
  const diffFile = pickDiff(dir, opts.diff);
  const diff = PNG.sync.read(readFileSync(diffFile));
  const live = PNG.sync.read(readFileSync(join(dir, 'live.png')));
  const buildPng = PNG.sync.read(readFileSync(join(dir, 'build.png')));
  const width = opts.width || buildPng.width;
  const browser = await openBrowser({ mode: 'plain' });
  let blocks;
  try {
    const page = await newPage(browser, { viewport: { width, height: 900 } });
    await goto(page, build, { waitUntil: 'networkidle', timeout: 60000 });
    await page.evaluate(async () => { for (let y = 0; y < document.body.scrollHeight; y += 600) { window.scrollTo(0, y); await new Promise((r) => { setTimeout(r, 40); }); } window.scrollTo(0, 0); });
    // late (lazy) images loaded by the scroll pass can still shift boxes: settle before reading them
    await page.waitForLoadState('networkidle', { timeout: 15000 }).catch(() => {});
    await page.waitForFunction(() => [...document.images].every((i) => i.complete), null, { timeout: 10000 }).catch(() => {});
    await page.waitForTimeout(300);
    blocks = foldNested(await page.evaluate(readBlocks, opts.blocks));
  } finally { await browser.close(); }
  if (!blocks.length) throw new Error(`no blocks on ${build} — pass --blocks <css>`);
  const table = blockTable(diff, blocks);
  const warning = heightWarning(live.height, buildPng.height, diff.height);
  const out = opts.out || join(dir, 'report');
  mkdirSync(out, { recursive: true });
  // overview: live | build | diff, each scaled to 300 px wide, side by side
  const parts = [live, buildPng, diff].map((img) => scaleTo(img, 300));
  const ovH = Math.max(...parts.map((p) => p.height));
  const ov = new PNG({ width: 920, height: ovH }); ov.data.fill(255);
  parts.forEach((p, i) => { for (let y = 0; y < p.height; y += 1) p.data.copy(ov.data, (y * 920 + i * 310) * 4, y * 300 * 4, (y + 1) * 300 * 4); });
  writeFileSync(join(out, 'overview.png'), PNG.sync.write(ov));
  const hottest = table.blocks.filter((r) => r.compared !== 'none' && r.differing > 0).sort((a, b) => b.pct - a.pct).slice(0, opts.top);
  const crops = hottest.map((r, n) => {
    const files = ['live', 'build', 'diff'].map((side) => `crop-${n + 1}-${side}.png`);
    [live, buildPng, diff].forEach((img, i) => { const c = cropRows(img, r.y0, r.y1); const o = new PNG({ width: c.width, height: c.height }); c.data.copy(o.data); writeFileSync(join(out, files[i]), PNG.sync.write(o)); });
    return { ...r, files };
  });
  writeFileSync(join(out, 'report.html'), reportHtml({ dir, build, width, diffFile, table, crops, warning }));
  if (opts.json) { console.log(JSON.stringify({ diff: diffFile, width, warning: warning || null, liveHeight: live.height, buildHeight: buildPng.height, comparedHeight: diff.height, blocks: table.blocks, outside: table.outside, report: join(out, 'report.html') }, null, 2)); return; }
  console.log(`diff report @ ${width}px — ${basename(diffFile)}, ${table.blocks.length} blocks on ${build}`);
  if (warning) console.log(warning);
  for (const r of table.blocks) console.log(rowText(r));
  console.log(`     ${'outside blocks'.padEnd(24)} ${' '.repeat(16)} ${table.outside.pct.toFixed(2).padStart(6)} %`);
  console.log(`report: ${join(out, 'report.html')}`);
}

function safeRealpath(p) { try { return realpathSync(p); } catch { return p; } }
if (process.argv[1] && fileURLToPath(import.meta.url) === safeRealpath(process.argv[1])) {
  main().catch((e) => { console.error(`diff-report error: ${e.message}`); process.exitCode = 1; });
}

skills

README.md

tile.json