pursr 0.7.0 → 0.7.2

package/bin/pursr.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // pursr CLI. Thin wrapper around src/* that mirrors the npm bin.
 
 import { VERSION } from "../src/index.js";
@@ -79,14 +79,15 @@ await loadPlugins(pluginPaths);
       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 flags = parseFlags(argv.slice(5));
         // --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);
+          ? await runDiffWithAi(url, ref, out, threshold, flags, { model: aiModel, baseUrl: aiBaseUrl, apiKey: aiApiKey })
+          : await runDiff(url, ref, out, threshold, flags);
         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; }
@@ -204,6 +205,12 @@ await loadPlugins(pluginPaths);
           let meta = null;
           if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
           else if (flags.url) meta = { url: flags.url };
+          else {
+            const sidecar = png.replace(/\.png$/i, ".json");
+            if (existsSync(sidecar)) {
+              try { meta = JSON.parse(readFile(sidecar, "utf8")); } catch { meta = null; }
+            }
+          }
           const id = flags.id || diffKey({ url: meta?.url || "", viewport: meta?.viewport, flags: meta?.flags || {} });
           const result = saveBaseline({ project, id, step, png, meta });
           console.log(JSON.stringify({ saved: true, ...result }, null, 2));
@@ -317,6 +324,18 @@ await loadPlugins(pluginPaths);
               }
               break;
             }
+            case "check": {
+              // pursr check <url> [--preset <name>] [--update] [--json] [--threshold 0.1] [--out <diff.png>]
+              if (!url) die("check: missing <url>");
+              const flags = parseFlags(argv.slice(4));
+              const update = !!flags.update;
+              const threshold = flags.threshold !== undefined ? Number(flags.threshold) : 0.1;
+              const { runCheck } = await import("../src/check.js");
+              const r = await runCheck({ url, flags, threshold, update, out: flags.out || null });
+              if (flags.json) console.log(JSON.stringify(r, null, 2));
+              else console.log(JSON.stringify(r, null, 2));
+              process.exit(r.exitCode || 0);
+            }
             default: { die(`unknown subcommand: ${cmd}`); }
     }
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "private": false,
   "description": "pursr — 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",

package/src/baseline.js

@@ -28,7 +28,8 @@ import { __PURSR_GET } from "./util.js";
 
 function baseDir(project) {
   const root = __PURSR_GET("PURSR_BASELINES_DIR") || join(homedir(), ".pursr", "baselines");
-  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  // Normalize: strip trailing slashes so "http://x/" and "http://x" map to the same folder.
+  const proj = String(project || "default").replace(/\/+$/, "").replace(/[^a-zA-Z0-9._-]+/g, "_") || "default";
   return join(root, proj);
 }
 

package/src/check.js

