pursr 0.6.0 → 0.7.0

package/src/plugin.js

@@ -1,121 +1,121 @@
-// pursor — plugin API.
-//
-// A plugin is a plain ES module that exports a default object with one
-// or more hook handlers. The host loads plugins from:
-//   1. The built-in `plugins/` directory (shipped with the package).
-//   2. A path passed to `loadPlugins([...paths])`.
-//   3. Any package named `pursor-plugin-*` in node_modules.
-//
-// Hook reference:
-//
-//   name:        "my-plugin"  // optional, for logs
-//   viewport:    { <presetName>: { width, height, dpr, label } }
-//   sweepOp:     { <opName>: async (ctx, opts) => Result }
-//   beforeShoot: async (ctx) => void   // mutate ctx.flags / ctx.viewport
-//   afterShoot:  async (ctx, meta) => void  // augment sidecar
-//   flagHelp:    { "my-flag": "what it does" }
-//
-// ctx fields available to hooks:
-//   url, out, viewport, flags, browser, page
-//
-// Example plugin (plugins/my-plugin.js):
-//
-//   export default {
-//     name: "my-plugin",
-//     viewport: {
-//       "my-laptop": { width: 1440, height: 900, dpr: 2, label: "MBP 14" },
-//     },
-//     sweepOp: {
-//       "lighthouse": async (ctx, opts) => {
-//         // ... run lighthouse, return { out, meta }
-//       },
-//     },
-//     beforeShoot: async (ctx) => {
-//       // e.g. set extra cookies, click a button, etc.
-//     },
-//   };
-
-const plugins = [];
-const registeredRefs = new Set();
-const sweepOps = new Map();
-const viewportPresets = new Map();
-const flagHelp = new Map();
-
-export function registerPlugin(p) {
-  if (!p || typeof p !== "object") return;
-  if (registeredRefs.has(p)) return;
-  registeredRefs.add(p);
-  plugins.push(p);
-  if (p.name) console.error(`[pursor] loaded plugin: ${p.name}`);
-  if (p.viewport) {
-    for (const [k, v] of Object.entries(p.viewport)) viewportPresets.set(k, v);
-  }
-  if (p.sweepOp) {
-    for (const [k, v] of Object.entries(p.sweepOp)) sweepOps.set(k, v);
-  }
-  if (p.flagHelp) {
-    for (const [k, v] of Object.entries(p.flagHelp)) flagHelp.set(k, v);
-  }
-}
-
-export async function loadPlugins(paths = []) {
-  if (typeof paths === "string") paths = [paths];
-  const loadedPaths = new Set();
-  // auto-load built-in plugins from plugins/ directory
-  const { readdirSync, existsSync } = await import("node:fs");
-  const { join, dirname } = await import("node:path");
-  const { fileURLToPath, pathToFileURL } = await import("node:url");
-  const selfDir = dirname(fileURLToPath(import.meta.url));
-  const pluginDir = join(selfDir, "..", "plugins");
-  if (existsSync(pluginDir)) {
-    for (const f of readdirSync(pluginDir)) {
-      if (f.endsWith(".js")) {
-        const fullPath = pathToFileURL(join(pluginDir, f)).href;
-        if (loadedPaths.has(fullPath)) continue;
-        loadedPaths.add(fullPath);
-        try {
-          const mod = await import(/* @vite-ignore */ fullPath);
-          registerPlugin(mod.default || mod);
-        } catch (e) {
-          console.error(`[pursor] failed to load built-in plugin ${f}: ${e.message}`);
-        }
-      }
-    }
-  }
-  // user-supplied plugins — resolve relative to cwd
-  for (const p of paths) {
-    if (loadedPaths.has(p)) continue;
-    loadedPaths.add(p);
-    try {
-      const resolved = pathToFileURL(join(process.cwd(), p)).href;
-      const mod = await import(/* @vite-ignore */ resolved);
-      registerPlugin(mod.default || mod);
-    } catch (e) {
-      console.error(`[pursor] failed to load plugin ${p}: ${e.message}`);
-    }
-  }
-  return plugins.length;
-}
-
-export function listPlugins() { return plugins.map(p => p?.name || "(unnamed)"); }
-
-export function getSweepOp(name) { return sweepOps.get(name); }
-export function getViewportPreset(name) { return viewportPresets.get(name); }
-export function listViewportPresets() { return Object.fromEntries(viewportPresets); }
-export function getFlagHelp() { return Object.fromEntries(flagHelp); }
-
-export async function runBeforeShoot(ctx) {
-  for (const p of plugins) {
-    if (typeof p.beforeShoot === "function") {
-      try { await p.beforeShoot(ctx); } catch (e) { console.error(`[plugin ${p.name}] beforeShoot: ${e.message}`); }
-    }
-  }
-}
-
-export async function runAfterShoot(ctx, meta) {
-  for (const p of plugins) {
-    if (typeof p.afterShoot === "function") {
-      try { await p.afterShoot(ctx, meta); } catch (e) { console.error(`[plugin ${p.name}] afterShoot: ${e.message}`); }
-    }
-  }
+//  pursr — plugin API.
+//
+// A plugin is a plain ES module that exports a default object with one
+// or more hook handlers. The host loads plugins from:
+//   1. The built-in `plugins/` directory (shipped with the package).
+//   2. A path passed to `loadPlugins([...paths])`.
+//   3. Any package named `pursr-plugin-*` in node_modules.
+//
+// Hook reference:
+//
+//   name:        "my-plugin"  // optional, for logs
+//   viewport:    { <presetName>: { width, height, dpr, label } }
+//   sweepOp:     { <opName>: async (ctx, opts) => Result }
+//   beforeShoot: async (ctx) => void   // mutate ctx.flags / ctx.viewport
+//   afterShoot:  async (ctx, meta) => void  // augment sidecar
+//   flagHelp:    { "my-flag": "what it does" }
+//
+// ctx fields available to hooks:
+//   url, out, viewport, flags, browser, page
+//
+// Example plugin (plugins/my-plugin.js):
+//
+//   export default {
+//     name: "my-plugin",
+//     viewport: {
+//       "my-laptop": { width: 1440, height: 900, dpr: 2, label: "MBP 14" },
+//     },
+//     sweepOp: {
+//       "lighthouse": async (ctx, opts) => {
+//         // ... run lighthouse, return { out, meta }
+//       },
+//     },
+//     beforeShoot: async (ctx) => {
+//       // e.g. set extra cookies, click a button, etc.
+//     },
+//   };
+
+const plugins = [];
+const registeredRefs = new Set();
+const sweepOps = new Map();
+const viewportPresets = new Map();
+const flagHelp = new Map();
+
+export function registerPlugin(p) {
+  if (!p || typeof p !== "object") return;
+  if (registeredRefs.has(p)) return;
+  registeredRefs.add(p);
+  plugins.push(p);
+  if (p.name) console.error(`[pursr] loaded plugin: ${p.name}`);
+  if (p.viewport) {
+    for (const [k, v] of Object.entries(p.viewport)) viewportPresets.set(k, v);
+  }
+  if (p.sweepOp) {
+    for (const [k, v] of Object.entries(p.sweepOp)) sweepOps.set(k, v);
+  }
+  if (p.flagHelp) {
+    for (const [k, v] of Object.entries(p.flagHelp)) flagHelp.set(k, v);
+  }
+}
+
+export async function loadPlugins(paths = []) {
+  if (typeof paths === "string") paths = [paths];
+  const loadedPaths = new Set();
+  // auto-load built-in plugins from plugins/ directory
+  const { readdirSync, existsSync } = await import("node:fs");
+  const { join, dirname } = await import("node:path");
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+  const selfDir = dirname(fileURLToPath(import.meta.url));
+  const pluginDir = join(selfDir, "..", "plugins");
+  if (existsSync(pluginDir)) {
+    for (const f of readdirSync(pluginDir)) {
+      if (f.endsWith(".js")) {
+        const fullPath = pathToFileURL(join(pluginDir, f)).href;
+        if (loadedPaths.has(fullPath)) continue;
+        loadedPaths.add(fullPath);
+        try {
+          const mod = await import(/* @vite-ignore */ fullPath);
+          registerPlugin(mod.default || mod);
+        } catch (e) {
+          console.error(`[pursr] failed to load built-in plugin ${f}: ${e.message}`);
+        }
+      }
+    }
+  }
+  // user-supplied plugins — resolve relative to cwd
+  for (const p of paths) {
+    if (loadedPaths.has(p)) continue;
+    loadedPaths.add(p);
+    try {
+      const resolved = pathToFileURL(join(process.cwd(), p)).href;
+      const mod = await import(/* @vite-ignore */ resolved);
+      registerPlugin(mod.default || mod);
+    } catch (e) {
+      console.error(`[pursr] failed to load plugin ${p}: ${e.message}`);
+    }
+  }
+  return plugins.length;
+}
+
+export function listPlugins() { return plugins.map(p => p?.name || "(unnamed)"); }
+
+export function getSweepOp(name) { return sweepOps.get(name); }
+export function getViewportPreset(name) { return viewportPresets.get(name); }
+export function listViewportPresets() { return Object.fromEntries(viewportPresets); }
+export function getFlagHelp() { return Object.fromEntries(flagHelp); }
+
+export async function runBeforeShoot(ctx) {
+  for (const p of plugins) {
+    if (typeof p.beforeShoot === "function") {
+      try { await p.beforeShoot(ctx); } catch (e) { console.error(`[plugin ${p.name}] beforeShoot: ${e.message}`); }
+    }
+  }
+}
+
+export async function runAfterShoot(ctx, meta) {
+  for (const p of plugins) {
+    if (typeof p.afterShoot === "function") {
+      try { await p.afterShoot(ctx, meta); } catch (e) { console.error(`[plugin ${p.name}] afterShoot: ${e.message}`); }
+    }
+  }
 }

package/src/probe.js

@@ -1,20 +1,20 @@
-// Probe: open a viewport, navigate, return basic info. No screenshot.
-
-import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
-import { gotoOrThrow } from "./overlays.js";
-import { requireArg } from "./util.js";
-
-export async function runProbe(url) {
-  requireArg("url", url, "string");
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
-    let navError = null, status = null, title = null;
-    try {
-      const r = await gotoOrThrow(page, url);
-      status = r.status; title = r.title;
-    } catch (e) { navError = e.message; }
-    return { url, status, title, navError, viewport: DEFAULT_VIEWPORT };
-  } finally { try { await browser.close(); } catch {} }
+// Probe: open a viewport, navigate, return basic info. No screenshot.
+
+import { launch, newPage } from "./runway.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { gotoOrThrow } from "./overlays.js";
+import { requireArg } from "./util.js";
+
+export async function runProbe(url) {
+  requireArg("url", url, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    let navError = null, status = null, title = null;
+    try {
+      const r = await gotoOrThrow(page, url);
+      status = r.status; title = r.title;
+    } catch (e) { navError = e.message; }
+    return { url, status, title, navError, viewport: DEFAULT_VIEWPORT };
+  } finally { try { await browser.close(); } catch {} }
 }

package/src/report.js

@@ -1,176 +1,176 @@
-// pursor - PDF report generator.
-//
-// Renders a sweep summary into a styled, self-contained PDF report.
-// Embeds each capture (PNG) inline so the report can be emailed/shared
-// without any external assets.
-//
-// CLI:
-//   pursr report --sweep ./out/sweep-xxx/sweep.json --out ./out/report.pdf
-//   pursr sweep plan.json   # writes sweep.json + .html; PDF generated separately
-//
-// Library:
-//   import { renderSweepPdf } from "pursr/report";
-//   const bytes = await renderSweepPdf(summary, { out: "report.pdf" });
-
-import PDFDocument from "pdfkit";
-import { createReadStream, existsSync, statSync } from "node:fs";
-import { join, dirname, basename } from "node:path";
-import { writeFile } from "node:fs/promises";
-import { escapeHtml } from "./util.js";
-
-// A4 in points (1pt = 1/72 in)
-const PAGE_W = 595.28;
-const PAGE_H = 841.89;
-const MARGIN = 40;
-const CONTENT_W = PAGE_W - MARGIN * 2;
-
-/**
- * Render a sweep summary as a PDF.
- *
- * @param {object} summary       - Sweep summary from runSweep()
- * @param {object} [opts]
- * @param {string} [opts.out]    - Output PDF file path
- * @param {string} [opts.title]  - Report title (defaults to sweep.name)
- * @param {string} [opts.subtitle] - Subtitle
- * @param {boolean} [opts.embedImages=true] - Embed each capture PNG inline
- * @returns {Promise<Buffer>}   - PDF bytes (also written to opts.out if set)
- */
-export async function renderSweepPdf(summary, opts = {}) {
-  if (!summary || !Array.isArray(summary.steps)) {
-    throw new Error("renderSweepPdf: summary.steps must be an array");
-  }
-  const title = opts.title || `pursr sweep: ${summary.name || "(unnamed)"}`;
-  const subtitle = opts.subtitle || `${summary.steps.length} steps · ${summary.ts || ""} · ${summary.outDir || ""}`;
-  const embedImages = opts.embedImages !== false;
-
-  const doc = new PDFDocument({ size: "A4", margin: MARGIN, info: {
-    Title: title,
-    Author: "pursr",
-    Subject: "Visual sweep report",
-    CreationDate: new Date(),
-  }});
-
-  // Collect bytes
-  const chunks = [];
-  doc.on("data", (c) => chunks.push(c));
-  const done = new Promise((resolve, reject) => {
-    doc.on("end", () => resolve(Buffer.concat(chunks)));
-    doc.on("error", reject);
-  });
-
-  // ---- Header ----
-  doc.fillColor("#0B0B0F").rect(0, 0, PAGE_W, 80).fill();
-  doc.fillColor("#FF2EA6").fontSize(22).font("Helvetica-Bold").text("pursr", MARGIN, 30);
-  doc.fillColor("#FFFFFF").fontSize(14).font("Helvetica").text(title, MARGIN + 70, 36);
-  doc.fillColor("#A0A0AA").fontSize(9).text(subtitle, MARGIN + 70, 56);
-  doc.moveDown(3);
-
-  // ---- Summary stats ----
-  const total = summary.steps.length;
-  const passed = summary.steps.filter((s) => s.ok).length;
-  const failed = total - passed;
-  const totalMs = summary.steps.reduce((acc, s) => acc + (s.ms || 0), 0);
-
-  doc.fillColor("#0B0B0F").font("Helvetica-Bold").fontSize(14).text("Summary", MARGIN, doc.y);
-  doc.moveDown(0.5);
-  const stats = [
-    ["Steps", `${total}`],
-    ["Passed", `${passed}`],
-    ["Failed", `${failed}`],
-    ["Total time", `${(totalMs / 1000).toFixed(1)}s`],
-  ];
-  drawStatGrid(doc, stats, MARGIN, doc.y, CONTENT_W);
-  doc.moveDown(1.5);
-
-  // ---- Per-step results ----
-  for (let i = 0; i < summary.steps.length; i++) {
-    const step = summary.steps[i];
-    // Page break if less than 200pt left
-    if (doc.y > PAGE_H - 200) doc.addPage();
-
-    // Step header
-    const status = step.ok ? "OK" : "FAIL";
-    const statusColor = step.ok ? "#0a8a4a" : "#d03030";
-    doc.fillColor("#0B0B0F").font("Helvetica-Bold").fontSize(12).text(`#${step.i} ${step.name || "step-" + step.i}`, MARGIN, doc.y);
-    doc.fillColor(statusColor).font("Helvetica-Bold").fontSize(10).text(status, MARGIN + CONTENT_W - 40, doc.y - 12, { width: 40, align: "right" });
-    doc.moveDown(0.3);
-    doc.fillColor("#666").font("Helvetica").fontSize(9);
-    const opLine = `${step.op || "?"} · ${step.ms || 0}ms${step.meta?.url ? " · " + step.meta.url : ""}`;
-    doc.text(opLine, MARGIN, doc.y);
-    doc.moveDown(0.3);
-
-    // Embed image
-    if (embedImages) {
-      const img = step.meta?.out || (step.meta?.currentPath);
-      if (img && existsSync(img)) {
-        try {
-          const maxW = CONTENT_W;
-          const maxH = 280;
-          doc.image(img, MARGIN, doc.y, { fit: [maxW, maxH], align: "center" });
-          doc.moveDown(0.5);
-          doc.y += 5;
-        } catch (e) {
-          doc.fillColor("#999").font("Helvetica-Oblique").fontSize(8).text(`[image error: ${e.message}]`, MARGIN, doc.y);
-          doc.moveDown(0.5);
-        }
-      }
-    }
-
-    // Diffs / errors
-    if (step.meta?.numDiff !== undefined) {
-      doc.fillColor("#444").font("Helvetica").fontSize(9);
-      const pct = step.meta.diffPct?.toFixed?.(3) ?? "?";
-      doc.text(`Diff: ${step.meta.numDiff} pixels (${pct}%) differ from reference`, MARGIN, doc.y);
-      doc.moveDown(0.3);
-    }
-    if (!step.ok && step.error) {
-      doc.fillColor("#a01010").font("Helvetica").fontSize(9).text(`Error: ${step.error}`, MARGIN, doc.y);
-      doc.moveDown(0.3);
-    }
-    if (step.meta?.har) {
-      doc.fillColor("#666").font("Helvetica").fontSize(8).text(`HAR: ${step.meta.har}`, MARGIN, doc.y);
-      doc.moveDown(0.3);
-    }
-    if (step.meta?.violations !== undefined) {
-      const v = step.meta.violations || step.meta.violationSummary;
-      const total = typeof v === "object" ? v.total : v;
-      doc.fillColor("#444").font("Helvetica").fontSize(9).text(`Audit: ${total} violations`, MARGIN, doc.y);
-      doc.moveDown(0.3);
-    }
-
-    doc.moveDown(0.8);
-    // Separator
-    doc.strokeColor("#e0e0e8").lineWidth(0.5).moveTo(MARGIN, doc.y).lineTo(MARGIN + CONTENT_W, doc.y).stroke();
-    doc.moveDown(0.5);
-  }
-
-  // ---- Footer ----
-  const range = doc.bufferedPageRange();
-  for (let i = 0; i < range.count; i++) {
-    doc.switchToPage(range.start + i);
-    doc.fillColor("#999").fontSize(8).font("Helvetica");
-    doc.text(`${i + 1} / ${range.count}`, MARGIN, PAGE_H - 30, { width: CONTENT_W, align: "center" });
-    doc.text("Generated by pursr", MARGIN, PAGE_H - 30, { width: CONTENT_W, align: "right" });
-  }
-
-  doc.end();
-  const buf = await done;
-  if (opts.out) {
-    await writeFile(opts.out, buf);
-  }
-  return buf;
-}
-
-function drawStatGrid(doc, items, x, y, w) {
-  const cols = items.length;
-  const cellW = w / cols;
-  for (let i = 0; i < cols; i++) {
-    const [label, value] = items[i];
-    const cx = x + cellW * i;
-    doc.fillColor("#FF2EA6").font("Helvetica-Bold").fontSize(20).text(value, cx, y, { width: cellW - 8, align: "left" });
-    doc.fillColor("#666").font("Helvetica").fontSize(8).text(label, cx, y + 24, { width: cellW - 8, align: "left" });
-  }
-  return y + 50;
-}
-
+//  pursr - PDF report generator.
+//
+// Renders a sweep summary into a styled, self-contained PDF report.
+// Embeds each capture (PNG) inline so the report can be emailed/shared
+// without any external assets.
+//
+// CLI:
+//   pursr report --sweep ./out/sweep-xxx/sweep.json --out ./out/report.pdf
+//   pursr sweep plan.json   # writes sweep.json + .html; PDF generated separately
+//
+// Library:
+//   import { renderSweepPdf } from "pursr/report";
+//   const bytes = await renderSweepPdf(summary, { out: "report.pdf" });
+
+import PDFDocument from "pdfkit";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { writeFile } from "node:fs/promises";
+import { escapeHtml } from "./util.js";
+
+// A4 in points (1pt = 1/72 in)
+const PAGE_W = 595.28;
+const PAGE_H = 841.89;
+const MARGIN = 40;
+const CONTENT_W = PAGE_W - MARGIN * 2;
+
+/**
+ * Render a sweep summary as a PDF.
+ *
+ * @param {object} summary       - Sweep summary from runSweep()
+ * @param {object} [opts]
+ * @param {string} [opts.out]    - Output PDF file path
+ * @param {string} [opts.title]  - Report title (defaults to sweep.name)
+ * @param {string} [opts.subtitle] - Subtitle
+ * @param {boolean} [opts.embedImages=true] - Embed each capture PNG inline
+ * @returns {Promise<Buffer>}   - PDF bytes (also written to opts.out if set)
+ */
+export async function renderSweepPdf(summary, opts = {}) {
+  if (!summary || !Array.isArray(summary.steps)) {
+    throw new Error("renderSweepPdf: summary.steps must be an array");
+  }
+  const title = opts.title || `pursr sweep: ${summary.name || "(unnamed)"}`;
+  const subtitle = opts.subtitle || `${summary.steps.length} steps · ${summary.ts || ""} · ${summary.outDir || ""}`;
+  const embedImages = opts.embedImages !== false;
+
+  const doc = new PDFDocument({ size: "A4", margin: MARGIN, info: {
+    Title: title,
+    Author: "pursr",
+    Subject: "Visual sweep report",
+    CreationDate: new Date(),
+  }});
+
+  // Collect bytes
+  const chunks = [];
+  doc.on("data", (c) => chunks.push(c));
+  const done = new Promise((resolve, reject) => {
+    doc.on("end", () => resolve(Buffer.concat(chunks)));
+    doc.on("error", reject);
+  });
+
+  // ---- Header ----
+  doc.fillColor("#0B0B0F").rect(0, 0, PAGE_W, 80).fill();
+  doc.fillColor("#FF2EA6").fontSize(22).font("Helvetica-Bold").text("pursr", MARGIN, 30);
+  doc.fillColor("#FFFFFF").fontSize(14).font("Helvetica").text(title, MARGIN + 70, 36);
+  doc.fillColor("#A0A0AA").fontSize(9).text(subtitle, MARGIN + 70, 56);
+  doc.moveDown(3);
+
+  // ---- Summary stats ----
+  const total = summary.steps.length;
+  const passed = summary.steps.filter((s) => s.ok).length;
+  const failed = total - passed;
+  const totalMs = summary.steps.reduce((acc, s) => acc + (s.ms || 0), 0);
+
+  doc.fillColor("#0B0B0F").font("Helvetica-Bold").fontSize(14).text("Summary", MARGIN, doc.y);
+  doc.moveDown(0.5);
+  const stats = [
+    ["Steps", `${total}`],
+    ["Passed", `${passed}`],
+    ["Failed", `${failed}`],
+    ["Total time", `${(totalMs / 1000).toFixed(1)}s`],
+  ];
+  drawStatGrid(doc, stats, MARGIN, doc.y, CONTENT_W);
+  doc.moveDown(1.5);
+
+  // ---- Per-step results ----
+  for (let i = 0; i < summary.steps.length; i++) {
+    const step = summary.steps[i];
+    // Page break if less than 200pt left
+    if (doc.y > PAGE_H - 200) doc.addPage();
+
+    // Step header
+    const status = step.ok ? "OK" : "FAIL";
+    const statusColor = step.ok ? "#0a8a4a" : "#d03030";
+    doc.fillColor("#0B0B0F").font("Helvetica-Bold").fontSize(12).text(`#${step.i} ${step.name || "step-" + step.i}`, MARGIN, doc.y);
+    doc.fillColor(statusColor).font("Helvetica-Bold").fontSize(10).text(status, MARGIN + CONTENT_W - 40, doc.y - 12, { width: 40, align: "right" });
+    doc.moveDown(0.3);
+    doc.fillColor("#666").font("Helvetica").fontSize(9);
+    const opLine = `${step.op || "?"} · ${step.ms || 0}ms${step.meta?.url ? " · " + step.meta.url : ""}`;
+    doc.text(opLine, MARGIN, doc.y);
+    doc.moveDown(0.3);
+
+    // Embed image
+    if (embedImages) {
+      const img = step.meta?.out || (step.meta?.currentPath);
+      if (img && existsSync(img)) {
+        try {
+          const maxW = CONTENT_W;
+          const maxH = 280;
+          doc.image(img, MARGIN, doc.y, { fit: [maxW, maxH], align: "center" });
+          doc.moveDown(0.5);
+          doc.y += 5;
+        } catch (e) {
+          doc.fillColor("#999").font("Helvetica-Oblique").fontSize(8).text(`[image error: ${e.message}]`, MARGIN, doc.y);
+          doc.moveDown(0.5);
+        }
+      }
+    }
+
+    // Diffs / errors
+    if (step.meta?.numDiff !== undefined) {
+      doc.fillColor("#444").font("Helvetica").fontSize(9);
+      const pct = step.meta.diffPct?.toFixed?.(3) ?? "?";
+      doc.text(`Diff: ${step.meta.numDiff} pixels (${pct}%) differ from reference`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+    if (!step.ok && step.error) {
+      doc.fillColor("#a01010").font("Helvetica").fontSize(9).text(`Error: ${step.error}`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+    if (step.meta?.har) {
+      doc.fillColor("#666").font("Helvetica").fontSize(8).text(`HAR: ${step.meta.har}`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+    if (step.meta?.violations !== undefined) {
+      const v = step.meta.violations || step.meta.violationSummary;
+      const total = typeof v === "object" ? v.total : v;
+      doc.fillColor("#444").font("Helvetica").fontSize(9).text(`Audit: ${total} violations`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+
+    doc.moveDown(0.8);
+    // Separator
+    doc.strokeColor("#e0e0e8").lineWidth(0.5).moveTo(MARGIN, doc.y).lineTo(MARGIN + CONTENT_W, doc.y).stroke();
+    doc.moveDown(0.5);
+  }
+
+  // ---- Footer ----
+  const range = doc.bufferedPageRange();
+  for (let i = 0; i < range.count; i++) {
+    doc.switchToPage(range.start + i);
+    doc.fillColor("#999").fontSize(8).font("Helvetica");
+    doc.text(`${i + 1} / ${range.count}`, MARGIN, PAGE_H - 30, { width: CONTENT_W, align: "center" });
+    doc.text("Generated by pursr", MARGIN, PAGE_H - 30, { width: CONTENT_W, align: "right" });
+  }
+
+  doc.end();
+  const buf = await done;
+  if (opts.out) {
+    await writeFile(opts.out, buf);
+  }
+  return buf;
+}
+
+function drawStatGrid(doc, items, x, y, w) {
+  const cols = items.length;
+  const cellW = w / cols;
+  for (let i = 0; i < cols; i++) {
+    const [label, value] = items[i];
+    const cx = x + cellW * i;
+    doc.fillColor("#FF2EA6").font("Helvetica-Bold").fontSize(20).text(value, cx, y, { width: cellW - 8, align: "left" });
+    doc.fillColor("#666").font("Helvetica").fontSize(8).text(label, cx, y + 24, { width: cellW - 8, align: "left" });
+  }
+  return y + 50;
+}
+
 export { renderSweepPdf as default };