pursr 0.5.0 → 0.7.0

package/plans/m5.4-polish.json

@@ -1,22 +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" } }
-  ]
+{
+  "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

@@ -1,57 +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 };
-    },
-  },
-};
+// 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

@@ -1,63 +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 };
-  },
-};
+// Built-in demo plugin — shows every plugin API surface.
+//
+// Serves as both a reference implementation AND a useful tool:
+//   pursr - adds a `demo-canvas` viewport alias
+//   pursr - adds a `nav` sweep-op that clicks each navbar link in turn
+//     and captures a screenshot per page
+//   pursr - 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/ai-diff.js

@@ -0,0 +1,125 @@
+//  pursr - AI diff summary.
+//
+// Sends two images (reference + current) to a vision-capable LLM and asks
+// it to describe the visual differences in plain language. This gives you
+// a human-readable summary alongside the pixel-diff percentage.
+//
+// Supports any OpenAI-compatible chat completions endpoint that accepts
+// image_url content parts (OpenAI, Anthropic via proxy, local llama.cpp,
+// Codex tokenrouter, etc).
+//
+// CLI:
+//   pursr diff <url> <ref.png> <out.png> --ai
+//   pursr diff <url> <ref.png> <out.png> --ai-model gh/gpt-5.4
+//
+// Library:
+//   import { aiDiffSummary } from "pursr/ai-diff";
+//   const summary = await aiDiffSummary({ refPath, curPath, url, model });
+
+import { readFileSync, existsSync } from "node:fs";
+import { __PURSR_GET } from "./util.js";
+
+// Read env at call time so tests can mutate process.env between calls.
+function _defaultBase() { return __PURSR_GET("PURSR_AI_BASE_URL") || process.env.ANTHROPIC_BASE_URL || "https://api.openai.com/v1"; }
+function _defaultKey()  { return __PURSR_GET("PURSR_AI_API_KEY") || process.env.ANTHROPIC_AUTH_TOKEN || process.env.OPENAI_API_KEY; }
+function _defaultModel(){ return __PURSR_GET("PURSR_AI_MODEL") || process.env.ANTHROPIC_DEFAULT_SONNET_MODEL || "gpt-4o"; }
+
+const SYSTEM_PROMPT = `You are a visual regression analyst. Given two screenshots of the same web page (reference vs current), produce a concise, structured report of the visual differences.
+
+Output format (markdown, keep under 250 words):
+
+**Overall:** one sentence verdict (looks identical / minor changes / major regression).
+**Layout shifts:** list any element that moved, resized, or appeared/disappeared.
+**Color / style:** any color, font, or spacing changes.
+**Content:** new, removed, or changed text/imagery.
+**Likely cause:** best guess at what code or content change caused this.
+
+Be specific (mention element labels, regions). Be honest about uncertainty.`;
+
+/**
+ * Send reference + current PNGs to a vision model and return a textual diff summary.
+ *
+ * @param {object} opts
+ * @param {string} opts.refPath   - Path to reference PNG
+ * @param {string} opts.curPath   - Path to current PNG
+ * @param {string} [opts.url]     - URL that was captured (for context)
+ * @param {string} [opts.model]   - Model id (default: gpt-4o)
+ * @param {string} [opts.baseUrl] - OpenAI-compatible base URL
+ * @param {string} [opts.apiKey]  - API key
+ * @param {number} [opts.maxTokens=600]
+ * @returns {Promise<{ summary: string, model: string, elapsedMs: number, usage?: object }>}
+ */
+export async function aiDiffSummary(opts) {
+  if (!opts.refPath || !opts.curPath) throw new Error("aiDiffSummary: refPath and curPath required");
+  if (!existsSync(opts.refPath)) throw new Error(`aiDiffSummary: ref not found: ${opts.refPath}`);
+  if (!existsSync(opts.curPath)) throw new Error(`aiDiffSummary: cur not found: ${opts.curPath}`);
+
+  const baseUrl = (opts.baseUrl || _defaultBase()).replace(/\/+$/, "");
+  const apiKey = opts.apiKey || _defaultKey();
+  const model = opts.model || _defaultModel();
+  if (!apiKey) {
+    throw new Error("aiDiffSummary: no API key. Set PURSR_$1, ANTHROPIC_AUTH_TOKEN, or OPENAI_API_KEY.");
+  }
+
+  const refB64 = readFileSync(opts.refPath).toString("base64");
+  const curB64 = readFileSync(opts.curPath).toString("base64");
+  const userText = opts.url
+    ? `URL: ${opts.url}\n\nCompare these two screenshots of the same page (reference first, current second). Describe the visual differences.`
+    : `Compare these two screenshots (reference first, current second). Describe the visual differences.`;
+
+  const body = {
+    model,
+    max_tokens: opts.maxTokens || 600,
+    temperature: 0.2,
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      {
+        role: "user",
+        content: [
+          { type: "text", text: "REFERENCE:" },
+          { type: "image_url", image_url: { url: `data:image/png;base64,${refB64}` } },
+          { type: "text", text: "CURRENT:" },
+          { type: "image_url", image_url: { url: `data:image/png;base64,${curB64}` } },
+          { type: "text", text: userText },
+        ],
+      },
+    ],
+  };
+
+  const t0 = Date.now();
+  const res = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => "");
+    throw new Error(`aiDiffSummary: ${res.status} ${res.statusText} - ${errText.slice(0, 300)}`);
+  }
+  const data = await res.json();
+  const summary = data.choices?.[0]?.message?.content?.trim() || "(empty response)";
+  return {
+    summary,
+    model,
+    elapsedMs: Date.now() - t0,
+    usage: data.usage,
+  };
+}
+
+/**
+ * Compare two PNGs and return a JSON-friendly object suitable for embedding
+ * in a sweep step's meta sidecar.
+ */
+export async function aiDiffSidecar(opts) {
+  const r = await aiDiffSummary(opts);
+  return {
+    aiSummary: r.summary,
+    aiModel: r.model,
+    aiElapsedMs: r.elapsedMs,
+    aiAt: new Date().toISOString(),
+  };
+}

