pursr 0.5.0 → 0.7.0

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/dom-snapshot.js

@@ -1,192 +1,192 @@
-// pursor — DOM Snapshot + CSSOM + Selector Map.
-//
-// Every capture can optionally produce a .dom.json sidecar containing:
-//   - serialized DOM (document.documentElement.outerHTML)
-//   - computed styles for every visible element
-//   - selector map (id → role → accessible name → xpath → css selector)
-//   - viewport-relative bounding rects
-//
-// Useful for visual regression debugging without a browser —
-// compare DOM structure directly.
-
-import { launch, newPage } from "./runway.js";
-import { resolveViewport } from "./viewport.js";
-import { gotoOrThrow, settle } from "./overlays.js";
-import { writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { nowIso, requireArg } from "./util.js";
-
-// ─── Injected page script ──────────────────────────────────────────────
-// Runs inside the browser to collect all DOM + CSSOM data in one pass.
-
-const SNAPSHOT_PAGE_SCRIPT = `(() => {
-  const results = {
-    url: location.href,
-    title: document.title,
-    timestamp: new Date().toISOString(),
-    viewport: { width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio },
-    dom: null,          // outerHTML
-    selectorMap: [],    // element entries
-    styles: {},         // cssText keyed by selector
-  };
-
-  // --- build xpath for an element ---
-  function getXPath(el) {
-    if (el === document.body) return '/html/body';
-    if (el === document.documentElement) return '/html';
-    let path = '';
-    let current = el;
-    while (current && current !== document.documentElement) {
-      let idx = 1;
-      let sib = current;
-      while ((sib = sib.previousElementSibling) !== null) {
-        if (sib.tagName === current.tagName) idx++;
-      }
-      path = '/' + current.tagName.toLowerCase() + '[' + idx + ']' + path;
-      current = current.parentElement;
-    }
-    return '/html' + path;
-  }
-
-  // --- CSS selector for an element ---
-  function getCSSSelector(el) {
-    if (el.id) return '#' + CSS.escape(el.id);
-    let path = [];
-    let c = el;
-    while (c && c !== document.documentElement) {
-      let sel = c.tagName.toLowerCase();
-      if (c.id) { path.unshift('#' + CSS.escape(c.id)); break; }
-      if (c.className && typeof c.className === 'string') {
-        const cls = c.className.trim().split(/\\s+/).filter(Boolean).map(cl => '.' + CSS.escape(cl)).join('');
-        if (cls) sel += cls;
-      }
-      // add nth-child if needed
-      const parent = c.parentElement;
-      if (parent) {
-        const siblings = Array.from(parent.children).filter(ch => ch.tagName === c.tagName);
-        if (siblings.length > 1) {
-          const idx = siblings.indexOf(c) + 1;
-          sel += ':nth-of-type(' + idx + ')';
-        }
-      }
-      path.unshift(sel);
-      c = c.parentElement;
-    }
-    return path.join(' > ');
-  }
-
-  // --- collect element data ---
-  const allElements = document.querySelectorAll('*');
-  for (const el of allElements) {
-    const tag = el.tagName.toLowerCase();
-    // skip non-visible / empty elements (but keep <canvas>, <img>, <video>, <svg>, input, textarea)
-    const keep = ['canvas','img','video','svg','input','textarea','select','button','a','p','h1','h2','h3','h4','h5','h6','li','td','th','blockquote','code','pre','figure','figcaption'];
-    const rect = el.getBoundingClientRect();
-    const visible = rect.width > 0 && rect.height > 0 && el.offsetParent !== null;
-    if (!visible && !keep.includes(tag)) continue;
-    if (['script','style','link','meta','head'].includes(tag)) continue;
-
-    const id = el.id || null;
-    const role = el.getAttribute('role');
-    const ariaLabel = el.getAttribute('aria-label');
-    const text = ((el.textContent || '').trim().slice(0, 200)) || null;
-    const placeholder = el.getAttribute('placeholder');
-    const alt = el.getAttribute('alt');
-    const href = el.getAttribute('href');
-    const src = el.getAttribute('src');
-
-    const entry = {
-      tag,
-      id,
-      css: getCSSSelector(el),
-      xpath: getXPath(el),
-      role: role || null,
-      ariaLabel: ariaLabel || null,
-      text,
-      placeholder: placeholder || null,
-      alt: alt || null,
-      href: href || null,
-      src: src || null,
-      rect: visible ? { x: round(rect.x), y: round(rect.y), w: round(rect.width), h: round(rect.height) } : null,
-      visible,
-    };
-
-    // get computed role from accessibility tree
-    try { entry.ariaRole = el.computedRole || el.getAttribute('role') || null; } catch {}
-
-    results.selectorMap.push(entry);
-  }
-
-  function round(n) { return Math.round(n * 10) / 10; }
-
-  // --- get all computed stylesheets ---
-  for (let i = 0; i < document.styleSheets.length; i++) {
-    try {
-      const ss = document.styleSheets[i];
-      const rules = ss.cssRules || ss.rules;
-      if (!rules) continue;
-      for (let j = 0; j < rules.length; j++) {
-        const r = rules[j];
-        if (r && r.cssText && r.selectorText) {
-          if (!results.styles[r.selectorText]) results.styles[r.selectorText] = [];
-          if (results.styles[r.selectorText].length < 5) {  // cap per selector
-            results.styles[r.selectorText].push(r.cssText);
-          }
-        }
-      }
-    } catch {}
-  }
-
-  // --- serialize DOM ---
-  results.dom = document.documentElement.outerHTML;
-
-  return results;
-})()`;
-
-// ─── Public API ─────────────────────────────────────────────────────────
-
-/**
- * Capture full DOM snapshot of a URL.
- * Returns the snapshot data AND writes it to out path.
- */
-export async function captureDomSnapshot({ url, out, flags = {} }) {
-  requireArg("url", url, "string");
-  const viewport = resolveViewport(flags);
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, viewport);
-    const r = await gotoOrThrow(page, url);
-    await settle(page);
-    // Give dynamic content a moment
-    await page.waitForTimeout(500);
-    const snapshot = await page.evaluate(SNAPSHOT_PAGE_SCRIPT);
-    snapshot.navStatus = r.status;
-    snapshot.navTitle = r.title;
-
-    // Write output
-    if (out) {
-      mkdirSync(dirname(out), { recursive: true });
-      writeFileSync(out, JSON.stringify(snapshot, null, 2));
-    }
-
-    return snapshot;
-  } finally {
-    try { await browser.close(); } catch {}
-  }
-}
-
-/**
- * Attach DOM snapshot as sidecar to an existing shoot result.
- * Call after runShoot — reuses the active page.
- */
-export async function captureDomSnapshotSidecar(page, out) {
-  if (!page || !out) return null;
-  try {
-    const snapshot = await page.evaluate(SNAPSHOT_PAGE_SCRIPT);
-    const domPath = out.replace(/\.png$/i, ".dom.json");
-    writeFileSync(domPath, JSON.stringify(snapshot, null, 2));
-    return domPath;
-  } catch {
-    return null;
-  }
-}
+//  pursr — DOM Snapshot + CSSOM + Selector Map.
+//
+// Every capture can optionally produce a .dom.json sidecar containing:
+//   pursr - serialized DOM (document.documentElement.outerHTML)
+//   pursr - computed styles for every visible element
+//   pursr - selector map (id → role → accessible name → xpath → css selector)
+//   pursr - viewport-relative bounding rects
+//
+// Useful for visual regression debugging without a browser —
+// compare DOM structure directly.
+
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle } from "./overlays.js";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { nowIso, requireArg } from "./util.js";
+
+// ─── Injected page script ──────────────────────────────────────────────
+// Runs inside the browser to collect all DOM + CSSOM data in one pass.
+
+const SNAPSHOT_PAGE_SCRIPT = `(() => {
+  const results = {
+    url: location.href,
+    title: document.title,
+    timestamp: new Date().toISOString(),
+    viewport: { width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio },
+    dom: null,          // outerHTML
+    selectorMap: [],    // element entries
+    styles: {},         // cssText keyed by selector
+  };
+
+  // --- build xpath for an element ---
+  function getXPath(el) {
+    if (el === document.body) return '/html/body';
+    if (el === document.documentElement) return '/html';
+    let path = '';
+    let current = el;
+    while (current && current !== document.documentElement) {
+      let idx = 1;
+      let sib = current;
+      while ((sib = sib.previousElementSibling) !== null) {
+        if (sib.tagName === current.tagName) idx++;
+      }
+      path = '/' + current.tagName.toLowerCase() + '[' + idx + ']' + path;
+      current = current.parentElement;
+    }
+    return '/html' + path;
+  }
+
+  // --- CSS selector for an element ---
+  function getCSSSelector(el) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    let path = [];
+    let c = el;
+    while (c && c !== document.documentElement) {
+      let sel = c.tagName.toLowerCase();
+      if (c.id) { path.unshift('#' + CSS.escape(c.id)); break; }
+      if (c.className && typeof c.className === 'string') {
+        const cls = c.className.trim().split(/\\s+/).filter(Boolean).map(cl => '.' + CSS.escape(cl)).join('');
+        if (cls) sel += cls;
+      }
+      // add nth-child if needed
+      const parent = c.parentElement;
+      if (parent) {
+        const siblings = Array.from(parent.children).filter(ch => ch.tagName === c.tagName);
+        if (siblings.length > 1) {
+          const idx = siblings.indexOf(c) + 1;
+          sel += ':nth-of-type(' + idx + ')';
+        }
+      }
+      path.unshift(sel);
+      c = c.parentElement;
+    }
+    return path.join(' > ');
+  }
+
+  // --- collect element data ---
+  const allElements = document.querySelectorAll('*');
+  for (const el of allElements) {
+    const tag = el.tagName.toLowerCase();
+    // skip non-visible / empty elements (but keep <canvas>, <img>, <video>, <svg>, input, textarea)
+    const keep = ['canvas','img','video','svg','input','textarea','select','button','a','p','h1','h2','h3','h4','h5','h6','li','td','th','blockquote','code','pre','figure','figcaption'];
+    const rect = el.getBoundingClientRect();
+    const visible = rect.width > 0 && rect.height > 0 && el.offsetParent !== null;
+    if (!visible && !keep.includes(tag)) continue;
+    if (['script','style','link','meta','head'].includes(tag)) continue;
+
+    const id = el.id || null;
+    const role = el.getAttribute('role');
+    const ariaLabel = el.getAttribute('aria-label');
+    const text = ((el.textContent || '').trim().slice(0, 200)) || null;
+    const placeholder = el.getAttribute('placeholder');
+    const alt = el.getAttribute('alt');
+    const href = el.getAttribute('href');
+    const src = el.getAttribute('src');
+
+    const entry = {
+      tag,
+      id,
+      css: getCSSSelector(el),
+      xpath: getXPath(el),
+      role: role || null,
+      ariaLabel: ariaLabel || null,
+      text,
+      placeholder: placeholder || null,
+      alt: alt || null,
+      href: href || null,
+      src: src || null,
+      rect: visible ? { x: round(rect.x), y: round(rect.y), w: round(rect.width), h: round(rect.height) } : null,
+      visible,
+    };
+
+    // get computed role from accessibility tree
+    try { entry.ariaRole = el.computedRole || el.getAttribute('role') || null; } catch {}
+
+    results.selectorMap.push(entry);
+  }
+
+  function round(n) { return Math.round(n * 10) / 10; }
+
+  // --- get all computed stylesheets ---
+  for (let i = 0; i < document.styleSheets.length; i++) {
+    try {
+      const ss = document.styleSheets[i];
+      const rules = ss.cssRules || ss.rules;
+      if (!rules) continue;
+      for (let j = 0; j < rules.length; j++) {
+        const r = rules[j];
+        if (r && r.cssText && r.selectorText) {
+          if (!results.styles[r.selectorText]) results.styles[r.selectorText] = [];
+          if (results.styles[r.selectorText].length < 5) {  // cap per selector
+            results.styles[r.selectorText].push(r.cssText);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  // --- serialize DOM ---
+  results.dom = document.documentElement.outerHTML;
+
+  return results;
+})()`;
+
+// ─── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Capture full DOM snapshot of a URL.
+ * Returns the snapshot data AND writes it to out path.
+ */
+export async function captureDomSnapshot({ url, out, flags = {} }) {
+  requireArg("url", url, "string");
+  const viewport = resolveViewport(flags);
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url);
+    await settle(page);
+    // Give dynamic content a moment
+    await page.waitForTimeout(500);
+    const snapshot = await page.evaluate(SNAPSHOT_PAGE_SCRIPT);
+    snapshot.navStatus = r.status;
+    snapshot.navTitle = r.title;
+
+    // Write output
+    if (out) {
+      mkdirSync(dirname(out), { recursive: true });
+      writeFileSync(out, JSON.stringify(snapshot, null, 2));
+    }
+
+    return snapshot;
+  } finally {
+    try { await browser.close(); } catch {}
+  }
+}
+
+/**
+ * Attach DOM snapshot as sidecar to an existing shoot result.
+ * Call after runShoot — reuses the active page.
+ */
+export async function captureDomSnapshotSidecar(page, out) {
+  if (!page || !out) return null;
+  try {
+    const snapshot = await page.evaluate(SNAPSHOT_PAGE_SCRIPT);
+    const domPath = out.replace(/\.png$/i, ".dom.json");
+    writeFileSync(domPath, JSON.stringify(snapshot, null, 2));
+    return domPath;
+  } catch {
+    return null;
+  }
+}

