Skip to content

Clone any website into a pixel-accurate Next.js app with AI — Playwright-measured extraction (no eyeballing), spec-gated parallel builder agents, and scored pixel-diff QA at phone/tablet/desktop. Works with Claude Code, Cursor, Copilot + 9 more.

22.5 KB
Raw Blame
#!/usr/bin/env node
// Scored visual diff: original vs clone. Three modes:
//
// File mode:    node scripts/diff.mjs --a original.png --b clone.png [--out diff.png]
// Live mode:    node scripts/diff.mjs --original <url> --clone <url> [--selector css]
//                 [--clone-selector css] [--viewport pc|ipad|phone|all|pc,phone] [--name hero]
// Batched mode: node scripts/diff.mjs --original <url> --clone <url> --viewport all
//                 --section hero=section.hero --section features=#features
//                 (or --route / to pull every section of that route from the manifest)
//
// Triage mode:  node scripts/diff.mjs --original <url> --clone <url> --route /
//                 --triage --viewport all
//               Whole-page diff FIRST per viewport; a passing viewport (match +
//               every band ≥ threshold, heights agree) skips its per-section
//               diffs entirely, a failing one per-section-diffs ONLY the
//               sections overlapping the failing bands. Sections it never
//               touched get an inferred score (worst overlapping page band).
//               This is the default QA sweep — a good clone costs 2 loads per
//               viewport instead of 2 + 2×N.
//
// Batched mode loads each side ONCE per viewport and screenshots every section
// from that load — an 8-section sweep costs 6 page loads instead of 48. Use it
// when you want individual scores for every section regardless of page result;
// fix iterations should stay single-section.
//
// The original side of a live/batched run is cached: a PNG + .meta.json sidecar
// under docs/research/qa/ is reused when the url/selector/viewport match and the
// shot is <24h old, so fix iterations only re-render the clone. --fresh-original
// forces a re-shoot (use it if the live site itself changed mid-run).
//
// --selector applies to both sides; --clone-selector overrides it for the clone
// when your component's markup uses different hooks than the target's. Batched
// mode applies each section's selector to both sides (fall back to single mode
// for per-side selector overrides).
// --viewport takes one name, a comma list, or "all" (= pc,ipad,phone). Default: pc.
//
// Prints ONE JSON object to stdout:
//   live/file:  { name, viewports: { pc: {...}, ipad: {...} } }
//   batched:    { route, sections: { hero: { viewports: {...} }, ... } }
// Each viewport carries a 10-band breakdown so the caller learns WHERE the
// mismatch lives, not just how much of it there is.
// Exit code 1 if --threshold given and ANY requested viewport (any section) is below it.
// Live-mode artifacts land in docs/research/qa/.
import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
import { PNG } from "pngjs";
import pixelmatch from "pixelmatch";
import {
  VIEWPORTS,
  openPage,
  closeBrowser,
  gotoAndSettle,
  autoScroll,
  freezePage,
  shootSectionsFromFullPage,
  writeReviewPng,
  reviewPathFor,
  slugify,
  parseArgs,
  toList,
} from "./lib.mjs";
import { selfReport, findPage, findSection, advanceStage, updatePageStatus } from "./manifest-lib.mjs";

const args = parseArgs(process.argv.slice(2));

const DIR = "docs/research/qa";
const ORIGINAL_FRESH_MS = 24 * 3600 * 1000;

// ---------------------------------------------------------------------------
// Original-side shot cache. The original site never changes between QA fix
// iterations, so re-rendering it every time was pure waste. The sidecar (not
// the filename) is the invalidation key — it catches a reused --name pointing
// at a different url/selector/viewport.
// ---------------------------------------------------------------------------
const metaPathFor = (pngPath) => pngPath.replace(/\.png$/, ".meta.json");