package/src/auth.js

@@ -1,92 +1,93 @@
-// pursor — auth state (browser storage state) management.
-//
-// Playwright's `storageState` is the canonical way to persist
-// cookies + localStorage between browser sessions. pursor wraps it
-// in a small CLI/library API so users can:
-//   1. login once interactively and save the state
-//   2. reuse the saved state in any subsequent capture (CI included)
-//
-// Storage layout:
-//   ~/.pursor/auth/<project>/<name>.json
-//
-// Override with PURSOR_AUTH_DIR.
-//
-// Public API:
-//   saveAuthState({ project, name, state })    -> manifest + state file
-//   loadAuthState({ project, name })           -> state object (Playwright shape)
-//   listAuthStates(project)                    -> [{ name, ts, ... }]
-//   deleteAuthState({ project, name })         -> bool
-//
-// CLI:
-//   pursor auth save <project> <name> --from <state.json>
-//   pursor auth load <project> <name> --out <state.json>
-//   pursor auth list [project]
-//   pursor auth delete <project> <name>
-
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { nowIso } from "./util.js";
-
-function authRoot() {
-  return process.env.PURSOR_AUTH_DIR || join(homedir(), ".pursor", "auth");
-}
-
-function authPath(project, name) {
-  const root = authRoot();
-  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
-  const nm = String(name || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
-  return join(root, proj, `${nm}.json`);
-}
-
-export function saveAuthState({ project, name, state }) {
-  if (!state) throw new Error("saveAuthState: missing state object");
-  // state shape from Playwright: { cookies, origins }
-  if (!Array.isArray(state.cookies)) state.cookies = [];
-  if (!Array.isArray(state.origins)) state.origins = [];
-  const file = authPath(project, name);
-  mkdirSync(join(file, ".."), { recursive: true });
-  const blob = {
-    _meta: { project: project || "default", name, ts: nowIso() },
-    cookies: state.cookies,
-    origins: state.origins,
-  };
-  writeFileSync(file, JSON.stringify(blob, null, 2), "utf8");
-  return { file, ...blob._meta };
-}
-
-export function loadAuthState({ project, name }) {
-  const file = authPath(project, name);
-  if (!existsSync(file)) return null;
-  try {
-    const blob = JSON.parse(readFileSync(file, "utf8"));
-    return { cookies: blob.cookies || [], origins: blob.origins || [] };
-  } catch {
-    return null;
-  }
-}
-
-export function listAuthStates(project) {
-  const root = join(authRoot(), (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_"));
-  if (!existsSync(root)) return [];
-  const out = [];
-  for (const f of readdirSync(root)) {
-    if (!f.endsWith(".json")) continue;
-    try {
-      const blob = JSON.parse(readFileSync(join(root, f), "utf8"));
-      out.push({
-        name: blob?._meta?.name || f.replace(/\.json$/, ""),
-        ts: blob?._meta?.ts || null,
-        cookies: (blob.cookies || []).length,
-        origins: (blob.origins || []).length,
-      });
-    } catch {}
-  }
-  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
-}
-
-export function deleteAuthState({ project, name }) {
-  const file = authPath(project, name);
-  if (!existsSync(file)) return false;
-  try { rmSync(file, { force: true }); return true; } catch { return false; }
+//  pursr — auth state (browser storage state) management.
+//
+// Playwright's `storageState` is the canonical way to persist
+// cookies + localStorage between browser sessions. pursr wraps it
+// in a small CLI/library API so users can:
+//   1. login once interactively and save the state
+//   2. reuse the saved state in any subsequent capture (CI included)
+//
+// Storage layout:
+//   ~/.pursr/auth/<project>/<name>.json
+//
+// Override with PURSR_$1.
+//
+// Public API:
+//   saveAuthState({ project, name, state })    -> manifest + state file
+//   loadAuthState({ project, name })           -> state object (Playwright shape)
+//   listAuthStates(project)                    -> [{ name, ts, ... }]
+//   deleteAuthState({ project, name })         -> bool
+//
+// CLI:
+//    auth save <project> <name> --from <state.json>
+//    auth load <project> <name> --out <state.json>
+//    auth list [project]
+//    auth delete <project> <name>
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { nowIso } from "./util.js";
+import { __PURSR_GET } from "./util.js";
+
+function authRoot() {
+  return __PURSR_GET("PURSR_AUTH_DIR") || join(homedir(), ".pursr", "auth");
+}
+
+function authPath(project, name) {
+  const root = authRoot();
+  const proj = (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  const nm = String(name || "default").replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return join(root, proj, `${nm}.json`);
+}
+
+export function saveAuthState({ project, name, state }) {
+  if (!state) throw new Error("saveAuthState: missing state object");
+  // state shape from Playwright: { cookies, origins }
+  if (!Array.isArray(state.cookies)) state.cookies = [];
+  if (!Array.isArray(state.origins)) state.origins = [];
+  const file = authPath(project, name);
+  mkdirSync(join(file, ".."), { recursive: true });
+  const blob = {
+    _meta: { project: project || "default", name, ts: nowIso() },
+    cookies: state.cookies,
+    origins: state.origins,
+  };
+  writeFileSync(file, JSON.stringify(blob, null, 2), "utf8");
+  return { file, ...blob._meta };
+}
+
+export function loadAuthState({ project, name }) {
+  const file = authPath(project, name);
+  if (!existsSync(file)) return null;
+  try {
+    const blob = JSON.parse(readFileSync(file, "utf8"));
+    return { cookies: blob.cookies || [], origins: blob.origins || [] };
+  } catch {
+    return null;
+  }
+}
+
+export function listAuthStates(project) {
+  const root = join(authRoot(), (project || "default").replace(/[^a-zA-Z0-9._-]+/g, "_"));
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const f of readdirSync(root)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const blob = JSON.parse(readFileSync(join(root, f), "utf8"));
+      out.push({
+        name: blob?._meta?.name || f.replace(/\.json$/, ""),
+        ts: blob?._meta?.ts || null,
+        cookies: (blob.cookies || []).length,
+        origins: (blob.origins || []).length,
+      });
+    } catch {}
+  }
+  return out.sort((a, b) => (b.ts || "").localeCompare(a.ts || ""));
+}
+
+export function deleteAuthState({ project, name }) {
+  const file = authPath(project, name);
+  if (!existsSync(file)) return false;
+  try { rmSync(file, { force: true }); return true; } catch { return false; }
 }