@@ -0,0 +1,77 @@
+//  pursr — CI-friendly visual regression check.
+//
+// Renders a URL at a given (url + viewport + flags) and diffs it against the
+// stored baseline (identified by the same diffKey). Exits 0 if equal, 1 if
+// different, 2 if no baseline.
+
+import { resolveViewport } from "./viewport.js";
+import { diffKey, loadBaseline, approveBaseline } from "./baseline.js";
+import { runDiff } from "./diff.js";
+import { makeOut, nowIso } from "./util.js";
+
+export async function runCheck({ url, flags = {}, project = null, threshold = 0.1, update = false, out = null, baselineStep = "default" }) {
+  if (!url) throw new Error("runCheck: missing url");
+  // Strip action-only flags that don't affect rendering. If they were part of the
+  // diffKey, the same URL+preset combo would hash differently depending on which
+  // CLI flags the user passed, which is wrong.
+  const renderFlags = {};
+  for (const [k, v] of Object.entries(flags || {})) {
+    if (k === "update" || k === "threshold" || k === "out" || k === "json" || k === "project") continue;
+    renderFlags[k] = v;
+  }
+  const viewport = resolveViewport(renderFlags);
+  const id = diffKey({ url, viewport, flags: renderFlags });
+  let proj = project;
+  if (!proj) {
+    try { const u = new URL(url); proj = u.origin + (u.pathname === "/" ? "/" : u.pathname.replace(/\/$/, "")); }
+    catch { proj = url; }
+  }
+  const loaded = loadBaseline({ project: proj, id, step: baselineStep });
+  if (!loaded) {
+    return {
+      url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+      status: "no-baseline",
+      exitCode: 2,
+      ts: nowIso(),
+      hint: "No baseline found. Run `pursr shoot " + url + " --save-baseline` first, or `pursr check " + url + " --update` to capture the current render as the new baseline.",
+    };
+  }
+  const diffOut = out || makeOut("check-diff.png");
+  const result = await runDiff(url, loaded.png, diffOut, threshold, flags);
+  if (result.error === "size mismatch") {
+    return {
+      url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+      refPng: loaded.png, currentPath: result.currentPath, out: diffOut,
+      status: "size-mismatch",
+      equal: false,
+      refSize: result.refSize, currentSize: result.currentSize,
+      exitCode: 1,
+      ts: nowIso(),
+      hint: "Reference baseline is " + result.refSize.w + "x" + result.refSize.h + " but current render is " + result.currentSize.w + "x" + result.currentSize.h + ". Re-baseline with the same viewport.",
+    };
+  }
+  if (update || result.numDiff === 0) {
+    const currentPng = result.currentPath;
+    const saved = (update || result.numDiff > 0) ? approveBaseline({ project: proj, id, step: baselineStep, fromPng: currentPng }) : null;
+    return {
+      url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+      refPng: loaded.png, currentPath: currentPng, out: diffOut,
+      refSize: result.refSize, totalPx: result.totalPx, numDiff: result.numDiff, diffPct: result.diffPct, threshold,
+      status: result.numDiff === 0 ? "equal" : "updated",
+      equal: result.numDiff === 0,
+      exitCode: 0,
+      saved: saved ? { ts: saved.ts, sha1: saved.sha1, approvedFrom: saved.approvedFrom } : null,
+      ts: nowIso(),
+    };
+  }
+  return {
+    url, flags, viewport, baselineKey: { project: proj, id, step: baselineStep },
+    refPng: loaded.png, currentPath: result.currentPath, out: diffOut,
+    refSize: result.refSize, totalPx: result.totalPx, numDiff: result.numDiff, diffPct: result.diffPct, threshold,
+    status: "differ",
+    equal: false,
+    exitCode: 1,
+    ts: nowIso(),
+    hint: "Differences detected (" + result.numDiff + " px, " + result.diffPct + "%). Run `pursr check " + url + " --update` to approve the current render as the new baseline.",
+  };
+}

package/src/diff.js

@@ -3,9 +3,9 @@
 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 { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle, applyCamera, waitForStableFrame } from "./overlays.js";
+import { asNum, requireArg } from "./util.js";
 import { aiDiffSidecar } from "./ai-diff.js";
 
 const DIFF_DEFAULT_THRESHOLD = 0.1;
@@ -20,7 +20,7 @@ async function loadPixelmatch() {
   catch { throw new Error("pixelmatch not found. Install: npm i pixelmatch"); }
 }
 
-export async function runDiff(url, refPath, out, threshold, browser) {
+export async function runDiff(url, refPath, out, threshold, flags = {}, browser) {
   requireArg("url", url, "string");
   requireArg("refPath", refPath, "string");
   const t = threshold !== undefined ? Number(threshold) : DIFF_DEFAULT_THRESHOLD;
@@ -28,10 +28,21 @@ export async function runDiff(url, refPath, out, threshold, browser) {
   const PNG = await loadPngjs();
   const pixelmatch = await loadPixelmatch();
   const ownBrowser = !browser;
+  const viewport = resolveViewport(flags || {});
   browser = browser || await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, viewport);
     const r = await gotoOrThrow(page, url); await settle(page);
+    if (flags && (flags["wait-frame"] || flags["no-animation"])) {
+      await waitForStableFrame(page, asNum(flags["wait-frame"], 600));
+    }
+    if (flags && (flags.zoom || flags.panX || flags.panY)) {
+      await applyCamera(page, {
+        zoom: asNum(flags.zoom, 1),
+        panX: asNum(flags.panX, 0),
+        panY: asNum(flags.panY, 0),
+      });
+    }
     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));
@@ -53,8 +64,8 @@ export async function runDiff(url, refPath, out, threshold, browser) {
  * 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);
