pursr 0.4.0 → 0.6.0

package/bin/pursr.mjs

@@ -9,14 +9,15 @@ import { runShot } from "../src/shot.js";
 import { runShootWithSidecar } from "../src/shoot.js";
 import { runHover } from "../src/hover.js";
 import { runFrames } from "../src/frames.js";
-import { runDiff } from "../src/diff.js";
+import { runDiff, runDiffWithAi } from "../src/diff.js";
 import { runSweep } from "../src/sweep.js";
 import { runEveryViewport } from "../src/every-viewport.js";
 import { runAudit } from "../src/plugin-audit.js";
 import { captureDomSnapshot } from "../src/dom-snapshot.js";
 import { listViewports } from "../src/viewport.js";
 import { parseFlags, asNum, readArg, makeOut, pickOutPath } from "../src/util.js";
-import { writeFileSync } from "node:fs";
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { readFileSync as _readFileSync } from "node:fs";
 const readFile = _readFileSync;
 import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
@@ -31,6 +32,8 @@ const USAGE = `usage:
          --grid --grid-tile 64 --grid-color rgba(255,0,255,0.35)
          --no-animation --wait-frame 600 --full
   @file prefix reads argv contents from file (UTF-8, newline trimmed).
+  report: pursr report --sweep <sweep.json> [--out <report.pdf>] [--title "..."] [--no-embed]
+         diff extras: --ai [--ai-model M] [--ai-base-url U] [--ai-api-key K]
   plugins: pursor automatically loads built-in plugins from plugins/.
   You can also pass --plugin <path> to load custom plugins (repeatable).`;
 
@@ -42,6 +45,16 @@ function die(msg, code = 2) {
 const argv = process.argv;
 const [, , cmd, a, b, c, d] = argv;
 const url = process.env.PURSOR_URL || a;
+// Top-level --plan / --out parsing for subcommands that need it before dispatch
+function _topOpts() {
+  const o = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--plan" && i + 1 < argv.length) o.plan = argv[++i];
+    if (argv[i] === "--out" && i + 1 < argv.length) o.out = argv[++i];
+  }
+  return o;
+}
+const opts = _topOpts();
 
 // Plugin loading: scan for --plugin <path> and built-in plugins/
 const pluginPaths = [];
@@ -63,7 +76,19 @@ await loadPlugins(pluginPaths);
       case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = c || makeOut(`click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out); console.log(JSON.stringify(r, null, 2)); break; }
       case "type": { if (!url) die("missing url"); const sel = b; const text = readArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = d || makeOut(`type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out); console.log(JSON.stringify(r, null, 2)); break; }
       case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t); console.log(JSON.stringify(r, null, 2)); break; }
