pursor 0.2.0

package/bin/pursor.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// pursor CLI. Thin wrapper around src/* that mirrors the npm bin.
+
+import { VERSION } from "../src/index.js";
+import { runClick, runType, runWait, runSeq } from "../src/interact.js";
+import { runEval } from "../src/eval.js";
+import { runProbe } from "../src/probe.js";
+import { runShot } from "../src/shot.js";
+import { runShootWithSidecar } from "../src/shoot.js";
+import { runHover } from "../src/hover.js";
+import { runFrames } from "../src/frames.js";
+import { runDiff } from "../src/diff.js";
+import { runSweep } from "../src/sweep.js";
+import { runEveryViewport } from "../src/every-viewport.js";
+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 { readFileSync as _readFileSync } from "node:fs";
+const readFile = _readFileSync;
+import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
+
+const USAGE = `usage:
+  v1: pursor {probe|shot|full|eval|click|type|wait|diff|seq} <url> [...]
+  v2: pursor {viewports|shoot|layer|frames|hover|sweep} <...>
+  flags: --preset <name> --width N --height N --dpr N
+         --zoom 1.5 --panX 200 --panY -100
+         --cursor pointer|grab|grabbing|crosshair|none
+         --layer entity|terrain|hud|ui
+         --grid --grid-tile 64 --grid-color rgba(255,0,255,0.35)
+         --no-animation --wait-frame 600 --full
+  @file prefix reads argv contents from file (UTF-8, newline trimmed).
+  plugins: pursor automatically loads built-in plugins from plugins/.
+  You can also pass --plugin <path> to load custom plugins (repeatable).`;
+
+function die(msg, code = 2) {
+  console.error(JSON.stringify({ error: msg, usage: USAGE }, null, 2));
+  process.exit(code);
+}
+
+const argv = process.argv;
+const [, , cmd, a, b, c, d] = argv;
+const url = process.env.PURSOR_URL || a;
+
+// Plugin loading: scan for --plugin <path> and built-in plugins/
+const pluginPaths = [];
+for (let i = 0; i < argv.length; i++) if (argv[i] === "--plugin" && i + 1 < argv.length) pluginPaths.push(argv[++i]);
+await loadPlugins(pluginPaths);
+
+(async () => {
+  try {
+    switch (cmd) {
+      case undefined: case "help": case "--help": case "-h": { console.log(JSON.stringify({ usage: USAGE }, null, 2)); break; }
+      case "version": case "--version": case "-v": {
+        console.log(JSON.stringify({ name: "pursor", version: VERSION, plugins: listPlugins() }, null, 2));
+        break;
+      }
+      case "probe": { if (!url) die("missing url"); const r = await runProbe(url); console.log(JSON.stringify(r, null, 2)); break; }
+      case "shot": { if (!url) die("missing url"); const out = b || makeOut("shot.png"); const r = await runShot(url, out, { fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "full": { if (!url) die("missing url"); const out = b || makeOut("full.png"); const r = await runShot(url, out, { fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "eval": { if (!url) die("missing url"); const js = readArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = c || makeOut("eval.png"); const r = await runEval(url, js, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = c || makeOut(`click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "type": { if (!url) die("missing url"); const sel = b; const text = readArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = d || makeOut(`type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t); console.log(JSON.stringify(r, null, 2)); break; }
+      case "diff": { if (!url) die("missing url"); const ref = b; if (!ref) die("diff: missing <ref.png>"); const out = c || makeOut("diff.png"); const threshold = d !== undefined ? Number(d) : 0.1; const r = await runDiff(url, ref, out, threshold); console.log(JSON.stringify(r, null, 2)); break; }
+      case "seq": { if (!url) die("missing url"); const actions = readArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = c || makeOut("seq.png"); const r = await runSeq(url, actions, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
+      case "shoot": {
+        if (!url) die("missing url");
+        const out = (b && !b.startsWith("--")) ? b : pickOutPath(argv.slice(5)) || makeOut("shoot.png");
+        const r = await runShootWithSidecar({ url, out, flags: parseFlags(argv.slice(5)) });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "layer": {
+        if (!url) die("missing url");
+        const layerName = b; if (!layerName) die("layer: missing <name>");
+        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`layer-${layerName}.png`);
+        const flags = parseFlags(argv.slice(7)); flags.layer = layerName;
+        const r = await runShootWithSidecar({ url, out, flags });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "frames": {
+        if (!url) die("missing url");
+        const count = asNum(b, 8);
+        const stepMs = asNum(c, 250);
+        const outDir = (d && !d.startsWith("--")) ? d : makeOut(`frames-${count}x${stepMs}ms`);
+        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: parseFlags(argv.slice(7)) });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "hover": {
+        if (!url) die("missing url");
+        const sel = b; if (!sel) die("hover: missing <selector>");
+        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
+        const r = await runHover({ url, selector: sel, out, flags: parseFlags(argv.slice(6)) });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "sweep": {
+        const planPath = readArg(a);
+        if (!planPath) die("sweep: missing <plan.json> (or @file)");
+        const outDirArg = (b && !b.startsWith("--")) ? b : undefined;
+        const r = await runSweep(planPath, outDirArg);
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "every-viewport": {
+        if (!url) die("missing url");
+        const outDir = (b && !b.startsWith("--")) ? b : undefined;
+        const viewports = c?.startsWith("--") ? undefined : c?.split(",");
+        const r = await runEveryViewport({ url, outDir, viewports });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "audit": {
+        if (!url) die("missing url");
+        const tags = (b && !b.startsWith("--")) ? b : undefined;
+        const outDir = (c && !c.startsWith("--")) ? c : undefined;
+        const r = await runAudit({ url, tags: tags?.split(",").map(t => t.trim()), outDir });
+        console.log(JSON.stringify(r, null, 2));
+        break;
+      }
+      case "dom-snapshot": case "dom": {
+        if (!url) die("missing url");
+        const out = (b && !b.startsWith("--")) ? b : undefined;
+        const r = await captureDomSnapshot({ url, out });
+        console.log(JSON.stringify({ url: r.url, title: r.title, elements: r.selectorMap?.length, domSize: r.dom?.length, out: r.url?.replace(/[^/]+$/, "") + "dom.json" }, null, 2));
+        break;
+      }
+      case "validate": {
+        const planPath = readArg(a);
+        if (!planPath) die("validate: missing <plan.json> (or @file)");
+        let plan;
+        try { plan = JSON.parse(readFile(planPath, "utf8")); }
+        catch (e) { die("validate: " + e.message); }
+        const { validateSweepPlan } = await import("../src/sweep-schema.js");
+        const v = validateSweepPlan(plan);
+        console.log(JSON.stringify({ valid: v.valid, errors: v.errors, plan: planPath }, null, 2));
+        if (!v.valid) process.exit(1);
+        break;
+      }
+      case "baseline": {
+        // pursor baseline <sub> [...args]
+        //   sub=list                    -> list baselines
+        //   sub=save <project> <png> <step>  [--id <id>] [--url <u>] [--meta-json <file>]
+        //   sub=approve <project> <png> <step>  [--id <id>] [--url <u>]
+        //   sub=show <project> <step>    [--id <id>] [--url <u>]
+        const sub = a;
+        const { saveBaseline, listBaselines, loadBaseline, approveBaseline, diffKey } = await import("../src/baseline.js");
+        if (sub === "list") {
+          // baseline list [project]
+          const project = b;
+          console.log(JSON.stringify(listBaselines(project), null, 2));
+        } else if (sub === "save") {
+          if (!b || !c || !d) die("baseline save: <project> <png> <step> [--id <id>] [--url <u>] [--meta-json <file>]");
+          const project = b, png = c, step = d;
+          const flags = parseFlags(argv.slice(7));
+          let meta = null;
+          if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
+          else if (flags.url) meta = { url: flags.url };
+          const id = flags.id || diffKey({ url: meta?.url || "", viewport: meta?.viewport, flags: meta?.flags || {} });
+          const result = saveBaseline({ project, id, step, png, meta });
+          console.log(JSON.stringify({ saved: true, ...result }, null, 2));
+        } else if (sub === "approve") {
+          if (!b || !c || !d) die("baseline approve: <project> <png> <step> [--id <id>] [--url <u>]");
+          const project = b, png = c, step = d;
+          const flags = parseFlags(argv.slice(7));
+          const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
+          const result = approveBaseline({ project, id, step, fromPng: png });
+          console.log(JSON.stringify({ approved: true, ...result }, null, 2));
+        } else if (sub === "show") {
+          if (!b || !c) die("baseline show: <project> <step> [--id <id>] [--url <u>]");
+          const project = b, step = c;
+          const flags = parseFlags(argv.slice(5));
+          const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
+          const r = loadBaseline({ project, id, step });
+          console.log(JSON.stringify(r, null, 2));
+        } else {
+          die("baseline subcommand: list | save | approve | show");
+        }
+        break;
+      }
+      default: { die(`unknown subcommand: ${cmd}`); }
+    }
+  } catch (e) {
+    console.error(JSON.stringify({ error: e.message, stack: e.stack?.split("\n").slice(0, 3).join("\n") }, null, 2));
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "pursor",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Visual QA & audit & MCP for the browser. Capture, sweep, and review any web target with multi-viewport, layered, animated, hover, grid, and cursor states.",
+  "type": "module",
+  "bin": {
+    "pursor": "./bin/pursor.mjs",
+    "pursor-mcp": "./bin/pursor-mcp.mjs"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./plugin": "./src/plugin.js",
+    "./plugins/*": "./plugins/*.js",
+    "./util": "./src/util.js",
+    "./runway": "./src/runway.js",
+    "./selector": "./src/selector.js",
+    "./overlays": "./src/overlays.js",
+    "./viewport": "./src/viewport.js",
+    "./dom-snapshot": "./src/dom-snapshot.js",
+    "./plugin-audit": "./src/plugin-audit.js",
+    "./selector-heal": "./src/selector-heal.js",
+    "./ci-output": "./src/ci-output.js",
+    "./mcp": "./src/mcp.js",
+    "./baseline": "./src/baseline.js",
+    "./sweep-schema": "./src/sweep-schema.js",
+    "./mcp-resources": "./src/mcp-resources.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "plugins",
+    "plans",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/pursor.mjs",
+    "test": "node --test \"test/*.test.js\"",
+    "smoke": "node bin/pursor.mjs viewports"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "visual-qa",
+    "visual-regression",
+    "screenshot",
+    "audit",
+    "isometric",
+    "playwright",
+    "testing",
+    "devtools"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "axe-core": "^4.12.1",
+    "pixelmatch": "^5.3.0",
+    "pngjs": "^7.0.0"
+  },
+  "peerDependencies": {
+    "playwright-core": "*"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "playwright-core": "^1.61.0"
+  }
+}

package/plans/m5.4-polish.json

@@ -0,0 +1,22 @@
+{
+  "name": "m5.4-polish",
+  "base": "http://localhost:3010",
+  "outDir": "./out/m54-sweep",
+  "steps": [
+    { "name": "baseline",         "shoot":  { "preset": "desktop-1280" } },
+    { "name": "cursor-pointer",   "shoot":  { "preset": "desktop-1280", "cursor": "pointer" } },
+    { "name": "grid-64",          "shoot":  { "preset": "desktop-1280", "grid": true, "grid-tile": 64 } },
+    { "name": "grid-128",         "shoot":  { "preset": "desktop-1280", "grid": true, "grid-tile": 128 } },
+    { "name": "layer-entity",     "shoot":  { "preset": "desktop-1280", "layer": "entity" } },
+    { "name": "layer-terrain",    "shoot":  { "preset": "desktop-1280", "layer": "terrain" } },
+    { "name": "no-hud",           "shoot":  { "preset": "desktop-1280", "no-hud": true } },
+    { "name": "frozen",           "shoot":  { "preset": "desktop-1280", "no-animation": true } },
+    { "name": "tablet-768",       "shoot":  { "preset": "tablet-768" } },
+    { "name": "mobile-375",       "shoot":  { "preset": "mobile-375" } },
+    { "name": "ultrawide-3440",   "shoot":  { "preset": "ultrawide-3440" } },
+    { "name": "hover-build",      "hover":  { "selector": "text=Build" } },
+    { "name": "hover-decor",      "hover":  { "selector": "text=Decor" } },
+    { "name": "frames-8",         "frames": { "count": 8, "intervalMs": 200 } },
+    { "name": "diff-vs-baseline", "diff":   { "ref": "baseline.png" } }
+  ]
+}

package/plugins/plugin-audit.js

@@ -0,0 +1,57 @@
+// Built-in plugin: axe-core accessibility audit.
+//
+// Adds:
+//   viewport  "audit-canvas"     — 1280x800 @1x ideal for audit screenshots
+//   sweepOp   "audit"            — run axe-core WCAG audit in a sweep plan
+//   sweepOp   "every-viewport"   — capture every viewport preset
+//
+// The audit sweep-op stores results to ctx.out/audit.json plus a
+// highlighted screenshot. This is a thin wrapper around src/plugin-audit.js
+// that exposes the same functionality through the plugin system.
+
+import { runAudit } from "../src/plugin-audit.js";
+import { launch, newPage } from "../src/runway.js";
+import { listViewports, resolveViewport } from "../src/viewport.js";
+import { runShootWithSidecar } from "../src/shoot.js";
+import { join } from "node:path";
+import { writeFileSync } from "node:fs";
+
+export default {
+  name: "audit",
+
+  viewport: {
+    "audit-canvas": { width: 1280, height: 800, dpr: 1, label: "Audit canvas 1280x800" },
+  },
+
+  sweepOp: {
+    // Run axe-core accessibility audit
+    "audit": async (ctx, opts) => {
+      const url = opts.url || ctx.url;
+      if (!url) throw new Error("audit: missing url");
+      const tags = opts.tags ? opts.tags.split(",").map(t => t.trim()) : undefined;
+      const outDir = opts.outDir || ctx.out?.replace(/\.png$/i, "-audit") || join(process.cwd(), `audit-${Date.now()}`);
+      const result = await runAudit({ url, tags, outDir, screenshot: opts.screenshot !== false });
+      return { url, mode: "audit", outDir, violations: result.violationSummary?.total || 0, summary: result.violationSummary };
+    },
+
+    // Capture one shot per viewport preset
+    "every-viewport": async (ctx, opts) => {
+      const url = opts.base || ctx.url;
+      if (!url) throw new Error("every-viewport: missing base url");
+      const wanted = opts.viewports?.length ? opts.viewports : listViewports().map(v => v.name);
+      const dir = ctx.out.replace(/\.png$/i, "-every-viewport");
+      const captures = [];
+      for (const name of wanted) {
+        const out = join(dir, `${name}.png`);
+        try {
+          const meta = await runShootWithSidecar({ url, out, flags: { preset: name } });
+          captures.push({ name, out, ok: true, meta });
+        } catch (e) {
+          captures.push({ name, out, ok: false, error: e.message });
+        }
+      }
+      writeFileSync(join(dir, "every-viewport.json"), JSON.stringify({ url, captures, ts: new Date().toISOString() }, null, 2));
+      return { url, mode: "every-viewport", outDir: dir, captures };
+    },
+  },
+};

package/plugins/plugin-demo.js

@@ -0,0 +1,63 @@
+// Built-in demo plugin — shows every plugin API surface.
+//
+// Serves as both a reference implementation AND a useful tool:
+//   - adds a `demo-canvas` viewport alias
+//   - adds a `nav` sweep-op that clicks each navbar link in turn
+//     and captures a screenshot per page
+//   - augments sidecar with `demo: { mode }` when `--demo-mode` flag is set
+//
+// Copy this file as a starting point for your own plugin.
+
+import { newPage } from "../src/runway.js";
+import { resolveViewport } from "../src/viewport.js";
+import { gotoOrThrow, settle } from "../src/overlays.js";
+import { resolveLocator } from "../src/selector.js";
+
+export default {
+  name: "demo",
+
+  viewport: {
+    "demo-canvas": { width: 1280, height: 800, dpr: 1, label: "Demo canvas 1280x800" },
+  },
+
+  flagHelp: {
+    "demo-mode": "logical mode label recorded in sidecar (e.g. dark / light / settings).",
+  },
+
+  sweepOp: {
+    "nav": async (ctx, opts) => {
+      // opts: { buttons: string[], settleMs?: number }
+      const browser = ctx.browser;
+      const page = ctx.page || await newPage(browser, resolveViewport({}));
+      const url = ctx.url;
+      if (!url) throw new Error("nav: missing url (provide plan.base)");
+      const r = await gotoOrThrow(page, url); await settle(page);
+      const buttons = opts.buttons || ["Home", "About", "Services", "Portfolio", "Contact"];
+      const frames = [];
+      for (const label of buttons) {
+        try {
+          const loc = await resolveLocator(page, `text=${label}`);
+          await loc.first().waitFor({ state: "visible", timeout: 5000 });
+          await loc.first().click({ timeout: 5000 });
+          await page.waitForTimeout(opts.settleMs || 600);
+          const f = ctx.out.replace(/\.png$/i, `-${label.toLowerCase()}.png`);
+          await page.screenshot({ path: f, fullPage: false });
+          frames.push({ button: label, out: f });
+        } catch (e) {
+          frames.push({ button: label, error: e.message });
+        }
+      }
+      return { ...r, url, mode: "nav-sweep", frames };
+    },
+  },
+
+  beforeShoot: async (ctx) => {
+    if (ctx.flags["demo-mode"]) {
+      ctx._demoMode = ctx.flags["demo-mode"];
+    }
+  },
+
+  afterShoot: async (ctx, meta) => {
+    if (ctx._demoMode) meta.demo = { mode: ctx._demoMode };
+  },
+};

package/src/baseline.js

@@ -0,0 +1,126 @@
+// pursor — baseline storage for visual regression.
+//
+// Baselines live under $PURSOR_BASELINES_DIR || ~/.pursor/baselines/<project>/
+// Each baseline is keyed by a stable id derived from the URL + viewport +
+// flag set (a short hash), so re-running a sweep deterministically points
+// to the same baseline slot.
+//
+// Layout:
+//   ~/.pursor/baselines/<project>/<id>/<step>.png
+//   ~/.pursor/baselines/<project>/<id>/manifest.json   (url, viewport, flags, ts)
+//
+// Public API:
+//   resolveBaselinePath({ project, id, step }) -> { dir, file, manifest? }
+//   saveBaseline({ project, id, step, png, meta }) -> manifest path
+//   loadBaseline({ project, id, step }) -> { png, manifest } | null
+//   listBaselines(project) -> [{ id, step, ts, url }]
+//   approveBaseline({ project, id, step, fromPng }) -> manifest path
+//   diffKey({ url, viewport, flags }) -> string  (stable id)
+//
+// CLI subcommands added: pursor baseline save/approve/list/diff-key
+
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { shortHash, nowIso } from "./util.js";
+
+function baseDir(project) {
+  const root = process.env.PURSOR_BASELINES_DIR || join(homedir(), ".pursor", "baselines");
+  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return join(root, proj);
+}
+
+export function diffKey({ url = "", viewport = {}, flags = {} } = {}) {
+  // Stable hash: project-agnostic, viewport+flag+url sensitive.
+  const v = `${viewport.width || 0}x${viewport.height || 0}@${viewport.dpr || 1}${viewport.name ? ":" + viewport.name : ""}`;
+  const fl = Object.keys(flags).sort().filter(k => k !== "out").map(k => `${k}=${flags[k]}`).join("&");
+  const src = `${url}|${v}|${fl}`;
+  return createHash("sha1").update(src).digest("hex").slice(0, 16);
+}
+
+export function resolveBaselinePath({ project, id, step }) {
+  const dir = join(baseDir(project), id);
+  const file = join(dir, `${String(step).replace(/[^a-z0-9._-]+/gi, "_")}.png`);
+  const manifestPath = join(dir, "manifest.json");
+  return { dir, file, manifestPath, manifest: existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null };
+}
+
+export function saveBaseline({ project, id, step, png, meta }) {
+  if (!png) throw new Error("saveBaseline: missing png path");
+  if (!existsSync(png)) throw new Error(`saveBaseline: png not found: ${png}`);
+  const { dir, file, manifestPath } = resolveBaselinePath({ project, id, step });
+  mkdirSync(dir, { recursive: true });
+  // Copy file (renameSync would also work but keep semantics explicit)
+  const buf = readFileSync(png);
+  writeFileSync(file, buf);
+  const manifest = {
+    project: project || "default",
+    id,
+    step: String(step),
+    file,
+    size: buf.length,
+    sha1: createHash("sha1").update(buf).digest("hex").slice(0, 16),
+    url: meta?.url || null,
+    viewport: meta?.viewport || null,
+    flags: meta?.flags || null,
+    ts: nowIso(),
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return { ...manifest, manifestPath };
+}
+
+export function loadBaseline({ project, id, step }) {
+  const { file, manifest } = resolveBaselinePath({ project, id, step });
+  if (!existsSync(file)) return null;
+  return {
+    png: file,
+    size: statSync(file).size,
+    hash: shortHash(readFileSync(file)),
+    manifest: manifest || null,
+  };
+}
+
+export function listBaselines(project) {
+  const root = baseDir(project);
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const id of readdirSync(root)) {
+    const dir = join(root, id);
+    if (!statSync(dir).isDirectory()) continue;
+    const manifestPath = join(dir, "manifest.json");
+    const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null;
+    if (!manifest) continue;
+    out.push({
+      id,
+      step: manifest.step,
+      url: manifest.url,
+      ts: manifest.ts,
+      sha1: manifest.sha1,
+    });
+  }
+  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
+}
+
+export function approveBaseline({ project, id, step, fromPng }) {
+  if (!fromPng) throw new Error("approveBaseline: missing fromPng");
+  if (!existsSync(fromPng)) throw new Error(`approveBaseline: fromPng not found: ${fromPng}`);
+  const buf = readFileSync(fromPng);
+  const { file, dir, manifestPath } = resolveBaselinePath({ project, id, step });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, buf);
+  const prev = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : {};
+  const manifest = {
+    ...prev,
+    project: project || prev.project || "default",
+    id,
+    step: String(step),
+    file,
+    size: buf.length,
+    sha1: createHash("sha1").update(buf).digest("hex").slice(0, 16),
+    ts: nowIso(),
+    approvedFrom: fromPng,
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return manifest;
+}