pursr 0.5.0 → 0.7.0

package/src/frames.js

@@ -1,34 +1,34 @@
-// Frames: capture N screenshots at intervalMs.
-
-import { launch, newPage } from "./runway.js";
-import { resolveViewport } from "./viewport.js";
-import { gotoOrThrow, settle } from "./overlays.js";
-import { asNum, nowIso, shortHash, requireArg } from "./util.js";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-export async function runFrames({ url, count, intervalMs, outDir, flags = {}, browser: extBrowser }) {
-  requireArg("url", url, "string");
-  const n = Math.max(1, Math.min(120, asNum(count, 8)));
-  const stepMs = Math.max(16, asNum(intervalMs, 250));
-  const dir = outDir;
-  mkdirSync(dir, { recursive: true });
-  const viewport = resolveViewport(flags);
-  const ownBrowser = !extBrowser;
-  const browser = extBrowser || await launch();
-  const meta = { url, outDir: dir, count: n, intervalMs: stepMs, viewport, files: [], ts: nowIso() };
-  try {
-    const page = await newPage(browser, viewport);
-    const r = await gotoOrThrow(page, url); await settle(page);
-    meta.status = r.status; meta.title = r.title;
-    for (let i = 0; i < n; i++) {
-      const f = join(dir, `frame-${String(i).padStart(3, "0")}.png`);
-      await page.screenshot({ path: f, fullPage: false });
-      const buf = readFileSync(f);
-      meta.files.push({ i, out: f, size: buf.length, hash: shortHash(buf) });
-      if (i + 1 < n) await page.waitForTimeout(stepMs);
-    }
-    writeFileSync(join(dir, "frames.json"), JSON.stringify(meta, null, 2));
-    return meta;
-  } finally { if (ownBrowser) try { await browser.close(); } catch {} }
+// Frames: capture N screenshots at intervalMs.
+
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle } from "./overlays.js";
+import { asNum, nowIso, shortHash, requireArg } from "./util.js";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export async function runFrames({ url, count, intervalMs, outDir, flags = {}, browser: extBrowser }) {
+  requireArg("url", url, "string");
+  const n = Math.max(1, Math.min(120, asNum(count, 8)));
+  const stepMs = Math.max(16, asNum(intervalMs, 250));
+  const dir = outDir;
+  mkdirSync(dir, { recursive: true });
+  const viewport = resolveViewport(flags);
+  const ownBrowser = !extBrowser;
+  const browser = extBrowser || await launch();
+  const meta = { url, outDir: dir, count: n, intervalMs: stepMs, viewport, files: [], ts: nowIso() };
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    meta.status = r.status; meta.title = r.title;
+    for (let i = 0; i < n; i++) {
+      const f = join(dir, `frame-${String(i).padStart(3, "0")}.png`);
+      await page.screenshot({ path: f, fullPage: false });
+      const buf = readFileSync(f);
+      meta.files.push({ i, out: f, size: buf.length, hash: shortHash(buf) });
+      if (i + 1 < n) await page.waitForTimeout(stepMs);
+    }
+    writeFileSync(join(dir, "frames.json"), JSON.stringify(meta, null, 2));
+    return meta;
+  } finally { if (ownBrowser) try { await browser.close(); } catch {} }
 }

package/src/har.js