-      case "diff": { if (!url) die("missing url"); const ref = b; if (!ref) die("diff: missing <ref.png>"); const out = c || makeOut("diff.png"); const threshold = d !== undefined ? Number(d) : 0.1; const r = await runDiff(url, ref, out, threshold); console.log(JSON.stringify(r, null, 2)); break; }
+      case "diff": {
+        if (!url) die("missing url"); const ref = b; if (!ref) die("diff: missing <ref.png>");
+        const out = c || makeOut("diff.png"); const threshold = d !== undefined ? Number(d) : 0.1;
+        // --ai / --ai-model / --ai-base-url / --ai-api-key
+        const useAi = argv.includes("--ai");
+        const aiModel = (() => { const i = argv.indexOf("--ai-model"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
+        const aiBaseUrl = (() => { const i = argv.indexOf("--ai-base-url"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
+        const aiApiKey = (() => { const i = argv.indexOf("--ai-api-key"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
+        const r = useAi
+          ? await runDiffWithAi(url, ref, out, threshold, { model: aiModel, baseUrl: aiBaseUrl, apiKey: aiApiKey })
+          : await runDiff(url, ref, out, threshold);
+        console.log(JSON.stringify(r, null, 2)); break;
+      }
       case "seq": { if (!url) die("missing url"); const actions = readArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = c || makeOut("seq.png"); const r = await runSeq(url, actions, out); console.log(JSON.stringify(r, null, 2)); break; }
       case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
       case "shoot": {
@@ -107,6 +132,24 @@ await loadPlugins(pluginPaths);
         console.log(JSON.stringify(r, null, 2));
         break;
       }
+      case "report": {
+        // pursr report --sweep <sweep.json> [--out report.pdf] [--title "..."]
+        const sweepIdx = argv.indexOf("--sweep");
+        const sweepPath = sweepIdx >= 0 && sweepIdx + 1 < argv.length ? argv[sweepIdx + 1] : a;
+        if (!sweepPath) die("report: missing --sweep <sweep.json>");
+        if (!existsSync(sweepPath)) die("report: sweep not found: " + sweepPath);
+        const outIdx = argv.indexOf("--out");
+        const outPath = outIdx >= 0 && outIdx + 1 < argv.length ? argv[outIdx + 1] : (opts.out || makeOut("report.pdf").replace(/pursor-[^-]+-shot.png$/, "report.pdf"));
+        if (outPath && outPath !== "-") mkdirSync(dirname(outPath), { recursive: true });
+        const titleIdx = argv.indexOf("--title");
+        const title = titleIdx >= 0 && titleIdx + 1 < argv.length ? argv[titleIdx + 1] : undefined;
+        const noEmbed = argv.includes("--no-embed");
+        const summary = JSON.parse(readFile(sweepPath, "utf8"));
+        const { renderSweepPdf } = await import("../src/report.js");
+        const buf = await renderSweepPdf(summary, { out: outPath === "-" ? undefined : outPath, title, embedImages: !noEmbed });
+        console.log(JSON.stringify({ ok: true, sweep: sweepPath, out: outPath, bytes: buf.length }, null, 2));
+        break;
+      }
       case "every-viewport": {
         if (!url) die("missing url");
         const outDir = (b && !b.startsWith("--")) ? b : undefined;
@@ -218,6 +261,62 @@ await loadPlugins(pluginPaths);
               }
               break;
             }
+            case "watch": {
+              // pursr watch <url> [--out ./shot.png] [--on <glob>...] [--plan <plan.json>]
+              if (opts.plan) {
+                if (!existsSync(opts.plan)) die("watch: plan not found: " + opts.plan);
+              } else if (!url) {
+                die("watch: missing <url> (or use --plan <plan.json>)");
+              }
+              const { startWatch } = await import("../src/watch.js");
+              const out = (b && !b.startsWith("--")) ? b : (opts.out || makeOut("watch.png"));
+              if (out && out !== "--plan") mkdirSync(dirname(out), { recursive: true });
+              const flags = parseFlags(argv.slice(3));
+              const onGlobs = [];
+              for (let i = 0; i < argv.length; i++) {
+                if (argv[i] === "--on" && i + 1 < argv.length) onGlobs.push(argv[++i]);
+              }
+              console.error(JSON.stringify({ watching: true, url: opts.plan ? null : url, plan: opts.plan || null, out, on: onGlobs }));
+              const w = await startWatch({
+                url: opts.plan ? undefined : url,
+                out,
+                plan: opts.plan,
+                on: onGlobs,
+                flags,
+                verbose: true,
+                onChange: (e) => console.error(JSON.stringify({ event: e.type, path: e.path, captureOk: !e.capture?.error, captureOut: e.capture?.out, ts: e.ts })),
+              });
+              // Keep alive until SIGINT
+              await new Promise((resolve) => {
+                process.on("SIGINT", () => { console.error("[pursr watch] stopping..."); w.close().then(resolve); });
+                process.on("SIGTERM", () => { w.close().then(resolve); });
+              });
+              console.log(JSON.stringify({ fires: w.fires() }, null, 2));
+              break;
+            }
+            case "snap": {
+              // pursr snap <url> <selector> [--out <dir>] [--name <slug>] [--max N] [--baseline <project>]
+              if (!url) die("snap: missing <url>");
+              const sel = b; if (!sel) die("snap: missing <selector>");
+              const flags = parseFlags(argv.slice(4));
+              const { runSnap, approveSnapsAsBaselines } = await import("../src/snap.js");
+              const outDir = flags.out || makeOut("snaps").replace(/pursor-[^-]+-snap\.png$/, "snaps");
+              const snap = await runSnap({ url, selector: sel, outDir, name: flags.name, max: flags.max, flags });
+              console.log(JSON.stringify({
+                url: snap.url,
+                selector: snap.selector,
+                count: snap.count,
+                captured: snap.captured,
+                outDir: snap.outDir,
+                captures: snap.captures,
+                nav: snap.nav,
+              }, null, 2));
+              if (flags.baseline) {
+                const r = approveSnapsAsBaselines({ project: flags.baseline, snapResult: snap });
+                console.error(JSON.stringify({ approved: r.length, project: flags.baseline }));
+              }
+              break;
+            }
             default: { die(`unknown subcommand: ${cmd}`); }
     }
   } catch (e) {

package/package.json

@@ -1,90 +1,95 @@
-{
-  "name": "pursr",
-  "version": "0.4.0",
-  "private": false,
-  "description": "Visual QA, audit, and MCP for the browser. One CLI + one MCP server for screenshots, sweeps, baselines, diffs, axe-core a11y audits, HAR capture, and auth state — with parallel sweep workers, auto-healing selectors, and a plugin system. Zero browser bundled: drives your system Chrome via Playwright.",
-  "homepage": "https://github.com/0xheycat/pursr",
-  "bugs": "https://github.com/0xheycat/pursr/issues",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/0xheycat/pursr.git"
-  },
-  "funding": "https://github.com/sponsors/0xheycat",
-  "type": "module",
-  "bin": {
-    "pursr": "./bin/pursr.mjs",
-    "pursr-mcp": "./bin/pursr-mcp.mjs"
-  },
-  "main": "./src/index.js",
-  "exports": {
-    ".": "./src/index.js",
-    "./plugin": "./src/plugin.js",
-    "./plugins/*": "./plugins/*.js",
-    "./util": "./src/util.js",
-    "./runway": "./src/runway.js",
-    "./selector": "./src/selector.js",
-    "./overlays": "./src/overlays.js",
-    "./viewport": "./src/viewport.js",
-    "./dom-snapshot": "./src/dom-snapshot.js",
-    "./plugin-audit": "./src/plugin-audit.js",
-    "./selector-heal": "./src/selector-heal.js",
-    "./ci-output": "./src/ci-output.js",
-    "./mcp": "./src/mcp.js",
-    "./baseline": "./src/baseline.js",
-    "./sweep-schema": "./src/sweep-schema.js",
-    "./mcp-resources": "./src/mcp-resources.js",
-    "./har": "./src/har.js",
-    "./auth": "./src/auth.js"
-  },
-  "files": [
-    "bin",
-    "src",
-    "plugins",
-    "plans",
-    "assets",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "start": "node bin/pursor.mjs",
-    "test": "node --test \"test/*.test.js\"",
-    "smoke": "node bin/pursor.mjs viewports"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "visual-qa",
-    "visual-regression",
-    "screenshot",
-    "audit",
-    "accessibility",
-    "axe-core",
-    "playwright",
-    "mcp",
-    "model-context-protocol",
-    "baseline",
-    "diff",
-    "har",
-    "testing",
-    "devtools",
-    "pursr"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "axe-core": "^4.12.1",
-    "pixelmatch": "^5.3.0",
-    "pngjs": "^7.0.0"
-  },
-  "peerDependencies": {
-    "playwright-core": "*"
-  },
-  "peerDependenciesMeta": {
-    "playwright-core": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "playwright-core": "^1.61.0"
-  }
-}
+{
+  "name": "pursr",
+  "version": "0.6.0",
+  "private": false,
+  "description": "Visual QA, audit, and MCP for the browser. One CLI + one MCP server for screenshots, sweeps, baselines, diffs, axe-core a11y audits, HAR capture, and auth state — with parallel sweep workers, auto-healing selectors, and a plugin system. Zero browser bundled: drives your system Chrome via Playwright.",
+  "homepage": "https://github.com/0xheycat/pursr",
+  "bugs": "https://github.com/0xheycat/pursr/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xheycat/pursr.git"
+  },
+  "funding": "https://github.com/sponsors/0xheycat",
+  "type": "module",
+  "bin": {
+    "pursr": "./bin/pursr.mjs",
+    "pursr-mcp": "./bin/pursr-mcp.mjs"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./plugin": "./src/plugin.js",
+    "./plugins/*": "./plugins/*.js",
+    "./util": "./src/util.js",
+    "./runway": "./src/runway.js",
+    "./selector": "./src/selector.js",
+    "./overlays": "./src/overlays.js",
+    "./viewport": "./src/viewport.js",
+    "./dom-snapshot": "./src/dom-snapshot.js",
+    "./plugin-audit": "./src/plugin-audit.js",
+    "./selector-heal": "./src/selector-heal.js",
+    "./ci-output": "./src/ci-output.js",
+    "./mcp": "./src/mcp.js",
+    "./baseline": "./src/baseline.js",
+    "./sweep-schema": "./src/sweep-schema.js",
+    "./mcp-resources": "./src/mcp-resources.js",
+    "./har": "./src/har.js",
+    "./auth": "./src/auth.js",
+    "./watch": "./src/watch.js",
+    "./snap": "./src/snap.js",
+    "./report": "./src/report.js",
+    "./ai-diff": "./src/ai-diff.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugins",
+    "plans",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/pursor.mjs",
+    "test": "node --test \"test/*.test.js\"",
+    "smoke": "node bin/pursor.mjs viewports"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "visual-qa",
+    "visual-regression",
+    "screenshot",
+    "audit",
+    "accessibility",
+    "axe-core",
+    "playwright",
+    "mcp",
+    "model-context-protocol",
+    "baseline",
+    "diff",
+    "har",
+    "testing",
+    "devtools",
+    "pursr"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "axe-core": "^4.12.1",
+    "pdfkit": "^0.19.1",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0"
+  },
+  "peerDependencies": {
+    "playwright-core": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "playwright-core": "^1.61.0"
+  }
+}

package/src/ai-diff.js

@@ -0,0 +1,124 @@
+// pursor - AI diff summary.
+//
+// Sends two images (reference + current) to a vision-capable LLM and asks
+// it to describe the visual differences in plain language. This gives you
+// a human-readable summary alongside the pixel-diff percentage.
+//
+// Supports any OpenAI-compatible chat completions endpoint that accepts
+// image_url content parts (OpenAI, Anthropic via proxy, local llama.cpp,
+// Codex tokenrouter, etc).
+//
+// CLI:
+//   pursr diff <url> <ref.png> <out.png> --ai
+//   pursr diff <url> <ref.png> <out.png> --ai-model gh/gpt-5.4
+//
+// Library:
+//   import { aiDiffSummary } from "pursr/ai-diff";
+//   const summary = await aiDiffSummary({ refPath, curPath, url, model });
+
+import { readFileSync, existsSync } from "node:fs";
+
+// Read env at call time so tests can mutate process.env between calls.
+function _defaultBase() { return process.env.PURSOR_AI_BASE_URL || process.env.ANTHROPIC_BASE_URL || "https://api.openai.com/v1"; }
+function _defaultKey()  { return process.env.PURSOR_AI_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN || process.env.OPENAI_API_KEY; }
+function _defaultModel(){ return process.env.PURSOR_AI_MODEL || process.env.ANTHROPIC_DEFAULT_SONNET_MODEL || "gpt-4o"; }
+
+const SYSTEM_PROMPT = `You are a visual regression analyst. Given two screenshots of the same web page (reference vs current), produce a concise, structured report of the visual differences.
+
+Output format (markdown, keep under 250 words):
+
+**Overall:** one sentence verdict (looks identical / minor changes / major regression).
+**Layout shifts:** list any element that moved, resized, or appeared/disappeared.
+**Color / style:** any color, font, or spacing changes.
+**Content:** new, removed, or changed text/imagery.
+**Likely cause:** best guess at what code or content change caused this.
+
+Be specific (mention element labels, regions). Be honest about uncertainty.`;
+
+/**
+ * Send reference + current PNGs to a vision model and return a textual diff summary.
+ *
+ * @param {object} opts
+ * @param {string} opts.refPath   - Path to reference PNG
+ * @param {string} opts.curPath   - Path to current PNG
+ * @param {string} [opts.url]     - URL that was captured (for context)
+ * @param {string} [opts.model]   - Model id (default: gpt-4o)
+ * @param {string} [opts.baseUrl] - OpenAI-compatible base URL
+ * @param {string} [opts.apiKey]  - API key
+ * @param {number} [opts.maxTokens=600]
+ * @returns {Promise<{ summary: string, model: string, elapsedMs: number, usage?: object }>}
+ */
+export async function aiDiffSummary(opts) {
+  if (!opts.refPath || !opts.curPath) throw new Error("aiDiffSummary: refPath and curPath required");
+  if (!existsSync(opts.refPath)) throw new Error(`aiDiffSummary: ref not found: ${opts.refPath}`);
+  if (!existsSync(opts.curPath)) throw new Error(`aiDiffSummary: cur not found: ${opts.curPath}`);
+
+  const baseUrl = (opts.baseUrl || _defaultBase()).replace(/\/+$/, "");
+  const apiKey = opts.apiKey || _defaultKey();
+  const model = opts.model || _defaultModel();
+  if (!apiKey) {
+    throw new Error("aiDiffSummary: no API key. Set PURSOR_AI_API_KEY, ANTHROPIC_AUTH_TOKEN, or OPENAI_API_KEY.");
+  }
+
+  const refB64 = readFileSync(opts.refPath).toString("base64");
+  const curB64 = readFileSync(opts.curPath).toString("base64");
+  const userText = opts.url
+    ? `URL: ${opts.url}\n\nCompare these two screenshots of the same page (reference first, current second). Describe the visual differences.`
+    : `Compare these two screenshots (reference first, current second). Describe the visual differences.`;
+
+  const body = {
+    model,
+    max_tokens: opts.maxTokens || 600,
+    temperature: 0.2,
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "REFERENCE:" },
+          { type: "image_url", image_url: { url: `data:image/png;base64,${refB64}` } },
+          { type: "text", text: "CURRENT:" },
+          { type: "image_url", image_url: { url: `data:image/png;base64,${curB64}` } },
+          { type: "text", text: userText },
+        ],
+      },
+    ],
+  };
+
+  const t0 = Date.now();
+  const res = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => "");
+    throw new Error(`aiDiffSummary: ${res.status} ${res.statusText} - ${errText.slice(0, 300)}`);
+  }
+  const data = await res.json();
+  const summary = data.choices?.[0]?.message?.content?.trim() || "(empty response)";
+  return {
+    summary,
+    model,
+    elapsedMs: Date.now() - t0,
+    usage: data.usage,
+  };
+}
+
+/**
+ * Compare two PNGs and return a JSON-friendly object suitable for embedding
+ * in a sweep step's meta sidecar.
+ */
+export async function aiDiffSidecar(opts) {
+  const r = await aiDiffSummary(opts);
+  return {
+    aiSummary: r.summary,
+    aiModel: r.model,
+    aiElapsedMs: r.elapsedMs,
+    aiAt: new Date().toISOString(),
+  };
+}

