pursor 0.2.0

package/src/selector-heal.js

@@ -0,0 +1,85 @@
+// pursor — Auto-heal Selector Chain.
+//
+// In sweep plans, a selector can be an array of fallback strategies:
+//   "click": { "selector": ["text=Login", "button[type=submit]", "#login-btn"] }
+//
+// resolveHealedSelector tries each one in order, returns the first match.
+// Also supports named matchers (text=, role=, aria=, placeholder=, css=)
+// and plain CSS selectors.
+
+import { resolveLocator } from "./selector.js";
+import { CLICK_TIMEOUT_MS } from "./overlays.js";
+
+/**
+ * Resolve a selector that may be a chain of fallbacks.
+ *
+ * @param {import("playwright-core").Page} page
+ * @param {string|string[]} selector - Single selector or array of fallbacks
+ * @param {object} [opts]
+ * @param {number} [opts.timeout] - Per-selector timeout
+ * @param {boolean} [opts.returnAll] - Return ALL matching locators (first found, rest as fallbacks)
+ * @returns {Promise<{ locator: import("playwright-core").Locator, selector: string, index: number }|null>}
+ *
+ * Example:
+ *   const result = await resolveHealedSelector(page, ["text=Login", "button[type=submit]", "#login-btn"]);
+ *   if (result) await result.locator.first().click();
+ */
+export async function resolveHealedSelector(page, selector, opts = {}) {
+  if (!selector) throw new Error("empty selector");
+  if (!page) throw new Error("page required");
+
+  const chains = Array.isArray(selector) ? selector : [selector];
+  const timeout = opts.timeout || CLICK_TIMEOUT_MS;
+  let lastError = null;
+
+  for (let i = 0; i < chains.length; i++) {
+    const sel = String(chains[i]).trim();
+    if (!sel) continue;
+
+    try {
+      // Use existing resolveLocator for text=/role=/aria=/placeholder= prefixes
+      const locator = await resolveLocator(page, sel);
+      const count = await locator.count();
+      if (count > 0) {
+        // Quick visibility check without awaiting each element individually
+        const visible = await locator.first().isVisible().catch(() => false);
+        if (visible) {
+          return { locator, selector: sel, index: i, count };
+        }
+        // Found but not visible — try next if available
+        lastError = new Error(`Found "${sel}" (x${count}) but not visible`);
+        continue;
+      }
+    } catch (e) {
+      lastError = e;
+      continue;
+    }
+  }
+
+  // If nothing matched, throw with helpful message about what was tried
+  if (lastError) throw new Error(`Selector chain exhausted: tried [${chains.join(", ")}]. Last error: ${lastError.message}`);
+  throw new Error(`Selector chain exhausted: tried [${chains.join(", ")}]. No match found.`);
+}
+
+/**
+ * Simplify: extract a single selector string for logging / display
+ * from a selector chain.
+ */
+export function displaySelector(selector) {
+  return Array.isArray(selector) ? selector[0] : selector;
+}
+
+/**
+ * Wrap a step's click/hover/type/wait selector calls with auto-heal support.
+ * Mutates the step action object in-place: resolves string → {selector, ...} to
+ * the first matching selector.
+ */
+export async function healStepAction(page, action) {
+  if (!action || !action.selector) return action;
+  const result = await resolveHealedSelector(page, action.selector);
+  // Replace chain with the single resolved selector for logging
+  action._resolvedSelector = result.selector;
+  action._healAttempts = Array.isArray(action.selector) ? action.selector.length : 1;
+  action.selector = result.selector;
+  return action;
+}

package/src/selector.js