function originalCached(pngPath, url, viewport, selector) {
  if (args["fresh-original"]) return false;
  try {
    const m = JSON.parse(readFileSync(metaPathFor(pngPath), "utf8"));
    return (
      existsSync(pngPath) &&
      m.url === url &&
      (m.selector || null) === (selector || null) &&
      m.viewport?.width === viewport.width &&
      m.viewport?.height === viewport.height &&
      Date.now() - m.capturedAt < ORIGINAL_FRESH_MS
    );
  } catch {
    return false;
  }
}

function writeOriginalMeta(pngPath, url, viewport, selector) {
  writeFileSync(
    metaPathFor(pngPath),
    JSON.stringify({ url, selector: selector || null, viewport, capturedAt: Date.now() }, null, 2) + "\n"
  );
}

async function shoot(url, path, viewport, selector) {
  const { page, close } = await openPage(viewport);
  try {
    await gotoAndSettle(page, url);
    // Full-page shots must include lazy content; section shots need only the section.
    await autoScroll(page, { force: !selector });
    await freezePage(page); // deterministic pixels: no animations, paused videos
    if (selector) {
      const loc = page.locator(selector).first();
      await loc.scrollIntoViewIfNeeded();
      await loc.screenshot({ path });
    } else {
      await page.screenshot({ path, fullPage: true });
    }
  } finally {
    await close();
  }
  return path;
}

// Whole-page shot for triage mode; optionally measures each selector's page-Y
// box from the same load, so failing diff bands can be mapped to the sections
// that occupy them without any extra navigation.
async function shootPageWithBoxes(url, path, viewport, selectors = null) {
  const { page, close } = await openPage(viewport);
  try {
    await gotoAndSettle(page, url);
    await autoScroll(page, { force: true });
    await freezePage(page);
    await page.screenshot({ path, fullPage: true });
    if (!selectors) return null;
    return await page.evaluate((sels) => {
      window.scrollTo(0, 0);
      const out = {};
      for (const sel of sels) {
        const el = document.querySelector(sel);
        if (!el) {
          out[sel] = null;
          continue;
        }
        const r = el.getBoundingClientRect();
        out[sel] = { y: Math.round(r.y + scrollY), h: Math.round(r.height) };
      }
      return out;
    }, selectors);
  } finally {
    await close();
  }
}

// Batched capture: one load, one forced scroll, one freeze — then every section
// cropped out of ONE full-page screenshot (pixel-identical to a per-section
// locator chain, minus N scroll+shoot round-trips). A section the crop can't
// produce falls back to a locator shot inside the helper; anything neither
// path captures is reported and skipped, not fatal.
async function shootSectionsOnce(url, viewport, sections, pathFor) {
  const { page, close } = await openPage(viewport);
  const captured = {};
  try {
    await gotoAndSettle(page, url);
    await autoScroll(page, { force: true });
    await freezePage(page);
    const { failed } = await shootSectionsFromFullPage(page, sections, {
      pathFor: (s) => pathFor(s.name),
      review: false, // QA captures feed pixelmatch, not eyes
    });
    for (const { name } of sections) captured[name] = !failed.includes(name);
    for (const name of failed) console.error(`  ! section shot failed: ${name} @ ${viewport.width}px`);
  } finally {
    await close();
  }
  return captured;
}

const BAND_COUNT = 10;

