pursr 0.4.0 → 0.5.0

package/README.md

@@ -413,11 +413,11 @@ npm install --save-dev playwright-core
 npm test
 ```
 
-`npm test` runs 47 unit + integration tests (Node's built-in test runner, zero test deps). Coverage includes: viewport resolution, flag parsing, selector parsing, HTML escaping, hashing, baseline storage, sweep-plan validation, MCP resources, HAR 1.2 shape, auth state, and end-to-end CLI smoke tests.
+`npm test` runs 53 unit + integration tests (Node's built-in test runner, zero test deps). Coverage includes: viewport resolution, flag parsing, selector parsing, HTML escaping, hashing, baseline storage, sweep-plan validation, MCP resources, HAR 1.2 shape, auth state, and end-to-end CLI smoke tests.
 
 ```
 src/           - 25 modules
-test/          - 47 tests, 0 failures
+test/          - 53 tests, 0 failures
 plugins/       - 2 built-in plugins, auto-loaded
 ```
 
@@ -429,12 +429,43 @@ plugins/       - 2 built-in plugins, auto-loaded
 - [x] HAR 1.2 capture
 - [x] Auth state (Playwright storageState)
 - [x] Parallel sweep workers
-- [ ] Watch mode (`pursr watch <url>`)
-- [ ] Component-level snapshot (`pursr snap <selector>`)
+- [x] Watch mode (`pursr watch <url>`)
+- [x] Component-level snapshot (`pursr snap <selector>`)
 - [ ] PDF report export
 - [ ] Cloud output adapters (S3 / GCS)
 - [ ] AI diff summary (vision model)
 
+## Watch Mode (v0.5.0)
+
+```bash
+# Re-shoot every time a CSS or HTML file changes
+pursr watch https://my.app --on src/**/*.css --on src/**/*.html
+
+# Re-run a sweep plan on file change
+pursr watch --plan ./plan.json --on src/**/*.{css,html}
+
+# Default (no --on) = watch everything in cwd
+pursr watch https://my.app
+```
+
+Glob patterns: * (one path segment), ** (any depth), ? (one char), backslash-X (literal X). Debounce is 300ms by default.
+
+## Component Snapshots (v0.5.0)
+
+```bash
+# Capture one screenshot per matched element
+pursr snap https://my.app a.btn --out ./snaps --max 20
+
+# Use auto-heal selector chain
+pursr snap https://my.app "text=Sign up" --out ./snaps
+
+# Promote to baselines in one command
+pursr snap https://my.app article.product --baseline myapp
+```
+
+Each capture is clipped precisely to the elements bounding box (even when scrolled offscreen), labelled with aria-label / text / tag, and written to ./snaps/<index>-<label>.png + snap.json summary.
+
+---
 ## License
 
 MIT (c) 2026 - [0xheycat](https://github.com/0xheycat)

package/bin/pursr.mjs

@@ -16,7 +16,8 @@ import { runAudit } from "../src/plugin-audit.js";
 import { captureDomSnapshot } from "../src/dom-snapshot.js";
 import { listViewports } from "../src/viewport.js";
 import { parseFlags, asNum, readArg, makeOut, pickOutPath } from "../src/util.js";
-import { writeFileSync } from "node:fs";
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { readFileSync as _readFileSync } from "node:fs";
 const readFile = _readFileSync;
 import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
@@ -42,6 +43,16 @@ function die(msg, code = 2) {
 const argv = process.argv;
 const [, , cmd, a, b, c, d] = argv;
 const url = process.env.PURSOR_URL || a;
+// Top-level --plan / --out parsing for subcommands that need it before dispatch
+function _topOpts() {
+  const o = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--plan" && i + 1 < argv.length) o.plan = argv[++i];
+    if (argv[i] === "--out" && i + 1 < argv.length) o.out = argv[++i];
+  }
+  return o;
+}
+const opts = _topOpts();
 
 // Plugin loading: scan for --plugin <path> and built-in plugins/
 const pluginPaths = [];
@@ -218,6 +229,62 @@ await loadPlugins(pluginPaths);
               }
               break;
             }
+            case "watch": {
+              // pursr watch <url> [--out ./shot.png] [--on <glob>...] [--plan <plan.json>]
+              if (opts.plan) {
+                if (!existsSync(opts.plan)) die("watch: plan not found: " + opts.plan);
+              } else if (!url) {
+                die("watch: missing <url> (or use --plan <plan.json>)");
+              }
+              const { startWatch } = await import("../src/watch.js");
+              const out = (b && !b.startsWith("--")) ? b : (opts.out || makeOut("watch.png"));
+              if (out && out !== "--plan") mkdirSync(dirname(out), { recursive: true });
+              const flags = parseFlags(argv.slice(3));
+              const onGlobs = [];
+              for (let i = 0; i < argv.length; i++) {
+                if (argv[i] === "--on" && i + 1 < argv.length) onGlobs.push(argv[++i]);
+              }
+              console.error(JSON.stringify({ watching: true, url: opts.plan ? null : url, plan: opts.plan || null, out, on: onGlobs }));
+              const w = await startWatch({
+                url: opts.plan ? undefined : url,
+                out,
+                plan: opts.plan,
+                on: onGlobs,
+                flags,
+                verbose: true,
+                onChange: (e) => console.error(JSON.stringify({ event: e.type, path: e.path, captureOk: !e.capture?.error, captureOut: e.capture?.out, ts: e.ts })),
+              });
+              // Keep alive until SIGINT
+              await new Promise((resolve) => {
+                process.on("SIGINT", () => { console.error("[pursr watch] stopping..."); w.close().then(resolve); });
+                process.on("SIGTERM", () => { w.close().then(resolve); });
+              });
+              console.log(JSON.stringify({ fires: w.fires() }, null, 2));
+              break;
+            }
+            case "snap": {
+              // pursr snap <url> <selector> [--out <dir>] [--name <slug>] [--max N] [--baseline <project>]
+              if (!url) die("snap: missing <url>");
+              const sel = b; if (!sel) die("snap: missing <selector>");
+              const flags = parseFlags(argv.slice(4));
+              const { runSnap, approveSnapsAsBaselines } = await import("../src/snap.js");
+              const outDir = flags.out || makeOut("snaps").replace(/pursor-[^-]+-snap\.png$/, "snaps");
+              const snap = await runSnap({ url, selector: sel, outDir, name: flags.name, max: flags.max, flags });
+              console.log(JSON.stringify({
+                url: snap.url,
+                selector: snap.selector,
+                count: snap.count,
+                captured: snap.captured,
+                outDir: snap.outDir,
+                captures: snap.captures,
+                nav: snap.nav,
+              }, null, 2));
+              if (flags.baseline) {
+                const r = approveSnapsAsBaselines({ project: flags.baseline, snapResult: snap });
+                console.error(JSON.stringify({ approved: r.length, project: flags.baseline }));
+              }
+              break;
+            }
             default: { die(`unknown subcommand: ${cmd}`); }
     }
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Visual QA, audit, and MCP for the browser. One CLI + one MCP server for screenshots, sweeps, baselines, diffs, axe-core a11y audits, HAR capture, and auth state — with parallel sweep workers, auto-healing selectors, and a plugin system. Zero browser bundled: drives your system Chrome via Playwright.",
   "homepage": "https://github.com/0xheycat/pursr",
@@ -34,7 +34,9 @@
     "./sweep-schema": "./src/sweep-schema.js",
     "./mcp-resources": "./src/mcp-resources.js",
     "./har": "./src/har.js",
-    "./auth": "./src/auth.js"
+    "./auth": "./src/auth.js",
+    "./watch": "./src/watch.js",
+    "./snap": "./src/snap.js"
   },
   "files": [
     "bin",

package/src/index.js

@@ -39,6 +39,8 @@ import { validateSweepPlan, registerSweepOp } from "./sweep-schema.js";
 import { listResources, readResource, recordResource } from "./mcp-resources.js";
 import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
 import { saveAuthState, loadAuthState, listAuthStates, deleteAuthState } from "./auth.js";
+import { startWatch, matchGlob, shouldFire } from "./watch.js";
+import { runSnap, approveSnapsAsBaselines } from "./snap.js";
 
 
 // Derive VERSION from package.json to prevent drift
@@ -72,6 +74,9 @@ export {
   // v5: HAR capture, auth state, parallel sweep
   startHarCapture, stopHarCapture, writeHar,
   saveAuthState, loadAuthState, listAuthStates, deleteAuthState,
+  // v6: watch mode, component snapshot
+  startWatch, matchGlob, shouldFire,
+  runSnap, approveSnapsAsBaselines,
   VERSION,
 };
 

package/src/snap.js

@@ -0,0 +1,129 @@
+// pursor — component-level snapshot.
+//
+// Capture one screenshot per matched element (Percy / Chromatic style).
+// Uses Playwright's elementHandle.screenshot() to clip precisely to the
+// element's bounding box, even if it scrolls offscreen.
+//
+// CLI:
+//   pursr snap <url> "<selector>" [--out ./snaps/] [--selector "a.btn"]
+//   pursr snap <url> "<selector>" --baseline myapp
+//
+// Library:
+//   import { runSnap } from "pursr/snap";
+//   const result = await runSnap({ url, selector, outDir: "./snaps" });
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle, CLICK_TIMEOUT_MS } from "./overlays.js";
+import { resolveLocator, parseTextSelector } from "./selector.js";
+import { resolveHealedSelector } from "./selector-heal.js";
+import { asNum, nowIso, requireArg } from "./util.js";
+import { saveBaseline, diffKey } from "./baseline.js";
+
+/**
+ * Capture one screenshot per matched element on a page.
+ *
+ * @param {object} opts
+ * @param {string} opts.url                    Target URL
+ * @param {string|string[]} opts.selector      CSS selector, or chain (heal-fallback)
+ * @param {string} [opts.outDir=./snaps]      Output directory
+ * @param {string} [opts.name]                 Optional name prefix (defaults to selector slug)
+ * @param {object} [opts.flags]                Viewport/flags (resolved via resolveViewport)
+ * @param {number} [opts.settleMs=400]         Wait after locator resolves
+ * @param {number} [opts.max=20]               Max elements to capture (safety)
+ * @param {boolean} [opts.scrollIntoView=true] Scroll each into view before capture
+ * @param {boolean} [opts.omitBackground=false] Transparent background
+ * @returns {Promise<{ url, selector, count, captures: [...], outDir, ts }>}
+ */
+export async function runSnap(opts) {
+  requireArg("url", opts?.url, "string");
+  requireArg("selector", opts?.selector, "string");
+  const url = opts.url;
+  const selector = opts.selector;
+  const outDir = opts.outDir || "./snaps";
+  const flags = opts.flags || {};
+  const viewport = resolveViewport(flags);
+  const settleMs = asNum(opts.settleMs, 400);
+  const max = Math.max(1, asNum(opts.max, 20));
+  const scrollIntoView = opts.scrollIntoView !== false;
+  const omitBackground = !!opts.omitBackground;
+  const name = opts.name || (Array.isArray(selector) ? selector[0] : selector).replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").slice(0, 48) || "snap";
+
+  mkdirSync(outDir, { recursive: true });
+  const browser = await launch();
+  const captures = [];
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url);
+    await settle(page);
+
+    // Resolve to a locator (with auto-heal chain support)
+    const locator = Array.isArray(selector)
+      ? (await resolveHealedSelector(page, selector)).locator
+      : await resolveLocator(page, selector);
+
+    const count = await locator.count();
+    if (!count) throw new Error(`snap: selector matched 0 elements`);
+
+    const limit = Math.min(count, max);
+    for (let i = 0; i < limit; i++) {
+      const handle = locator.nth(i);
+      try {
+        if (scrollIntoView) await handle.scrollIntoViewIfNeeded({ timeout: CLICK_TIMEOUT_MS }).catch(() => {});
+        await page.waitForTimeout(settleMs);
+        const file = join(outDir, `${String(i).padStart(2, "0")}-${name}.png`);
+        await handle.screenshot({ path: file, omitBackground });
+        // Try to get a human label
+        let label = null;
+        try {
+          label = (await handle.evaluate((el) => {
+            return el.getAttribute("aria-label")
+              || el.getAttribute("title")
+              || el.getAttribute("alt")
+              || (el.textContent || "").trim().slice(0, 80)
+              || el.tagName.toLowerCase();
+          }));
+        } catch {}
+        captures.push({ i, file, label });
+      } catch (e) {
+        captures.push({ i, error: e.message });
+      }
+    }
+
+    // Write summary
+    const summary = {
+      url,
+      selector,
+      viewport: { width: viewport.width, height: viewport.height, dpr: viewport.dpr },
+      count,
+      captured: captures.length,
+      outDir,
+      captures,
+      ts: nowIso(),
+      nav: { status: r.status, title: r.title },
+    };
+    writeFileSync(join(outDir, "snap.json"), JSON.stringify(summary, null, 2));
+    return summary;
+  } finally {
+    try { await browser.close(); } catch {}
+  }
+}
+
+/**
+ * Save a snap result as baselines (one per captured element).
+ * Useful for "approve all current component screenshots as the new baseline".
+ */
+export async function approveSnapsAsBaselines({ project, snapResult, id }) {
+  if (!snapResult?.captures) throw new Error("approveSnapsAsBaselines: missing snapResult");
+  const _id = id || diffKey({ url: snapResult.url, viewport: snapResult.viewport, flags: {} });
+  const out = [];
+  for (const c of snapResult.captures) {
+    if (c.error || !c.file) continue;
+    const step = `snap-${String(c.i).padStart(2, "0")}-${(c.label || "elem").replace(/[^a-z0-9._-]+/gi, "_").slice(0, 32)}`;
+    const saved = saveBaseline({ project, id: _id, step, png: c.file, meta: { url: snapResult.url, viewport: snapResult.viewport, flags: {} } });
+    out.push(saved);
+  }
+  return out;
+}

package/src/watch.js

@@ -0,0 +1,134 @@
+// pursor - watch mode.
+//
+// Re-runs a shoot/sweep whenever watched files change.
+
+import { watch as fsWatch, existsSync } from "node:fs";
+import { resolve, join, dirname, relative } from "node:path";
+import { runShootWithSidecar } from "./shoot.js";
+import { runSweep } from "./sweep.js";
+import { nowIso } from "./util.js";
+
+function normalizeGlobs(globs) {
+  if (!globs) return null;
+  const arr = Array.isArray(globs) ? globs : [globs];
+  return arr.filter(Boolean);
+}
+
+const BC = String.fromCharCode(92);
+const ESC_RX = /[.+^$X()|YZ\\]/g;
+function escapeForRegex(s) {
+  return s.replace(ESC_RX, function (m) {
+    if (m === "X") return BC + "$";
+    if (m === "Y") return BC + "{";
+    if (m === "Z") return BC + "}";
+    return BC + m;
+  });
+}
+
+function matchGlob(path, pattern) {
+  const p = String(path).split(BC).join("/");
+  const pat = String(pattern);
+  let re = "^";
+  for (let i = 0; i < pat.length; i++) {
+    const c = pat[i];
+    if (c === BC) {
+      const next = pat[i + 1];
+      if (next === undefined) { re += BC + BC; continue; }
+      re += escapeForRegex(next);
+      i++;
+    } else if (c === "*") {
+      if (pat[i + 1] === "*") { re += ".*"; i++; }
+      else { re += "[^/]*"; }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += escapeForRegex(c);
+    }
+  }
+  re += "$";
+  return new RegExp(re).test(p);
+}
+
+function shouldFire(path, globs) {
+  if (!globs || globs.length === 0) return true;
+  return globs.some((g) => matchGlob(path, g));
+}
+
+function debounce(fn, ms) {
+  let t = null;
+  return (...args) => {
+    if (t) clearTimeout(t);
+    t = setTimeout(() => { t = null; fn(...args); }, ms);
+  };
+}
+
+export async function startWatch(opts) {
+  if (!opts.url && !opts.plan) throw new Error("startWatch: requires url or plan");
+  const globs = normalizeGlobs(opts.on);
+  const debounceMs = opts.debounceMs ?? 300;
+  const verbose = !!opts.verbose;
+
+  let fireCount = 0;
+  let runningPromise = Promise.resolve();
+  let closed = false;
+
+  const runOne = async (event) => {
+    if (closed) return;
+    fireCount++;
+    try {
+      let capture = null;
+      if (opts.plan) {
+        capture = await runSweep(opts.plan, opts.outDir);
+      } else {
+        capture = await runShootWithSidecar({ url: opts.url, out: opts.out, flags: opts.flags || {} });
+      }
+      if (typeof opts.onChange === "function") {
+        try { await opts.onChange({ ...event, capture }); } catch (e) {
+          if (verbose) console.error("[pursr watch] onChange error:", e.message);
+        }
+      }
+    } catch (e) {
+      if (verbose) console.error("[pursr watch] capture error:", e.message);
+    }
+  };
+
+  const debouncedRun = debounce((event) => { runningPromise = runningPromise.then(() => runOne(event)); }, debounceMs);
+
+  const targets = globs && globs.length > 0
+    ? globs.map((g) => {
+        const lit = g.split(/[*?]/)[0];
+        return resolve(lit || ".");
+      })
+    : [resolve(process.cwd())];
+
+  const watchers = [];
+  for (const target of targets) {
+    if (!existsSync(target)) continue;
+    try {
+      const w = fsWatch(target, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        const full = join(target, filename);
+        const rel = relative(process.cwd(), full).split(BC).join("/");
+        if (!shouldFire(rel, globs)) return;
+        debouncedRun({ type: eventType, path: full, ts: nowIso() });
+      });
+      w.on("error", (e) => { if (verbose) console.error("[pursr watch] watcher error:", e.message); });
+      watchers.push(w);
+    } catch (e) {
+      if (verbose) console.error("[pursr watch] cannot watch", target, e.message);
+    }
+  }
+
+  runningPromise = runningPromise.then(() => runOne({ type: "init", path: null, ts: nowIso() }));
+
+  return {
+    close: async () => {
+      closed = true;
+      for (const w of watchers) { try { w.close(); } catch {} }
+      await runningPromise.catch(() => {});
+    },
+    fires: () => fireCount,
+  };
+}
+
+export { matchGlob, shouldFire };