@@ -1,159 +1,159 @@
-// pursor — HAR (HTTP Archive) capture.
-//
-// Hooks page.on("request") / page.on("response") / page.on("requestfailed")
-// on an active page and produces a HAR 1.2 spec blob:
-//   { log: { version: "1.2", creator: {...}, browser: {...}, pages: [...], entries: [...] } }
-//
-// Use in code:
-//   const { startHarCapture, stopHarCapture } = await import("pursor/har");
-//   const har = await startHarCapture(page);
-//   await page.goto(url);
-//   await stopHarCapture(page);  // returns the HAR object
-//
-// Or via CLI/sweep:
-//   pursor shoot <url> --har ./out/req.har.json
-//
-// HAR is useful for:
-//   - killing flakiness from analytics/ads/CDN by mocking responses later
-//   - inspecting what the page actually fetched during a capture
-//   - regression diffing along with visual diffs
-
-import { writeFileSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
-import { nowIso } from "./util.js";
-
-const SYM = Symbol.for("pursor.har.capture");
-
-function makeEntry(req, resp, startTs, endTs) {
-  const url = req.url();
-  const u = new URL(url);
-  const headersList = (obj) => {
-    if (!obj) return [];
-    try {
-      const out = [];
-      for (const [name, value] of Object.entries(obj)) {
-        if (Array.isArray(value)) {
-          for (const v of value) out.push({ name, value: String(v) });
-        } else {
-          out.push({ name, value: String(value) });
-        }
-      }
-      return out;
-    } catch { return []; }
-  };
-  const queryString = u.search ? u.search.slice(1).split("&").filter(Boolean).map(kv => {
-    const [k, v = ""] = kv.split("=");
-    return { name: decodeURIComponent(k), value: decodeURIComponent(v) };
-  }) : [];
-  const postData = req.postData() ? { mimeType: req.postData() || "application/octet-stream", text: req.postData() } : undefined;
-  const entry = {
-    pageref: req.frame()?.url?.() || "_top",
-    startedDateTime: new Date(startTs).toISOString(),
-    time: Math.max(0, endTs - startTs),
-    request: {
-      method: req.method(),
-      url,
-      httpVersion: "HTTP/1.1",
-      cookies: [],
-      headers: headersList(req.headers()),
-      queryString,
-      headersSize: -1,
-      bodySize: postData?.text?.length || 0,
-      postData,
-    },
-    response: resp ? {
-      status: resp.status(),
-      statusText: resp.statusText() || "",
-      httpVersion: "HTTP/1.1",
-      cookies: [],
-      headers: headersList(resp.headers()),
-      content: { size: -1, mimeType: resp.headers()?.["content-type"] || "" },
-      redirectURL: resp.headers()?.location || "",
-      headersSize: -1,
-      bodySize: -1,
-    } : { status: 0, statusText: "Failed", httpVersion: "HTTP/1.1", cookies: [], headers: [], content: { size: 0, mimeType: "" }, redirectURL: "", headersSize: -1, bodySize: -1 },
-    cache: {},
-    timings: { send: 0, wait: Math.max(0, endTs - startTs), receive: 0 },
-    serverIPAddress: "",
-    connection: "",
-  };
-  return entry;
-}
-
-export async function startHarCapture(page, opts = {}) {
-  if (!page) throw new Error("startHarCapture: page required");
-  if (page[SYM]) return page[SYM]; // idempotent
-  const started = Date.now();
-  const entries = [];
-  const pending = new Map(); // req -> startTs
-  const state = {
-    started,
-    creator: { name: "pursor", version: opts.version || "0.3.0" },
-    browser: { name: "chromium", version: "playwright-core" },
-    pages: [],
-    entries,
-    pending,
-  };
-  const onReq = (req) => {
-    pending.set(req, Date.now());
-  };
-  const onResp = async (resp) => {
-    try {
-      const req = resp.request();
-      const startTs = pending.get(req) || Date.now();
-      pending.delete(req);
-      const endTs = Date.now();
-      entries.push(makeEntry(req, resp, startTs, endTs));
-    } catch {}
-  };
-  const onFailed = (req) => {
-    try {
-      const startTs = pending.get(req) || Date.now();
-      pending.delete(req);
-      entries.push(makeEntry(req, null, startTs, Date.now()));
-    } catch {}
-  };
-  page.on("request", onReq);
-  page.on("response", onResp);
-  page.on("requestfailed", onFailed);
-  state._teardown = () => {
-    try { page.off("request", onReq); } catch {}
-    try { page.off("response", onResp); } catch {}
-    try { page.off("requestfailed", onFailed); } catch {}
-  };
-  page[SYM] = state;
-  return state;
-}
-
-export function stopHarCapture(page) {
-  if (!page || !page[SYM]) return null;
-  const state = page[SYM];
-  try { state._teardown?.(); } catch {}
-  delete page[SYM];
-  return finalizeHar(state);
-}
-
-export function finalizeHar(state) {
-  if (!state) return null;
-  return {
-    log: {
-      version: "1.2",
-      creator: state.creator,
-      browser: state.browser,
-      pages: state.pages,
-      entries: state.entries,
-    },
-    _meta: {
-      started: state.started,
-      finished: Date.now(),
-      entryCount: state.entries.length,
-    },
-  };
-}
-
-export async function writeHar(har, file) {
-  if (!har || !file) return null;
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, JSON.stringify(har, null, 2), "utf8");
-  return file;
+//  pursr — HAR (HTTP Archive) capture.
+//
+// Hooks page.on("request") / page.on("response") / page.on("requestfailed")
+// on an active page and produces a HAR 1.2 spec blob:
+//   { log: { version: "1.2", creator: {...}, browser: {...}, pages: [...], entries: [...] } }
+//
+// Use in code:
+//   const { startHarCapture, stopHarCapture } = await import("pursr/har");
+//   const har = await startHarCapture(page);
+//   await page.goto(url);
+//   await stopHarCapture(page);  // returns the HAR object
+//
+// Or via CLI/sweep:
+//   pursr shoot <url> --har ./out/req.har.json
+//
+// HAR is useful for:
+//   pursr - killing flakiness from analytics/ads/CDN by mocking responses later
+//   pursr - inspecting what the page actually fetched during a capture
+//   pursr - regression diffing along with visual diffs
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { nowIso } from "./util.js";
+
+const SYM = Symbol.for("pursr.har.capture");
+
+function makeEntry(req, resp, startTs, endTs) {
+  const url = req.url();
+  const u = new URL(url);
+  const headersList = (obj) => {
+    if (!obj) return [];
+    try {
+      const out = [];
+      for (const [name, value] of Object.entries(obj)) {
+        if (Array.isArray(value)) {
+          for (const v of value) out.push({ name, value: String(v) });
+        } else {
+          out.push({ name, value: String(value) });
+        }
+      }
+      return out;
+    } catch { return []; }
+  };
+  const queryString = u.search ? u.search.slice(1).split("&").filter(Boolean).map(kv => {
+    const [k, v = ""] = kv.split("=");
+    return { name: decodeURIComponent(k), value: decodeURIComponent(v) };
+  }) : [];
+  const postData = req.postData() ? { mimeType: req.postData() || "application/octet-stream", text: req.postData() } : undefined;
+  const entry = {
+    pageref: req.frame()?.url?.() || "_top",
+    startedDateTime: new Date(startTs).toISOString(),
+    time: Math.max(0, endTs - startTs),
+    request: {
+      method: req.method(),
+      url,
+      httpVersion: "HTTP/1.1",
+      cookies: [],
+      headers: headersList(req.headers()),
+      queryString,
+      headersSize: -1,
+      bodySize: postData?.text?.length || 0,
+      postData,
+    },
+    response: resp ? {
+      status: resp.status(),
+      statusText: resp.statusText() || "",
+      httpVersion: "HTTP/1.1",
+      cookies: [],
+      headers: headersList(resp.headers()),
+      content: { size: -1, mimeType: resp.headers()?.["content-type"] || "" },
+      redirectURL: resp.headers()?.location || "",
+      headersSize: -1,
+      bodySize: -1,
+    } : { status: 0, statusText: "Failed", httpVersion: "HTTP/1.1", cookies: [], headers: [], content: { size: 0, mimeType: "" }, redirectURL: "", headersSize: -1, bodySize: -1 },
+    cache: {},
+    timings: { send: 0, wait: Math.max(0, endTs - startTs), receive: 0 },
+    serverIPAddress: "",
+    connection: "",
+  };
+  return entry;
+}
+
+export async function startHarCapture(page, opts = {}) {
+  if (!page) throw new Error("startHarCapture: page required");
+  if (page[SYM]) return page[SYM]; // idempotent
+  const started = Date.now();
+  const entries = [];
+  const pending = new Map(); // req -> startTs
+  const state = {
+    started,
+    creator: { name: "pursr", version: opts.version || "0.3.0" },
+    browser: { name: "chromium", version: "playwright-core" },
+    pages: [],
+    entries,
+    pending,
+  };
+  const onReq = (req) => {
+    pending.set(req, Date.now());
+  };
+  const onResp = async (resp) => {
+    try {
+      const req = resp.request();
+      const startTs = pending.get(req) || Date.now();
+      pending.delete(req);
+      const endTs = Date.now();
+      entries.push(makeEntry(req, resp, startTs, endTs));
+    } catch {}
+  };
+  const onFailed = (req) => {
+    try {
+      const startTs = pending.get(req) || Date.now();
+      pending.delete(req);
+      entries.push(makeEntry(req, null, startTs, Date.now()));
+    } catch {}
+  };
+  page.on("request", onReq);
+  page.on("response", onResp);
+  page.on("requestfailed", onFailed);
+  state._teardown = () => {
+    try { page.off("request", onReq); } catch {}
+    try { page.off("response", onResp); } catch {}
+    try { page.off("requestfailed", onFailed); } catch {}
+  };
+  page[SYM] = state;
+  return state;
+}
+
+export function stopHarCapture(page) {
+  if (!page || !page[SYM]) return null;
+  const state = page[SYM];
+  try { state._teardown?.(); } catch {}
+  delete page[SYM];
+  return finalizeHar(state);
+}
+
+export function finalizeHar(state) {
+  if (!state) return null;
+  return {
+    log: {
+      version: "1.2",
+      creator: state.creator,
+      browser: state.browser,
+      pages: state.pages,
+      entries: state.entries,
+    },
+    _meta: {
+      started: state.started,
+      finished: Date.now(),
+      entryCount: state.entries.length,
+    },
+  };
+}
+
+export async function writeHar(har, file) {
+  if (!har || !file) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(har, null, 2), "utf8");
+  return file;
 }