// Compare two PNGs cropped to their shared area (full-page heights rarely match
// exactly). The diff runs once per horizontal band instead of once overall:
// band-level numbers tell the caller WHICH tenth of the page drifted, and the
// total is the sum of the bands so both numbers always agree — a separate
// whole-image pass could disagree slightly at band seams, where pixelmatch's
// anti-aliasing detection loses its vertical neighbors.
function compare(pathA, pathB, outPath) {
  const imgA = PNG.sync.read(readFileSync(pathA));
  const imgB = PNG.sync.read(readFileSync(pathB));
  const width = Math.min(imgA.width, imgB.width);
  const height = Math.min(imgA.height, imgB.height);

  const diffImg = new PNG({ width, height });
  const bands = [];
  let mismatched = 0;
  for (let i = 0; i < BAND_COUNT; i++) {
    const y0 = Math.floor((height * i) / BAND_COUNT);
    const y1 = i === BAND_COUNT - 1 ? height : Math.floor((height * (i + 1)) / BAND_COUNT);
    const bandH = y1 - y0;
    const label = { band: `${i * 10}-${(i + 1) * 10}%`, yRange: `${y0}-${y1}px` };
    if (bandH <= 0) {
      // Image shorter than 10px: report the empty band as perfect instead of
      // handing pixelmatch a zero-height buffer.
      bands.push({ ...label, match: 100 });
      continue;
    }
    // bitblt straight out of the source images with a y offset — the shared-area
    // crop and the band slice are the same copy.
    const sliceA = new PNG({ width, height: bandH });
    const sliceB = new PNG({ width, height: bandH });
    const sliceDiff = new PNG({ width, height: bandH });
    PNG.bitblt(imgA, sliceA, 0, y0, width, bandH, 0, 0);
    PNG.bitblt(imgB, sliceB, 0, y0, width, bandH, 0, 0);
    const bandMismatch = pixelmatch(sliceA.data, sliceB.data, sliceDiff.data, width, bandH, { threshold: 0.1 });
    // Reassemble the band diffs into one full-size diff image at their offsets,
    // so the artifact looks identical to a single whole-image pass.
    PNG.bitblt(sliceDiff, diffImg, 0, 0, width, bandH, 0, y0);
    mismatched += bandMismatch;
    bands.push({ ...label, match: Number((100 - (bandMismatch / (width * bandH)) * 100).toFixed(2)) });
  }
  const match = 100 - (mismatched / (width * height)) * 100;
  if (outPath) writeFileSync(outPath, PNG.sync.write(diffImg));
  return {
    match: Number(match.toFixed(2)),
    mismatchedPixels: mismatched,
    width,
    height,
    originalHeight: imgA.height,
    cloneHeight: imgB.height,
    diffImage: outPath || null,
    bands,
  };
}

// --section name=css (repeatable) plus --route </r> (reads the manifest).
function parseSections() {
  const out = [];
  for (const item of toList(args.section).map(String)) {
    const eq = item.indexOf("=");
    if (eq < 1) {
      console.error(`Bad --section "${item}" — use --section name=css-selector`);
      process.exit(1);
    }
    out.push({ name: slugify(item.slice(0, eq).trim()), selector: item.slice(eq + 1).trim() });
  }
  if (args.route && args.route !== true) {
    let manifest;
    try {
      manifest = JSON.parse(readFileSync("docs/research/manifest.json", "utf8"));
    } catch {
      console.error("No readable docs/research/manifest.json — --route needs an initialized manifest");
      process.exit(1);
    }
    const p = manifest.pages.find((p) => p.route === args.route);
    if (!p) {
      console.error(`Route ${args.route} not in manifest. Routes: ${manifest.pages.map((p) => p.route).join(", ")}`);
      process.exit(1);
    }
    for (const s of p.sections) {
      const name = slugify(s.name);
      if (!out.some((o) => o.name === name)) out.push({ name, selector: s.selector });
    }
  }
  return out;
}

function parseViewports() {
  const vpArg = !args.viewport || args.viewport === true ? "pc" : String(args.viewport);
  const vpNames = vpArg === "all" ? ["pc", "ipad", "phone"] : vpArg.split(",").map((s) => s.trim()).filter(Boolean);
  const unknown = vpNames.filter((v) => !VIEWPORTS[v]);
  if (!vpNames.length || unknown.length) {
    console.error(`Unknown viewport(s): ${unknown.join(", ") || vpArg} — use ${Object.keys(VIEWPORTS).join(", ")}, a comma list, or "all"`);
    process.exit(1);
  }
  return vpNames;
}

let output; // final stdout JSON
const flat = []; // [scope, viewportName, result] for the stderr summary + threshold

