@blazediff/agent 0.0.1

package/dist/index.mjs

@@ -0,0 +1,1865 @@
+import { mkdir, readFile, writeFile, readdir, stat, rm } from 'fs/promises';
+import path from 'path';
+import { availableParallelism, cpus } from 'os';
+import { chromium } from 'playwright';
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { createRequire } from 'module';
+import { createHash } from 'crypto';
+import { compare, interpret } from '@blazediff/core-native';
+import sharp from 'sharp';
+import { Annotation, StateGraph, START, Send, END } from '@langchain/langgraph';
+
+// src/browser/capture.ts
+var DEFAULT_VIEWPORT = { width: 1280, height: 800 };
+var DEFAULT_WAIT_FOR = ["networkidle", "fonts"];
+var DEFAULT_FULL_PAGE = true;
+var DEFAULT_THRESHOLD = 0.1;
+var MIN_AUTO_CONCURRENCY = 2;
+var MAX_AUTO_CONCURRENCY = 8;
+function defaultConcurrency() {
+  const cores = typeof availableParallelism === "function" ? availableParallelism() : cpus().length;
+  if (!cores || !Number.isFinite(cores)) return MIN_AUTO_CONCURRENCY;
+  return Math.max(
+    MIN_AUTO_CONCURRENCY,
+    Math.min(MAX_AUTO_CONCURRENCY, cores - 1)
+  );
+}
+var BLAZEDIFF_DIR = ".blazediff";
+var paths = (cwd = process.cwd()) => {
+  const root = path.join(cwd, BLAZEDIFF_DIR);
+  return {
+    root,
+    config: path.join(root, "config.json"),
+    manifest: path.join(root, "manifest.json"),
+    baselines: path.join(root, "baselines"),
+    actual: path.join(root, "actual"),
+    judgments: path.join(root, "judgments"),
+    summary: path.join(root, "summary.md"),
+    gitignore: path.join(root, ".gitignore"),
+    serverLog: path.join(root, "dev-server.log"),
+    serverPid: path.join(root, "dev-server.pid")
+  };
+};
+var FROZEN_NOW = Date.UTC(2025, 0, 1, 0, 0, 0);
+var STABILITY_CSS = `
+*,*::before,*::after{
+	animation-delay:-0.0001s !important;
+	animation-duration:0s !important;
+	animation-iteration-count:1 !important;
+	transition-delay:0s !important;
+	transition-duration:0s !important;
+	caret-color:transparent !important;
+}
+html{scroll-behavior:auto !important}
+`;
+var CHROMIUM_FLAGS = [
+  "--font-render-hinting=none",
+  "--disable-skia-runtime-opts",
+  "--force-color-profile=srgb",
+  "--disable-lcd-text",
+  "--disable-background-timer-throttling",
+  "--disable-renderer-backgrounding",
+  "--disable-backgrounding-occluded-windows",
+  "--hide-scrollbars"
+];
+var cachedBrowser = null;
+var launchInFlight = null;
+async function getBrowser() {
+  if (cachedBrowser?.isConnected()) return cachedBrowser;
+  if (launchInFlight) return launchInFlight;
+  launchInFlight = chromium.launch({ headless: true, args: CHROMIUM_FLAGS }).then((b) => {
+    cachedBrowser = b;
+    return b;
+  }).finally(() => {
+    launchInFlight = null;
+  });
+  return launchInFlight;
+}
+async function closeBrowser() {
+  if (launchInFlight) {
+    await launchInFlight.catch(() => {
+    });
+  }
+  if (!cachedBrowser) return;
+  await cachedBrowser.close().catch(() => {
+  });
+  cachedBrowser = null;
+}
+async function openStableContext(opts) {
+  const browser = await getBrowser();
+  const context = await browser.newContext({
+    viewport: opts.viewport,
+    deviceScaleFactor: 1,
+    reducedMotion: "reduce",
+    forcedColors: "none",
+    colorScheme: "light",
+    bypassCSP: true
+  });
+  await context.addInitScript(
+    ({ frozenNow }) => {
+      Object.defineProperty(Date, "now", {
+        value: () => frozenNow,
+        writable: true,
+        configurable: true
+      });
+      let perfTick = 0;
+      Object.defineProperty(performance, "now", {
+        value: () => {
+          perfTick += 16.6667;
+          return perfTick;
+        },
+        writable: true,
+        configurable: true
+      });
+      let seed = 2654435769 | 0;
+      Math.random = () => {
+        seed = seed + 1831565813 | 0;
+        let t = seed;
+        t = Math.imul(t ^ t >>> 15, t | 1);
+        t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+        return ((t ^ t >>> 14) >>> 0) / 4294967296;
+      };
+      if (typeof crypto !== "undefined") {
+        let uuidCounter = 0;
+        Object.defineProperty(crypto, "randomUUID", {
+          value: () => {
+            uuidCounter += 1;
+            return `00000000-0000-4000-8000-${uuidCounter.toString(16).padStart(12, "0")}`;
+          },
+          writable: true,
+          configurable: true
+        });
+      }
+    },
+    { frozenNow: FROZEN_NOW }
+  );
+  const page = await context.newPage();
+  const injectStability = () => page.addStyleTag({ content: STABILITY_CSS }).catch(() => {
+  });
+  await injectStability();
+  page.on("load", injectStability);
+  return { context, page };
+}
+async function waitForStability(page, waitFor) {
+  for (const w of waitFor) {
+    if (w === "networkidle") {
+      await page.waitForLoadState("networkidle").catch(() => {
+      });
+    } else if (w === "fonts") {
+      await page.evaluate(
+        () => document.fonts && "ready" in document.fonts ? document.fonts.ready.then(() => void 0) : void 0
+      ).catch(() => {
+      });
+    } else {
+      await page.waitForSelector(w.selector, { timeout: w.timeoutMs ?? 5e3 }).catch(() => {
+      });
+    }
+  }
+}
+var DEFAULT_MASK_ATTR = "data-blazediff-agent-mask";
+var DEFAULT_MASK_SELECTOR = `[${DEFAULT_MASK_ATTR}]`;
+async function applyMaskOverlays(page, masks) {
+  const selectors = [DEFAULT_MASK_SELECTOR, ...masks];
+  await page.evaluate((selectors2) => {
+    for (const sel of selectors2) {
+      for (const el of Array.from(
+        document.querySelectorAll(sel)
+      )) {
+        const rect = el.getBoundingClientRect();
+        const overlay = document.createElement("div");
+        overlay.style.position = "absolute";
+        overlay.style.left = `${rect.left + window.scrollX}px`;
+        overlay.style.top = `${rect.top + window.scrollY}px`;
+        overlay.style.width = `${rect.width}px`;
+        overlay.style.height = `${rect.height}px`;
+        overlay.style.background = "#ff00ff";
+        overlay.style.zIndex = "2147483647";
+        overlay.style.pointerEvents = "none";
+        overlay.setAttribute("data-blazediff-mask", "1");
+        document.body.appendChild(overlay);
+      }
+    }
+  }, selectors);
+}
+
+// src/browser/capture.ts
+async function captureScreenshot(baseUrl, opts, cwd = process.cwd()) {
+  const viewport = opts.viewport ?? DEFAULT_VIEWPORT;
+  const waitFor = opts.waitFor ?? DEFAULT_WAIT_FOR;
+  const masks = opts.mask ?? [];
+  const fullPage = opts.fullPage ?? DEFAULT_FULL_PAGE;
+  const { context, page } = await openStableContext({ viewport});
+  try {
+    const url = new URL(opts.url, baseUrl).toString();
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 3e4 });
+    await waitForStability(page, waitFor);
+    await applyMaskOverlays(page, masks);
+    await page.evaluate(
+      () => new Promise((r) => requestAnimationFrame(() => r()))
+    );
+    const outputDir = opts.mode === "baseline" ? paths(cwd).baselines : paths(cwd).actual;
+    await mkdir(outputDir, { recursive: true });
+    const outputPath = path.join(outputDir, `${opts.id}.png`);
+    const buffer = await page.screenshot({
+      path: outputPath,
+      type: "png",
+      fullPage,
+      animations: "disabled",
+      caret: "hide",
+      scale: "device"
+    });
+    return { id: opts.id, outputPath, mode: opts.mode, bytes: buffer.length };
+  } finally {
+    await context.close().catch(() => {
+    });
+  }
+}
+function resolvePlaywrightCli() {
+  const require_ = createRequire(import.meta.url);
+  const pkgJson = require_.resolve("playwright/package.json");
+  const dir = path.dirname(pkgJson);
+  const candidates = [
+    path.join(dir, "cli.js"),
+    path.join(dir, "lib", "cli.js")
+  ];
+  const found = candidates.find((p) => existsSync(p));
+  if (!found) {
+    throw new Error(`could not locate playwright CLI under ${dir}`);
+  }
+  return found;
+}
+async function readExecutablePath() {
+  try {
+    const require_ = createRequire(import.meta.url);
+    const pw = require_("playwright");
+    const p = pw.chromium.executablePath();
+    return p && existsSync(p) ? p : null;
+  } catch {
+    return null;
+  }
+}
+async function installBrowsers(opts = {}) {
+  const cliPath = resolvePlaywrightCli();
+  if (opts.check) {
+    const executablePath2 = await readExecutablePath();
+    return { installed: Boolean(executablePath2), executablePath: executablePath2, cliPath };
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [cliPath, "install", "chromium"], {
+      stdio: ["ignore", "inherit", "inherit"],
+      env: process.env
+    });
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(`playwright install chromium exited with code ${code}`)
+        );
+    });
+    child.on("error", reject);
+  });
+  const executablePath = await readExecutablePath();
+  return { installed: Boolean(executablePath), executablePath, cliPath };
+}
+async function loadConfig(cwd = process.cwd()) {
+  const file = paths(cwd).config;
+  if (!existsSync(file)) return null;
+  return JSON.parse(await readFile(file, "utf8"));
+}
+async function saveConfig(config, cwd = process.cwd()) {
+  const file = paths(cwd).config;
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
+function configHash(config) {
+  return `sha256:${createHash("sha256").update(JSON.stringify(config)).digest("hex")}`;
+}
+function resolveBaseUrl(config, override) {
+  if (override) return override;
+  if (config?.baseUrl) return config.baseUrl;
+  if (config?.devServer) return `http://127.0.0.1:${config.devServer.port}`;
+  throw new Error("no baseUrl: pass --base-url or run `blazediff-agent init`");
+}
+
+// src/types.ts
+var STABILITY_HOOKS_VERSION = 1;
+
+// src/manifest.ts
+async function loadManifest(cwd = process.cwd()) {
+  const file = paths(cwd).manifest;
+  if (!existsSync(file)) return null;
+  return JSON.parse(await readFile(file, "utf8"));
+}
+async function saveManifest(manifest, cwd = process.cwd()) {
+  const file = paths(cwd).manifest;
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+}
+function emptyManifest(configHashValue) {
+  return {
+    version: 1,
+    configHash: configHashValue,
+    stabilityHooksVersion: STABILITY_HOOKS_VERSION,
+    entries: []
+  };
+}
+function hashMaterial(input) {
+  const material = {
+    url: input.url,
+    viewport: input.viewport,
+    mask: [...input.mask].sort(),
+    waitFor: input.waitFor,
+    auth: input.auth,
+    fullPage: input.fullPage,
+    hooks: STABILITY_HOOKS_VERSION
+  };
+  return `sha256:${createHash("sha256").update(JSON.stringify(material)).digest("hex")}`;
+}
+function makeEntry(input) {
+  const viewport = input.viewport ?? DEFAULT_VIEWPORT;
+  const waitFor = input.waitFor ?? DEFAULT_WAIT_FOR;
+  const mask = input.mask ?? [];
+  const auth = input.auth ?? null;
+  const fullPage = input.fullPage ?? DEFAULT_FULL_PAGE;
+  return {
+    id: input.id,
+    url: input.url,
+    viewport,
+    auth,
+    waitFor,
+    mask,
+    fullPage,
+    baselinePath: path.posix.join(".blazediff", "baselines", `${input.id}.png`),
+    captureHash: hashMaterial({
+      url: input.url,
+      viewport,
+      mask,
+      waitFor,
+      auth,
+      fullPage
+    }),
+    createdBy: input.createdBy ?? "agent",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+}
+function addOrReplaceEntry(manifest, entry) {
+  const entries = [
+    ...manifest.entries.filter((e) => e.id !== entry.id),
+    entry
+  ].sort((a, b) => a.id.localeCompare(b.id));
+  return { ...manifest, entries };
+}
+function isEntryStale(entry) {
+  const recomputed = hashMaterial({
+    url: entry.url,
+    viewport: entry.viewport,
+    mask: entry.mask,
+    waitFor: entry.waitFor,
+    auth: entry.auth,
+    fullPage: entry.fullPage ?? DEFAULT_FULL_PAGE
+  });
+  return recomputed !== entry.captureHash;
+}
+
+// src/captures.ts
+function validateRoute(route, i) {
+  if (!route || typeof route !== "object")
+    return `route[${i}] must be an object`;
+  if (!route.id || typeof route.id !== "string")
+    return `route[${i}] missing id`;
+  if (!route.url || typeof route.url !== "string")
+    return `route[${i}] missing url`;
+  return null;
+}
+async function loadOrCreateManifest(cwd) {
+  const existing = await loadManifest(cwd);
+  if (existing) return existing;
+  const config = await loadConfig(cwd);
+  return emptyManifest(config ? configHash(config) : "sha256:none");
+}
+async function runCaptures(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const defaultMode = opts.mode ?? "baseline";
+  const writeManifest = opts.writeManifest ?? true;
+  const results = [];
+  const valid = [];
+  opts.routes.forEach((r, i) => {
+    const err = validateRoute(r, i);
+    if (err) {
+      results.push({
+        id: r?.id ?? `route[${i}]`,
+        url: r?.url ?? "",
+        mode: r?.mode ?? defaultMode,
+        ok: false,
+        error: err
+      });
+    } else {
+      valid.push(r);
+    }
+  });
+  let manifest = writeManifest ? await loadOrCreateManifest(cwd) : null;
+  let manifestUpdates = 0;
+  try {
+    for (const r of valid) {
+      const mode = r.mode ?? defaultMode;
+      try {
+        const shot = await captureScreenshot(
+          opts.baseUrl,
+          {
+            id: r.id,
+            url: r.url,
+            viewport: r.viewport,
+            mask: r.mask,
+            waitFor: r.waitFor,
+            fullPage: r.fullPage,
+            mode
+          },
+          cwd
+        );
+        results.push({
+          id: r.id,
+          url: r.url,
+          mode,
+          ok: true,
+          outputPath: shot.outputPath,
+          bytes: shot.bytes
+        });
+        if (manifest && mode === "baseline") {
+          manifest = addOrReplaceEntry(
+            manifest,
+            makeEntry({
+              id: r.id,
+              url: r.url,
+              viewport: r.viewport,
+              mask: r.mask,
+              waitFor: r.waitFor,
+              fullPage: r.fullPage
+            })
+          );
+          manifestUpdates += 1;
+        }
+      } catch (err) {
+        results.push({
+          id: r.id,
+          url: r.url,
+          mode,
+          ok: false,
+          error: err.message
+        });
+      }
+    }
+    if (manifest && manifestUpdates > 0) await saveManifest(manifest, cwd);
+  } finally {
+    await closeBrowser();
+  }
+  const succeeded = results.filter((r) => r.ok).length;
+  return {
+    total: results.length,
+    succeeded,
+    failed: results.length - succeeded,
+    manifestUpdates,
+    results
+  };
+}
+var ENTRIES = [
+  "actual/",
+  "judgments/",
+  "summary.md",
+  "dev-server.log",
+  "dev-server.pid",
+  "*.tmp"
+];
+var STALE_ENTRIES = /* @__PURE__ */ new Set(["diffs/", "pending-judgments/", "report.json"]);
+var HEADER = "# blazediff: generated artifacts (committed: config.json, manifest.json, baselines/)\n";
+async function ensureGitignore(cwd) {
+  const file = paths(cwd).gitignore;
+  await mkdir(path.dirname(file), { recursive: true });
+  const existing = existsSync(file) ? await readFile(file, "utf8") : "";
+  const lines = existing.split("\n").map((l) => l.trim());
+  const hasStale = lines.some((l) => STALE_ENTRIES.has(l));
+  const missing = ENTRIES.filter((e) => !lines.includes(e));
+  if (!missing.length && !hasStale && existing) return;
+  if (hasStale) {
+    const kept = lines.filter(
+      (l) => !STALE_ENTRIES.has(l) && !ENTRIES.includes(l) && l !== ""
+    );
+    const body2 = `${kept.length ? `${kept.join("\n")}
+` : HEADER}${ENTRIES.join("\n")}
+`;
+    await writeFile(file, body2, "utf8");
+    return;
+  }
+  const body = existing ? `${existing.replace(/\n+$/, "")}
+${missing.join("\n")}
+` : `${HEADER}${ENTRIES.join("\n")}
+`;
+  await writeFile(file, body, "utf8");
+}
+async function diffEntry(id, baselinePath, actualPath, opts = {}, cwd = process.cwd()) {
+  if (!existsSync(baselinePath) || !existsSync(actualPath)) {
+    return {
+      id,
+      baselinePath,
+      actualPath,
+      match: false,
+      reason: "file-not-exists"
+    };
+  }
+  let diffPath;
+  if (opts.emitDiffPng) {
+    const actualDir = paths(cwd).actual;
+    await mkdir(actualDir, { recursive: true });
+    diffPath = path.join(actualDir, `${id}.diff.png`);
+  }
+  const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+  const antialiasing = opts.antialiasing ?? true;
+  const result = await compare(baselinePath, actualPath, diffPath, {
+    threshold,
+    antialiasing
+  });
+  if (result.match) return { id, baselinePath, actualPath, match: true };
+  if (result.reason === "file-not-exists") {
+    return {
+      id,
+      baselinePath,
+      actualPath,
+      match: false,
+      reason: "file-not-exists"
+    };
+  }
+  if (result.reason === "layout-diff") {
+    return {
+      id,
+      baselinePath,
+      actualPath,
+      diffPath,
+      match: false,
+      reason: "layout-diff"
+    };
+  }
+  const interpretation = await interpret(baselinePath, actualPath, {
+    threshold,
+    antialiasing
+  }).catch(() => void 0);
+  return {
+    id,
+    baselinePath,
+    actualPath,
+    diffPath,
+    match: false,
+    reason: "pixel-diff",
+    diffCount: result.diffCount,
+    diffPercentage: result.diffPercentage,
+    interpretation
+  };
+}
+
+// src/diff/verdict.ts
+var REGRESSIVE_TYPES = /* @__PURE__ */ new Set(["content-change", "addition", "deletion"]);
+var INTENTIONAL_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
+var NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
+var ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
+var SUB_PERCEPTUAL_PCT = 0.01;
+function pctText(pct) {
+  if (typeof pct !== "number") return "?%";
+  return pct >= 0.01 ? `${pct.toFixed(2)}%` : `${pct.toFixed(3)}%`;
+}
+function countByType(regions) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const r of regions)
+    counts.set(r.changeType, (counts.get(r.changeType) ?? 0) + 1);
+  return counts;
+}
+function dominantType(counts) {
+  let best = "";
+  let bestN = 0;
+  for (const [type, n] of counts) {
+    if (n > bestN) {
+      best = type;
+      bestN = n;
+    }
+  }
+  return best;
+}
+function topPosition(regions) {
+  let best;
+  for (const r of regions)
+    if (!best || r.pixelCount > best.pixelCount) best = r;
+  return best?.position;
+}
+function meanConfidence(regions) {
+  if (regions.length === 0) return 0;
+  return regions.reduce((a, r) => a + (r.confidence ?? 0), 0) / regions.length;
+}
+function formatBreakdown(counts) {
+  return [...counts].sort((a, b) => b[1] - a[1]).map(([type, n]) => `${n} ${type}`).join(", ");
+}
+function buildHeadline(input) {
+  const { reason, interpretation, diffCount, diffPercentage } = input;
+  if (reason === "layout-diff") return "image dimensions changed";
+  if (reason === "file-not-exists") return "baseline or actual capture missing";
+  if (!interpretation || interpretation.regions.length === 0) {
+    const px = diffCount?.toLocaleString() ?? "?";
+    return `${px} px (${pctText(diffPercentage)}) - no region analysis`;
+  }
+  const regions = interpretation.regions;
+  const counts = countByType(regions);
+  const pos = topPosition(regions);
+  const pct = pctText(diffPercentage ?? interpretation.diffPercentage);
+  const sev = interpretation.severity ?? "?";
+  if (regions.length === 1) {
+    return `1 ${dominantType(counts)}${pos ? ` @ ${pos}` : ""} (${pct}, ${sev})`;
+  }
+  return `${regions.length} regions: ${formatBreakdown(counts)}${pos ? ` @ ${pos}` : ""} (${pct}, ${sev})`;
+}
+function deriveVerdict(input) {
+  const { reason, interpretation, diffPercentage } = input;
+  const headline = buildHeadline(input);
+  if (reason === "layout-diff") {
+    return {
+      label: "ambiguous",
+      headline,
+      rationale: [
+        "baseline and actual image dimensions differ \u2014 page height likely shifted",
+        "could be intentional (content added/removed) or regression (broken layout)"
+      ],
+      action: "investigate"
+    };
+  }
+  if (reason === "file-not-exists") {
+    return {
+      label: "regression-likely",
+      headline,
+      rationale: ["baseline or actual capture is missing from disk"],
+      action: "investigate"
+    };
+  }
+  if (!interpretation || interpretation.regions.length === 0) {
+    return {
+      label: "ambiguous",
+      headline,
+      rationale: ["pixels differ but interpret returned no regions"],
+      action: "investigate"
+    };
+  }
+  const regions = interpretation.regions;
+  const severity = interpretation.severity;
+  const counts = countByType(regions);
+  const allNoise = regions.every((r) => NOISE_TYPES.has(r.changeType));
+  const allColor = regions.every((r) => r.changeType === "color-change");
+  const allMoved = regions.every((r) => INTENTIONAL_TYPES.has(r.changeType));
+  const hasRegressive = regions.some((r) => REGRESSIVE_TYPES.has(r.changeType));
+  const pct = typeof diffPercentage === "number" ? diffPercentage : interpretation.diffPercentage;
+  if (allNoise) {
+    return {
+      label: "noise-likely",
+      headline,
+      rationale: ["all regions classified as rendering-noise"],
+      action: "ignore-or-rewrite"
+    };
+  }
+  if (typeof pct === "number" && pct < SUB_PERCEPTUAL_PCT && severity === "low") {
+    return {
+      label: "noise-likely",
+      headline,
+      rationale: [
+        `delta < ${SUB_PERCEPTUAL_PCT}% (got ${pctText(pct)}) at "low" severity`,
+        "sub-perceptual change - review optional"
+      ],
+      action: "ignore-or-rewrite"
+    };
+  }
+  if (hasRegressive && ELEVATED_SEVERITY.has(severity ?? "")) {
+    const types = [...counts].filter(([t]) => REGRESSIVE_TYPES.has(t)).map(([t, n]) => `${n} ${t}`).join(", ");
+    return {
+      label: "regression-likely",
+      headline,
+      rationale: [
+        `severity ${severity} with structural changes (${types})`,
+        "likely affects content or layout, not just styling"
+      ],
+      action: "investigate"
+    };
+  }
+  if (allColor && meanConfidence(regions) > 0.7) {
+    return {
+      label: "intentional-likely",
+      headline,
+      rationale: [
+        `${regions.length} color-change region${regions.length === 1 ? "" : "s"} with mean confidence > 0.7`,
+        "edge structure preserved - looks like a theming / palette change"
+      ],
+      action: "rewrite-if-intended"
+    };
+  }
+  if (allMoved && !allColor) {
+    return {
+      label: "intentional-likely",
+      headline,
+      rationale: [
+        "all regions are shift/color-change - content moved or restyled, structure preserved"
+      ],
+      action: "rewrite-if-intended"
+    };
+  }
+  return {
+    label: "ambiguous",
+    headline,
+    rationale: [
+      `mix of change types (${formatBreakdown(counts)}) at "${severity ?? "?"}" severity`,
+      `${pctText(pct)} of image differs`
+    ],
+    action: "investigate"
+  };
+}
+var DEFAULT_TOP_N = 5;
+var DEFAULT_PADDING = 16;
+var DEFAULT_LOCATOR_MAX_WIDTH = 400;
+var DEFAULT_GUTTER = 2;
+var DEFAULT_ROW_GUTTER = 8;
+var BG_WHITE = { r: 255, g: 255, b: 255 };
+function padAndClamp(bbox, padding, imgWidth, imgHeight) {
+  const left = Math.max(0, Math.floor(bbox.x - padding));
+  const top = Math.max(0, Math.floor(bbox.y - padding));
+  const right = Math.min(imgWidth, Math.ceil(bbox.x + bbox.width + padding));
+  const bottom = Math.min(imgHeight, Math.ceil(bbox.y + bbox.height + padding));
+  return {
+    x: left,
+    y: top,
+    width: Math.max(1, right - left),
+    height: Math.max(1, bottom - top)
+  };
+}
+async function prepareTiles(opts) {
+  const topN = opts.topN ?? DEFAULT_TOP_N;
+  const padding = opts.padding ?? DEFAULT_PADDING;
+  const locatorMaxWidth = opts.locatorMaxWidth ?? DEFAULT_LOCATOR_MAX_WIDTH;
+  const gutter = opts.gutter ?? DEFAULT_GUTTER;
+  const rowGutter = opts.rowGutter ?? DEFAULT_ROW_GUTTER;
+  const diffMeta = await sharp(opts.diffPath).metadata();
+  const imgWidth = diffMeta.width ?? 0;
+  const imgHeight = diffMeta.height ?? 0;
+  if (!imgWidth || !imgHeight) {
+    throw new Error(`unable to read diff image dimensions: ${opts.diffPath}`);
+  }
+  const ranked = [...opts.regions].sort((a, b) => b.pixelCount - a.pixelCount).slice(0, topN);
+  const regionData = await Promise.all(
+    ranked.map(async (region) => {
+      const padded = padAndClamp(region.bbox, padding, imgWidth, imgHeight);
+      const extract = {
+        left: padded.x,
+        top: padded.y,
+        width: padded.width,
+        height: padded.height
+      };
+      const [base, actual] = await Promise.all([
+        sharp(opts.baselinePath).extract(extract).toBuffer(),
+        sharp(opts.actualPath).extract(extract).toBuffer()
+      ]);
+      return { region, padded, base, actual };
+    })
+  );
+  let tilesName;
+  if (regionData.length > 0) {
+    const canvasWidth = Math.max(
+      ...regionData.map((r) => r.padded.width * 2 + gutter)
+    );
+    const totalHeight = regionData.reduce(
+      (sum, r, i) => sum + r.padded.height + (i > 0 ? rowGutter : 0),
+      0
+    );
+    const composites = [];
+    let y = 0;
+    for (let i = 0; i < regionData.length; i++) {
+      const r = regionData[i];
+      const w = r.padded.width;
+      composites.push(
+        { input: r.base, left: 0, top: y },
+        { input: r.actual, left: w + gutter, top: y }
+      );
+      y += r.padded.height;
+      if (i < regionData.length - 1) y += rowGutter;
+    }
+    tilesName = "regions.png";
+    await sharp({
+      create: {
+        width: canvasWidth,
+        height: totalHeight,
+        channels: 3,
+        background: BG_WHITE
+      }
+    }).composite(composites).png().toFile(path.join(opts.outputDir, tilesName));
+  }
+  const scale = locatorMaxWidth / Math.max(imgWidth, imgHeight);
+  const locW = Math.max(1, Math.round(imgWidth * scale));
+  const locH = Math.max(1, Math.round(imgHeight * scale));
+  const rects = opts.regions.map((r) => {
+    const x = Math.round(r.bbox.x * scale);
+    const y = Math.round(r.bbox.y * scale);
+    const w = Math.max(1, Math.round(r.bbox.width * scale));
+    const h = Math.max(1, Math.round(r.bbox.height * scale));
+    return `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="red" stroke-width="2" />`;
+  }).join("");
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${locW}" height="${locH}">${rects}</svg>`;
+  const locatorName = "locator.png";
+  await sharp(opts.diffPath).resize(locW, locH, { fit: "fill" }).composite([{ input: Buffer.from(svg), left: 0, top: 0 }]).png().toFile(path.join(opts.outputDir, locatorName));
+  return {
+    locatorPath: locatorName,
+    tilesPath: tilesName,
+    regions: regionData.map((r) => ({
+      bbox: r.region.bbox,
+      pixelCount: r.region.pixelCount
+    }))
+  };
+}
+
+// src/judge/host-harness.ts
+async function tryPrepareTiles(input, entryDir) {
+  if (!input.regions || input.regions.length === 0 || !input.diffPath) {
+    return null;
+  }
+  try {
+    return await prepareTiles({
+      regions: input.regions,
+      baselinePath: input.baselinePath,
+      actualPath: input.actualPath,
+      diffPath: input.diffPath,
+      outputDir: entryDir
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[blazediff] tile generation failed for ${input.entry.id}: ${message}`
+    );
+    return null;
+  }
+}
+var hostHarnessJudge = {
+  name: "host",
+  async judge(input, cwd) {
+    const p = paths(cwd);
+    const entryDir = path.join(p.judgments, input.entry.id);
+    await mkdir(entryDir, { recursive: true });
+    await tryPrepareTiles(input, entryDir);
+    return { kind: "deferred", requestPath: entryDir };
+  }
+};
+
+// src/judge/none.ts
+var noneJudge = {
+  name: "none",
+  async judge(input) {
+    return { kind: "judged", verdict: input.heuristicVerdict };
+  }
+};
+var PREVIEW_WIDTH = 320;
+function escapeCell(s) {
+  return s.replace(/\n/g, " ");
+}
+function toBlazediffRel(cwd, abs) {
+  if (!abs) return void 0;
+  const root = paths(cwd).root;
+  const rel = path.isAbsolute(abs) ? path.relative(root, abs) : path.relative(paths(cwd).root, path.join(cwd, abs));
+  return rel.split(path.sep).join("/");
+}
+function img(src, alt) {
+  return `<img src="${src}" width="${PREVIEW_WIDTH}" alt="${alt}">`;
+}
+function baselineCell(r, cwd) {
+  const rel = toBlazediffRel(cwd, r.baselinePath) ?? `baselines/${r.id}.png`;
+  return img(rel, `${r.id} baseline`);
+}
+function actualCell(r, cwd) {
+  const actual = toBlazediffRel(cwd, r.actualPath);
+  return actual ? img(actual, `${r.id} actual`) : "-";
+}
+function diffCell(r, cwd) {
+  const diff = toBlazediffRel(cwd, r.diffPath);
+  return diff ? img(diff, `${r.id} diff`) : "-";
+}
+function verdictCell(r) {
+  if (r.status === "missing-baseline") {
+    return `missing-baseline - ${r.message ?? "baseline missing"}`;
+  }
+  if (r.status === "stale-baseline") {
+    return `stale-baseline - ${r.message ?? "manifest entry edited without re-capturing"}`;
+  }
+  if (r.status === "needs-judgment") {
+    return `needs-judgment - see judgments/${r.id}/`;
+  }
+  if (!r.verdict) {
+    return r.message ?? r.status;
+  }
+  return `${r.verdict.label} - ${r.verdict.headline} -> ${r.verdict.action}`;
+}
+function renderRow(r, cwd) {
+  return `| ${r.id} | ${escapeCell(baselineCell(r, cwd))} | ${escapeCell(actualCell(r, cwd))} | ${escapeCell(diffCell(r, cwd))} | ${escapeCell(verdictCell(r))} |`;
+}
+function headerLine(report) {
+  const { passed, failed, pendingJudgments, totalEntries } = report;
+  const parts = [`${passed}/${totalEntries} passed`];
+  if (failed > 0) parts.push(`${failed} failed`);
+  if (pendingJudgments > 0) parts.push(`${pendingJudgments} pending judgment`);
+  return parts.length > 1 ? `${parts[0]} (${parts.slice(1).join(", ")})` : parts[0];
+}
+function renderSummary(report, cwd = process.cwd()) {
+  const nonPass = report.results.filter((r) => r.status !== "pass");
+  const lines = [
+    `# blazediff check - ${report.createdAt}`,
+    "",
+    headerLine(report),
+    ""
+  ];
+  if (nonPass.length === 0) {
+    lines.push("All entries passed.");
+    return `${lines.join("\n")}
+`;
+  }
+  lines.push("| id | baseline | actual | diff | verdict |");
+  lines.push("| --- | --- | --- | --- | --- |");
+  for (const r of nonPass) lines.push(renderRow(r, cwd));
+  return `${lines.join("\n")}
+`;
+}
+async function writeSummaryMarkdown(report, cwd = process.cwd()) {
+  const file = paths(cwd).summary;
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, renderSummary(report, cwd), "utf8");
+  return file;
+}
+
+// src/judge/apply.ts
+var VALID_LABELS = [
+  "regression-likely",
+  "intentional-likely",
+  "noise-likely",
+  "ambiguous"
+];
+var VALID_ACTIONS = [
+  "investigate",
+  "rewrite-if-intended",
+  "ignore-or-rewrite"
+];
+function parseVerdict(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  if (typeof r.id !== "string") return null;
+  const v = r.verdict;
+  if (!v || typeof v !== "object") return null;
+  if (typeof v.label !== "string" || !VALID_LABELS.includes(v.label))
+    return null;
+  if (typeof v.headline !== "string") return null;
+  if (typeof v.action !== "string" || !VALID_ACTIONS.includes(v.action))
+    return null;
+  const rationale = Array.isArray(v.rationale) ? v.rationale.filter((x) => typeof x === "string") : [];
+  return {
+    id: r.id,
+    verdict: {
+      label: v.label,
+      headline: v.headline,
+      rationale,
+      action: v.action
+    },
+    rationale: typeof r.rationale === "string" ? r.rationale : void 0,
+    confidence: typeof r.confidence === "number" ? r.confidence : void 0
+  };
+}
+async function readJsonOrNull(file) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function readJudgmentDirs(root) {
+  let names;
+  try {
+    names = await readdir(root);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    const dir = path.join(root, name);
+    let isDir = false;
+    try {
+      isDir = (await stat(dir)).isDirectory();
+    } catch {
+      isDir = false;
+    }
+    if (!isDir) continue;
+    const request = await readJsonOrNull(
+      path.join(dir, "request.json")
+    );
+    const verdictFile = path.join(dir, "verdict.json");
+    let verdict = null;
+    let verdictInvalid = false;
+    if (existsSync(verdictFile)) {
+      const raw = await readJsonOrNull(verdictFile);
+      verdict = raw ? parseVerdict(raw) : null;
+      if (raw && !verdict) verdictInvalid = true;
+    }
+    out.push({ id: name, request, verdict, verdictInvalid });
+  }
+  return out;
+}
+function toAbs(cwd, rel) {
+  if (!rel) return void 0;
+  return path.isAbsolute(rel) ? rel : path.join(cwd, rel);
+}
+function buildResult(cwd, dir, entry) {
+  const req = dir.request;
+  const finalVerdict = dir.verdict?.verdict ?? req?.heuristicVerdict;
+  const status = req ? dir.verdict ? "fail" : req.status : "fail";
+  const message = dir.verdict?.rationale ?? (dir.verdict?.confidence !== void 0 ? `judged (confidence ${dir.verdict.confidence.toFixed(2)})` : req?.message);
+  return {
+    id: dir.id,
+    url: req?.url ?? entry?.url ?? "",
+    status,
+    diffPercentage: req?.diffPercentage,
+    severity: req?.severity,
+    regions: req?.regions,
+    verdict: finalVerdict,
+    diffPath: toAbs(cwd, req?.paths.diff),
+    actualPath: toAbs(cwd, req?.paths.actual),
+    baselinePath: toAbs(cwd, req?.paths.baseline),
+    message
+  };
+}
+function passResult(entry, cwd) {
+  const baselineAbs = path.join(paths(cwd).baselines, `${entry.id}.png`);
+  const actualAbs = path.join(paths(cwd).actual, `${entry.id}.png`);
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "pass",
+    baselinePath: baselineAbs,
+    actualPath: existsSync(actualAbs) ? actualAbs : void 0
+  };
+}
+async function applyJudgments(cwd = process.cwd()) {
+  const p = paths(cwd);
+  const manifest = await loadManifest(cwd);
+  if (!manifest) {
+    throw new Error(
+      `no manifest at ${p.manifest}. Run \`blazediff-agent init\` first.`
+    );
+  }
+  const dirs = await readJudgmentDirs(p.judgments);
+  const dirById = new Map(dirs.map((d) => [d.id, d]));
+  const applied = [];
+  const missing = [];
+  const invalid = [];
+  for (const d of dirs) {
+    if (d.verdictInvalid) invalid.push(path.join(p.judgments, d.id));
+    else if (d.verdict) applied.push(d.id);
+    else missing.push(d.id);
+  }
+  const nonPassResults = [];
+  for (const d of dirs) {
+    const entry = manifest.entries.find((e) => e.id === d.id);
+    nonPassResults.push(buildResult(cwd, d, entry));
+  }
+  const passResults = [];
+  for (const entry of manifest.entries) {
+    if (dirById.has(entry.id)) continue;
+    passResults.push(passResult(entry, cwd));
+  }
+  const results = [...passResults, ...nonPassResults];
+  const passed = results.filter((r) => r.status === "pass").length;
+  const pendingJudgments = results.filter(
+    (r) => r.status === "needs-judgment"
+  ).length;
+  const report = {
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    totalEntries: results.length,
+    passed,
+    failed: results.length - passed - pendingJudgments,
+    pendingJudgments,
+    results
+  };
+  await writeSummaryMarkdown(report, cwd);
+  return { report, applied, missing, invalid };
+}
+var HOST_INSTRUCTIONS = [
+  "The visual-regression heuristic could not classify this diff confidently.",
+  "Read `locator.png` AND `regions.png` in parallel - issue both Read calls in a single tool batch. locator.png is a small thumbnail of the diff with every change region outlined in red; regions.png is a vertical stack of [baseline | actual] pairs, one row per change region at native resolution. Row order matches the `regions[]` array (top = largest by pixelCount).",
+  "Decide from the tile pairs. Only open the full diff / baseline / actual PNGs if the composite is itself ambiguous (e.g., a change clearly continues outside the cropped region).",
+  "Decide whether the change is a regression, an intentional UI change, or rendering noise.",
+  "Write your decision to `verdict.json` (next to this `request.json`) with shape:",
+  '  { "id": string, "verdict": { "label": "regression-likely" | "intentional-likely" | "noise-likely", "headline": string, "rationale": string[], "action": "investigate" | "rewrite-if-intended" | "ignore-or-rewrite" }, "rationale": string, "confidence": number }',
+  "Then re-run `blazediff-agent check --apply-judgments --json` to regenerate summary.md."
+].join("\n");
+function relTo(cwd, abs) {
+  if (!abs) return void 0;
+  return path.relative(cwd, abs).split(path.sep).join("/");
+}
+function signatureOf(r) {
+  const pct = typeof r.diffPercentage === "number" ? r.diffPercentage.toFixed(4) : "?";
+  const regions = r.regions?.length ?? 0;
+  const severity = r.severity ?? "?";
+  return `${r.status}|diff:${pct}|regions:${regions}|severity:${severity}`;
+}
+async function readJsonOrNull2(file) {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function entryById(manifest, id) {
+  return manifest.entries.find((e) => e.id === id);
+}
+function buildRequest(result, entry, cwd, tiles) {
+  const isAmbiguous = result.status === "needs-judgment" || result.verdict?.label === "ambiguous" && result.status === "fail";
+  return {
+    id: result.id,
+    url: result.url,
+    status: result.status,
+    diffPercentage: result.diffPercentage,
+    severity: result.severity,
+    regions: result.regions,
+    paths: {
+      baseline: relTo(cwd, result.baselinePath),
+      actual: relTo(cwd, result.actualPath),
+      diff: relTo(cwd, result.diffPath),
+      locator: tiles.locatorPath,
+      tiles: tiles.tilesPath
+    },
+    heuristicVerdict: result.verdict,
+    manifestEntry: {
+      viewport: entry.viewport,
+      mask: entry.mask,
+      waitFor: entry.waitFor,
+      fullPage: entry.fullPage
+    },
+    signature: signatureOf(result),
+    message: result.message,
+    instructions: isAmbiguous ? HOST_INSTRUCTIONS : void 0,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function autoVerdict(result) {
+  if (!result.verdict) return null;
+  if (result.status === "needs-judgment") return null;
+  if (result.verdict.label === "ambiguous") return null;
+  return {
+    id: result.id,
+    verdict: result.verdict,
+    rationale: result.verdict.rationale.join(" "),
+    confidence: 1
+  };
+}
+async function discoverTiles(dir) {
+  const locatorAbs = path.join(dir, "locator.png");
+  const tilesAbs = path.join(dir, "regions.png");
+  return {
+    locatorPath: existsSync(locatorAbs) ? "locator.png" : void 0,
+    tilesPath: existsSync(tilesAbs) ? "regions.png" : void 0
+  };
+}
+async function writeJudgments(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const root = paths(cwd).judgments;
+  await mkdir(root, { recursive: true });
+  const knownIds = /* @__PURE__ */ new Set();
+  for (const r of opts.report.results) knownIds.add(r.id);
+  for (const result of opts.report.results) {
+    const dir = path.join(root, result.id);
+    if (result.status === "pass") {
+      if (existsSync(dir)) await rm(dir, { recursive: true, force: true });
+      continue;
+    }
+    const entry = entryById(opts.manifest, result.id);
+    if (!entry) continue;
+    await mkdir(dir, { recursive: true });
+    const tiles = await discoverTiles(dir);
+    const request = buildRequest(result, entry, cwd, tiles);
+    const requestFile = path.join(dir, "request.json");
+    const prior = await readJsonOrNull2(requestFile);
+    const verdictFile = path.join(dir, "verdict.json");
+    const priorVerdict = existsSync(verdictFile) ? await readJsonOrNull2(verdictFile) : null;
+    const signatureMatches = prior !== null && prior.signature === request.signature;
+    await writeFile(
+      requestFile,
+      `${JSON.stringify(request, null, 2)}
+`,
+      "utf8"
+    );
+    if (priorVerdict && signatureMatches) {
+      continue;
+    }
+    const auto = autoVerdict(result);
+    if (auto) {
+      await writeFile(
+        verdictFile,
+        `${JSON.stringify(auto, null, 2)}
+`,
+        "utf8"
+      );
+    } else if (priorVerdict && !signatureMatches) {
+      await rm(verdictFile, { force: true });
+    }
+  }
+  let entries;
+  try {
+    entries = await readdir(root);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (knownIds.has(name)) continue;
+    await rm(path.join(root, name), { recursive: true, force: true });
+  }
+}
+
+// src/judge/index.ts
+function resolveJudge(backend) {
+  switch (backend) {
+    case "none":
+      return noneJudge;
+    case "host":
+      return hostHarnessJudge;
+  }
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+async function writeJunit(report, destPath) {
+  await mkdir(path.dirname(destPath), { recursive: true });
+  const cases = report.results.map((r) => {
+    if (r.status === "pass") {
+      return `    <testcase classname="blazediff" name="${escapeXml(r.id)}"/>`;
+    }
+    const message = r.message ?? r.status;
+    return `    <testcase classname="blazediff" name="${escapeXml(r.id)}">
+      <failure message="${escapeXml(message)}" type="${escapeXml(r.status)}">${escapeXml(message)}</failure>
+    </testcase>`;
+  });
+  const failures = report.totalEntries - report.passed;
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="blazediff" tests="${report.totalEntries}" failures="${failures}">
+${cases.join("\n")}
+  </testsuite>
+</testsuites>
+`;
+  await writeFile(destPath, xml, "utf8");
+  return destPath;
+}
+
+// src/check.ts
+function narrowRegion(r) {
+  return {
+    bbox: r.bbox,
+    pixelCount: r.pixelCount,
+    percentage: r.percentage,
+    changeType: r.changeType,
+    confidence: r.confidence
+  };
+}
+async function pool(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workerCount = Math.max(1, Math.min(limit, items.length));
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (true) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+function passResult2(entry, baselinePath, actualPath) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "pass",
+    baselinePath,
+    actualPath
+  };
+}
+function skipResult(entry, message) {
+  return { id: entry.id, url: entry.url, status: "pass", message };
+}
+function staleResult(entry) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "stale-baseline",
+    message: "captureHash mismatch: entry was edited without re-capturing"
+  };
+}
+function missingBaselineResult(entry, baselinePath) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "missing-baseline",
+    message: `baseline missing at ${baselinePath}`
+  };
+}
+function failResult(entry, outcome, actualPath, baselinePath, verdict) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "fail",
+    diffCount: outcome.diffCount,
+    diffPercentage: outcome.diffPercentage,
+    severity: outcome.interpretation?.severity,
+    regions: outcome.interpretation?.regions?.map(narrowRegion),
+    verdict,
+    diffPath: outcome.diffPath,
+    baselinePath,
+    actualPath,
+    message: outcome.reason === "layout-diff" ? "layout differs (dimensions changed)" : `${outcome.diffCount ?? 0} pixels differ (${(outcome.diffPercentage ?? 0).toFixed(3)}%)`
+  };
+}
+async function judgeAmbiguous(result, entry, judge, cwd) {
+  if (result.status !== "fail" || !result.verdict || result.verdict.label !== "ambiguous" || !result.baselinePath || !result.actualPath) {
+    return result;
+  }
+  const output = await judge.judge(
+    {
+      entry,
+      baselinePath: result.baselinePath,
+      actualPath: result.actualPath,
+      diffPath: result.diffPath,
+      regions: result.regions,
+      diffPercentage: result.diffPercentage,
+      severity: result.severity,
+      heuristicVerdict: result.verdict
+    },
+    cwd
+  );
+  if (output.kind === "judged") {
+    return { ...result, verdict: output.verdict };
+  }
+  return {
+    ...result,
+    status: "needs-judgment",
+    message: `awaiting judgment in ${output.requestPath}`
+  };
+}
+async function checkEntry(entry, opts, cwd, baselinesDir, judge) {
+  if (entry.auth === "required") {
+    return skipResult(entry, "skipped: auth required (deferred to v0.2)");
+  }
+  if (isEntryStale(entry)) {
+    return staleResult(entry);
+  }
+  const baselinePath = path.join(baselinesDir, `${entry.id}.png`);
+  const capture = await captureScreenshot(
+    opts.baseUrl,
+    {
+      id: entry.id,
+      url: entry.url,
+      viewport: entry.viewport,
+      mask: entry.mask,
+      waitFor: entry.waitFor,
+      fullPage: entry.fullPage ?? DEFAULT_FULL_PAGE,
+      mode: "actual"
+    },
+    cwd
+  );
+  const outcome = await diffEntry(
+    entry.id,
+    baselinePath,
+    capture.outputPath,
+    { threshold: opts.threshold, emitDiffPng: opts.emitDiffPng ?? true },
+    cwd
+  );
+  if (outcome.match) return passResult2(entry, baselinePath, capture.outputPath);
+  if (outcome.reason === "file-not-exists")
+    return missingBaselineResult(entry, baselinePath);
+  const verdict = deriveVerdict({
+    reason: outcome.reason,
+    interpretation: outcome.interpretation,
+    diffCount: outcome.diffCount,
+    diffPercentage: outcome.diffPercentage
+  });
+  const failed = failResult(
+    entry,
+    outcome,
+    capture.outputPath,
+    baselinePath,
+    verdict
+  );
+  return judgeAmbiguous(failed, entry, judge, cwd);
+}
+async function runCheck(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const manifest = await loadManifest(cwd);
+  if (!manifest) {
+    throw new Error(
+      `no manifest found at ${paths(cwd).manifest}. Run \`blazediff init\` then \`/blazediff\` (or capture manually) first.`
+    );
+  }
+  const baselinesDir = paths(cwd).baselines;
+  const concurrency = opts.concurrency ?? defaultConcurrency();
+  const judge = resolveJudge(opts.judge ?? "none");
+  let results;
+  try {
+    results = await pool(
+      manifest.entries,
+      concurrency,
+      (entry) => checkEntry(entry, opts, cwd, baselinesDir, judge)
+    );
+  } finally {
+    await closeBrowser();
+  }
+  const passed = results.filter((r) => r.status === "pass").length;
+  const pendingJudgments = results.filter(
+    (r) => r.status === "needs-judgment"
+  ).length;
+  const report = {
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    totalEntries: results.length,
+    passed,
+    failed: results.length - passed - pendingJudgments,
+    pendingJudgments,
+    results
+  };
+  await writeJudgments({ report, manifest, cwd });
+  await writeSummaryMarkdown(report, cwd);
+  await ensureGitignore(cwd);
+  if (opts.junitPath) {
+    const target = path.isAbsolute(opts.junitPath) ? opts.junitPath : path.join(cwd, opts.junitPath);
+    await writeJunit(report, target);
+  }
+  return report;
+}
+
+// src/discover/crawl.ts
+function extractInternalLinks(base, target, hrefs) {
+  const out = [];
+  for (const href of hrefs) {
+    if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) {
+      continue;
+    }
+    try {
+      const u = new URL(href, target);
+      if (u.origin !== base.origin) continue;
+      const path18 = u.pathname + u.search;
+      if (path18.startsWith("/api/")) continue;
+      out.push(path18);
+    } catch {
+    }
+  }
+  return out;
+}
+async function crawlRoutes(opts) {
+  const maxRoutes = opts.maxRoutes ?? 50;
+  const maxDepth = opts.maxDepth ?? 2;
+  const base = new URL(opts.baseUrl);
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [{ url: "/", depth: 0 }];
+  visited.add("/");
+  const discovered = [];
+  const browser = await getBrowser();
+  const context = await browser.newContext({
+    viewport: { width: 1024, height: 768 },
+    deviceScaleFactor: 1
+  });
+  try {
+    while (queue.length && discovered.length < maxRoutes) {
+      const { url, depth } = queue.shift();
+      const page = await context.newPage();
+      try {
+        const target = new URL(url, base).toString();
+        await page.goto(target, {
+          waitUntil: "domcontentloaded",
+          timeout: 15e3
+        });
+        discovered.push({ url, source: "crawl" });
+        if (depth >= maxDepth) continue;
+        const hrefs = await page.evaluate(
+          () => Array.from(
+            document.querySelectorAll("a[href]")
+          ).map((a) => a.getAttribute("href") ?? "")
+        );
+        for (const path18 of extractInternalLinks(base, target, hrefs)) {
+          if (visited.has(path18)) continue;
+          visited.add(path18);
+          queue.push({ url: path18, depth: depth + 1 });
+        }
+      } catch {
+      } finally {
+        await page.close().catch(() => {
+        });
+      }
+    }
+  } finally {
+    await context.close().catch(() => {
+    });
+  }
+  return discovered;
+}
+var DYNAMIC_SEGMENT = /\[[^\]]+\]/;
+async function readJson(file) {
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isPublicRoute(route) {
+  if (DYNAMIC_SEGMENT.test(route)) return false;
+  if (route === "/api" || route.startsWith("/api/")) return false;
+  return true;
+}
+async function discoverFromNextManifest(cwd = process.cwd()) {
+  const nextDir = path.join(cwd, ".next");
+  if (!existsSync(nextDir)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const add = (url) => {
+    if (seen.has(url)) return;
+    seen.add(url);
+    out.push({ url, source: "next-manifest" });
+  };
+  const routes = await readJson(
+    path.join(nextDir, "routes-manifest.json")
+  );
+  for (const r of routes?.staticRoutes ?? []) {
+    if (isPublicRoute(r.page)) add(r.page);
+  }
+  const appPaths = await readJson(
+    path.join(nextDir, "server", "app-paths-manifest.json")
+  );
+  for (const route of Object.keys(appPaths ?? {})) {
+    const normalized = route.replace(/\/page$/, "") || "/";
+    if (isPublicRoute(normalized)) add(normalized);
+  }
+  return out;
+}
+
+// src/discover/sitemap.ts
+var CANDIDATES = ["/sitemap.xml", "/sitemap_index.xml"];
+var LOC_RE = /<loc>([^<]+)<\/loc>/g;
+async function discoverFromSitemap(baseUrl) {
+  for (const candidate of CANDIDATES) {
+    try {
+      const res = await fetch(new URL(candidate, baseUrl));
+      if (!res.ok) continue;
+      const text = await res.text();
+      const urls = Array.from(text.matchAll(LOC_RE)).map((m) => m[1]);
+      if (!urls.length) continue;
+      return urls.map((u) => {
+        const url = new URL(u);
+        return { url: url.pathname + url.search, source: "sitemap" };
+      });
+    } catch {
+    }
+  }
+  return [];
+}
+
+// src/discover/index.ts
+function normalizePath(url) {
+  const [pathPart, query = ""] = url.split("?", 2);
+  const trimmed = pathPart.replace(/\/+$/, "");
+  const normalizedPath = trimmed === "" ? "/" : trimmed;
+  return query ? `${normalizedPath}?${query}` : normalizedPath;
+}
+function mergeBy(routes, into) {
+  for (const r of routes) {
+    const key = normalizePath(r.url);
+    if (!into.has(key)) into.set(key, { ...r, url: key });
+  }
+}
+async function discover(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const merged = /* @__PURE__ */ new Map();
+  mergeBy(await discoverFromNextManifest(cwd), merged);
+  mergeBy(await discoverFromSitemap(opts.baseUrl), merged);
+  if (!opts.skipCrawl) {
+    const crawlMax = Math.max(0, (opts.maxRoutes ?? 50) - merged.size);
+    if (crawlMax > 0) {
+      mergeBy(
+        await crawlRoutes({ baseUrl: opts.baseUrl, maxRoutes: crawlMax }),
+        merged
+      );
+    }
+  }
+  return Array.from(merged.values()).sort((a, b) => a.url.localeCompare(b.url));
+}
+
+// src/graph/nodes/aggregate.ts
+async function aggregateNode(state) {
+  const options = state.options;
+  if (!options) throw new Error("aggregateNode: options missing");
+  const manifest = state.manifest;
+  if (!manifest) throw new Error("aggregateNode: manifest missing");
+  const results = state.results;
+  const passed = results.filter((r) => r.status === "pass").length;
+  const pendingJudgments = results.filter(
+    (r) => r.status === "needs-judgment"
+  ).length;
+  const report = {
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    totalEntries: results.length,
+    passed,
+    failed: results.length - passed - pendingJudgments,
+    pendingJudgments,
+    results
+  };
+  await writeJudgments({ report, manifest, cwd: options.cwd });
+  await writeSummaryMarkdown(report, options.cwd);
+  await ensureGitignore(options.cwd);
+  return { report };
+}
+
+// src/graph/nodes/load.ts
+async function loadNode(state) {
+  if (!state.options) {
+    throw new Error("loadNode: graph options missing");
+  }
+  const manifest = await loadManifest(state.options.cwd);
+  if (!manifest) {
+    throw new Error(
+      `no manifest found at ${paths(state.options.cwd).manifest}. Run \`blazediff init\` then \`/blazediff\` (or capture manually) first.`
+    );
+  }
+  return { entries: manifest.entries, manifest };
+}
+function narrowRegion2(r) {
+  return {
+    bbox: r.bbox,
+    pixelCount: r.pixelCount,
+    percentage: r.percentage,
+    changeType: r.changeType,
+    confidence: r.confidence
+  };
+}
+function skipResult2(entry, message) {
+  return { id: entry.id, url: entry.url, status: "pass", message };
+}
+function staleResult2(entry) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "stale-baseline",
+    message: "captureHash mismatch: entry was edited without re-capturing"
+  };
+}
+function passResult3(entry, baselinePath, actualPath) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "pass",
+    baselinePath,
+    actualPath
+  };
+}
+function missingBaselineResult2(entry, baselinePath) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "missing-baseline",
+    message: `baseline missing at ${baselinePath}`
+  };
+}
+function failResult2(entry, outcome, actualPath, baselinePath, verdict) {
+  return {
+    id: entry.id,
+    url: entry.url,
+    status: "fail",
+    diffCount: outcome.diffCount,
+    diffPercentage: outcome.diffPercentage,
+    severity: outcome.interpretation?.severity,
+    regions: outcome.interpretation?.regions?.map(narrowRegion2),
+    verdict,
+    diffPath: outcome.diffPath,
+    baselinePath,
+    actualPath,
+    message: outcome.reason === "layout-diff" ? "layout differs (dimensions changed)" : `${outcome.diffCount ?? 0} pixels differ (${(outcome.diffPercentage ?? 0).toFixed(3)}%)`
+  };
+}
+function makeProcessNode(semaphore) {
+  return async function processNode(state) {
+    const entry = state.entry;
+    const options = state.options;
+    if (!entry || !options) {
+      throw new Error("processNode: entry or options missing");
+    }
+    if (entry.auth === "required") {
+      return {
+        results: [
+          skipResult2(entry, "skipped: auth required (deferred to v0.2)")
+        ]
+      };
+    }
+    if (isEntryStale(entry)) {
+      return { results: [staleResult2(entry)] };
+    }
+    const capture = await semaphore.run(
+      () => captureScreenshot(
+        options.baseUrl,
+        {
+          id: entry.id,
+          url: entry.url,
+          viewport: entry.viewport,
+          mask: entry.mask,
+          waitFor: entry.waitFor,
+          fullPage: entry.fullPage ?? DEFAULT_FULL_PAGE,
+          mode: "actual"
+        },
+        options.cwd
+      )
+    );
+    const baselinePath = path.join(options.baselinesDir, `${entry.id}.png`);
+    const outcome = await diffEntry(
+      entry.id,
+      baselinePath,
+      capture.outputPath,
+      { threshold: options.threshold, emitDiffPng: options.emitDiffPng },
+      options.cwd
+    );
+    if (outcome.match) {
+      return { results: [passResult3(entry, baselinePath, capture.outputPath)] };
+    }
+    if (outcome.reason === "file-not-exists") {
+      return { results: [missingBaselineResult2(entry, baselinePath)] };
+    }
+    const verdict = deriveVerdict({
+      reason: outcome.reason,
+      interpretation: outcome.interpretation,
+      diffCount: outcome.diffCount,
+      diffPercentage: outcome.diffPercentage
+    });
+    let result = failResult2(
+      entry,
+      outcome,
+      capture.outputPath,
+      baselinePath,
+      verdict
+    );
+    if (result.verdict?.label === "ambiguous" && result.baselinePath && result.actualPath) {
+      const judge = resolveJudge(options.judge);
+      const output = await judge.judge(
+        {
+          entry,
+          baselinePath: result.baselinePath,
+          actualPath: result.actualPath,
+          diffPath: result.diffPath,
+          regions: result.regions,
+          diffPercentage: result.diffPercentage,
+          severity: result.severity,
+          heuristicVerdict: result.verdict
+        },
+        options.cwd
+      );
+      if (output.kind === "judged") {
+        result = { ...result, verdict: output.verdict };
+      } else {
+        result = {
+          ...result,
+          status: "needs-judgment",
+          message: `awaiting judgment in ${output.requestPath}`
+        };
+      }
+    }
+    return { results: [result] };
+  };
+}
+
+// src/graph/semaphore.ts
+var Semaphore = class {
+  constructor(limit) {
+    this.limit = limit;
+    this.current = 0;
+    this.queue = [];
+    if (limit < 1)
+      throw new Error(`semaphore limit must be >= 1 (got ${limit})`);
+  }
+  async run(fn) {
+    if (this.current >= this.limit) {
+      await new Promise((resolve) => this.queue.push(resolve));
+    }
+    this.current++;
+    try {
+      return await fn();
+    } finally {
+      this.current--;
+      const next = this.queue.shift();
+      if (next) next();
+    }
+  }
+};
+var GraphState = Annotation.Root({
+  options: Annotation({
+    reducer: (acc, next) => next ?? acc,
+    default: () => void 0
+  }),
+  entries: Annotation({
+    reducer: (acc, next) => next ?? acc,
+    default: () => []
+  }),
+  entry: Annotation({
+    reducer: (_, next) => next,
+    default: () => void 0
+  }),
+  results: Annotation({
+    reducer: (acc, next) => [...acc, ...next],
+    default: () => []
+  }),
+  manifest: Annotation({
+    reducer: (acc, next) => next ?? acc,
+    default: () => void 0
+  }),
+  report: Annotation({
+    reducer: (acc, next) => next ?? acc,
+    default: () => void 0
+  })
+});
+
+// src/graph/index.ts
+function buildGraph(semaphore) {
+  return new StateGraph(GraphState).addNode("load", loadNode).addNode("process", makeProcessNode(semaphore)).addNode("aggregate", aggregateNode).addEdge(START, "load").addConditionalEdges(
+    "load",
+    (state) => state.entries.map(
+      (entry) => new Send("process", { entry, options: state.options })
+    ),
+    ["process"]
+  ).addEdge("process", "aggregate").addEdge("aggregate", END).compile();
+}
+async function runGraph(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const concurrency = opts.concurrency ?? defaultConcurrency();
+  const semaphore = new Semaphore(concurrency);
+  const baselinesDir = paths(cwd).baselines;
+  const graph = buildGraph(semaphore);
+  let finalState;
+  try {
+    finalState = await graph.invoke({
+      options: {
+        baseUrl: opts.baseUrl,
+        cwd,
+        threshold: opts.threshold,
+        concurrency,
+        emitDiffPng: opts.emitDiffPng ?? true,
+        judge: opts.judge ?? "none",
+        baselinesDir
+      }
+    });
+  } finally {
+    await closeBrowser();
+  }
+  const report = finalState.report;
+  if (!report) {
+    throw new Error("runGraph: graph completed without producing a report");
+  }
+  if (opts.junitPath) {
+    const target = path.isAbsolute(opts.junitPath) ? opts.junitPath : path.join(cwd, opts.junitPath);
+    await writeJunit(report, target);
+  }
+  return report;
+}
+
+export { STABILITY_HOOKS_VERSION, applyJudgments, captureScreenshot, configHash, diffEntry, discover, installBrowsers, loadConfig, loadManifest, paths, resolveBaseUrl, resolveJudge, runCaptures, runCheck, runGraph, saveConfig, saveManifest };