package/src/hover.js

@@ -1,26 +1,26 @@
-// Hover capture: navigate, hover a selector, screenshot.
-
-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 { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
-
-export async function runHover({ url, selector, out, flags = {} }) {
-  requireArg("url", url, "string");
-  requireArg("selector", selector, "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);
-    const loc = await resolveLocator(page, selector);
-    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
-    await loc.first().hover({ timeout: CLICK_TIMEOUT_MS });
-    await page.waitForTimeout(asNum(flags["hover-ms"], 250));
-    if (out) await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
-    const meta = { ...r, url, out, selector, viewport, ts: nowIso() };
-    if (out) await writeSidecar(meta);
-    return meta;
-  } finally { try { await browser.close(); } catch {} }
+// Hover capture: navigate, hover a selector, screenshot.
+
+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 { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
+
+export async function runHover({ url, selector, out, flags = {} }) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "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);
+    const loc = await resolveLocator(page, selector);
+    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+    await loc.first().hover({ timeout: CLICK_TIMEOUT_MS });
+    await page.waitForTimeout(asNum(flags["hover-ms"], 250));
+    if (out) await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
+    const meta = { ...r, url, out, selector, viewport, ts: nowIso() };
+    if (out) await writeSidecar(meta);
+    return meta;
+  } finally { try { await browser.close(); } catch {} }
 }

package/src/index.js

@@ -1,8 +1,8 @@
-// pursor — public library API.
+//  pursr — public library API.
 //
-// This is the entry point for consumers who want to embed pursor
+// This is the entry point for consumers who want to embed pursr
 // inside their own scripts (instead of using the CLI). The CLI in
-// bin/pursor.mjs is a thin wrapper around the same exports.
+// bin/pursr.mjs is a thin wrapper around the same exports.
 //
 // All capture / sweep helpers return a `Result` object: the path to the
 // PNG, a sidecar JSON metadata object, and timing info. They never throw
@@ -17,7 +17,7 @@ import { runSweep } from "./sweep.js";
 import { runEveryViewport } from "./every-viewport.js";
 import { runFrames } from "./frames.js";
 import { runHover } from "./hover.js";
-import { runDiff } from "./diff.js";
+import { runDiff, runDiffWithAi } from "./diff.js";
 import { runProbe } from "./probe.js";
 import { runShot } from "./shot.js";
 import { runEval } from "./eval.js";
@@ -32,7 +32,7 @@ import { captureDomSnapshot, captureDomSnapshotSidecar } from "./dom-snapshot.js
 import { runAudit } from "./plugin-audit.js";
 import { resolveHealedSelector, healStepAction } from "./selector-heal.js";
 import { writeCiOutput } from "./ci-output.js";
-import { PursorMCPServer, loadConfig as loadMcpConfig, MCP_VERSION } from "./mcp.js";
+import { PursrMCPServer, loadConfig as loadMcpConfig, MCP_VERSION } from "./mcp.js";
 import { createRequire } from "node:module";
 import { saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath } from "./baseline.js";
 import { validateSweepPlan, registerSweepOp } from "./sweep-schema.js";
@@ -41,6 +41,8 @@ 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";
+import { renderSweepPdf } from "./report.js";
+import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
 
 
 // Derive VERSION from package.json to prevent drift
@@ -66,7 +68,7 @@ export {
   // v3: selector healing, CI output, MCP server
   resolveHealedSelector, healStepAction,
   writeCiOutput,
-  PursorMCPServer, loadMcpConfig, MCP_VERSION,
+  PursrMCPServer, loadMcpConfig, MCP_VERSION,
   // v4: baselines, sweep validation, MCP resources
   saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
   validateSweepPlan, registerSweepOp,
@@ -77,6 +79,10 @@ export {
   // v6: watch mode, component snapshot
   startWatch, matchGlob, shouldFire,
   runSnap, approveSnapsAsBaselines,
+  // v6: PDF report, AI diff summary
+  runDiffWithAi,
+  renderSweepPdf,
+  aiDiffSummary, aiDiffSidecar,
   VERSION,
 };
 
@@ -92,9 +98,11 @@ export default {
   resolveLocator, parseTextSelector,
   resolveHealedSelector, healStepAction,
   writeCiOutput,
-  PursorMCPServer, loadMcpConfig, MCP_VERSION,
+  PursrMCPServer, loadMcpConfig, MCP_VERSION,
   saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
   validateSweepPlan, registerSweepOp,
   listResources, readResource, recordResource,
+  // v6: PDF report, AI diff summary
+  runDiffWithAi, renderSweepPdf, aiDiffSummary, aiDiffSidecar,
   VERSION,
 };