pursr 0.4.0

package/src/plugin-audit.js

@@ -0,0 +1,260 @@
+// pursor — axe-core accessibility audit.
+//
+// Injects axe-core into the page, runs a WCAG audit, returns violations.
+// Optionally highlights violated elements with a red overlay and
+// generates a full audit report.
+//
+// Used internally via runAudit() and also exposed as a sweep-op
+// so it works in batch plans.
+//
+// Dependencies: axe-core (npm i axe-core)
+
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle } from "./overlays.js";
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { asNum, nowIso } from "./util.js";
+
+// ─── Injected audit runner ──────────────────────────────────────────────
+
+const AUDIT_RUNNER = (axeSource) => `
+${axeSource}
+(function() {
+  return new Promise((resolve, reject) => {
+    const config = typeof window.__PURR_AUDIT_CONFIG__ !== 'undefined' ? window.__PURR_AUDIT_CONFIG__ : {};
+    var tags = config.tags || ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'];
+    axe.run(
+      { runOnly: { type: 'tag', values: tags } },
+      function(err, results) {
+        if (err) { reject(err.message); return; }
+        // Also collect element references for highlighting
+        resolve(JSON.parse(JSON.stringify(results)));
+      }
+    );
+  });
+})()
+`;
+
+// ─── Highlight overlay script ──────────────────────────────────────────
+
+const HIGHLIGHT_VIOLATIONS = (violationsJson) => `
+(function() {
+  var violations = ${violationsJson};
+  if (!violations || !violations.length) return;
+  var style = document.createElement('style');
+  style.id = '__purr_audit_highlight__';
+  style.textContent = \`
+    [data-purr-audit-violation] {
+      outline: 3px solid rgba(255, 0, 0, 0.85) !important;
+      background: rgba(255, 0, 0, 0.12) !important;
+      position: relative !important;
+    }
+    [data-purr-audit-violation]::after {
+      content: attr(data-purr-audit-violation);
+      position: absolute;
+      top: -20px;
+      left: 0;
+      background: #d00;
+      color: #fff;
+      font: 10px/14px monospace;
+      padding: 1px 5px;
+      border-radius: 3px;
+      z-index: 999999;
+      white-space: nowrap;
+    }
+  \`;
+  document.documentElement.appendChild(style);
+  for (var v of violations) {
+    for (var n of v.nodes || []) {
+      for (var t of n.target || []) {
+        try {
+          var sel = Array.isArray(t) ? t.join(' ') : t;
+          var els = document.querySelectorAll(sel);
+          for (var e of els) {
+            e.setAttribute('data-purr-audit-violation', v.id + ': ' + v.impact);
+          }
+        } catch(e) {}
+      }
+    }
+  }
+})()
+`;
+
+// ─── Load axe-core ──────────────────────────────────────────────────────
+
+let _axeSource = null;
+async function getAxeSource() {
+  if (_axeSource) return _axeSource;
+  // Try node_modules/axe-core
+  const paths = [
+    join(process.cwd(), "node_modules", "axe-core", "axe.min.js"),
+    join(process.cwd(), "node_modules", "axe-core", "axe.js"),
+    new URL("..", import.meta.url).pathname && join(dirname(new URL(import.meta.url).pathname), "node_modules", "axe-core", "axe.min.js"),
+    join(dirname(process.execPath), "node_modules", "axe-core", "axe.min.js"),
+  ];
+  for (const p of paths) {
+    if (p && existsSync(p)) {
+      _axeSource = readFileSync(p, "utf8");
+      return _axeSource;
+    }
+  }
+  throw new Error("axe-core not found. Install: npm i axe-core");
+}
+
+// ─── Group helper ───────────────────────────────────────────────────────
+
+/** Count violations by WCAG impact level */
+function summarizeViolations(violations) {
+  const byImpact = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  const byTag = {};
+  for (const v of violations) {
+    byImpact[v.impact] = (byImpact[v.impact] || 0) + v.nodes.length;
+    for (const t of v.tags || []) {
+      if (!byTag[t]) byTag[t] = 0;
+      byTag[t] += v.nodes.length;
+    }
+  }
+  return { total: violations.length, totalNodes: violations.reduce((s, v) => s + v.nodes.length, 0), byImpact, byTag };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Run axe-core audit on a URL.
+ *
+ * @param {object} opts
+ * @param {string} opts.url        - Target URL
+ * @param {string[]} [opts.tags]   - WCAG tags (default: wcag2a, wcag2aa, wcag21a, wcag21aa, best-practice)
+ * @param {string}  [opts.outDir]  - Output directory
+ * @param {boolean} [opts.screenshot=true] - Capture highlighted screenshot
+ * @param {object}  [opts.flags]   - Extra capture flags
+ * @returns {Promise<object>} Audit result
+ */
+export async function runAudit({ url, tags, outDir, screenshot = true, flags = {} }) {
+  const dir = outDir || join(process.cwd(), `audit-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+
+  const viewport = resolveViewport(flags);
+  const browser = await launch();
+  const axeSource = await getAxeSource();
+
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url);
+    await settle(page);
+    // Give dynamic content time to fully render
+    await page.waitForTimeout(800);
+
+    // Inject axe config
+    await page.evaluate((t) => {
+      window.__PURR_AUDIT_CONFIG__ = { tags: t || ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'] };
+    }, tags || undefined);
+
+    // Inject and run axe
+    const rawResults = await page.evaluate(AUDIT_RUNNER, axeSource);
+
+    const result = {
+      url,
+      title: r.title,
+      ts: nowIso(),
+      viewport: { width: viewport.width, height: viewport.height, dpr: viewport.dpr },
+      violationSummary: summarizeViolations(rawResults.violations || []),
+      passes: (rawResults.passes || []).length,
+      incomplete: (rawResults.incomplete || []).length,
+      inapplicable: (rawResults.inapplicable || []).length,
+      violations: rawResults.violations || [],
+    };
+
+    // Write audit report
+    const auditPath = join(dir, "audit.json");
+    writeFileSync(auditPath, JSON.stringify(result, null, 2));
+
+    // Write summary Markdown
+    const mdPath = join(dir, "audit-summary.md");
+    writeFileSync(mdPath, renderAuditMarkdown(result));
+
+    // Highlighted screenshot
+    if (screenshot && result.violations.length > 0) {
+      const violationsJson = JSON.stringify(result.violations.map(v => ({
+        id: v.id,
+        impact: v.impact,
+        nodes: (v.nodes || []).map(n => ({ target: n.target })),
+      })));
+      await page.evaluate(HIGHLIGHT_VIOLATIONS, violationsJson);
+      await page.waitForTimeout(200);
+      const shotPath = join(dir, "audit-highlighted.png");
+      await page.screenshot({ path: shotPath, fullPage: true });
+      result.highlightedScreenshot = shotPath;
+    } else if (screenshot) {
+      const shotPath = join(dir, "audit-clean.png");
+      await page.screenshot({ path: shotPath, fullPage: true });
+      result.cleanScreenshot = shotPath;
+    }
+
+    return result;
+  } finally {
+    try { await browser.close(); } catch {}
+  }
+}
+
+// ─── Markdown report ────────────────────────────────────────────────────
+
+function renderAuditMarkdown(result) {
+  const s = result.violationSummary || {};
+  const lines = [
+    `# Accessibility Audit: ${result.url}`,
+    ``,
+    `**Date:** ${result.ts}`,
+    `**Viewport:** ${result.viewport.width}x${result.viewport.height} @${result.viewport.dpr}x`,
+    ``,
+    `## Summary`,
+    ``,
+    `| Severity | Count |`,
+    `|----------|-------|`,
+    `| 🔴 Critical | ${s.byImpact?.critical || 0} nodes`,
+    `| 🟠 Serious | ${s.byImpact?.serious || 0} nodes`,
+    `| 🟡 Moderate | ${s.byImpact?.moderate || 0} nodes`,
+    `| ⚪ Minor | ${s.byImpact?.minor || 0} nodes`,
+    `| **Total violations** | **${s.total} rules, ${s.totalNodes} nodes** |`,
+    ``,
+    `| Check | Count |`,
+    `|-------|-------|`,
+    `| Passes | ${result.passes || 0} |`,
+    `| Incomplete | ${result.incomplete || 0} |`,
+    `| Inapplicable | ${result.inapplicable || 0} |`,
+    ``,
+  ];
+
+  if (result.violations.length) {
+    lines.push(`## Violations`);
+    lines.push(``);
+    for (const v of result.violations) {
+      lines.push(`### ${v.id} — ${v.impact}`);
+      lines.push(``);
+      lines.push(`**Help:** ${v.helpUrl || v.help || 'N/A'}`);
+      lines.push(``);
+      lines.push(`**Tags:** ${(v.tags || []).join(', ')}`);
+      lines.push(``);
+      lines.push(`**Affected nodes:** ${(v.nodes || []).length}`);
+      lines.push(``);
+      for (const n of (v.nodes || []).slice(0, 10)) { // top 10 per violation
+        const target = (n.target || []).join(', ');
+        const snippet = (n.html || '').slice(0, 200);
+        const failureSummary = n.failureSummary || '';
+        lines.push(`- \`${target}\``);
+        if (snippet) lines.push(`  - \`${snippet.replace(/`/g, '')}\``);
+        if (failureSummary) lines.push(`  - ${failureSummary.split('\\n')[0]}`);
+      }
+      if ((v.nodes || []).length > 10) lines.push(`  - … and ${v.nodes.length - 10} more nodes`);
+      lines.push(``);
+    }
+  }
+
+  if (result.highlightedScreenshot) lines.push(`![Highlighted screenshot](${result.highlightedScreenshot})`);
+  if (result.cleanScreenshot) lines.push(`![Clean screenshot](${result.cleanScreenshot})`);
+
+  lines.push(``);
+  lines.push(`_Generated by pursor audit_`);
+  return lines.join('\n');
+}