package/src/eval.js

@@ -1,18 +1,18 @@
-// Evaluate a JS string in the page, optionally screenshot after.
-
-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 runEval(url, js, out) {
-  requireArg("url", url, "string");
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
-    const r = await gotoOrThrow(page, url);
-    const result = await page.evaluate(js);
-    if (out) await page.screenshot({ path: out, fullPage: false });
-    return { ...r, url, out, result };
-  } finally { try { await browser.close(); } catch {} }
+// Evaluate a JS string in the page, optionally screenshot after.
+
+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 runEval(url, js, out) {
+  requireArg("url", url, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url);
+    const result = await page.evaluate(js);
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, result };
+  } finally { try { await browser.close(); } catch {} }
 }

package/src/every-viewport.js

@@ -1,51 +1,51 @@
-// Every-viewport: capture one screenshot at every registered viewport
-// preset in a single command. No JSON plan needed.
-//
-// Usage:
-//   pursor every-viewport https://example.com
-//   pursor every-viewport https://example.com --out ./report
-
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { launch } from "./runway.js";
-import { listViewports } from "./viewport.js";
-import { runShoot } from "./shoot.js";
-import { asNum, nowIso, renderEveryViewportHtml } from "./util.js";
-
-export async function runEveryViewport({ url, outDir, viewports, browser: extBrowser }) {
-  const ownBrowser = !extBrowser;
-  const browser = extBrowser || await launch();
-  const dir = outDir || join(".", `every-viewport-${Date.now()}`);
-  mkdirSync(dir, { recursive: true });
-  const all = listViewports();
-  const wanted = viewports?.length ? all.filter(v => viewports.includes(v.name)) : all;
-  const captures = [];
-  try {
-    // Bounded concurrency: 3 viewports at a time. Each runShoot reuses the
-    // shared browser, so we cap the pool to avoid exhausting Chromium.
-    const POOL = 3;
-    let cursor = 0;
-    async function worker() {
-      while (cursor < wanted.length) {
-        const idx = cursor++;
-        const vp = wanted[idx];
-        const out = join(dir, `${vp.name}.png`);
-        const t0 = Date.now();
-        try {
-          const meta = await runShoot({ url, out, flags: { preset: vp.name }, browser });
-          captures.push({ name: vp.name, out, ok: true, ms: Date.now() - t0, meta });
-        } catch (e) {
-          captures.push({ name: vp.name, out, ok: false, ms: Date.now() - t0, error: e.message });
-        }
-      }
-    }
-    const workers = Array.from({ length: Math.min(POOL, wanted.length) }, () => worker());
-    await Promise.all(workers);
-  } finally {
-    if (ownBrowser) try { await browser.close(); } catch {}
-  }
-  const summary = { url, outDir: dir, captures, ts: nowIso(), ok: captures.every(c => c.ok) };
-  writeFileSync(join(dir, "every-viewport.json"), JSON.stringify(summary, null, 2));
-  writeFileSync(join(dir, "index.html"), renderEveryViewportHtml(summary));
-  return summary;
-}
+// Every-viewport: capture one screenshot at every registered viewport
+// preset in a single command. No JSON plan needed.
+//
+// Usage:
+//   pursr every-viewport https://example.com
+//   pursr every-viewport https://example.com --out ./report
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { launch } from "./runway.js";
+import { listViewports } from "./viewport.js";
+import { runShoot } from "./shoot.js";
+import { asNum, nowIso, renderEveryViewportHtml } from "./util.js";
+
+export async function runEveryViewport({ url, outDir, viewports, browser: extBrowser }) {
+  const ownBrowser = !extBrowser;
+  const browser = extBrowser || await launch();
+  const dir = outDir || join(".", `every-viewport-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+  const all = listViewports();
+  const wanted = viewports?.length ? all.filter(v => viewports.includes(v.name)) : all;
+  const captures = [];
+  try {
+    // Bounded concurrency: 3 viewports at a time. Each runShoot reuses the
+    // shared browser, so we cap the pool to avoid exhausting Chromium.
+    const POOL = 3;
+    let cursor = 0;
+    async function worker() {
+      while (cursor < wanted.length) {
+        const idx = cursor++;
+        const vp = wanted[idx];
+        const out = join(dir, `${vp.name}.png`);
+        const t0 = Date.now();
+        try {
+          const meta = await runShoot({ url, out, flags: { preset: vp.name }, browser });
+          captures.push({ name: vp.name, out, ok: true, ms: Date.now() - t0, meta });
+        } catch (e) {
+          captures.push({ name: vp.name, out, ok: false, ms: Date.now() - t0, error: e.message });
+        }
+      }
+    }
+    const workers = Array.from({ length: Math.min(POOL, wanted.length) }, () => worker());
+    await Promise.all(workers);
+  } finally {
+    if (ownBrowser) try { await browser.close(); } catch {}
+  }
+  const summary = { url, outDir: dir, captures, ts: nowIso(), ok: captures.every(c => c.ok) };
+  writeFileSync(join(dir, "every-viewport.json"), JSON.stringify(summary, null, 2));
+  writeFileSync(join(dir, "index.html"), renderEveryViewportHtml(summary));
+  return summary;
+}