package/src/diff.js

@@ -1,48 +1,76 @@
-// Pixelmatch diff against a reference PNG.
-
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
-import { gotoOrThrow, settle } from "./overlays.js";
-import { requireArg } from "./util.js";
-
-const DIFF_DEFAULT_THRESHOLD = 0.1;
-
-async function loadPngjs() {
-  try { return (await import("pngjs")).PNG; }
-  catch { throw new Error("pngjs not found. Install: npm i pngjs"); }
-}
-
-async function loadPixelmatch() {
-  try { return (await import("pixelmatch")).default; }
-  catch { throw new Error("pixelmatch not found. Install: npm i pixelmatch"); }
-}
-
-export async function runDiff(url, refPath, out, threshold, browser) {
-  requireArg("url", url, "string");
-  requireArg("refPath", refPath, "string");
-  const t = threshold !== undefined ? Number(threshold) : DIFF_DEFAULT_THRESHOLD;
-  if (!existsSync(refPath)) return { url, refPath, error: "reference file not found" };
-  const PNG = await loadPngjs();
-  const pixelmatch = await loadPixelmatch();
-  const ownBrowser = !browser;
-  browser = browser || await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
-    const r = await gotoOrThrow(page, url); await settle(page);
-    const currentPath = out ? out.replace(/\.png$/i, "-current.png") : join(dirname(refPath), "current.png");
-    await page.screenshot({ path: currentPath, fullPage: false });
-    const refPng = PNG.sync.read(readFileSync(refPath));
-    const curPng = PNG.sync.read(readFileSync(currentPath));
-    if (refPng.width !== curPng.width || refPng.height !== curPng.height) {
-      return { ...r, url, refPath, currentPath, error: "size mismatch", refSize: { w: refPng.width, h: refPng.height }, currentSize: { w: curPng.width, h: curPng.height } };
-    }
-    const diffPng = new PNG({ width: refPng.width, height: refPng.height });
-    const numDiff = pixelmatch(refPng.data, curPng.data, diffPng.data, refPng.width, refPng.height, { threshold: t });
-    const totalPx = refPng.width * refPng.height;
-    const diffPct = (numDiff / totalPx) * 100;
-    if (out) writeFileSync(out, PNG.sync.write(diffPng));
-    return { ...r, url, refPath, currentPath, out: out || null, threshold: t, refSize: { w: refPng.width, h: refPng.height }, totalPx, numDiff, diffPct: Number(diffPct.toFixed(3)), equal: numDiff === 0 };
-  } finally { if (ownBrowser) try { await browser.close(); } catch {} }
-}
+// Pixelmatch diff against a reference PNG.
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { launch, newPage } from "./runway.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { gotoOrThrow, settle } from "./overlays.js";
+import { requireArg } from "./util.js";
+import { aiDiffSidecar } from "./ai-diff.js";
+
+const DIFF_DEFAULT_THRESHOLD = 0.1;
+
+async function loadPngjs() {
+  try { return (await import("pngjs")).PNG; }
+  catch { throw new Error("pngjs not found. Install: npm i pngjs"); }
+}
+
+async function loadPixelmatch() {
+  try { return (await import("pixelmatch")).default; }
+  catch { throw new Error("pixelmatch not found. Install: npm i pixelmatch"); }
+}
+
+export async function runDiff(url, refPath, out, threshold, browser) {
+  requireArg("url", url, "string");
+  requireArg("refPath", refPath, "string");
+  const t = threshold !== undefined ? Number(threshold) : DIFF_DEFAULT_THRESHOLD;
+  if (!existsSync(refPath)) return { url, refPath, error: "reference file not found" };
+  const PNG = await loadPngjs();
+  const pixelmatch = await loadPixelmatch();
+  const ownBrowser = !browser;
+  browser = browser || await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const currentPath = out ? out.replace(/\.png$/i, "-current.png") : join(dirname(refPath), "current.png");
+    await page.screenshot({ path: currentPath, fullPage: false });
+    const refPng = PNG.sync.read(readFileSync(refPath));
+    const curPng = PNG.sync.read(readFileSync(currentPath));
+    if (refPng.width !== curPng.width || refPng.height !== curPng.height) {
+      return { ...r, url, refPath, currentPath, error: "size mismatch", refSize: { w: refPng.width, h: refPng.height }, currentSize: { w: curPng.width, h: curPng.height } };
+    }
+    const diffPng = new PNG({ width: refPng.width, height: refPng.height });
+    const numDiff = pixelmatch(refPng.data, curPng.data, diffPng.data, refPng.width, refPng.height, { threshold: t });
+    const totalPx = refPng.width * refPng.height;
+    const diffPct = (numDiff / totalPx) * 100;
+    if (out) writeFileSync(out, PNG.sync.write(diffPng));
+    return { ...r, url, refPath, currentPath, out: out || null, threshold: t, refSize: { w: refPng.width, h: refPng.height }, totalPx, numDiff, diffPct: Number(diffPct.toFixed(3)), equal: numDiff === 0 };
+  } finally { if (ownBrowser) try { await browser.close(); } catch {} }
+}
+
+/**
+ * Like runDiff, but additionally calls a vision LLM to produce a human-readable
+ * summary of the visual differences. The AI summary is written to <out>.ai.json
+ * and also returned on the result object.
+ */
+export async function runDiffWithAi(url, refPath, out, threshold, aiOpts, browser) {
+  const r = await runDiff(url, refPath, out, threshold, browser);
+  if (r.error) return r;
+  try {
+    const curPath = r.currentPath;
+    const sidecar = await aiDiffSidecar({
+      refPath, curPath, url,
+      model: aiOpts && aiOpts.model,
+      baseUrl: aiOpts && aiOpts.baseUrl,
+      apiKey: aiOpts && aiOpts.apiKey,
+      maxTokens: aiOpts && aiOpts.maxTokens,
+    });
+    r.ai = sidecar;
+    const sidecarPath = (out || curPath).replace(/.png$/i, "") + ".ai.json";
+    fs.writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2), "utf8");
+    r.aiFile = sidecarPath;
+  } catch (e) {
+    r.ai = { error: e.message };
+  }
+  return r;
+}