package/src/plugin.js

@@ -0,0 +1,121 @@
+// pursor — plugin API.
+//
+// A plugin is a plain ES module that exports a default object with one
+// or more hook handlers. The host loads plugins from:
+//   1. The built-in `plugins/` directory (shipped with the package).
+//   2. A path passed to `loadPlugins([...paths])`.
+//   3. Any package named `pursor-plugin-*` in node_modules.
+//
+// Hook reference:
+//
+//   name:        "my-plugin"  // optional, for logs
+//   viewport:    { <presetName>: { width, height, dpr, label } }
+//   sweepOp:     { <opName>: async (ctx, opts) => Result }
+//   beforeShoot: async (ctx) => void   // mutate ctx.flags / ctx.viewport
+//   afterShoot:  async (ctx, meta) => void  // augment sidecar
+//   flagHelp:    { "my-flag": "what it does" }
+//
+// ctx fields available to hooks:
+//   url, out, viewport, flags, browser, page
+//
+// Example plugin (plugins/my-plugin.js):
+//
+//   export default {
+//     name: "my-plugin",
+//     viewport: {
+//       "my-laptop": { width: 1440, height: 900, dpr: 2, label: "MBP 14" },
+//     },
+//     sweepOp: {
+//       "lighthouse": async (ctx, opts) => {
+//         // ... run lighthouse, return { out, meta }
+//       },
+//     },
+//     beforeShoot: async (ctx) => {
+//       // e.g. set extra cookies, click a button, etc.
+//     },
+//   };
+
+const plugins = [];
+const registeredRefs = new Set();
+const sweepOps = new Map();
+const viewportPresets = new Map();
+const flagHelp = new Map();
+
+export function registerPlugin(p) {
+  if (!p || typeof p !== "object") return;
+  if (registeredRefs.has(p)) return;
+  registeredRefs.add(p);
+  plugins.push(p);
+  if (p.name) console.error(`[pursor] loaded plugin: ${p.name}`);
+  if (p.viewport) {
+    for (const [k, v] of Object.entries(p.viewport)) viewportPresets.set(k, v);
+  }
+  if (p.sweepOp) {
+    for (const [k, v] of Object.entries(p.sweepOp)) sweepOps.set(k, v);
+  }
+  if (p.flagHelp) {
+    for (const [k, v] of Object.entries(p.flagHelp)) flagHelp.set(k, v);
+  }
+}
+
+export async function loadPlugins(paths = []) {
+  if (typeof paths === "string") paths = [paths];
+  const loadedPaths = new Set();
+  // auto-load built-in plugins from plugins/ directory
+  const { readdirSync, existsSync } = await import("node:fs");
+  const { join, dirname } = await import("node:path");
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+  const selfDir = dirname(fileURLToPath(import.meta.url));
+  const pluginDir = join(selfDir, "..", "plugins");
+  if (existsSync(pluginDir)) {
+    for (const f of readdirSync(pluginDir)) {
+      if (f.endsWith(".js")) {
+        const fullPath = pathToFileURL(join(pluginDir, f)).href;
+        if (loadedPaths.has(fullPath)) continue;
+        loadedPaths.add(fullPath);
+        try {
+          const mod = await import(/* @vite-ignore */ fullPath);
+          registerPlugin(mod.default || mod);
+        } catch (e) {
+          console.error(`[pursor] failed to load built-in plugin ${f}: ${e.message}`);
+        }
+      }
+    }
+  }
+  // user-supplied plugins — resolve relative to cwd
+  for (const p of paths) {
+    if (loadedPaths.has(p)) continue;
+    loadedPaths.add(p);
+    try {
+      const resolved = pathToFileURL(join(process.cwd(), p)).href;
+      const mod = await import(/* @vite-ignore */ resolved);
+      registerPlugin(mod.default || mod);
+    } catch (e) {
+      console.error(`[pursor] failed to load plugin ${p}: ${e.message}`);
+    }
+  }
+  return plugins.length;
+}
+
+export function listPlugins() { return plugins.map(p => p?.name || "(unnamed)"); }
+
+export function getSweepOp(name) { return sweepOps.get(name); }
+export function getViewportPreset(name) { return viewportPresets.get(name); }
+export function listViewportPresets() { return Object.fromEntries(viewportPresets); }
+export function getFlagHelp() { return Object.fromEntries(flagHelp); }
+
+export async function runBeforeShoot(ctx) {
+  for (const p of plugins) {
+    if (typeof p.beforeShoot === "function") {
+      try { await p.beforeShoot(ctx); } catch (e) { console.error(`[plugin ${p.name}] beforeShoot: ${e.message}`); }
+    }
+  }
+}
+
+export async function runAfterShoot(ctx, meta) {
+  for (const p of plugins) {
+    if (typeof p.afterShoot === "function") {
+      try { await p.afterShoot(ctx, meta); } catch (e) { console.error(`[plugin ${p.name}] afterShoot: ${e.message}`); }
+    }
+  }
+}