@@ -0,0 +1,39 @@
+// Selector parsing + resolution. Reused by click/type/wait/hover/seq.
+
+export function parseTextSelector(rest) {
+  // text==Exact[0]  → exact match, nth 0
+  // text~regex      → regex match
+  // text=Hello      → substring match
+  let m = rest.match(/^text~\/?(.+?)\/?(\[(\d+)\])?$/);
+  if (m) {
+    const source = m[1].replace(/\\\//g, "/");
+    try {
+      return { text: new RegExp(source, "i"), exact: false, regex: true, nth: m[3] !== undefined ? Number(m[3]) : undefined };
+    } catch { return null; }
+  }
+  m = rest.match(/^text(={1,2})(.*?)(\[(\d+)\])?$/);
+  if (!m) return null;
+  const exact = m[1] === "==";
+  const nth = m[3] !== undefined ? Number(m[4]) : undefined;
+  return { text: m[2], exact, regex: false, nth };
+}
+
+export async function resolveLocator(page, selector) {
+  if (!selector) throw new Error("empty selector");
+  if (selector.startsWith("text=")) {
+    const p = parseTextSelector(selector);
+    if (!p) throw new Error(`bad text= selector: ${selector}`);
+    let loc = p.exact ? page.getByText(p.text, { exact: true })
+      : p.regex ? page.getByText(p.text)
+      : page.getByText(p.text);
+    if (p.nth !== undefined) loc = loc.nth(p.nth - 1);
+    return loc;
+  }
+  if (selector.startsWith("role=")) {
+    const [role, name] = selector.slice(5).split("|", 2);
+    return page.getByRole(role.trim(), name ? { name: name.trim() } : undefined);
+  }
+  if (selector.startsWith("aria=")) return page.getByLabel(selector.slice(5));
+  if (selector.startsWith("placeholder=")) return page.getByPlaceholder(selector.slice("placeholder=".length));
+  return page.locator(selector);
+}

package/src/shoot.js

@@ -0,0 +1,62 @@
+// The core capture function: open a viewport, navigate, apply all the
+// overlays + camera + frame-stable waits, then screenshot.
+
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import {
+  gotoOrThrow, settle, overlayCursor, overlayGrid, hideHud,
+  isolateLayer, freezeAnimation, waitForStableFrame, applyCamera,
+} from "./overlays.js";
+import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
+import { runBeforeShoot, runAfterShoot } from "./plugin.js";
+
+export async function runShoot({ url, out, flags = {}, prepare, browser: extBrowser }) {
+  requireArg("url", url, "string");
+  const viewport = resolveViewport(flags);
+  const ownBrowser = !extBrowser;
+  const browser = extBrowser || await launch();
+  const cleanups = [];
+  try {
+    return await (async () => {
+      const page = await newPage(browser, viewport);
+      const r = await gotoOrThrow(page, url);
+      await settle(page);
+
+      // Build a ctx object so plugins can mutate it
+      const ctx = { url, out, viewport, flags, browser, page };
+
+      await runBeforeShoot(ctx);
+
+      cleanups.push(await freezeAnimation(page, asBool(flags["no-animation"], false)));
+      cleanups.push(await overlayCursor(page, flags.cursor || "default"));
+      if (asBool(flags.grid, false)) cleanups.push(await overlayGrid(page, { tileSize: flags["grid-tile"], color: flags["grid-color"] }));
+      if (asBool(flags["no-hud"], false)) cleanups.push(await hideHud(page));
+      cleanups.push(await isolateLayer(page, flags.layer || "all"));
+      if (typeof prepare === "function") { const c = await prepare(page); if (typeof c === "function") cleanups.push(c); }
+
+      if (flags["wait-frame"]) await waitForStableFrame(page, asNum(flags["wait-frame"], 600));
+
+      if (flags.zoom || flags.panX || flags.panY) {
+        await applyCamera(page, { zoom: asNum(flags.zoom, 1), panX: asNum(flags.panX, 0), panY: asNum(flags.panY, 0) });
+        await page.waitForTimeout(400);
+      }
+
+      await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
+      const meta = { url, out, ts: nowIso(), status: r.status, title: r.title, viewport, flags: { ...flags } };
+      await runAfterShoot(ctx, meta);
+      return meta;
+    })().catch(e => ({ url, out, ts: nowIso(), error: e.message, viewport, flags: { ...flags } }));
+  } finally {
+    // Run cleanups (remove injected overlay styles)
+    for (const fn of cleanups) {
+      try { await fn(); } catch {}
+    }
+    if (ownBrowser) await browser.close();
+  }
+}
+
+export async function runShootWithSidecar(args) {
+  const meta = await runShoot(args);
+  await writeSidecar(meta);
+  return meta;
+}

package/src/shot.js

@@ -0,0 +1,18 @@
+// Simple screenshot (no flags / overlays).
+
+import { launch, newPage } from "./runway.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { gotoOrThrow, settle } from "./overlays.js";
+import { requireArg } from "./util.js";
+
+export async function runShot(url, out, opts = {}) {
+  requireArg("url", url, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url);
+    await settle(page);
+    await page.screenshot({ path: out, fullPage: !!opts.fullPage });
+    return { ...r, url, out, fullPage: !!opts.fullPage };
+  } finally { try { await browser.close(); } catch {} }
+}

