renderdiff 0.0.0-stage → 0.1.0

package/dist/report.d.ts

@@ -0,0 +1,106 @@
+import type { Band, Box, Region, TextDiff } from "./compare.ts";
+import { type ResolvedConfig, type Sides } from "./config.ts";
+interface BaseResult {
+    /** The route: `/a`, or `/a::/b` for a pair. */
+    url: string;
+    /** The path loaded on each side; both equal `url` unless it is a pair. */
+    left: string;
+    right: string;
+    /** The element compared on each side; null for the whole page. */
+    selector: Sides | null;
+    width: number;
+}
+/** A route that was captured on both sides and diffed. */
+export interface ComparedResult extends BaseResult {
+    status: "compared";
+    score: number;
+    diffPixels: number;
+    totalPixels: number;
+    heightDelta: number;
+    widthDelta: number;
+    /** Pixels that changed between shots of the same load, painted out on both sides. */
+    unstablePixels: number;
+    /** Connected diff patches, largest first. */
+    regions: Region[];
+    /** Rows only one side has; null when the rows were too different to align. */
+    bands: Band[] | null;
+    /** Score over the rows the alignment pairs; null unless there are bands. */
+    alignedScore: number | null;
+    /** innerText line diff; `added` is on left only, `removed` on right only. */
+    text: TextDiff;
+    /** Paths relative to the out dir. */
+    images: {
+        left: string;
+        right: string;
+        diff: string;
+    };
+    /** At most three: bands, tallest first, then the largest regions. Not one per region. */
+    crops: CropResult[];
+}
+/** A crop of one change: left and right panels, a 1px red box round it, or a 2px red seam. */
+export interface CropResult {
+    /** `{slug}.{width}.c{n}.png`, relative to the out dir. */
+    path: string;
+    kind: "band" | "region";
+    /** The change on each side, in that side's page px. `h` 0 is where the other side's band would go. */
+    left: Box;
+    right: Box;
+    /** Left is always on top (`stacked`) or on the left (`side`). */
+    layout: "stacked" | "side";
+    /** 1 is native; never below 0.75. */
+    scale: number;
+    /** Only the top rows (or left columns) of the change fit. */
+    clipped: boolean;
+}
+/** A route that threw before it could be diffed — neither a pass nor a fail. */
+export interface ErrorResult extends BaseResult {
+    status: "error";
+    error: string;
+}
+export type RouteResult = ComparedResult | ErrorResult;
+export interface RunMeta {
+    tool: "renderdiff";
+    version: string;
+    generatedAt: string;
+    left: string;
+    right: string;
+    widths: number[];
+    threshold: number | null;
+    /** The instant both sides' clocks start at on every load, ISO. */
+    clock: string;
+    blockUrlPatterns: string[];
+    hideSelectors: string[];
+    /** `urlPath` is absent for a mask that applies to every route. */
+    masks: {
+        urlPath?: string;
+        reason: string;
+    }[];
+}
+export interface Summary {
+    compared: number;
+    errors: number;
+    /** Null when nothing was compared. */
+    mean: number | null;
+    worst: {
+        url: string;
+        width: number;
+        score: number;
+    } | null;
+    /** Comparisons under `meta.threshold`; 0 when no threshold was set. */
+    belowThreshold: number;
+}
+/** The shape of `results.json`, written to the out dir on every run. */
+export interface Results {
+    meta: RunMeta;
+    results: RouteResult[];
+    summary: Summary;
+}
+/** Sort ascending by score; surface the mean and the worst (lowest-scoring) row. */
+export declare function stats(rows: ComparedResult[]): {
+    sorted: ComparedResult[];
+    mean: number;
+    worst: ComparedResult;
+};
+export declare function writeResults(results: RouteResult[], meta: RunMeta, outDir: string): string;
+export declare function writeReport(results: RouteResult[], meta: RunMeta, cfg: ResolvedConfig): Promise<string>;
+export {};

package/dist/report.js