package/src/probe.js

@@ -0,0 +1,20 @@
+// Probe: open a viewport, navigate, return basic info. No screenshot.
+
+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 runProbe(url) {
+  requireArg("url", url, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    let navError = null, status = null, title = null;
+    try {
+      const r = await gotoOrThrow(page, url);
+      status = r.status; title = r.title;
+    } catch (e) { navError = e.message; }
+    return { url, status, title, navError, viewport: DEFAULT_VIEWPORT };
+  } finally { try { await browser.close(); } catch {} }
+}

package/src/runway.js

@@ -0,0 +1,66 @@
+// Browser launcher: auto-detect Playwright + system Chrome.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+let _chromium = null;
+async function getChromium() {
+  if (_chromium) return _chromium;
+  // Try local node_modules first
+  try { return _chromium = (await import("playwright-core")).chromium; } catch {}
+  // Try Codex cua_node runtime (current Codex Desktop bundles it).
+  // The cua_node folder has a hash subdir (e.g. 789504f803e82e2b), so we
+  // walk it to find the playwright-core entry.
+  const cuaRoot = join(homedir(), "AppData", "Local", "OpenAI", "Codex", "runtimes", "cua_node");
+  if (existsSync(cuaRoot)) {
+    const { readdirSync } = await import("node:fs");
+    const subdirs = (() => { try { return readdirSync(cuaRoot); } catch { return []; } })();
+    for (const sub of subdirs) {
+      const cand = join(cuaRoot, sub, "bin", "node_modules", "playwright-core", "index.mjs");
+      if (existsSync(cand)) {
+        try {
+          const url = "file:///" + cand.replace(/\\/g, "/");
+          return _chromium = (await import(url)).chromium;
+        } catch {}
+      }
+    }
+  }
+  throw new Error("playwright-core not found. Install it: npm i -D playwright-core");
+}
+
+const CHROME_PATHS = [
+  "C:/Program Files/Google/Chrome/Application/chrome.exe",
+  "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
+  "/usr/bin/google-chrome",
+  "/usr/bin/chromium-browser",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+];
+function findChrome() {
+  for (const p of CHROME_PATHS) if (existsSync(p)) return p;
+  return null;
+}
+
+const BROWSER_ARGS = Object.freeze(["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"]);
+
+export async function launch() {
+  const chromium = await getChromium();
+  const exec = findChrome();
+  if (!exec) throw new Error("system Chrome not found in standard paths");
+  return await chromium.launch({ headless: true, executablePath: exec, args: BROWSER_ARGS });
+}
+
+export async function newPage(browser, viewport, opts = {}) {
+  const ctx = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height },
+    deviceScaleFactor: viewport.dpr || 1,
+    reducedMotion: "no-preference",
+    colorScheme: "light",
+    hasTouch: !!(viewport.name && viewport.name.startsWith("mobile")),
+    isMobile: !!(viewport.name && viewport.name.startsWith("mobile")),
+    storageState: opts.storageState || undefined,
+  });
+  const page = await ctx.newPage();
+  page._pursorContext = ctx;
+  return page;
+}

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,74 @@
+// 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";
+import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
+import { loadAuthState } from "./auth.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, {
+        storageState: flags["auth-state"] ? loadAuthState({ project: flags["auth-project"] || "default", name: flags["auth-state"] }) : undefined,
+      });
+      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);
+      }
+
+      // Optional HAR capture
+      const harState = flags.har ? await startHarCapture(page) : null;
+      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 } };
+      if (harState) {
+        const har = stopHarCapture(page);
+        const harFile = await writeHar(har, String(flags.har));
+        meta.har = harFile;
+        meta.harEntryCount = har?._meta?.entryCount || 0;
+      }
+      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 {} }
+}