package/src/sweep-schema.js

@@ -0,0 +1,70 @@
+// pursor — sweep plan schema validator.
+//
+// Validates a parsed JSON object against the sweep plan grammar used by
+// runSweep(). Returns { valid, errors } with a flat list of human-readable
+// error messages. This is intentionally lightweight (no JSON-schema
+// dependency) but covers the practical cases that bite users: missing
+// op keys, wrong types, unknown ops, out-of-range numbers.
+
+const KNOWN_OPS = new Set([
+  "shoot", "hover", "frames", "diff", "audit", "dom", "seq", "eval",
+  "every-viewport", "baseline-save", "baseline-approve", "diff-baseline",
+]);
+
+const KNOWN_SWEEP_PLUGIN_OPS = new Set(); // populated at runtime by plugins
+
+export function registerSweepOp(name) { KNOWN_SWEEP_PLUGIN_OPS.add(name); }
+
+function isPlainObject(x) { return x != null && typeof x === "object" && !Array.isArray(x); }
+
+function err(errors, path, msg) { errors.push(`${path}: ${msg}`); }
+
+function validateStep(step, i, errors, ctx) {
+  const base = `steps[${i}]`;
+  if (!isPlainObject(step)) { err(errors, base, "must be an object"); return; }
+  const keys = Object.keys(step).filter(k => k !== "name");
+  if (step.name !== undefined && typeof step.name !== "string") err(errors, `${base}.name`, "must be a string");
+  if (!keys.length) { err(errors, base, `must define exactly one operation key (one of: ${[...KNOWN_OPS].join(", ")})`); return; }
+  if (keys.length > 1) err(errors, base, `defines multiple operation keys (${keys.join(", ")}); only one allowed`);
+  const op = keys[0];
+  if (!KNOWN_OPS.has(op) && !KNOWN_SWEEP_PLUGIN_OPS.has(op)) err(errors, `${base}.${op}`, `unknown op; expected one of ${[...KNOWN_OPS].join(", ")}`);
+  const v = step[op];
+  if (!isPlainObject(v)) { err(errors, `${base}.${op}`, "must be an object"); return; }
+  // Per-op checks
+  if (op === "shoot") {
+    if (v.url !== undefined && typeof v.url !== "string") err(errors, `${base}.shoot.url`, "must be a string");
+  } else if (op === "hover") {
+    if (typeof v.selector !== "string") err(errors, `${base}.hover.selector`, "required string");
+  } else if (op === "frames") {
+    if (v.count !== undefined && !(Number.isFinite(Number(v.count)) && Number(v.count) >= 1 && Number(v.count) <= 120))
+      err(errors, `${base}.frames.count`, "must be a number between 1 and 120");
+    if (v.intervalMs !== undefined && !(Number.isFinite(Number(v.intervalMs)) && Number(v.intervalMs) >= 16))
+      err(errors, `${base}.frames.intervalMs`, "must be >= 16");
+  } else if (op === "diff") {
+    if (typeof v.ref !== "string") err(errors, `${base}.diff.ref`, "required string (step name or filename)");
+    if (v.threshold !== undefined && !(Number.isFinite(Number(v.threshold)) && Number(v.threshold) >= 0 && Number(v.threshold) <= 1))
+      err(errors, `${base}.diff.threshold`, "must be 0..1");
+  } else if (op === "audit") {
+    if (v.tags !== undefined && typeof v.tags !== "string") err(errors, `${base}.audit.tags`, "must be a string (comma-separated)");
+  } else if (op === "baseline-save" || op === "baseline-approve") {
+    if (v.id !== undefined && typeof v.id !== "string") err(errors, `${base}.${op}.id`, "must be a string");
+  } else if (op === "diff-baseline") {
+    if (v.id !== undefined && typeof v.id !== "string") err(errors, `${base}.diff-baseline.id`, "must be a string");
+  }
+  // Step name uniqueness (soft check)
+  if (ctx.seenNames.has(step.name)) err(errors, `${base}.name`, `duplicate step name "${step.name}"`);
+  ctx.seenNames.add(step.name);
+}
+
+export function validateSweepPlan(plan) {
+  const errors = [];
+  if (!isPlainObject(plan)) { return { valid: false, errors: ["plan: must be an object"] }; }
+  if (!Array.isArray(plan.steps)) { return { valid: false, errors: ["plan.steps: required array"] }; }
+  if (!plan.steps.length) err(errors, "plan.steps", "must be non-empty");
+  if (plan.base !== undefined && typeof plan.base !== "string") err(errors, "plan.base", "must be a string");
+  if (plan.outDir !== undefined && typeof plan.outDir !== "string") err(errors, "plan.outDir", "must be a string");
+  if (plan.name !== undefined && typeof plan.name !== "string") err(errors, "plan.name", "must be a string");
+  const ctx = { seenNames: new Set() };
+  plan.steps.forEach((s, i) => validateStep(s, i, errors, ctx));
+  return { valid: errors.length === 0, errors };
+}

