pursor 0.2.0

package/src/ci-output.js

@@ -0,0 +1,156 @@
+// pursor — CI Output Formatters.
+//
+// Converts a sweep summary into:
+//   - JUnit XML  (sweep.junit.xml)  — CI pipeline integration
+//   - GitHub Actions annotations  (sweep.github.json)
+//   - Markdown summary            (sweep.md)
+//
+// Call writeCiOutput(summary) at the end of a sweep to write all three
+// sidecars alongside sweep.json.
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { escapeHtml } from "./util.js";
+
+// ─── JUnit XML ───────────────────────────────────────────────────────────
+// Produces a minimal JUnit-compatible XML that GitLab CI, Jenkins, CircleCI,
+// and other CI runners understand.
+
+function renderJUnitXml(summary) {
+  const { steps, name, ts, outDir } = summary;
+  const suiteName = escapeXml(name || "pursor-sweep");
+  const tests = steps.length;
+  const failures = steps.filter(s => !s.ok).length;
+  const time = (steps.reduce((s, t) => s + (t.ms || 0), 0) / 1000).toFixed(3);
+
+  const testcases = steps.map(s => {
+    const className = escapeXml(`${s.op || "step"}` || "unknown");
+    const testName = escapeXml(s.name || `step-${s.i}`);
+    const fileAttr = s.meta?.out ? ` file="${escapeXml(s.meta.out)}"` : "";
+    let extra = "";
+    if (!s.ok) {
+      const msg = escapeXml(s.error || "unknown error");
+      const meta = s.meta ? escapeXml(JSON.stringify(s.meta, null, 2).slice(0, 500)) : "";
+      extra = `\n      <failure message="${msg}">${meta ? `\n        <![CDATA[${meta}]]>\n      ` : ""}</failure>`;
+    }
+    return `    <testcase classname="${className}" name="${testName}" time="${((s.ms || 0) / 1000).toFixed(3)}"${fileAttr}>${extra}
+    </testcase>`;
+  }).join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuite name="${suiteName}" tests="${tests}" failures="${failures}" errors="0" time="${time}" timestamp="${escapeXml(summary.ts || "")}">
+${testcases}
+</testsuite>`;
+}
+
+function escapeXml(s) {
+  return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+
+// ─── GitHub Actions (JSON annotations) ───────────────────────────────────
+// Each annotation: { filename, fileLine, annotation_level, message, title }
+
+function renderGitHubAnnotations(summary) {
+  const annotations = [];
+  for (const s of summary.steps) {
+    if (s.ok) continue;
+    annotations.push({
+      filename: s.meta?.out || s.name || `step-${s.i}`,
+      fileLine: 1,
+      annotation_level: "failure",
+      title: `pursor: ${s.name || `step-${s.i}`}`,
+      message: s.error || "Step failed",
+      raw_details: s.meta ? JSON.stringify(s.meta) : "",
+    });
+  }
+  // Also add warnings for diffs with high diffPct
+  for (const s of summary.steps) {
+    if (s.ok && s.meta?.numDiff > 0 && s.meta?.diffPct > 1) {
+      annotations.push({
+        filename: s.meta.out || s.name || `step-${s.i}`,
+        fileLine: 1,
+        annotation_level: "warning",
+        title: `pursor: diff > 1%`,
+        message: `${s.name}: ${s.meta.diffPct}% pixels differ from reference`,
+        raw_details: JSON.stringify(s.meta),
+      });
+    }
+  }
+  return { annotations };
+}
+
+// ─── Markdown Summary ────────────────────────────────────────────────────
+
+function renderMarkdownSummary(summary) {
+  const lines = [
+    `# pursor Sweep: ${summary.name || "(unnamed)"}`,
+    ``,
+    `**Plan:** \`${summary.plan || "?"}\``,
+    `**Date:** ${summary.ts || "?"}`,
+    `**Steps:** ${summary.steps.length}`,
+    ``,
+    `## Results`,
+    ``,
+    `| # | Name | Op | Status | Time |`,
+    `|---|------|----|--------|------|`,
+  ];
+
+  for (const s of summary.steps) {
+    const status = s.ok ? "✅ OK" : "❌ FAIL";
+    const time = `${s.ms || 0}ms`;
+    lines.push(`| ${s.i} | ${escapeMd(s.name || "")} | \`${s.op || ""}\` | ${status} | ${time} |`);
+  }
+
+  // Failures detail
+  const failed = summary.steps.filter(s => !s.ok);
+  if (failed.length) {
+    lines.push(``, `## Failures`, ``);
+    for (const s of failed) {
+      lines.push(`### ${s.i}. ${s.name || "unknown"}`);
+      lines.push(``);
+      lines.push(`**Error:** \`${escapeMd(s.error || "unknown")}\``);
+      if (s.meta?.out) lines.push(`**Output:** \`${s.meta.out}\``);
+      lines.push(``);
+    }
+  }
+
+  // Diffs with non-zero diff
+  const diffs = summary.steps.filter(s => s.ok && s.meta?.numDiff > 0);
+  if (diffs.length) {
+    lines.push(``, `## Diffs`, ``);
+    for (const s of diffs) {
+      lines.push(`| ${s.name} | ${s.meta.diffPct}% | ${s.meta.numDiff}/${s.meta.totalPx} pixels |`);
+    }
+    lines.push(``);
+  }
+
+  lines.push(`_Generated by pursor_`);
+  return lines.join("\n");
+}
+
+function escapeMd(s) {
+  return String(s ?? "").replace(/([_*[\]()~`>#+\-=|{}!.])/g, "\\$1");
+}
+
+// ─── Writer ──────────────────────────────────────────────────────────────
+
+/**
+ * Write CI-format output files alongside the sweep summary.
+ *
+ * @param {object} summary - Sweep summary object from runSweep()
+ * @param {string} dir     - Output directory (same as sweep.json)
+ * @returns {{ junit: string, github: string, markdown: string }} Written paths
+ */
+export function writeCiOutput(summary, dir) {
+  if (!dir) dir = summary.outDir || ".";
+  mkdirSync(dir, { recursive: true });
+  const junitPath = join(dir, "sweep.junit.xml");
+  const githubPath = join(dir, "sweep.github.json");
+  const mdPath = join(dir, "sweep.md");
+
+  writeFileSync(junitPath, renderJUnitXml(summary), "utf8");
+  writeFileSync(githubPath, JSON.stringify(renderGitHubAnnotations(summary), null, 2), "utf8");
+  writeFileSync(mdPath, renderMarkdownSummary(summary), "utf8");
+
+  return { junit: junitPath, github: githubPath, markdown: mdPath };
+}

package/src/diff.js

@@ -0,0 +1,48 @@
+// 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 {} }
+}

package/src/dom-snapshot.js

@@ -0,0 +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;
+  }
+}

package/src/eval.js

@@ -0,0 +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 {} }
+}

package/src/every-viewport.js

@@ -0,0 +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;
+}

package/src/frames.js

@@ -0,0 +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 {} }
+}

package/src/hover.js

@@ -0,0 +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 {} }
+}

package/src/index.js

@@ -0,0 +1,90 @@
+// pursor — public library API.
+//
+// This is the entry point for consumers who want to embed pursor
+// inside their own scripts (instead of using the CLI). The CLI in
+// bin/pursor.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
+// on capture-time errors — those are reported in the result so the
+// caller can decide how to react.
+//
+// The plugin system lives in src/plugin.js — see that file for how to
+// write a custom plugin (viewport, sweep-op, before/after hooks).
+
+import { runShoot } from "./shoot.js";
+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 { runProbe } from "./probe.js";
+import { runShot } from "./shot.js";
+import { runEval } from "./eval.js";
+import { runClick, runType, runWait, runSeq } from "./interact.js";
+import { listViewports, resolveViewport, VIEWPORTS } from "./viewport.js";
+import { applyCamera, waitForStableFrame } from "./overlays.js";
+import { loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp } from "./plugin.js";
+import { launch, newPage } from "./runway.js";
+import { parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut } from "./util.js";
+import { resolveLocator, parseTextSelector } from "./selector.js";
+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 { createRequire } from "node:module";
+import { saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath } from "./baseline.js";
+import { validateSweepPlan, registerSweepOp } from "./sweep-schema.js";
+import { listResources, readResource, recordResource } from "./mcp-resources.js";
+
+
+// Derive VERSION from package.json to prevent drift
+const __require = createRequire(import.meta.url);
+const pkg = __require("../package.json");
+const VERSION = pkg.version;
+
+export {
+  // CLI-style actions
+  runProbe, runShot, runEval, runClick, runType, runWait, runSeq,
+  runShoot, runFrames, runHover, runSweep, runDiff, runEveryViewport,
+  // v3: audit, DOM snapshot, MCP
+  runAudit, captureDomSnapshot, captureDomSnapshotSidecar,
+  // viewport + camera helpers
+  listViewports, resolveViewport, VIEWPORTS,
+  applyCamera, waitForStableFrame,
+  // plugin system
+  loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp,
+  // low-level helpers (for plugin authors)
+  launch, newPage,
+  parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut,
+  resolveLocator, parseTextSelector,
+  // v3: selector healing, CI output, MCP server
+  resolveHealedSelector, healStepAction,
+  writeCiOutput,
+  PursorMCPServer, loadMcpConfig, MCP_VERSION,
+  // v4: baselines, sweep validation, MCP resources
+  saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
+  validateSweepPlan, registerSweepOp,
+  listResources, readResource, recordResource,
+  VERSION,
+};
+
+export default {
+  runProbe, runShot, runEval, runClick, runType, runWait, runSeq,
+  runShoot, runFrames, runHover, runSweep, runDiff, runEveryViewport,
+  runAudit, captureDomSnapshot, captureDomSnapshotSidecar,
+  listViewports, resolveViewport, VIEWPORTS,
+  applyCamera, waitForStableFrame,
+  loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp,
+  launch, newPage,
+  parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut,
+  resolveLocator, parseTextSelector,
+  resolveHealedSelector, healStepAction,
+  writeCiOutput,
+  PursorMCPServer, loadMcpConfig, MCP_VERSION,
+  saveBaseline, loadBaseline, listBaselines, approveBaseline, diffKey, resolveBaselinePath,
+  validateSweepPlan, registerSweepOp,
+  listResources, readResource, recordResource,
+  VERSION,
+};