pursr 0.6.0 → 0.7.1

package/src/baseline.js

@@ -1,126 +1,127 @@
-// pursor — baseline storage for visual regression.
-//
-// Baselines live under $PURSOR_BASELINES_DIR || ~/.pursor/baselines/<project>/
-// Each baseline is keyed by a stable id derived from the URL + viewport +
-// flag set (a short hash), so re-running a sweep deterministically points
-// to the same baseline slot.
-//
-// Layout:
-//   ~/.pursor/baselines/<project>/<id>/<step>.png
-//   ~/.pursor/baselines/<project>/<id>/manifest.json   (url, viewport, flags, ts)
-//
-// Public API:
-//   resolveBaselinePath({ project, id, step }) -> { dir, file, manifest? }
-//   saveBaseline({ project, id, step, png, meta }) -> manifest path
-//   loadBaseline({ project, id, step }) -> { png, manifest } | null
-//   listBaselines(project) -> [{ id, step, ts, url }]
-//   approveBaseline({ project, id, step, fromPng }) -> manifest path
-//   diffKey({ url, viewport, flags }) -> string  (stable id)
-//
-// CLI subcommands added: pursor baseline save/approve/list/diff-key
-
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
-import { join, dirname, basename } from "node:path";
-import { homedir } from "node:os";
-import { createHash } from "node:crypto";
-import { shortHash, nowIso } from "./util.js";
-
-function baseDir(project) {
-  const root = process.env.PURSOR_BASELINES_DIR || join(homedir(), ".pursor", "baselines");
-  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
-  return join(root, proj);
-}
-
-export function diffKey({ url = "", viewport = {}, flags = {} } = {}) {
-  // Stable hash: project-agnostic, viewport+flag+url sensitive.
-  const v = `${viewport.width || 0}x${viewport.height || 0}@${viewport.dpr || 1}${viewport.name ? ":" + viewport.name : ""}`;
-  const fl = Object.keys(flags).sort().filter(k => k !== "out").map(k => `${k}=${flags[k]}`).join("&");
-  const src = `${url}|${v}|${fl}`;
-  return createHash("sha1").update(src).digest("hex").slice(0, 16);
-}
-
-export function resolveBaselinePath({ project, id, step }) {
-  const dir = join(baseDir(project), id);
-  const file = join(dir, `${String(step).replace(/[^a-z0-9._-]+/gi, "_")}.png`);
-  const manifestPath = join(dir, "manifest.json");
-  return { dir, file, manifestPath, manifest: existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null };
-}
-
-export function saveBaseline({ project, id, step, png, meta }) {
-  if (!png) throw new Error("saveBaseline: missing png path");
-  if (!existsSync(png)) throw new Error(`saveBaseline: png not found: ${png}`);
-  const { dir, file, manifestPath } = resolveBaselinePath({ project, id, step });
-  mkdirSync(dir, { recursive: true });
-  // Copy file (renameSync would also work but keep semantics explicit)
-  const buf = readFileSync(png);
-  writeFileSync(file, buf);
-  const manifest = {
-    project: project || "default",
-    id,
-    step: String(step),
-    file,
-    size: buf.length,
-    sha1: createHash("sha1").update(buf).digest("hex").slice(0, 16),
-    url: meta?.url || null,
-    viewport: meta?.viewport || null,
-    flags: meta?.flags || null,
-    ts: nowIso(),
-  };
-  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-  return { ...manifest, manifestPath };
-}
-
-export function loadBaseline({ project, id, step }) {
-  const { file, manifest } = resolveBaselinePath({ project, id, step });
-  if (!existsSync(file)) return null;
-  return {
-    png: file,
-    size: statSync(file).size,
-    hash: shortHash(readFileSync(file)),
-    manifest: manifest || null,
-  };
-}
-
-export function listBaselines(project) {
-  const root = baseDir(project);
-  if (!existsSync(root)) return [];
-  const out = [];
-  for (const id of readdirSync(root)) {
-    const dir = join(root, id);
-    if (!statSync(dir).isDirectory()) continue;
-    const manifestPath = join(dir, "manifest.json");
-    const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null;
-    if (!manifest) continue;
-    out.push({
-      id,
-      step: manifest.step,
-      url: manifest.url,
-      ts: manifest.ts,
-      sha1: manifest.sha1,
-    });
-  }
-  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
-}
-
-export function approveBaseline({ project, id, step, fromPng }) {
-  if (!fromPng) throw new Error("approveBaseline: missing fromPng");
-  if (!existsSync(fromPng)) throw new Error(`approveBaseline: fromPng not found: ${fromPng}`);
-  const buf = readFileSync(fromPng);
-  const { file, dir, manifestPath } = resolveBaselinePath({ project, id, step });
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(file, buf);
-  const prev = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : {};
-  const manifest = {
-    ...prev,
-    project: project || prev.project || "default",
-    id,
-    step: String(step),
-    file,
-    size: buf.length,
-    sha1: createHash("sha1").update(buf).digest("hex").slice(0, 16),
-    ts: nowIso(),
-    approvedFrom: fromPng,
-  };
-  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-  return manifest;
+//  pursr — baseline storage for visual regression.
+//
+// Baselines live under $PURSR_BASELINES_DIR || ~/./baselines/<project>/
+// Each baseline is keyed by a stable id derived from the URL + viewport +
+// flag set (a short hash), so re-running a sweep deterministically points
+// to the same baseline slot.
+//
+// Layout:
+//   ~/.pursr/baselines/<project>/<id>/<step>.png
+//   ~/.pursr/baselines/<project>/<id>/manifest.json   (url, viewport, flags, ts)
+//
+// Public API:
+//   resolveBaselinePath({ project, id, step }) -> { dir, file, manifest? }
+//   saveBaseline({ project, id, step, png, meta }) -> manifest path
+//   loadBaseline({ project, id, step }) -> { png, manifest } | null
+//   listBaselines(project) -> [{ id, step, ts, url }]
+//   approveBaseline({ project, id, step, fromPng }) -> manifest path
+//   diffKey({ url, viewport, flags }) -> string  (stable id)
+//
+// CLI subcommands added:  baseline save/approve/list/diff-key
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { shortHash, nowIso } from "./util.js";
+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, "_");
+  return join(root, proj);
+}
+
+export function diffKey({ url = "", viewport = {}, flags = {} } = {}) {
+  // Stable hash: project-agnostic, viewport+flag+url sensitive.
+  const v = `${viewport.width || 0}x${viewport.height || 0}@${viewport.dpr || 1}${viewport.name ? ":" + viewport.name : ""}`;
+  const fl = Object.keys(flags).sort().filter(k => k !== "out").map(k => `${k}=${flags[k]}`).join("&");
+  const src = `${url}|${v}|${fl}`;
+  return createHash("sha1").update(src).digest("hex").slice(0, 16);
+}
+
+export function resolveBaselinePath({ project, id, step }) {
+  const dir = join(baseDir(project), id);
+  const file = join(dir, `${String(step).replace(/[^a-z0-9._-]+/gi, "_")}.png`);
+  const manifestPath = join(dir, "manifest.json");
+  return { dir, file, manifestPath, manifest: existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null };
+}
+
+export function saveBaseline({ project, id, step, png, meta }) {
+  if (!png) throw new Error("saveBaseline: missing png path");
+  if (!existsSync(png)) throw new Error(`saveBaseline: png not found: ${png}`);
+  const { dir, file, manifestPath } = resolveBaselinePath({ project, id, step });
+  mkdirSync(dir, { recursive: true });
+  // Copy file (renameSync would also work but keep semantics explicit)
+  const buf = readFileSync(png);
+  writeFileSync(file, buf);
+  const manifest = {
+    project: project || "default",
+    id,
+    step: String(step),
+    file,
+    size: buf.length,
+    sha1: createHash("sha1").update(buf).digest("hex").slice(0, 16),
+    url: meta?.url || null,
+    viewport: meta?.viewport || null,
+    flags: meta?.flags || null,
+    ts: nowIso(),
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return { ...manifest, manifestPath };
+}
+
+export function loadBaseline({ project, id, step }) {
+  const { file, manifest } = resolveBaselinePath({ project, id, step });
+  if (!existsSync(file)) return null;
+  return {
+    png: file,
+    size: statSync(file).size,
+    hash: shortHash(readFileSync(file)),
+    manifest: manifest || null,
+  };
+}
+
+export function listBaselines(project) {
+  const root = baseDir(project);
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const id of readdirSync(root)) {
+    const dir = join(root, id);
+    if (!statSync(dir).isDirectory()) continue;
+    const manifestPath = join(dir, "manifest.json");
+    const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null;
+    if (!manifest) continue;
+    out.push({
+      id,
+      step: manifest.step,
+      url: manifest.url,
+      ts: manifest.ts,
+      sha1: manifest.sha1,
+    });
+  }
+  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
+}
+
+export function approveBaseline({ project, id, step, fromPng }) {
+  if (!fromPng) throw new Error("approveBaseline: missing fromPng");
+  if (!existsSync(fromPng)) throw new Error(`approveBaseline: fromPng not found: ${fromPng}`);
+  const buf = readFileSync(fromPng);
+  const { file, dir, manifestPath } = resolveBaselinePath({ project, id, step });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, buf);
+  const prev = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : {};
+  const manifest = {
+    ...prev,
+    project: project || prev.project || "default",
+    id,
+    step: String(step),
+    file,
+    size: buf.length,
+    sha1: createHash("sha1").update(buf).digest("hex").slice(0, 16),
+    ts: nowIso(),
+    approvedFrom: fromPng,
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return manifest;
 }