package/src/sweep.js

@@ -0,0 +1,105 @@
+// Sweep: batch capture plan. Each step is one of:
+//   { name, shoot:  { url?, preset?, ...flags } }
+//   { name, hover:  { url?, selector } }
+//   { name, frames: { url?, count, intervalMs } }
+//   { name, diff:   { url?, ref, threshold? } }
+//   { name, <customOp>: { ... } }   // from a registered plugin
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve as pathResolve } from "node:path";
+import { runShootWithSidecar } from "./shoot.js";
+import { runFrames } from "./frames.js";
+import { runDiff } from "./diff.js";
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle, CLICK_TIMEOUT_MS } from "./overlays.js";
+import { resolveLocator } from "./selector.js";
+import { resolveHealedSelector } from "./selector-heal.js";
+import { asNum, nowIso, findStepPng, renderSweepHtml } from "./util.js";
+import { getSweepOp } from "./plugin.js";
+import { writeCiOutput } from "./ci-output.js";
+
+export async function runSweep(planPath, outDirArg) {
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  // Validate plan shape early for actionable errors.
+  const { validateSweepPlan } = await import("./sweep-schema.js");
+  const v = validateSweepPlan(plan);
+  if (!v.valid) {
+    const msg = v.errors.length === 1
+      ? v.errors[0]
+      : v.errors.map((e, i) => "  " + (i + 1) + ". " + e).join("\n");
+    throw new Error("sweep plan validation failed:\n" + msg);
+  }
+  const dir = outDirArg ?? plan.outDir ?? join(plan.outBase || ".", `sweep-${plan.name || "plan"}`);
+  mkdirSync(dir, { recursive: true });
+  const summary = { plan: pathResolve(planPath), outDir: dir, name: plan.name || null, steps: [], ts: nowIso() };
+  const browser = await launch();
+  try {
+    for (let i = 0; i < plan.steps.length; i++) {
+      const s = plan.steps[i] || {};
+      const stepName = s.name || `step-${i}`;
+      const stepOut = join(dir, `${String(i).padStart(2, "0")}-${stepName}.png`);
+      const t0 = Date.now();
+      const stepKeys = Object.keys(s).filter(k => k !== "name");
+      if (!stepKeys.length) throw new Error(`step ${i} has no operation key (only "name"?)`);
+      if (stepKeys.length > 1) throw new Error(`step ${i} has ${stepKeys.length} operation keys (${stepKeys.join(", ")}). Only one allowed per step.`);
+      const opKey = stepKeys[0];
+      const entry = { i, name: stepName, op: opKey };
+      try {
+        if (s.shoot) {
+          const url = s.shoot.url || (plan.base ? plan.base : null);
+          if (!url) throw new Error("shoot: missing url (and no plan.base)");
+          const flags = Object.fromEntries(Object.entries(s.shoot).filter(([k]) => k !== "url").map(([k, v]) => [k, v]));
+          const meta = await runShootWithSidecar({ url, out: stepOut, flags, browser });
+          entry.meta = meta;
+        } else if (s.hover) {
+          const url = s.hover.url || (plan.base ? plan.base : null);
+          if (!url) throw new Error("hover: missing url (and no plan.base)");
+          const selector = s.hover.selector;
+          if (!selector) throw new Error("hover: missing selector");
+          const viewport = resolveViewport(s.hover);
+          const page = await newPage(browser, viewport);
+          const r = await gotoOrThrow(page, url); await settle(page);
+          // Auto-heal: selector can be string or array of fallbacks
+          const healed = await resolveHealedSelector(page, selector);
+          await healed.locator.first().hover({ timeout: CLICK_TIMEOUT_MS });
+          await page.waitForTimeout(asNum(s.hover.settleMs, 300));
+          await page.screenshot({ path: stepOut, fullPage: false });
+          await page.close();
+          entry.meta = { ...r, url, out: stepOut, selector, viewport };
+        } else if (s.frames) {
+          const url = s.frames.url || (plan.base ? plan.base : null);
+          if (!url) throw new Error("frames: missing url (and no plan.base)");
+          const subDir = join(dir, `${String(i).padStart(2, "0")}-${stepName}-frames`);
+          const meta = await runFrames({ url, count: asNum(s.frames.count, 8), intervalMs: asNum(s.frames.intervalMs, 200), outDir: subDir, flags: s.frames, browser });
+          entry.meta = meta;
+        } else if (s.diff) {
+          const refName = s.diff.ref;
+          if (!refName) throw new Error("diff: missing ref (step name or filename)");
+          const refPath = findStepPng(dir, refName);
+          if (!refPath) throw new Error(`diff: ref not found in dir: ${refName}`);
+          const url = s.diff.url || (plan.base ? plan.base : null);
+          if (!url) throw new Error("diff: missing url (and no plan.base)");
+          const meta = await runDiff(url, refPath, stepOut, asNum(s.diff.threshold, 0.1), browser);
+          entry.meta = meta;
+        } else if (opKey && getSweepOp(opKey)) {
+          const customOp = getSweepOp(opKey);
+          if (typeof customOp !== "function") throw new Error(`custom op "${opKey}" is not a function`);
+          const ctx = { url: plan.base, out: stepOut, browser, page: null };
+          const result = await customOp(ctx, s[opKey] || {});
+          entry.meta = result != null ? result : { out: stepOut };
+        } else {
+          throw new Error(`step "${opKey}": unknown or unregistered operation`);
+        }
+        entry.ms = Date.now() - t0; entry.ok = true;
+      } catch (e) {
+        entry.ok = false; entry.error = e.message; entry.ms = Date.now() - t0;
+      }
+      summary.steps.push(entry);
+    }
+  } finally { try { await browser.close(); } catch {} }
+  writeFileSync(join(dir, "sweep.json"), JSON.stringify(summary, null, 2));
+  writeFileSync(join(dir, "index.html"), renderSweepHtml(summary));
+  try { writeCiOutput(summary, dir); } catch (e) { console.error("[pursor] CI output error:", e.message); }
+  return summary;
+}