+export async function runDiffWithAi(url, refPath, out, threshold, flags, aiOpts, browser) {
+  const r = await runDiff(url, refPath, out, threshold, flags, browser);
   if (r.error) return r;
   try {
     const curPath = r.currentPath;

package/src/index.js

@@ -41,6 +41,7 @@ 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 { runCheck } from "./check.js";
 import { renderSweepPdf } from "./report.js";
 import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
 
@@ -71,6 +72,8 @@ export {
   PursrMCPServer, loadMcpConfig, MCP_VERSION,
   // v4: baselines, sweep validation, MCP resources
   saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
+  // v0.7.2: CI visual regression check
+  runCheck,
   validateSweepPlan, registerSweepOp,
   listResources, readResource, recordResource,
   // v5: HAR capture, auth state, parallel sweep

package/src/mcp.js

@@ -7,13 +7,14 @@
 // Config via PURSR_MCP_CONFIG env or ~/./mcp-config.json:
 //   { "plugins": ["./my-plugin.js"], "defaultOutDir": "./mcp-output" }
 
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { __PURSR_GET } from "./util.js";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { runProbe } from "./probe.js";
 import { runShoot } from "./shoot.js";
 import { runDiff } from "./diff.js";
+import { runCheck } from "./check.js";
 import { runSweep } from "./sweep.js";
 import { runFrames } from "./frames.js";
 import { runShootWithSidecar } from "./shoot.js";
@@ -236,14 +237,28 @@ class PursrMCPServer {
       },
       {
         name: "pursr_diff",
-        description: "Pixel-diff a URL against a reference PNG. Returns diff stats and writes diff overlay image.",
+        description: "Pixel-diff a URL against a reference PNG. Honors the same viewport/camera/animation flags as pursr_shoot. Returns diff stats and writes diff overlay image.",
         inputSchema: {
           type: "object",
           properties: {
-            url:       { type: "string", description: "URL to capture" },
-            ref:       { type: "string", description: "Reference PNG path" },
-            out:       { type: "string", description: "Diff output PNG (auto-gen if omitted)" },
-            threshold: { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+            url:           { type: "string", description: "URL to capture" },
+            ref:           { type: "string", description: "Reference PNG path" },
+            out:           { type: "string", description: "Diff output PNG (auto-gen if omitted)" },
+            threshold:     { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+            preset:        { type: "string", description: "Viewport preset" },
+            width:         { type: "number", description: "Viewport width" },
+            height:        { type: "number", description: "Viewport height" },
+            dpr:           { type: "number", description: "Device pixel ratio" },
+            full:          { type: "boolean", description: "Full-page screenshot" },
+            cursor:        { type: "string", description: "Cursor: default|pointer|grab|grabbing|crosshair|none" },
+            grid:          { type: "boolean", description: "Overlay grid" },
+            zoom:          { type: "number", description: "Camera zoom" },
+            panX:          { type: "number", description: "Camera pan X (px)" },
+            panY:          { type: "number", description: "Camera pan Y (px)" },
+            "no-animation":{ type: "boolean", description: "Freeze CSS animations for a stable diff" },
+            "wait-frame": { type: "number", description: "Wait for stable canvas frame (ms)" },
+            "no-hud":     { type: "boolean", description: "Hide header/footer/nav elements" },
+            settleMs:      { type: "number", description: "Extra settle time before screenshot (ms, default 1200)" },
           },
           required: ["url", "ref"],
         },
@@ -311,6 +326,29 @@ class PursrMCPServer {
           required: ["url"],
         },
       },
+      {
+        name: "pursr_check",
+        description: "CI visual regression check. Renders a URL and diffs against the stored baseline. Exits 0 if equal, 1 if differs, 2 if no baseline. Use update:true to approve current as new baseline.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url:       { type: "string", description: "Target URL" },
+            preset:    { type: "string", description: "Viewport preset" },
+            width:     { type: "number", description: "Viewport width" },
+            height:    { type: "number", description: "Viewport height" },
+            dpr:       { type: "number", description: "Device pixel ratio" },
+            full:      { type: "boolean", description: "Full-page screenshot" },
+            zoom:      { type: "number", description: "Camera zoom" },
+            panX:      { type: "number", description: "Camera pan X" },
+            panY:      { type: "number", description: "Camera pan Y" },
+            threshold: { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+            update:    { type: "boolean", description: "Approve current render as the new baseline" },
+            out:       { type: "string", description: "Diff output PNG path" },
+            project:   { type: "string", description: "Project key (defaults to URL origin+path)" },
+          },
+          required: ["url"],
+        },
+      },
     ];
   }
 
@@ -325,6 +363,7 @@ class PursrMCPServer {
       case "pursr_probe":        return await this._probe(args);
       case "pursr_audit":        return await this._audit(args);
       case "pursr_dom_snapshot": return await this._domSnapshot(args);
+      case "pursr_check":        return await this._check(args);
       default: throw new McpError(-32602, `Unknown tool: ${name}`);
     }
   }
@@ -370,7 +409,11 @@ class PursrMCPServer {
     const out = args.out || ref.replace(/\.png$/i, "-diff.png");
     if (out) mkdirSync(dirname(out), { recursive: true });
     const threshold = args.threshold ?? 0.1;
-    const result = await runDiff(url, ref, out, threshold);
+    const flags = {};
+    for (const [k, v] of Object.entries(args)) {
+      if (k !== "url" && k !== "ref" && k !== "out" && k !== "threshold") flags[k] = v;
+    }
+    const result = await runDiff(url, ref, out, threshold, flags);
     return [{ type: "text", text: JSON.stringify(result, null, 2) }];
   }
 
@@ -432,6 +475,23 @@ class PursrMCPServer {
     const result = await captureDomSnapshot({ url: args.url, out });
     return [{ type: "text", text: JSON.stringify({ out, ...result }, null, 2) }];
   }
+
+  async _check(args) {
+    if (!args.url) throw new McpError(-32602, "Missing required: url");
+    const flags = {};
+    for (const [k, v] of Object.entries(args)) {
+      if (k !== "url" && k !== "threshold" && k !== "update" && k !== "out" && k !== "project") flags[k] = v;
+    }
+    const result = await runCheck({
+      url: args.url,
+      flags,
+      threshold: args.threshold ?? 0.1,
+      update: !!args.update,
+      out: args.out,
+      project: args.project || null,
+    });
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
 }
 
 export { PursrMCPServer, McpError, loadConfig, MCP_VERSION };

package/src/plugin-audit.js

@@ -10,6 +10,7 @@
 // Dependencies: axe-core (npm i axe-core)
 
 import { launch, newPage } from "./runway.js";
+import { createRequire } from "node:module";
 import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow, settle } from "./overlays.js";
 import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