package/src/ci-output.js

@@ -1,156 +1,156 @@
-// pursor — CI Output Formatters.
-//
-// Converts a sweep summary into:
-//   - JUnit XML  (sweep.junit.xml)  — CI pipeline integration
-//   - GitHub Actions annotations  (sweep.github.json)
-//   - Markdown summary            (sweep.md)
-//
-// Call writeCiOutput(summary) at the end of a sweep to write all three
-// sidecars alongside sweep.json.
-
-import { writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { escapeHtml } from "./util.js";
-
-// ─── JUnit XML ───────────────────────────────────────────────────────────
-// Produces a minimal JUnit-compatible XML that GitLab CI, Jenkins, CircleCI,
-// and other CI runners understand.
-
-function renderJUnitXml(summary) {
-  const { steps, name, ts, outDir } = summary;
-  const suiteName = escapeXml(name || "pursor-sweep");
-  const tests = steps.length;
-  const failures = steps.filter(s => !s.ok).length;
-  const time = (steps.reduce((s, t) => s + (t.ms || 0), 0) / 1000).toFixed(3);
-
-  const testcases = steps.map(s => {
-    const className = escapeXml(`${s.op || "step"}` || "unknown");
-    const testName = escapeXml(s.name || `step-${s.i}`);
-    const fileAttr = s.meta?.out ? ` file="${escapeXml(s.meta.out)}"` : "";
-    let extra = "";
-    if (!s.ok) {
-      const msg = escapeXml(s.error || "unknown error");
-      const meta = s.meta ? escapeXml(JSON.stringify(s.meta, null, 2).slice(0, 500)) : "";
-      extra = `\n      <failure message="${msg}">${meta ? `\n        <![CDATA[${meta}]]>\n      ` : ""}</failure>`;
-    }
-    return `    <testcase classname="${className}" name="${testName}" time="${((s.ms || 0) / 1000).toFixed(3)}"${fileAttr}>${extra}
-    </testcase>`;
-  }).join("\n");
-
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<testsuite name="${suiteName}" tests="${tests}" failures="${failures}" errors="0" time="${time}" timestamp="${escapeXml(summary.ts || "")}">
-${testcases}
-</testsuite>`;
-}
-
-function escapeXml(s) {
-  return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
-}
-
-// ─── GitHub Actions (JSON annotations) ───────────────────────────────────
-// Each annotation: { filename, fileLine, annotation_level, message, title }
-
-function renderGitHubAnnotations(summary) {
-  const annotations = [];
-  for (const s of summary.steps) {
-    if (s.ok) continue;
-    annotations.push({
-      filename: s.meta?.out || s.name || `step-${s.i}`,
-      fileLine: 1,
-      annotation_level: "failure",
-      title: `pursor: ${s.name || `step-${s.i}`}`,
-      message: s.error || "Step failed",
-      raw_details: s.meta ? JSON.stringify(s.meta) : "",
-    });
-  }
-  // Also add warnings for diffs with high diffPct
-  for (const s of summary.steps) {
-    if (s.ok && s.meta?.numDiff > 0 && s.meta?.diffPct > 1) {
-      annotations.push({
-        filename: s.meta.out || s.name || `step-${s.i}`,
-        fileLine: 1,
-        annotation_level: "warning",
-        title: `pursor: diff > 1%`,
-        message: `${s.name}: ${s.meta.diffPct}% pixels differ from reference`,
-        raw_details: JSON.stringify(s.meta),
-      });
-    }
-  }
-  return { annotations };
-}
-
-// ─── Markdown Summary ────────────────────────────────────────────────────
-
-function renderMarkdownSummary(summary) {
-  const lines = [
-    `# pursor Sweep: ${summary.name || "(unnamed)"}`,
-    ``,
-    `**Plan:** \`${summary.plan || "?"}\``,
-    `**Date:** ${summary.ts || "?"}`,
-    `**Steps:** ${summary.steps.length}`,
-    ``,
-    `## Results`,
-    ``,
-    `| # | Name | Op | Status | Time |`,
-    `|---|------|----|--------|------|`,
-  ];
-
-  for (const s of summary.steps) {
-    const status = s.ok ? "✅ OK" : "❌ FAIL";
-    const time = `${s.ms || 0}ms`;
-    lines.push(`| ${s.i} | ${escapeMd(s.name || "")} | \`${s.op || ""}\` | ${status} | ${time} |`);
-  }
-
-  // Failures detail
-  const failed = summary.steps.filter(s => !s.ok);
-  if (failed.length) {
-    lines.push(``, `## Failures`, ``);
-    for (const s of failed) {
-      lines.push(`### ${s.i}. ${s.name || "unknown"}`);
-      lines.push(``);
-      lines.push(`**Error:** \`${escapeMd(s.error || "unknown")}\``);
-      if (s.meta?.out) lines.push(`**Output:** \`${s.meta.out}\``);
-      lines.push(``);
-    }
-  }
-
-  // Diffs with non-zero diff
-  const diffs = summary.steps.filter(s => s.ok && s.meta?.numDiff > 0);
-  if (diffs.length) {
-    lines.push(``, `## Diffs`, ``);
-    for (const s of diffs) {
-      lines.push(`| ${s.name} | ${s.meta.diffPct}% | ${s.meta.numDiff}/${s.meta.totalPx} pixels |`);
-    }
-    lines.push(``);
-  }
-
-  lines.push(`_Generated by pursor_`);
-  return lines.join("\n");
-}
-
-function escapeMd(s) {
-  return String(s ?? "").replace(/([_*[\]()~`>#+\-=|{}!.])/g, "\\$1");
-}
-
-// ─── Writer ──────────────────────────────────────────────────────────────
-
-/**
- * Write CI-format output files alongside the sweep summary.
- *
- * @param {object} summary - Sweep summary object from runSweep()
- * @param {string} dir     - Output directory (same as sweep.json)
- * @returns {{ junit: string, github: string, markdown: string }} Written paths
- */
-export function writeCiOutput(summary, dir) {
-  if (!dir) dir = summary.outDir || ".";
-  mkdirSync(dir, { recursive: true });
-  const junitPath = join(dir, "sweep.junit.xml");
-  const githubPath = join(dir, "sweep.github.json");
-  const mdPath = join(dir, "sweep.md");
-
-  writeFileSync(junitPath, renderJUnitXml(summary), "utf8");
-  writeFileSync(githubPath, JSON.stringify(renderGitHubAnnotations(summary), null, 2), "utf8");
-  writeFileSync(mdPath, renderMarkdownSummary(summary), "utf8");
-
-  return { junit: junitPath, github: githubPath, markdown: mdPath };
-}
+//  pursr — CI Output Formatters.
+//
+// Converts a sweep summary into:
+//   pursr - JUnit XML  (sweep.junit.xml)  — CI pipeline integration
+//   pursr - GitHub Actions annotations  (sweep.github.json)
+//   pursr - Markdown summary            (sweep.md)
+//
+// Call writeCiOutput(summary) at the end of a sweep to write all three
+// sidecars alongside sweep.json.
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { escapeHtml } from "./util.js";
+
+// ─── JUnit XML ───────────────────────────────────────────────────────────
+// Produces a minimal JUnit-compatible XML that GitLab CI, Jenkins, CircleCI,
+// and other CI runners understand.
+
+function renderJUnitXml(summary) {
+  const { steps, name, ts, outDir } = summary;
+  const suiteName = escapeXml(name || "pursr-sweep");
+  const tests = steps.length;
+  const failures = steps.filter(s => !s.ok).length;
+  const time = (steps.reduce((s, t) => s + (t.ms || 0), 0) / 1000).toFixed(3);
+
+  const testcases = steps.map(s => {
+    const className = escapeXml(`${s.op || "step"}` || "unknown");
+    const testName = escapeXml(s.name || `step-${s.i}`);
+    const fileAttr = s.meta?.out ? ` file="${escapeXml(s.meta.out)}"` : "";
+    let extra = "";
+    if (!s.ok) {
+      const msg = escapeXml(s.error || "unknown error");
+      const meta = s.meta ? escapeXml(JSON.stringify(s.meta, null, 2).slice(0, 500)) : "";
+      extra = `\n      <failure message="${msg}">${meta ? `\n        <![CDATA[${meta}]]>\n      ` : ""}</failure>`;
+    }
+    return `    <testcase classname="${className}" name="${testName}" time="${((s.ms || 0) / 1000).toFixed(3)}"${fileAttr}>${extra}
+    </testcase>`;
+  }).join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuite name="${suiteName}" tests="${tests}" failures="${failures}" errors="0" time="${time}" timestamp="${escapeXml(summary.ts || "")}">
+${testcases}
+</testsuite>`;
+}
+
+function escapeXml(s) {
+  return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+// ─── GitHub Actions (JSON annotations) ───────────────────────────────────
+// Each annotation: { filename, fileLine, annotation_level, message, title }
+
+function renderGitHubAnnotations(summary) {
+  const annotations = [];
+  for (const s of summary.steps) {
+    if (s.ok) continue;
+    annotations.push({
+      filename: s.meta?.out || s.name || `step-${s.i}`,
+      fileLine: 1,
+      annotation_level: "failure",
+      title: `pursr: ${s.name || `step-${s.i}`}`,
+      message: s.error || "Step failed",
+      raw_details: s.meta ? JSON.stringify(s.meta) : "",
+    });
+  }
+  // Also add warnings for diffs with high diffPct
+  for (const s of summary.steps) {
+    if (s.ok && s.meta?.numDiff > 0 && s.meta?.diffPct > 1) {
+      annotations.push({
+        filename: s.meta.out || s.name || `step-${s.i}`,
+        fileLine: 1,
+        annotation_level: "warning",
+        title: `pursr: diff > 1%`,
+        message: `${s.name}: ${s.meta.diffPct}% pixels differ from reference`,
+        raw_details: JSON.stringify(s.meta),
+      });
+    }
+  }
+  return { annotations };
+}
+
+// ─── Markdown Summary ────────────────────────────────────────────────────
+
+function renderMarkdownSummary(summary) {
+  const lines = [
+    `# pursr Sweep: ${summary.name || "(unnamed)"}`,
+    ``,
+    `**Plan:** \`${summary.plan || "?"}\``,
+    `**Date:** ${summary.ts || "?"}`,
+    `**Steps:** ${summary.steps.length}`,
+    ``,
+    `## Results`,
+    ``,
+    `| # | Name | Op | Status | Time |`,
+    `|---|------|----|--------|------|`,
+  ];
+
+  for (const s of summary.steps) {
+    const status = s.ok ? "✅ OK" : "❌ FAIL";
+    const time = `${s.ms || 0}ms`;
+    lines.push(`| ${s.i} | ${escapeMd(s.name || "")} | \`${s.op || ""}\` | ${status} | ${time} |`);
+  }
+
+  // Failures detail
+  const failed = summary.steps.filter(s => !s.ok);
+  if (failed.length) {
+    lines.push(``, `## Failures`, ``);
+    for (const s of failed) {
+      lines.push(`### ${s.i}. ${s.name || "unknown"}`);
+      lines.push(``);
+      lines.push(`**Error:** \`${escapeMd(s.error || "unknown")}\``);
+      if (s.meta?.out) lines.push(`**Output:** \`${s.meta.out}\``);
+      lines.push(``);
+    }
+  }
+
+  // Diffs with non-zero diff
+  const diffs = summary.steps.filter(s => s.ok && s.meta?.numDiff > 0);
+  if (diffs.length) {
+    lines.push(``, `## Diffs`, ``);
+    for (const s of diffs) {
+      lines.push(`| ${s.name} | ${s.meta.diffPct}% | ${s.meta.numDiff}/${s.meta.totalPx} pixels |`);
+    }
+    lines.push(``);
+  }
+
+  lines.push(`_Generated by pursr_`);
+  return lines.join("\n");
+}
+
+function escapeMd(s) {
+  return String(s ?? "").replace(/([_*[\]()~`>#+\-=|{}!.])/g, "\\$1");
+}
+
+// ─── Writer ──────────────────────────────────────────────────────────────
+
+/**
+ * Write CI-format output files alongside the sweep summary.
+ *
+ * @param {object} summary - Sweep summary object from runSweep()
+ * @param {string} dir     - Output directory (same as sweep.json)
+ * @returns {{ junit: string, github: string, markdown: string }} Written paths
+ */
+export function writeCiOutput(summary, dir) {
+  if (!dir) dir = summary.outDir || ".";
+  mkdirSync(dir, { recursive: true });
+  const junitPath = join(dir, "sweep.junit.xml");
+  const githubPath = join(dir, "sweep.github.json");
+  const mdPath = join(dir, "sweep.md");
+
+  writeFileSync(junitPath, renderJUnitXml(summary), "utf8");
+  writeFileSync(githubPath, JSON.stringify(renderGitHubAnnotations(summary), null, 2), "utf8");
+  writeFileSync(mdPath, renderMarkdownSummary(summary), "utf8");
+
+  return { junit: junitPath, github: githubPath, markdown: mdPath };
+}

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;