package/src/util.js

@@ -0,0 +1,188 @@
+// Tiny utility module: arg reading, flag parsing, output path picking,
+// sidecar writing.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+
+export function outDir() {
+  // Use $XDG_PICTURES_DIR, ~/Pictures, or fallback to system tmp
+  const base = process.env.XDG_PICTURES_DIR || join(homedir(), "Pictures");
+  const dir = process.platform === "win32" ? join(base, "gen") : join(base, "gen");
+  try {
+    mkdirSync(dir, { recursive: true });
+    return dir;
+  } catch (e) {
+    const fallback = join(tmpdir(), "pursor");
+    try {
+      mkdirSync(fallback, { recursive: true });
+    } catch {}
+    // Surface a single warning so silent fallback is debuggable.
+    if (process.env.PURSOR_DEBUG) console.error("[pursor] outDir fallback to", fallback, "(", e?.message, ")");
+    return fallback;
+  }
+}
+
+/** Validate required arg — throws with caller-friendly message. Returns value. */
+export function requireArg(name, value, kind) {
+  if (value === undefined || value === null) throw new Error(`missing required argument: ${name}`);
+  if (kind === "string" && typeof value !== "string") throw new Error(`${name}: expected string, got ${typeof value}`);
+  if (kind === "number" && (typeof value !== "number" || !Number.isFinite(value))) throw new Error(`${name}: expected finite number, got ${typeof value}`);
+  if (kind === "string" && value.trim() === "") throw new Error(`${name}: must not be empty`);
+  return value;
+}
+
+export function makeOut(name) {
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  return join(outDir(), `pursor-${ts}-${name}`);
+}
+
+export function nowIso() { return new Date().toISOString(); }
+
+export function shortHash(buf) {
+  if (!buf || !Buffer.isBuffer(buf)) return "".padStart(10, "0");
+  return createHash("sha1").update(buf).digest("hex").slice(0, 10);
+}
+
+export function readArg(arg) {
+  if (arg === undefined || arg === null) return undefined;
+  if (typeof arg !== "string" || !arg.startsWith("@")) return arg;
+  const path = arg.slice(1);
+  if (!existsSync(path)) throw new Error(`@file not found: ${path}`);
+  return readFileSync(path, "utf8").replace(/\r?\n$/, "");
+}
+
+export function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a || !a.startsWith("--")) continue;
+    const eq = a.indexOf("=");
+    let key, val;
+    if (eq >= 0) { key = a.slice(2, eq); val = a.slice(eq + 1); }
+    else {
+      key = a.slice(2);
+      const next = i + 1 < argv.length ? argv[i + 1] : undefined;
+      val = (next !== undefined && !next.startsWith("--")) ? argv[++i] : true;
+    }
+    flags[key] = val;
+  }
+  return flags;
+}
+
+export function asNum(v, dflt) {
+  if (v === undefined || v === null) return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+export function asBool(v, dflt) {
+  if (v === true) return true;
+  if (v === false || v === undefined || v === null) return dflt;
+  const s = String(v).toLowerCase();
+  if (s === "1" || s === "true" || s === "yes" || s === "on") return true;
+  if (s === "0" || s === "false" || s === "no" || s === "off") return false;
+  return dflt;
+}
+
+// Pick a positional output path from argv, skipping --flags and their values.
+// Returns the path or undefined.
+export function pickOutPath(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a) continue;
+    if (a.startsWith("--")) { if (!a.includes("=")) i++; continue; }
+    if (a.startsWith("@")) continue;
+    if (/[\\\/]/.test(a) || a.endsWith(".png")) return a.endsWith(".png") ? a : a + ".png";
+    return undefined; // first positional non-path token is not an out path
+  }
+  return undefined;
+}
+
+export async function writeSidecar(meta) {
+  if (!meta?.out) return null;
+  try {
+    if (existsSync(meta.out)) {
+      const buf = readFileSync(meta.out);
+      meta.size = buf.length;
+      meta.hash = shortHash(buf);
+    }
+  } catch {}
+  const sidecar = meta.out.replace(/\.png$/i, ".json");
+  writeFileSync(sidecar, JSON.stringify(meta, null, 2));
+  return sidecar;
+}
+
+export function findStepPng(dir, stepName) {
+  const target = String(stepName || "").replace(/.png$/i, "").trim();
+  const files = readdirSyncFiles(dir);
+  if (!files.length) return null;
+  if (!target) return null;
+  // exact basename match first (handles refs like "baseline" or "00-baseline")
+  for (const f of files) {
+    const base = basename(f, ".png");
+    if (base === target) return join(dir, f);
+  }
+  // match the "NN-" prefix-stripped basename (e.g. "03-baseline" referenced as "baseline")
+  for (const f of files) {
+    const base = basename(f, ".png");
+    const m = base.match(/^\d+-(.+)$/);
+    if (m && m[1] === target) return join(dir, f);
+  }
+  // loose suffix match
+  for (const f of files) {
+    const base = basename(f, ".png");
+    if (base.endsWith("-" + target)) return join(dir, f);
+  }
+  // substring match last resort
+  for (const f of files) {
+    const base = basename(f, ".png");
+    if (base.includes(target)) return join(dir, f);
+  }
+  return null;
+}
+
+function readdirSyncFiles(dir) {
+  try { return readdirSync(dir).filter(f => f.endsWith(".png")); } catch { return []; }
+}
+
+const ESCAPE_MAP = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+export function escapeHtml(s) {
+  return String(s ?? "").replace(/[&<>"']/g, c => ESCAPE_MAP[c]);
+}
+
+export function stripLarge(obj) {
+  if (!obj || typeof obj !== "object") return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === "viewport" || k === "flags") continue;
+    if (typeof v === "string" && v.length > 400) { out[k] = v.slice(0, 400) + "…"; continue; }
+    out[k] = v;
+  }
+  return out;
+}
+
+export function renderSweepHtml(summary) {
+  if (!summary?.steps?.length) return `<!doctype html><html><meta charset="utf-8"><title>pursor sweep — empty</title><body><p>No steps.</p></body></html>`;
+  const rows = summary.steps.map(s => {
+    const png = s.meta && s.meta.out ? basename(s.meta.out) : null;
+    const errCell = s.ok ? "" : `<div class="err">${escapeHtml(s.error || "")}</div>`;
+    const meta = s.meta ? `<pre>${escapeHtml(JSON.stringify(stripLarge(s.meta), null, 2))}</pre>` : "";
+    return `<article class="step ${s.ok ? "ok" : "fail"}"><header><span class="i">#${s.i}</span><span class="name">${escapeHtml(s.name)}</span><span class="op">${escapeHtml(s.op || "")}</span><span class="ms">${s.ms}ms</span><span class="status">${s.ok ? "OK" : "FAIL"}</span></header>${png ? `<img src="${png}" loading="lazy" alt="${escapeHtml(s.name)}" />` : ""}${errCell}${meta}</article>`;
+  }).join("\n");
+  return `<!doctype html><html><head><meta charset="utf-8"><title>pursor sweep — ${escapeHtml(summary.name || "")}</title>
+<style>:root { color-scheme: light dark; } body { font: 14px/1.4 -apple-system, system-ui, sans-serif; margin: 0; background:#0b0b0b; color:#eee; } header.bar { padding: 12px 20px; background:#181818; border-bottom: 1px solid #2a2a2a; position: sticky; top:0; } header.bar h1 { font-size: 16px; margin: 0; } header.bar .meta { font-size: 12px; opacity: .7; } main { display: grid; grid-template-columns: repeat(auto-fill, minmax(360px, 1fr)); gap: 12px; padding: 12px; } article.step { background:#161616; border:1px solid #2a2a2a; border-radius: 8px; overflow: hidden; } article.step.fail { border-color: #b04; } article.step header { display: flex; gap: 6px; padding: 8px 10px; font-size: 12px; background: #1c1c1c; align-items: center; } article.step header .i { color:#888; } article.step header .name { font-weight: 600; } article.step header .op { color:#9ad; font-family: monospace; } article.step header .ms { color:#888; margin-left: auto; } article.step header .status { padding: 1px 6px; border-radius: 4px; background:#234; color:#adf; font-size: 11px; } article.step.fail header .status { background:#421; color:#fbb; } article.step img { display: block; width: 100%; height: auto; background:#000; } article.step pre { margin: 0; padding: 8px 10px; font-size: 11px; max-height: 180px; overflow: auto; background:#111; color:#aaa; border-top: 1px solid #222; } article.step .err { padding: 8px 10px; background: #2a0e0e; color: #fbb; font-size: 12px; }</style></head>
+<body><header class="bar"><h1>pursor sweep: ${escapeHtml(summary.name || "(unnamed)")}</h1><div class="meta">${summary.steps.length} steps &middot; ${escapeHtml(summary.outDir)} &middot; ${escapeHtml(summary.ts)}</div></header><main>${rows}</main></body></html>`;
+}
+
+export function renderEveryViewportHtml(summary) {
+  if (!summary?.captures?.length) return '<!doctype html><html><meta charset="utf-8"><title>every-viewport &mdash; empty</title><body><p>No captures.</p></body></html>';
+  const rows = summary.captures.map(c => {
+    const png = c.meta?.out ? basename(c.meta.out) : null;
+    const err = c.error ? '<div class="err">' + escapeHtml(c.error) + '</div>' : '';
+    const img = png ? '<img src="' + png + '" loading="lazy" alt="' + escapeHtml(c.name) + '" />' : '';
+    return '<article class="step ' + (c.ok ? "ok" : "fail") + '"><header><span class="name">' + escapeHtml(c.name) + '</span><span class="ms">' + c.ms + 'ms</span><span class="status">' + (c.ok ? "OK" : "FAIL") + '</span></header>' + img + err + '</article>';
+  }).join("\n");
+  return '<!doctype html><html><head><meta charset="utf-8"><title>every-viewport &mdash; ' + escapeHtml(summary.url || "") + '</title><style>:root{color-scheme:light dark}body{font:14px/1.4 -apple-system,system-ui,sans-serif;margin:0;background:#0b0b0b;color:#eee}header.bar{padding:12px 20px;background:#181818;border-bottom:1px solid #2a2a2a;position:sticky;top:0}header.bar h1{font-size:16px;margin:0}header.bar .meta{font-size:12px;opacity:.7}main{display:grid;grid-template-columns:repeat(auto-fill,minmax(360px,1fr));gap:12px;padding:12px}article.step{background:#161616;border:1px solid #2a2a2a;border-radius:8px;overflow:hidden}article.step.fail{border-color:#b04}article.step header{display:flex;gap:6px;padding:8px 10px;font-size:12px;background:#1c1c1c;align-items:center}article.step header .name{font-weight:600}article.step header .ms{color:#888;margin-left:auto}article.step header .status{padding:1px 6px;border-radius:4px;background:#234;color:#adf;font-size:11px}article.step.fail header .status{background:#421;color:#fbb}article.step img{display:block;width:100%;height:auto;background:#000}article.step .err{padding:8px 10px;background:#2a0e0e;color:#fbb;font-size:12px}</style></head><body><header class="bar"><h1>every-viewport: ' + escapeHtml(summary.url || "") + '</h1><div class="meta">' + summary.captures.length + ' viewports &middot; ' + escapeHtml(summary.outDir) + ' &middot; ' + escapeHtml(summary.ts) + '</div></header><main>' + rows + '</main></body></html>';
+}