// Manifest self-report shared by batched and triage modes: record per-viewport
// scores and advance qa_passed when all three viewports clear the threshold.
function reportScores(route, sections, sectionResults, vpNames) {
  if (!route) return;
  const qaThreshold = args.threshold ? Number(args.threshold) : 95;
  let scored = 0, passed = 0;
  selfReport((m) => {
    const p = findPage(m, route);
    if (!p) return false;
    let changed = false;
    for (const s of sections) {
      const sec = findSection(p, s.name);
      if (!sec) continue;
      for (const vp of vpNames) {
        const r = sectionResults[s.name]?.viewports[vp];
        if (r && !r.error && typeof r.match === "number") {
          sec.scores[vp] = r.match;
          changed = true;
          scored++;
        }
      }
      if (["pc", "ipad", "phone"].every((v) => typeof sec.scores[v] === "number" && sec.scores[v] >= qaThreshold)) {
        if (advanceStage(sec, "qa_passed")) passed++;
        changed = true;
      }
    }
    if (changed) updatePageStatus(p);
    return changed;
  });
  if (scored) console.error(`  ✓ manifest: ${scored} score(s) recorded${passed ? `, ${passed} section(s) → qa_passed` : ""}`);
}

if (args.original && args.clone) {
  const vpNames = parseViewports();
  mkdirSync(DIR, { recursive: true });
  const sections = parseSections();

  if (args.triage && sections.length) {
    // ── Triage mode: whole-page first, sections only where the page fails ──
    // A passing viewport (match ≥ threshold, every band ≥ threshold, heights
    // agree) proves its sections without N per-section diffs. A failing one
    // names the bands that failed; only sections overlapping those bands get
    // individually diffed. Untouched sections receive an inferred score (the
    // worst page band they overlap) so the manifest still fills in.
    const thr = args.threshold ? Number(args.threshold) : 95;
    const routeSlug = slugify(String(args.route || "page"));
    const sectionResults = {};
    for (const s of sections) sectionResults[s.name] = { viewports: {} };
    const triage = {};

    await Promise.all(
      vpNames.map(async (vp) => {
        const viewport = VIEWPORTS[vp];
        const origPath = `${DIR}/page-${routeSlug}-${vp}-original.png`;
        const clonePath = `${DIR}/page-${routeSlug}-${vp}-clone.png`;
        const cloneJob = shootPageWithBoxes(args.clone, clonePath, viewport, sections.map((s) => s.selector));
        let origJob = Promise.resolve();
        if (originalCached(origPath, args.original, viewport, null)) {
          console.error(`  reusing cached original page shot [${vp}]`);
        } else {
          origJob = shootPageWithBoxes(args.original, origPath, viewport).then(() =>
            writeOriginalMeta(origPath, args.original, viewport, null)
          );
        }
        const [boxes] = await Promise.all([cloneJob, origJob]);
        const r = compare(origPath, clonePath, `${DIR}/page-${routeSlug}-${vp}-diff.png`);
        flat.push([`page${args.route && args.route !== true ? args.route : ""}`, vp, r]);

        const heightOk = Math.abs(r.originalHeight - r.cloneHeight) <= Math.max(8, r.originalHeight * 0.005);
        const bandY = (i) => [
          Math.floor((r.height * i) / BAND_COUNT),
          i === BAND_COUNT - 1 ? r.height : Math.floor((r.height * (i + 1)) / BAND_COUNT),
        ];
        const failing = r.bands.map((b, i) => ({ ...b, i })).filter((b) => b.match < thr);
        const pass = r.match >= thr && heightOk && !failing.length;

        const overlapsFailing = (sel) => {
          const box = boxes?.[sel];
          // Not locatable — or matching a zero-height element (Next.js injects
          // empty divs at the top of <body>, so a positional selector can hit
          // one) — means the box proves nothing: don't guess, diff the section.
          if (!box || box.h < 1) return true;
          return failing.some((b) => {
            const [y0, y1] = bandY(b.i);
            return box.y < y1 && box.y + box.h > y0;
          });
        };
        const need = pass ? [] : sections.filter((s) => overlapsFailing(s.selector));
        triage[vp] = { page: r, pass, heightOk, failingBands: failing.map((b) => b.band), sectionsDiffed: need.map((s) => s.name) };

        const needNames = new Set(need.map((s) => s.name));
        for (const s of sections) {
          if (needNames.has(s.name)) continue;
          const box = boxes?.[s.selector];
          if (!box || box.h < 1) continue;
          const overlapped = r.bands.filter((_, i) => {
            const [y0, y1] = bandY(i);
            return box.y < y1 && box.y + box.h > y0;
          });
          if (!overlapped.length) continue;
          sectionResults[s.name].viewports[vp] = {
            match: Math.min(...overlapped.map((b) => b.match)),
            inferred: "worst overlapping page band",
          };
        }

        if (need.length) {
          const origPathFor = (n) => `${DIR}/${n}-${vp}-original.png`;
          const jobs = [shootSectionsOnce(args.clone, viewport, need, (n) => `${DIR}/${n}-${vp}-clone.png`)];
          const missing = need.filter((s) => !originalCached(origPathFor(s.name), args.original, viewport, s.selector));
          if (missing.length) {
            jobs.push(
              shootSectionsOnce(args.original, viewport, need, origPathFor).then((captured) => {
                for (const s of need) {
                  if (captured[s.name]) writeOriginalMeta(origPathFor(s.name), args.original, viewport, s.selector);
                }
              })
            );
          }
          await Promise.all(jobs);
          for (const s of need) {
            const a = origPathFor(s.name);
            const b = `${DIR}/${s.name}-${vp}-clone.png`;
            if (!existsSync(a) || !existsSync(b)) {
              sectionResults[s.name].viewports[vp] = { error: `missing ${!existsSync(a) ? "original" : "clone"} shot` };
              flat.push([s.name, vp, null]);
              continue;
            }
            const sr = compare(a, b, `${DIR}/${s.name}-${vp}-diff.png`);
            sectionResults[s.name].viewports[vp] = sr;
            flat.push([s.name, vp, sr]);
          }
        }
      })
    );
    await closeBrowser();
    output = { route: args.route && args.route !== true ? args.route : null, triage, sections: sectionResults };
    reportScores(output.route, sections, sectionResults, vpNames);
  } else if (sections.length) {
    // Batched mode: per (side × viewport) ONE load covers every section. All six
    // loads run concurrently on the shared browser.
    await Promise.all(
      vpNames.flatMap((vp) => {
        const origPathFor = (n) => `${DIR}/${n}-${vp}-original.png`;
        const jobs = [
          shootSectionsOnce(args.clone, VIEWPORTS[vp], sections, (n) => `${DIR}/${n}-${vp}-clone.png`),
        ];
        const missing = sections.filter((s) => !originalCached(origPathFor(s.name), args.original, VIEWPORTS[vp], s.selector));
        if (missing.length) {
          // Re-shoot ALL sections from the one load (marginal cost ~0) so every
          // sidecar carries the same capture time.
          jobs.push(
            shootSectionsOnce(args.original, VIEWPORTS[vp], sections, origPathFor).then((captured) => {
              for (const s of sections) {
                if (captured[s.name]) writeOriginalMeta(origPathFor(s.name), args.original, VIEWPORTS[vp], s.selector);
              }
            })
          );
        } else {
          console.error(`  reusing ${sections.length} cached original shots [${vp}]`);
        }
        return jobs;
      })
    );
    await closeBrowser();
    const sectionResults = {};
    for (const s of sections) {
      sectionResults[s.name] = { viewports: {} };
      for (const vp of vpNames) {
        const a = `${DIR}/${s.name}-${vp}-original.png`;
        const b = `${DIR}/${s.name}-${vp}-clone.png`;
        if (!existsSync(a) || !existsSync(b)) {
          sectionResults[s.name].viewports[vp] = { error: `missing ${!existsSync(a) ? "original" : "clone"} shot` };
          flat.push([s.name, vp, null]);
          continue;
        }
        const r = compare(a, b, `${DIR}/${s.name}-${vp}-diff.png`);
        sectionResults[s.name].viewports[vp] = r;
        flat.push([s.name, vp, r]);
      }
    }
    output = { route: args.route && args.route !== true ? args.route : null, sections: sectionResults };
    reportScores(output.route, sections, sectionResults, vpNames);
  } else {
    // Single live mode.
    const name = args.name || slugify(args.selector || "page");
    await Promise.all(
      vpNames.flatMap((vp) => {
        const origPath = `${DIR}/${name}-${vp}-original.png`;
        const jobs = [shoot(args.clone, `${DIR}/${name}-${vp}-clone.png`, VIEWPORTS[vp], args["clone-selector"] || args.selector)];
        if (originalCached(origPath, args.original, VIEWPORTS[vp], args.selector)) {
          console.error(`  reusing original ${name}-${vp}-original.png`);
        } else {
          jobs.push(
            shoot(args.original, origPath, VIEWPORTS[vp], args.selector).then(() =>
              writeOriginalMeta(origPath, args.original, VIEWPORTS[vp], args.selector)
            )
          );
        }
        return jobs;
      })
    );
    await closeBrowser();
    const results = {};
    for (const vp of vpNames) {
      // --out keeps its old single-run meaning; multi-viewport runs would clobber
      // one file with every diff, so they always use the per-viewport path.
      const outPath = vpNames.length === 1 && args.out ? args.out : `${DIR}/${name}-${vp}-diff.png`;
      results[vp] = compare(`${DIR}/${name}-${vp}-original.png`, `${DIR}/${name}-${vp}-clone.png`, outPath);
      flat.push([name, vp, results[vp]]);
    }
    output = { name, viewports: results };
  }
} else if (args.a && args.b) {
  const name = args.name || "file";
  const r = compare(args.a, args.b, args.out || null);
  flat.push([name, "file", r]);
  output = { name, viewports: { file: r } };
} else {
  console.error(
    "Usage: diff.mjs --a orig.png --b clone.png  OR  --original <url> --clone <url> [--selector css | --section name=css ... | --route /] [--viewport pc|ipad|phone|all|pc,phone]"
  );
  process.exit(1);
}