@@ -0,0 +1,195 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONTEXT_OPTIONS, name } from "./config.js";
+import { floor4, fmtBand, fmtRegion, pct, signed } from "./format.js";
+/** Sort ascending by score; surface the mean and the worst (lowest-scoring) row. */
+export function stats(rows) {
+    const sorted = [...rows].sort((a, b) => a.score - b.score);
+    const mean = sorted.reduce((s, r) => s + r.score, 0) / sorted.length;
+    return { sorted, mean, worst: sorted[0] };
+}
+/** Scores to 4 decimals, rounded down like `pct`. */
+const round = (key, v) => typeof v === "number" && /^(score|alignedScore|mean)$/.test(key) ? floor4(v) : v;
+export function writeResults(results, meta, outDir) {
+    const compared = results.filter((r) => r.status === "compared");
+    const { mean, worst } = compared.length
+        ? stats(compared)
+        : { mean: null, worst: null };
+    const out = {
+        meta,
+        results,
+        summary: {
+            compared: compared.length,
+            errors: results.length - compared.length,
+            mean,
+            worst: worst && { url: worst.url, width: worst.width, score: worst.score },
+            belowThreshold: meta.threshold === null
+                ? 0
+                : compared.filter((r) => r.score < meta.threshold).length,
+        },
+    };
+    const rows = results.map((r) => `    ${JSON.stringify(r, round)}`).join(",\n");
+    // One record per line: greppable, and a reader can pull one route without parsing the rest.
+    const json = JSON.stringify({ ...out, results: [] }, round, 2).replace('"results": []', 
+    // A function, so a `$` in a route or text line isn't read as a replacement pattern.
+    () => (rows ? `"results": [\n${rows}\n  ]` : '"results": []'));
+    const file = path.join(outDir, "results.json");
+    fs.writeFileSync(file, json + "\n");
+    return file;
+}
+const esc = (s) => s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+/** Green above 99.5%, amber to 97%, red below. Tuned to be read, not to be precise. */
+const band = (score) => score >= 0.995 ? "good" : score >= 0.97 ? "warn" : "bad";
+function section(rows) {
+    if (!rows.length)
+        return "";
+    const { sorted, mean, worst } = stats(rows);
+    return `
+<section>
+  <p class="agg">mean <b class="${band(mean)}">${pct(mean)}</b> &middot;
+     worst <b class="${band(worst.score)}">${pct(worst.score)}</b>
+     (${esc(name(worst))} @${worst.width}) &middot; ${sorted.length} comparison(s)</p>
+  ${sorted.map(card).join("\n")}
+</section>`;
+}
+/** Cap on regions and text lines listed per card; the counts are always full. */
+const LIST_CAP = 5;
+const TEXT_CAP = 20;
+function findings(r) {
+    const items = [];
+    if (r.regions.length) {
+        items.push(`<p>${r.regions.length} region(s)</p><ul class="regions">${r.regions
+            .slice(0, LIST_CAP)
+            .map((g) => `<li>${fmtRegion(g)} — ${g.pixels.toLocaleString("en-US")} px</li>`)
+            .join("")}</ul>`);
+    }
+    if (r.crops.length) {
+        items.push(`<div class="crops">${r.crops
+            .map((c) => `<a class="crop" href="${c.path}" target="_blank" title="${c.kind}, left ${c.layout === "stacked" ? "on top" : "on the left"}"><img loading="lazy" src="${c.path}"></a>`)
+            .join("")}</div>`);
+    }
+    if (r.bands?.length) {
+        items.push(`<ul class="bands">${r.bands.map((b) => `<li>band ${fmtBand(b)}</li>`).join("")}</ul>`);
+    }
+    const { added, removed } = r.text;
+    if (added.length || removed.length) {
+        const lines = [
+            ...added.map((t) => `<li class="add">+ ${esc(t)}</li>`),
+            ...removed.map((t) => `<li class="del">- ${esc(t)}</li>`),
+        ];
+        items.push(`<p>text: ${added.length} added, ${removed.length} removed</p>` +
+            `<ul class="text">${lines.slice(0, TEXT_CAP).join("")}</ul>`);
+    }
+    return items.length ? `<div class="findings">${items.join("")}</div>` : "";
+}
+function card(r) {
+    const imgs = r.images;
+    return `
+<article class="card">
+  <header>
+    <span class="score ${band(r.score)}">${pct(r.score)}</span>
+    <code>${esc(name(r))}</code>
+    <span class="w">@${r.width}px</span>
+    ${r.heightDelta ? `<span class="delta">height ${signed(r.heightDelta)}px</span>` : ""}
+    ${r.widthDelta ? `<span class="delta">width ${signed(r.widthDelta)}px</span>` : ""}
+    ${r.unstablePixels ? `<span class="unstable">${r.unstablePixels.toLocaleString("en-US")} px unstable</span>` : ""}
+    ${r.alignedScore !== null ? `<span class="aligned">aligned ${pct(r.alignedScore)}</span>` : ""}
+    <span class="px">${r.diffPixels.toLocaleString()} / ${r.totalPixels.toLocaleString()} px differ</span>
+  </header>
+  ${findings(r)}
+  <div class="grid">
+    <figure><figcaption>left</figcaption><a href="${imgs.left}" target="_blank"><img loading="lazy" src="${imgs.left}"></a></figure>
+    <figure><figcaption>right</figcaption><a href="${imgs.right}" target="_blank"><img loading="lazy" src="${imgs.right}"></a></figure>
+    <figure><figcaption>diff</figcaption><a href="${imgs.diff}" target="_blank"><img loading="lazy" src="${imgs.diff}"></a></figure>
+  </div>
+</article>`;
+}
+export async function writeReport(results, meta, cfg) {
+    const compared = results.filter((r) => r.status === "compared");
+    const errors = results.filter((r) => r.status === "error");
+    const html = `<!doctype html>
+<meta charset="utf-8">
+<title>Visual diff</title>
+<style>
+  :root { color-scheme: light dark; --bg:#fff; --fg:#1a1a1a; --mut:#666; --line:#e3e3e3; --card:#fafafa; }
+  @media (prefers-color-scheme: dark) { :root { --bg:#16181c; --fg:#e8e8e8; --mut:#999; --line:#2c2f36; --card:#1c1f24; } }
+  * { box-sizing: border-box }
+  body { margin:0; padding:2rem; background:var(--bg); color:var(--fg);
+         font:14px/1.5 ui-sans-serif,system-ui,-apple-system,sans-serif; }
+  h1 { font-size:1.4rem; margin:0 0 .25rem }
+  h2 { font-size:1.05rem; margin:2.5rem 0 .25rem }
+  .meta { color:var(--mut); font-size:12px; margin:0 0 2rem }
+  .meta code { color:var(--fg) }
+  .blurb { color:var(--mut); margin:.25rem 0 .75rem; max-width:70ch }
+  .agg { margin:.25rem 0 1rem }
+  .good { color:#2e7d32 } .warn { color:#b58900 } .bad { color:#c62828 }
+  .card { border:1px solid var(--line); border-radius:8px; background:var(--card);
+          margin:0 0 1rem; padding:.75rem 1rem 1rem; }
+  .card header { display:flex; align-items:center; gap:.75rem; flex-wrap:wrap; margin-bottom:.75rem }
+  .score { font-weight:700; font-variant-numeric:tabular-nums; min-width:4.5rem }
+  .w, .px, .delta, .unstable, .aligned { color:var(--mut); font-size:12px }
+  .findings { font-size:12px; color:var(--mut); margin:0 0 .75rem }
+  .findings p { margin:.25rem 0 0 }
+  .findings ul { margin:.25rem 0; font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace }
+  .crops { display:flex; flex-wrap:wrap; gap:.5rem; margin:.25rem 0 }
+  .crops img { width:auto; max-width:100%; max-height:160px }
+  .findings .add { color:#2e7d32 } .findings .del { color:#c62828 }
+  .unstable { background:rgba(255,0,255,.12); padding:.1rem .4rem; border-radius:4px }
+  .delta { background:rgba(181,137,0,.15); padding:.1rem .4rem; border-radius:4px }
+  .grid { display:grid; grid-template-columns:repeat(3,1fr); gap:.75rem }
+  @media (max-width:900px) { .grid { grid-template-columns:1fr } }
+  figure { margin:0 }
+  figcaption { color:var(--mut); font-size:11px; text-transform:uppercase;
+               letter-spacing:.05em; margin-bottom:.35rem }
+  img { width:100%; height:auto; border:1px solid var(--line); border-radius:4px;
+        background:#fff; display:block }
+  code { font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace }
+  details { margin:1rem 0; color:var(--mut) }
+  ul { margin:.5rem 0; padding-left:1.25rem }
+</style>
+
+<h1>Visual diff</h1>
+<p class="meta">
+  left <code>${esc(meta.left)}</code> vs right <code>${esc(meta.right)}</code><br>
+  ${esc(meta.generatedAt)}
+</p>
+
+${section(compared)}
+
+${errors.length
+        ? `<section><h2 class="bad">Errors</h2>
+<p class="blurb">These produced no measurement, so they are neither a pass nor a fail.</p>
+<ul>${errors.map((r) => `<li><code>${esc(name(r))}</code> @${r.width}px — ${esc(r.error)}</li>`).join("")}</ul></section>`
+        : ""}
+
+<details>
+  <summary>What was neutralized</summary>
+  <p>Blocked on both sides — analytics, consent, and A/B tooling that would otherwise
+     rewrite the DOM differently on each load:</p>
+  <ul>${cfg.blockUrlPatterns.map((p) => `<li><code>${esc(p)}</code></li>`).join("")}</ul>
+  <p>Masked, because they drift — painted over on both sides, so they can neither pass
+     nor fail:</p>
+  ${cfg.masks.length
+        ? `<ul>${cfg.masks.map((m) => `<li>${esc(m.reason)}</li>`).join("")}</ul>`
+        : `<p><em>None configured.</em></p>`}
+  <p>Pinned on both sides: clock starts at <code>${esc(meta.clock)}</code> on every load, a seeded
+     <code>Math.random</code>, timezone <code>${CONTEXT_OPTIONS.timezoneId}</code>, locale
+     <code>${CONTEXT_OPTIONS.locale}</code>, <code>${CONTEXT_OPTIONS.colorScheme}</code> colour
+     scheme, reduced motion, CSS animations and transitions off, videos paused at frame 0.</p>
+  <p>Unstable pixels — ones that changed between two shots of the same load — are painted
+     magenta on both sides, counted on each card, and excluded from the measurement. A route
+     more than 25% unstable is an error.</p>
+  <p>Magenta is also padding where one page is taller or wider than the other. It counts
+     against the score on purpose — see the height delta on the row.</p>
+</details>
+`;
+    fs.mkdirSync(cfg.outDir, { recursive: true });
+    const out = path.join(cfg.outDir, "report.html");
+    fs.writeFileSync(out, html);
+    return out;
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -0,0 +1,17 @@
+import { type ResolvedConfig, type Route } from "./config.ts";
+import { type RouteResult } from "./report.ts";
+interface RunOpts {
+    routes: Route[];
+    cfg: ResolvedConfig;
+    open: boolean;
+    /** A line per shot as it lands; otherwise one compact summary at the end. */
+    progress: boolean;
+}
+export declare function run({ routes, cfg, open, progress }: RunOpts): Promise<number>;
+/**
+ * The non-TTY summary, sized for an agent's context: clean routes on one line, then each
+ * differing route with its widths collapsed where everything but the score agrees, and a
+ * one-line verdict that names results.json.
+ */
+export declare function compact(results: RouteResult[], routes: string[], resultsPath: string, threshold: number | null): string;
+export {};

package/dist/run.js

@@ -0,0 +1,337 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { chromium, errors } from "playwright";
+import { cancelUnstable, capture, prepare } from "./capture.js";
+import { compare, crops } from "./compare.js";
+import { CONTEXT_OPTIONS, label, name, selectorText, version, } from "./config.js";
+import { fmtBand, fmtRegion, pct, signed } from "./format.js";
+import { stats, writeReport, writeResults, } from "./report.js";
+/** Past this share of a page unstable, too little was measured for a score to mean anything. */
+const MAX_UNSTABLE_SHARE = 0.25;
+const slug = (url) => url === "/"
+    ? "index"
+    : url
+        .slice(1)
+        .toLowerCase()
+        .replace(/\//g, "-")
+        .replace(/[^a-z0-9-]/g, "_");
+const slugSelector = (s) => s.toLowerCase().replace(/[^a-z0-9-]/g, "_");
+const stem = (r) => ((r.left === r.right ? slug(r.left) : `${slug(r.left)}~${slug(r.right)}`) +
+    (r.selector ? `@${[...new Set([r.selector.left, r.selector.right])].map(slugSelector).join("~")}` : "")).slice(0, 200);
+/** Route name -> file stem, unique across the run. Suffixes follow route order, so reruns agree. */
+function slugs(routes) {
+    const out = new Map();
+    const used = new Set();
+    for (const route of routes) {
+        let s = stem(route);
+        for (let n = 2; used.has(s); n++)
+            s = `${stem(route)}-${n}`;
+        used.add(s);
+        out.set(name(route), s);
+    }
+    return out;
+}
+/** Only a directory holding nothing but files renderdiff writes is safe to wipe. */
+const ours = (f) => f === "report.html" ||
+    f === "results.json" ||
+    /^[a-z0-9_~@-]+\.[\d.]+\.(left|right|diff|c\d+)\.png$/.test(f);
+function wipeable(dir) {
+    if (!fs.existsSync(dir))
+        return true;
+    return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).every(ours);
+}
+export async function run({ routes, cfg, open, progress }) {
+    if (!wipeable(cfg.outDir)) {
+        console.error(`✗ output directory ${cfg.outDir} holds files renderdiff didn't write — ` +
+            `refusing to wipe it. Pass --out with a new or empty directory.`);
+        return 2;
+    }
+    fs.rmSync(cfg.outDir, { recursive: true, force: true });
+    fs.mkdirSync(cfg.outDir, { recursive: true });
+    const jobs = [];
+    for (const route of routes)
+        for (const width of cfg.widths)
+            jobs.push({ route, width });
+    const stems = slugs(routes);
+    const results = [];
+    const browser = await launch();
+    const queue = [...jobs];
+    let done = 0;
+    // Whole minute, so an HH:MM display reads the same on both sides.
+    const now = Math.floor(Date.now() / 60_000) * 60_000;
+    const worker = async () => {
+        // One context per origin so cookies/localStorage never cross between them.
+        const leftCtx = await browser.newContext(CONTEXT_OPTIONS);
+        const rightCtx = await browser.newContext(CONTEXT_OPTIONS);
+        const leftPage = await leftCtx.newPage();
+        const rightPage = await rightCtx.newPage();
+        await prepare(leftPage, cfg, now);
+        await prepare(rightPage, cfg, now);
+        for (let job = queue.shift(); job; job = queue.shift()) {
+            const { route, width } = job;
+            const key = name(route);
+            const tag = `${label(route)} @${width}`;
+            // Its own line: parse.ts reads the route on the row as one \S+ token.
+            const sel = route.selector ? `selector ${selectorText(route.selector)}` : "";
+            try {
+                // allSettled, not all: a page must not start the next job while still loading this one.
+                const settled = await Promise.allSettled([
+                    shoot(leftPage, cfg.left + route.left, route, "left", width, cfg, now),
+                    shoot(rightPage, cfg.right + route.right, route, "right", width, cfg, now),
+                ]);
+                const failed = settled.find((r) => r.status === "rejected");
+                if (failed)
+                    throw failed.reason;
+                const [leftShot, rightShot] = settled.map((r) => r.value);
+                // A blank page matches any other blank page, so refuse rather than score two of
+                // them. One blank side is left to the diff, which shows it plainly.
+                if (leftShot.blank && rightShot.blank) {
+                    throw new Error(`page did not render on either side ` +
+                        `(left: ${leftShot.blank}; right: ${rightShot.blank}) at ${key}`);
+                }
+                const unstablePixels = await cancelUnstable(leftShot, rightShot);
+                const { diffPng, spots, ...metrics } = await compare(leftShot, rightShot);
+                if (unstablePixels > MAX_UNSTABLE_SHARE * metrics.totalPixels) {
+                    throw new Error(`page did not settle: ${unstablePixels}px unstable at ${key}`);
+                }
+                const measured = metrics.totalPixels - unstablePixels;
+                metrics.score = measured > 0 ? 1 - metrics.diffPixels / measured : 0;
+                const base = `${stems.get(key)}.${width}`;
+                const images = {
+                    left: `${base}.left.png`,
+                    right: `${base}.right.png`,
+                    diff: `${base}.diff.png`,
+                };
+                const write = (name, buf) => fs.promises.writeFile(path.join(cfg.outDir, name), buf);
+                const made = await crops(leftShot.png, rightShot.png, spots);
+                const cropped = made.map(({ png, ...c }, i) => ({ path: `${base}.c${i + 1}.png`, ...c }));
+                await Promise.all([
+                    write(images.left, leftShot.png),
+                    write(images.right, rightShot.png),
+                    write(images.diff, diffPng),
+                    ...made.map((c, i) => write(cropped[i].path, c.png)),
+                ]);
+                results.push({
+                    url: label(route),
+                    ...route,
+                    width,
+                    status: "compared",
+                    ...metrics,
+                    unstablePixels,
+                    images,
+                    crops: cropped,
+                });
+                const { regions, bands, alignedScore, text } = metrics;
+                const details = [
+                    sel,
+                    regions.length
+                        ? `${regions.length} region${regions.length > 1 ? "s" : ""}, largest ${fmtRegion(regions[0])}`
+                        : "",
+                    ...(bands ?? []).map((b) => `band ${fmtBand(b)}`),
+                    alignedScore !== null ? `aligned ${pct(alignedScore)}` : "",
+                    bands === null ? "rows too different to align" : "",
+                    text.added.length || text.removed.length
+                        ? `text: ${text.added.length} added, ${text.removed.length} removed`
+                        : "",
+                ].filter(Boolean);
+                ++done;
+                if (!progress)
+                    continue;
+                console.log(`  [${done}/${jobs.length}] ${pct(metrics.score)}  ${tag}` +
+                    (metrics.heightDelta
+                        ? `  (height ${signed(metrics.heightDelta)}px)`
+                        : "") +
+                    (unstablePixels
+                        ? `  (unstable ${unstablePixels.toLocaleString("en-US")}px)`
+                        : "") +
+                    details.map((d) => `\n        ${d}`).join(""));
+            }
+            catch (e) {
+                results.push({
+                    url: label(route),
+                    ...route,
+                    width,
+                    status: "error",
+                    error: e instanceof Error ? e.message : String(e),
+                });
+                ++done;
+                if (progress) {
+                    console.log(`  [${done}/${jobs.length}] ERROR  ${tag}` + (sel && `\n        ${sel}`));
+                }
+            }
+        }
+        await leftCtx.close();
+        await rightCtx.close();
+    };
+    if (progress) {
+        console.log(`Capturing ${jobs.length} pair(s) with ${cfg.concurrency} worker(s)...\n`);
+    }
+    await Promise.all(Array.from({ length: cfg.concurrency }, worker));
+    await browser.close();
+    // Workers finish out of order; job order keeps results.json stable across runs.
+    const names = routes.map(name);
+    const order = (r) => names.indexOf(name(r)) * cfg.widths.length + cfg.widths.indexOf(r.width);
+    results.sort((a, b) => order(a) - order(b));
+    const meta = {
+        tool: "renderdiff",
+        version: version(),
+        generatedAt: new Date().toISOString(),
+        left: cfg.left,
+        right: cfg.right,
+        widths: cfg.widths,
+        threshold: cfg.threshold,
+        clock: new Date(now).toISOString(),
+        blockUrlPatterns: cfg.blockUrlPatterns,
+        hideSelectors: cfg.hideSelectors,
+        masks: cfg.masks.map(({ urlPath, reason }) => ({ urlPath, reason })),
+    };
+    const reportPath = await writeReport(results, meta, cfg);
+    const resultsPath = writeResults(results, meta, cfg.outDir);
+    if (progress)
+        summarize(results, reportPath, resultsPath);
+    else
+        console.log(compact(results, names, resultsPath, cfg.threshold));
+    if (open) {
+        const opener = process.platform === "darwin" ? "open" : "xdg-open";
+        spawn(opener, [reportPath], { detached: true, stdio: "ignore" }).unref();
+    }
+    // Reported before the error exit, so an errored route can't hide a threshold failure.
+    const below = results.filter((r) => r.status === "compared" && cfg.threshold !== null && r.score < cfg.threshold);
+    if (below.length) {
+        console.error(`\n✗ ${below.length} route(s) below ${pct(cfg.threshold)}.`);
+    }
+    return below.length || results.some((r) => r.status === "error") ? 1 : 0;
+}
+/** A missing browser binary is the likeliest first-run failure — name the fix. */
+async function launch() {
+    try {
+        return await chromium.launch();
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`could not launch Chromium:\n  ${msg}\n\n` +
+            `  Install the browser with:  npx playwright install chromium`);
+    }
+}
+const transient = (e) => e instanceof errors.TimeoutError ||
+    (e instanceof Error &&
+        /net::ERR_|Execution context was destroyed/.test(e.message));
+/** One retry for a transient failure: a live site can time out once on a cold edge. */
+async function shoot(page, url, route, side, width, cfg, now) {
+    try {
+        return await capture(page, url, route, side, width, cfg, now);
+    }
+    catch (e) {
+        if (!transient(e))
+            throw e;
+        await page.waitForTimeout(1000);
+        return await capture(page, url, route, side, width, cfg, now);
+    }
+}
+function summarize(results, reportPath, resultsPath) {
+    const compared = results.filter((r) => r.status === "compared");
+    if (compared.length) {
+        const { sorted, mean, worst } = stats(compared);
+        console.log(`\nmean ${pct(mean)}   worst ${pct(worst.score)} (${name(worst)} @${worst.width})`);
+        for (const r of sorted.slice(0, 10)) {
+            console.log(`    ${pct(r.score).padStart(7)}  ${name(r)}@${r.width}` +
+                (r.heightDelta ? `  height ${signed(r.heightDelta)}px` : ""));
+        }
+    }
+    const errors = results.filter((r) => r.status === "error");
+    if (errors.length) {
+        console.log(`\nErrors (${errors.length}):`);
+        for (const e of errors)
+            console.log(`  ${name(e)}@${e.width}: ${e.error}`);
+    }
+    console.log(`\nReport: ${reportPath}`);
+    console.log(`Results: ${resultsPath}`);
+}
+/** At most this many text-diff lines per compact row. */
+const TEXT_LINES = 3;
+/**
+ * The non-TTY summary, sized for an agent's context: clean routes on one line, then each
+ * differing route with its widths collapsed where everything but the score agrees, and a
+ * one-line verdict that names results.json.
+ */
+export function compact(results, routes, resultsPath, threshold) {
+    const out = [];
+    const clean = [];
+    let differ = 0;
+    for (const route of routes) {
+        const rows = results.filter((r) => name(r) === route);
+        const ok = rows.filter((r) => r.status === "compared");
+        // Unstable pixels went unmeasured, so a shot with any is not clean, only unchanged.
+        const same = ok.filter((r) => r.diffPixels === 0 && r.unstablePixels === 0);
+        const changed = ok.filter((r) => !same.includes(r));
+        if (same.length === rows.length) {
+            clean.push(route);
+            continue;
+        }
+        if (changed.some((r) => r.diffPixels > 0))
+            differ++;
+        out.push(route + (same.length ? `  clean @${same.map((r) => r.width).join(",")}` : ""));
+        const groups = new Map();
+        for (const r of changed) {
+            const key = JSON.stringify([
+                r.heightDelta,
+                r.widthDelta,
+                r.bands?.map((b) => [b.side, b.h]) ?? null,
+                r.alignedScore === null ? null : pct(r.alignedScore),
+                r.text,
+            ]);
+            groups.set(key, [...(groups.get(key) ?? []), r]);
+        }
+        for (const g of groups.values())
+            out.push(`  @${g.map((r) => r.width).join(",")}  ${row(g)}`);
+        const failed = new Map();
+        for (const r of rows)
+            if (r.status === "error")
+                failed.set(r.error, [...(failed.get(r.error) ?? []), r.width]);
+        for (const [error, widths] of failed)
+            out.push(`  @${widths.join(",")}  ERROR ${error}`);
+    }
+    if (clean.length)
+        out.unshift(`clean: ${clean.join(" ")}`);
+    const compared = results.filter((r) => r.status === "compared");
+    const shots = compared.filter((r) => r.diffPixels > 0).length;
+    const errors = results.length - compared.length;
+    const worst = compared.length ? stats(compared).worst : null;
+    out.push(`renderdiff: ${differ} of ${routes.length} routes differ (${shots} of ${results.length} shots), ` +
+        `${errors} error${errors === 1 ? "" : "s"}` +
+        (worst ? `, worst ${pct(worst.score)} ${name(worst)}@${worst.width}` : "") +
+        (threshold === null ? "" : `, ${compared.filter((r) => r.score < threshold).length} below ${pct(threshold)}`) +
+        ` — ${resultsPath}`);
+    return out.join("\n");
+}
+/** One compact row for comparisons that agree on everything but score, regions and unstable px. */
+function row(g) {
+    const [r] = g;
+    const span = (ns, f) => {
+        const [lo, hi] = [Math.min(...ns), Math.max(...ns)];
+        return lo === hi ? f(lo) : `${f(lo)}–${f(hi)}`;
+    };
+    const regions = g.map((x) => x.regions.length);
+    const unstable = Math.max(...g.map((x) => x.unstablePixels));
+    // Band y varies with width; a collapsed row shows the first one's, marked approximate.
+    const y = (b) => `@y${g.length > 1 ? "~" : ""}${b.y}`;
+    const text = [...r.text.added.map((t) => `+"${t}"`), ...r.text.removed.map((t) => `-"${t}"`)];
+    return [
+        span(g.map((x) => x.score), pct),
+        r.heightDelta ? `h${signed(r.heightDelta)}` : "",
+        r.widthDelta ? `w${signed(r.widthDelta)}` : "",
+        r.bands === null ? "unaligned" : "",
+        ...(r.bands ?? []).map((b) => `band ${b.side === "left" ? "+" : "-"}${b.h}${y(b)}`),
+        r.alignedScore !== null ? `aligned ${pct(r.alignedScore)}` : "",
+        Math.max(...regions) ? `${span(regions, String)} reg` : "",
+        unstable ? `unstable ${unstable.toLocaleString("en-US")}px` : "",
+        text.length
+            ? `text ${text.slice(0, TEXT_LINES).join(" ")}` +
+                (text.length > TEXT_LINES ? ` (+${text.length - TEXT_LINES} more)` : "")
+            : "",
+    ]
+        .filter(Boolean)
+        .join("  ");
+}
+//# sourceMappingURL=run.js.map