package/src/viewport.js

@@ -0,0 +1,39 @@
+// viewport presets + flag -> viewport resolution.
+
+export const VIEWPORTS = {
+  "desktop-1280":  { width: 1280, height: 800,  dpr: 1, label: "Desktop 1280x800" },
+  "desktop-1440":  { width: 1440, height: 900,  dpr: 1, label: "Desktop 1440x900" },
+  "desktop-1920":  { width: 1920, height: 1080, dpr: 1, label: "Desktop 1920x1080" },
+  "desktop-2560":  { width: 2560, height: 1440, dpr: 1, label: "QHD 2560x1440" },
+  "ultrawide-3440":{ width: 3440, height: 1440, dpr: 1, label: "Ultrawide 3440x1440" },
+  "tablet-768":    { width: 768,  height: 1024, dpr: 2, label: "Tablet portrait 768x1024 @2x" },
+  "tablet-1024":   { width: 1024, height: 768,  dpr: 2, label: "Tablet landscape 1024x768 @2x" },
+  "mobile-375":    { width: 375,  height: 812,  dpr: 3, label: "iPhone X 375x812 @3x" },
+  "mobile-414":    { width: 414,  height: 896,  dpr: 3, label: "iPhone XR 414x896 @3x" },
+  "mobile-360":    { width: 360,  height: 800,  dpr: 2, label: "Android 360x800 @2x" },
+};
+
+export const DEFAULT_VIEWPORT = VIEWPORTS["desktop-1280"];
+
+import { listViewportPresets } from "./plugin.js";
+import { asNum } from "./util.js";
+
+export function listViewports() {
+  return Object.entries({ ...VIEWPORTS, ...listViewportPresets() }).map(([k, v]) => ({ name: k, ...v }));
+}
+
+export function resolveViewport(flags = {}) {
+  const all = { ...VIEWPORTS, ...listViewportPresets() };
+  const name = flags.preset || flags.viewport;
+  if (name && all[name]) return { ...all[name], name };
+  if (flags.width || flags.height) {
+    return {
+      name: "custom",
+      label: `Custom ${flags.width}x${flags.height}`,
+      width: asNum(flags.width, DEFAULT_VIEWPORT.width),
+      height: asNum(flags.height, DEFAULT_VIEWPORT.height),
+      dpr: asNum(flags.dpr, 1),
+    };
+  }
+  return { ...DEFAULT_VIEWPORT, name: "desktop-1280" };
+}