@@ -87,11 +88,29 @@ let _axeSource = null;
 async function getAxeSource() {
   if (_axeSource) return _axeSource;
   // Try node_modules/axe-core
+  // Primary: use createRequire to resolve axe-core from this module (works for the
+  // pursr package itself, the linked repo, or any project that has axe-core installed).
+  try {
+    const req = createRequire(import.meta.url);
+    const resolved = req.resolve("axe-core");
+    const dir = resolved.replace(/[\\\/][^\\\/]+$/, "");
+    for (const fname of ["axe.min.js", "axe.js"]) {
+      const p = dir + "/" + fname;
+      if (existsSync(p)) { _axeSource = readFileSync(p, "utf8"); return _axeSource; }
+    }
+  } catch { /* fall through to path-based lookup */ }
   const paths = [
     join(process.cwd(), "node_modules", "axe-core", "axe.min.js"),
     join(process.cwd(), "node_modules", "axe-core", "axe.js"),
     new URL("..", import.meta.url).pathname && join(dirname(new URL(import.meta.url).pathname), "node_modules", "axe-core", "axe.min.js"),
     join(dirname(process.execPath), "node_modules", "axe-core", "axe.min.js"),
+    // Global npm install (Windows: %APPDATA%\npm\node_modules, Unix: /usr/lib/node_modules)
+    join(process.env.APPDATA || "", "npm", "node_modules", "axe-core", "axe.min.js"),
+    join(process.env.HOME || "", ".npm-global", "lib", "node_modules", "axe-core", "axe.min.js"),
+    join("/usr", "lib", "node_modules", "axe-core", "axe.min.js"),
+    join("/usr", "local", "lib", "node_modules", "axe-core", "axe.min.js"),
+    // The pursr package's own node_modules (when running from local repo or via node bin)
+    join(dirname(new URL(import.meta.url).pathname), "..", "node_modules", "axe-core", "axe.min.js"),
   ];
   for (const p of paths) {
     if (p && existsSync(p)) {
@@ -99,8 +118,7 @@ async function getAxeSource() {
       return _axeSource;
     }
   }
-  throw new Error("axe-core not found. Install: npm i axe-core");
-}
+throw new Error("axe-core not found. Install: npm i axe-core");}
 
 // ─── Group helper ───────────────────────────────────────────────────────