console.log(JSON.stringify(output, null, 2));

for (const [scope, vp, r] of flat) {
  if (!r) {
    console.error(`[${scope} ${vp}] NOT CAPTURED`);
    continue;
  }
  const worst = r.bands.reduce((w, b) => (b.match < w.match ? b : w));
  const heightNote =
    r.originalHeight !== r.cloneHeight
      ? ` · HEIGHT MISMATCH: original ${r.originalHeight}px vs clone ${r.cloneHeight}px (compared top ${r.height}px)`
      : "";
  // Failing diffs get a 640px review copy — that's the image an agent opens to
  // inspect the failing band; the full-res artifact stays for pixel work.
  let reviewNote = "";
  if (r.match < 95 && r.diffImage && writeReviewPng(r.diffImage, reviewPathFor(r.diffImage))) {
    reviewNote = ` · review: ${reviewPathFor(r.diffImage)}`;
  }
  console.error(`[${scope} ${vp}] Match: ${r.match.toFixed(2)}% · worst band: ${worst.band} (y ${worst.yRange}) at ${worst.match}%${heightNote}${reviewNote}`);
}

if (args.threshold) {
  const t = Number(args.threshold);
  let failed = false;
  for (const [scope, vp, r] of flat) {
    if (!r || r.match < t) {
      console.error(`FAIL [${scope} ${vp}]: ${r ? `${r.match}%` : "not captured"} below threshold ${t}%`);
      failed = true;
    }
  }
  if (failed) process.exit(1);
}