package/src/index.js

@@ -17,7 +17,7 @@ import { runSweep } from "./sweep.js";
 import { runEveryViewport } from "./every-viewport.js";
 import { runFrames } from "./frames.js";
 import { runHover } from "./hover.js";
-import { runDiff } from "./diff.js";
+import { runDiff, runDiffWithAi } from "./diff.js";
 import { runProbe } from "./probe.js";
 import { runShot } from "./shot.js";
 import { runEval } from "./eval.js";
@@ -39,6 +39,10 @@ import { validateSweepPlan, registerSweepOp } from "./sweep-schema.js";
 import { listResources, readResource, recordResource } from "./mcp-resources.js";
 import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
 import { saveAuthState, loadAuthState, listAuthStates, deleteAuthState } from "./auth.js";
+import { startWatch, matchGlob, shouldFire } from "./watch.js";
+import { runSnap, approveSnapsAsBaselines } from "./snap.js";
+import { renderSweepPdf } from "./report.js";
+import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
 
 
 // Derive VERSION from package.json to prevent drift
@@ -72,6 +76,13 @@ export {
   // v5: HAR capture, auth state, parallel sweep
   startHarCapture, stopHarCapture, writeHar,
   saveAuthState, loadAuthState, listAuthStates, deleteAuthState,
+  // v6: watch mode, component snapshot
+  startWatch, matchGlob, shouldFire,
+  runSnap, approveSnapsAsBaselines,
+  // v6: PDF report, AI diff summary
+  runDiffWithAi,
+  renderSweepPdf,
+  aiDiffSummary, aiDiffSidecar,
   VERSION,
 };
 
@@ -91,5 +102,7 @@ export default {
   saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
   validateSweepPlan, registerSweepOp,
   listResources, readResource, recordResource,
+  // v6: PDF report, AI diff summary
+  runDiffWithAi, renderSweepPdf, aiDiffSummary, aiDiffSidecar,
   VERSION,
 };