qapture2 0.9.1 → 0.10.0

package/dist/bin/init.cjs

@@ -24,8 +24,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/bin/init.ts
-var path6 = __toESM(require("path"), 1);
-var fs6 = __toESM(require("fs"), 1);
+var path7 = __toESM(require("path"), 1);
+var fs7 = __toESM(require("fs"), 1);
 var process2 = __toESM(require("process"), 1);
 
 // src/artifacts/SKILL.md
@@ -35,13 +35,20 @@ var SKILL_default = "---\nname: qapture\ndescription: >\n  Activated when the us
 var AGENTS_SECTION_default = "<!-- qa-studio-section -->\n\n## Qapture\n\nThis project uses **Qapture** \u2014 an in-browser QA capture widget that ships\n**zero AI** (no model, no API keys, no network calls). **You** are the AI.\n\n### When you receive a `qa-notes-*.zip`\n\n1. **Unzip** the file.\n2. **Read `notes.md` top-to-bottom**, starting with everything above the\n   `---NOTES---` separator:\n   - **Project context** \u2014 name, stack, run commands, conventions.\n   - **Login Context** \u2014 dev/test/seed credentials for the relevant roles.\n     _(DEV/TEST/SEED only \u2014 never commit, log, or forward these values.)_\n   - **Coverage Report** \u2014 red/amber/green zone checklist.\n   - **Invariants** \u2014 rules you must never violate (e.g. \"prices \u2265 0\",\n     \"checkout requires auth\").\n3. **Flag uncovered RED zones** before acting. RED = money / auth / irreversible\n   state. If any red zone has no annotation in this ZIP, report it and ask the\n   developer whether to proceed.\n4. **Triage the whole batch before touching code.** Read every point first \u2014\n   points on different pages can share one root cause (check their runtime\n   context for a repeated failing URL or error message) and deserve one fix,\n   not N. Write the plan down before editing anything.\n5. **Orchestrate, don't grind through it yourself.** For anything past a\n   single trivial point: you're the brain, not the muscle. Spawn one Sonnet\n   subagent per point/cluster (model pinned explicitly on every call, never\n   inherited; effort is your judgment call per task), parallelized across\n   points that touch disjoint files \u2014 never two agents on the same file. You\n   supervise by checking what each subagent's report actually claims and by\n   running the project's own verify/test command yourself afterward, not by\n   rereading every diff or trusting a subagent's \"done.\"\n6. **Each point/cluster, before fixing:**\n   - **Page** + **Selector** + **Note** \u2192 locate the element in the source\n     (priority: `#id` \u2192 `[data-testid]` \u2192 `aria-label` \u2192 `name` \u2192 visual match\n     via the screenshot named in the point's **Screenshot** line \u2014\n     `screenshots/point-N.webp`, or `.png` on browsers without WebP).\n   - **Severity** (`bug`/`question`/`polish`) and **Status**\n     (`open`/`fixed`/`verified` \u2014 `fixed` means someone says it is done but\n     nobody has re-tested it yet)\n     tell you how to treat the point \u2014 a `question` may not need a code\n     change; a `verified` point was already re-checked once.\n   - **Runtime context** (when present, in a collapsed `<details>` block) \u2014\n     recent console errors/warnings and failed network calls captured right\n     before the tester clicked capture, plus an environment snapshot, plus\n     **forensics** (contrast/accessibility flags on the captured element) when\n     present \u2014 treat these as objective acceptance criteria, not just the\n     tester's prose. Read it before assuming a UI-only cause. Query strings in\n     any URL there are already redacted; bodies, headers, cookies, and storage\n     were never captured at all.\n   - **Reproduce it live first** \u2014 run the app, log in as the relevant role,\n     navigate to the page, actually trigger the failure \u2014 before writing a\n     fix. A static screenshot can hide a stale report or an interaction-only\n     bug.\n   - Make the change following the project conventions and invariants, then\n     re-verify the same repro.\n7. **Report** a summary table of changes, risk levels, and coverage status,\n   plus a `### Suggestions` section for anything noticed beyond the reported\n   points. Whether you may *implement* an extra idea (not just suggest it)\n   follows the same red/amber/green gating as everything else: green \u2014 do it\n   inline; amber \u2014 do it and disclose it; red \u2014 propose only, never touch it.\n\n### A single point, no ZIP\n\nA tester can also send you **one point directly**, pasted via Qapture's\n\"Copy as agent prompt\" button, with no ZIP and no preamble. Treat it exactly\nlike one point from step 6 above \u2014 there's nothing to cluster or triage with\nonly one point, and there's no Coverage Report to check or RED-zone flag to\nraise, since there's no journey context at all. Just fix it yourself if it's\ntrivial, or spawn a single subagent if it isn't.\n\n### Full protocol\n\n`.claude/skills/qapture/SKILL.md` (always kept current by `qapture init`).\n\n### Rules\n\n- Never read `.env`, `.env.local`, `.env.production`, or any `secrets/` path.\n- Never edit `qa.config.ts`, `qa.preamble.md`, or any qapture plugin files.\n- Never push/publish/deploy without explicit human approval.\n- Dev/test/seed credentials only \u2014 never use or request production credentials.\n\n_Qapture \u2014 https://github.com/mohammed-farhood/qapture_\n\n<!-- /qa-studio-section -->\n";
 
 // src/bin/utils/args.ts
+var DEFAULT_SHOT_PORT = 7017;
 function parseArgs(argv2) {
   const [cmd, ...rest] = argv2;
+  const base = {
+    dir: process.cwd(),
+    force: false,
+    port: DEFAULT_SHOT_PORT,
+    allow: []
+  };
   if (cmd === "version" || cmd === "--version" || cmd === "-v" || cmd === "-V") {
-    return { command: "version", dir: process.cwd(), force: false };
+    return { ...base, command: "version" };
   }
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
-    return { command: "help", dir: process.cwd(), force: false };
+    return { ...base, command: "help" };
   }
   if (cmd === "init") {
     let dir = process.cwd();
@@ -55,54 +62,229 @@ function parseArgs(argv2) {
         dir = arg;
       }
     }
-    return { command: "init", dir, force };
+    return { ...base, command: "init", dir, force };
+  }
+  if (cmd === "shots") {
+    let port = DEFAULT_SHOT_PORT;
+    const allow = [];
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--port" || arg === "-p") {
+        const n = Number(rest[++i]);
+        if (Number.isInteger(n) && n > 0 && n < 65536) port = n;
+      } else if (arg.startsWith("--port=")) {
+        const n = Number(arg.slice("--port=".length));
+        if (Number.isInteger(n) && n > 0 && n < 65536) port = n;
+      } else if (arg === "--allow") {
+        const origin = rest[++i];
+        if (origin) allow.push(origin.replace(/\/$/, ""));
+      } else if (arg.startsWith("--allow=")) {
+        const origin = arg.slice("--allow=".length);
+        if (origin) allow.push(origin.replace(/\/$/, ""));
+      }
+    }
+    return { ...base, command: "shots", port, allow };
   }
-  return { command: "help", dir: process.cwd(), force: false };
+  return { ...base, command: "help" };
 }
 
-// src/bin/utils/writeIdempotent.ts
+// src/bin/shotServer.ts
+var http = __toESM(require("http"), 1);
+var os = __toESM(require("os"), 1);
 var fs = __toESM(require("fs"), 1);
 var path = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
+var MAX_SIDE = 2e4;
+var CAPTURE_TIMEOUT_MS = 8e3;
+function isLoopbackOrigin(origin) {
+  try {
+    const u = new URL(origin);
+    return u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]" || u.hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+function originAllowed(origin, allow) {
+  if (!origin) return false;
+  if (isLoopbackOrigin(origin)) return true;
+  return allow.includes(origin);
+}
+function corsHeaders(origin) {
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+    "Access-Control-Allow-Headers": "content-type",
+    // Chrome's Private Network Access check: an https page reaching a loopback
+    // address is asked for explicitly, and refused unless we say yes here.
+    "Access-Control-Allow-Private-Network": "true",
+    "Vary": "Origin"
+  };
+}
+function sendJson(res, status, body, extra = {}) {
+  const text = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(text),
+    "Cache-Control": "no-store",
+    ...extra
+  });
+  res.end(text);
+}
+function readBody(req, limit = 4096) {
+  return new Promise((resolve2, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) {
+        reject(new Error("body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => resolve2(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+function captureRect(rect) {
+  const file = path.join(
+    os.tmpdir(),
+    `qapture-shot-${process.pid}-${Date.now()}.png`
+  );
+  const region = `${Math.round(rect.x)},${Math.round(rect.y)},${Math.round(rect.w)},${Math.round(rect.h)}`;
+  return new Promise((resolve2, reject) => {
+    (0, import_node_child_process.execFile)(
+      "/usr/sbin/screencapture",
+      ["-x", "-o", "-r", "-t", "png", "-R", region, file],
+      { timeout: CAPTURE_TIMEOUT_MS },
+      (err) => {
+        if (err) {
+          fs.promises.unlink(file).catch(() => {
+          });
+          reject(err);
+          return;
+        }
+        fs.promises.readFile(file).then((buf) => {
+          fs.promises.unlink(file).catch(() => {
+          });
+          if (!buf.length) {
+            reject(new Error("empty capture"));
+            return;
+          }
+          resolve2(buf);
+        }).catch((e) => {
+          fs.promises.unlink(file).catch(() => {
+          });
+          reject(e);
+        });
+      }
+    );
+  });
+}
+function parseRect(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const o = parsed;
+  const nums = ["x", "y", "w", "h"].map((k) => Number(o[k]));
+  if (nums.some((n) => !Number.isFinite(n))) return null;
+  const [x, y, w, h] = nums;
+  if (w < 1 || h < 1 || w > MAX_SIDE || h > MAX_SIDE) return null;
+  return { x, y, w, h };
+}
+function createShotServer(opts) {
+  return http.createServer((req, res) => {
+    const origin = req.headers.origin;
+    const url = (req.url ?? "").split("?")[0];
+    if (!originAllowed(origin, opts.allow)) {
+      sendJson(res, 403, { error: "origin not allowed" });
+      return;
+    }
+    const cors = corsHeaders(origin);
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, cors);
+      res.end();
+      return;
+    }
+    if (req.method === "GET" && url === "/qapture/health") {
+      sendJson(res, 200, { ok: true, engine: "screencapture", platform: process.platform }, cors);
+      return;
+    }
+    if (req.method === "POST" && url === "/qapture/shot") {
+      readBody(req).then((body) => {
+        const rect = parseRect(body);
+        if (!rect) {
+          sendJson(res, 400, { error: "bad rect" }, cors);
+          return;
+        }
+        return captureRect(rect).then((png) => {
+          if (opts.verbose) {
+            process.stdout.write(
+              `  shot ${Math.round(rect.w)}\xD7${Math.round(rect.h)} @ ${Math.round(rect.x)},${Math.round(rect.y)} \u2192 ${(png.length / 1024).toFixed(0)} KB
+`
+            );
+          }
+          sendJson(res, 200, {
+            png: `data:image/png;base64,${png.toString("base64")}`
+          }, cors);
+        });
+      }).catch((err) => {
+        sendJson(res, 500, { error: err.message || "capture failed" }, cors);
+      });
+      return;
+    }
+    sendJson(res, 404, { error: "not found" }, cors);
+  });
+}
+
+// src/bin/utils/writeIdempotent.ts
+var fs2 = __toESM(require("fs"), 1);
+var path2 = __toESM(require("path"), 1);
 function writeIfAbsent(filePath, content, force) {
-  if (!force && fs.existsSync(filePath)) {
+  if (!force && fs2.existsSync(filePath)) {
     return "skipped";
   }
   ensureParentDir(filePath);
-  fs.writeFileSync(filePath, content, "utf8");
+  fs2.writeFileSync(filePath, content, "utf8");
   return "written";
 }
 function writeAlways(filePath, content) {
   ensureParentDir(filePath);
-  fs.writeFileSync(filePath, content, "utf8");
+  fs2.writeFileSync(filePath, content, "utf8");
 }
 function ensureParentDir(filePath) {
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+  const dir = path2.dirname(filePath);
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
   }
 }
 
 // src/bin/utils/mergeAgentsMd.ts
-var fs2 = __toESM(require("fs"), 1);
+var fs3 = __toESM(require("fs"), 1);
 var SENTINEL_OPEN = "<!-- qa-studio-section -->";
 var SENTINEL_CLOSE = "<!-- /qa-studio-section -->";
 function mergeAgentsMd(agentsMdPath, sectionContent) {
-  if (!fs2.existsSync(agentsMdPath)) {
+  if (!fs3.existsSync(agentsMdPath)) {
     writeAlways(agentsMdPath, sectionContent.trimEnd() + "\n");
     return "created";
   }
-  const existing = fs2.readFileSync(agentsMdPath, "utf8");
+  const existing = fs3.readFileSync(agentsMdPath, "utf8");
   const openIdx = existing.indexOf(SENTINEL_OPEN);
   const closeIdx = existing.indexOf(SENTINEL_CLOSE);
   if (openIdx !== -1 && closeIdx !== -1 && closeIdx > openIdx) {
     const before = existing.slice(0, openIdx);
     const after = existing.slice(closeIdx + SENTINEL_CLOSE.length);
     const updated = before.replace(/\n*$/, "\n") + sectionContent.trimEnd() + "\n" + after.replace(/^\n*/, "\n");
-    fs2.writeFileSync(agentsMdPath, updated, "utf8");
+    fs3.writeFileSync(agentsMdPath, updated, "utf8");
     return "replaced";
   }
   const separator = existing.trimEnd().length === 0 ? "" : "\n\n";
-  fs2.writeFileSync(
+  fs3.writeFileSync(
     agentsMdPath,
     existing.trimEnd() + separator + sectionContent.trimEnd() + "\n",
     "utf8"
@@ -111,12 +293,12 @@ function mergeAgentsMd(agentsMdPath, sectionContent) {
 }
 
 // src/bin/detectors/detectRoutes.ts
-var path4 = __toESM(require("path"), 1);
-var fs4 = __toESM(require("fs"), 1);
+var path5 = __toESM(require("path"), 1);
+var fs5 = __toESM(require("fs"), 1);
 
 // src/bin/utils/walk.ts
-var fs3 = __toESM(require("fs"), 1);
-var path2 = __toESM(require("path"), 1);
+var fs4 = __toESM(require("fs"), 1);
+var path3 = __toESM(require("path"), 1);
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   ".git",
@@ -136,7 +318,7 @@ function walk(dir) {
   const results = [];
   let entries;
   try {
-    entries = fs3.readdirSync(dir, { withFileTypes: true });
+    entries = fs4.readdirSync(dir, { withFileTypes: true });
   } catch {
     return results;
   }
@@ -144,30 +326,30 @@ function walk(dir) {
     if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
-      results.push(...walk(path2.join(dir, entry.name)));
+      results.push(...walk(path3.join(dir, entry.name)));
     } else if (entry.isFile()) {
-      results.push(path2.join(dir, entry.name));
+      results.push(path3.join(dir, entry.name));
     }
   }
   return results;
 }
 function readFileSafe(filePath) {
   try {
-    return fs3.readFileSync(filePath, "utf8");
+    return fs4.readFileSync(filePath, "utf8");
   } catch {
     return "";
   }
 }
 function dirExists(dirPath) {
   try {
-    return fs3.statSync(dirPath).isDirectory();
+    return fs4.statSync(dirPath).isDirectory();
   } catch {
     return false;
   }
 }
 
 // src/bin/utils/secretGuard.ts
-var path3 = __toESM(require("path"), 1);
+var path4 = __toESM(require("path"), 1);
 var BLOCKED_EXACT_BASENAMES = /* @__PURE__ */ new Set([
   ".env",
   ".env.local",
@@ -223,8 +405,8 @@ var BLOCKED_PATH_SEGMENTS = [
 ];
 function assertSafeToRead(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
-  const basename3 = path3.basename(filePath);
-  const ext = path3.extname(filePath).toLowerCase();
+  const basename3 = path4.basename(filePath);
+  const ext = path4.extname(filePath).toLowerCase();
   if (basename3 === ".env.example") return true;
   if (/^\.env\.example(\.\w+)?$/.test(basename3)) return true;
   if (BLOCKED_EXACT_BASENAMES.has(basename3.toLowerCase())) return false;
@@ -285,8 +467,8 @@ function fileToNextPagesRoute(filePath, pagesDir) {
 }
 var APP_PAGE_BASENAME = /^page\.(tsx?|jsx?)$/;
 function fileToAppRoute(filePath, appDir) {
-  if (!APP_PAGE_BASENAME.test(path4.basename(filePath))) return "";
-  let rel = path4.dirname(filePath).slice(appDir.length).replace(/\\/g, "/");
+  if (!APP_PAGE_BASENAME.test(path5.basename(filePath))) return "";
+  let rel = path5.dirname(filePath).slice(appDir.length).replace(/\\/g, "/");
   if (rel.startsWith("/")) rel = rel.slice(1);
   rel = rel.replace(/\([^)]*\)\//g, "").replace(/\([^)]*\)$/, "");
   rel = rel.replace(/\[\.\.\.([^\]]+)\]/g, "*").replace(/\[([^\]]+)\]/g, ":$1");
@@ -298,7 +480,7 @@ var RE_REACT_OBJ = /\bpath:\s*["'](\/?[^"']+)["']/g;
 var RE_VUE_ROUTE = /\{\s*path:\s*["']([^"']+)["']/g;
 var RE_HTTP_ROUTE = /\bapp\.(?:get|post|put|patch|delete|all)\(["']([/][^"']+)["']/g;
 function grepSourceFile(filePath, addRoute) {
-  if (!SOURCE_EXTS.has(path4.extname(filePath).toLowerCase())) return;
+  if (!SOURCE_EXTS.has(path5.extname(filePath).toLowerCase())) return;
   if (!assertSafeToRead(filePath)) return;
   const content = readFileSafe(filePath);
   if (!content) return;
@@ -321,8 +503,8 @@ function detectRoutes(targetDir) {
     if (trimmed && trimmed !== "*") routes.add(trimmed);
   };
   for (const dir of [
-    path4.join(targetDir, "pages"),
-    path4.join(targetDir, "src", "pages")
+    path5.join(targetDir, "pages"),
+    path5.join(targetDir, "src", "pages")
   ]) {
     if (!dirExists(dir)) continue;
     for (const f of walk(dir)) {
@@ -333,8 +515,8 @@ function detectRoutes(targetDir) {
     }
   }
   for (const dir of [
-    path4.join(targetDir, "app"),
-    path4.join(targetDir, "src", "app")
+    path5.join(targetDir, "app"),
+    path5.join(targetDir, "src", "app")
   ]) {
     if (!dirExists(dir)) continue;
     for (const f of walk(dir)) {
@@ -344,7 +526,7 @@ function detectRoutes(targetDir) {
       }
     }
   }
-  const srcDir = path4.join(targetDir, "src");
+  const srcDir = path5.join(targetDir, "src");
   if (dirExists(srcDir)) {
     for (const f of walk(srcDir)) {
       grepSourceFile(f, addRoute);
@@ -352,8 +534,8 @@ function detectRoutes(targetDir) {
   }
   const rootCandidates = ["routes.ts", "routes.js", "router.ts", "router.js", "app.ts", "app.js"];
   for (const name of rootCandidates) {
-    const f = path4.join(targetDir, name);
-    if (fs4.existsSync(f)) grepSourceFile(f, addRoute);
+    const f = path5.join(targetDir, name);
+    if (fs5.existsSync(f)) grepSourceFile(f, addRoute);
   }
   const buckets = { buyer: [], seller: [], admin: [] };
   for (const route of Array.from(routes).sort()) {
@@ -384,8 +566,8 @@ function detectRoutes(targetDir) {
 }
 
 // src/bin/detectors/detectCredentials.ts
-var path5 = __toESM(require("path"), 1);
-var fs5 = __toESM(require("fs"), 1);
+var path6 = __toESM(require("path"), 1);
+var fs6 = __toESM(require("fs"), 1);
 var CREDENTIALS_BANNER = '// DEV/TEST/SEED ONLY \u2014 never production, never commit real passwords.\n// Extracted from .env.example and seeder files only.\n// Replace any "TODO: set from env \u2026" values with your actual dev/test credentials.';
 var SEEDER_PATH_PATTERNS = [
   /[\\/]seeders?[\\/]/i,
@@ -515,16 +697,16 @@ var SEEDER_SEARCH_DIRS = [
 ];
 function detectCredentials(targetDir) {
   const allMatches = [];
-  const envExample = path5.join(targetDir, ".env.example");
-  if (fs5.existsSync(envExample) && assertSafeToRead(envExample)) {
+  const envExample = path6.join(targetDir, ".env.example");
+  if (fs6.existsSync(envExample) && assertSafeToRead(envExample)) {
     const content = readFileSafe(envExample);
     if (content) allMatches.push(...extractMatches(content, envExample));
   }
   for (const rel of SEEDER_SEARCH_DIRS) {
-    const dirPath = path5.join(targetDir, rel);
+    const dirPath = path6.join(targetDir, rel);
     if (!dirExists(dirPath)) continue;
     const files = walk(dirPath).filter((f) => {
-      const ext = path5.extname(f);
+      const ext = path6.extname(f);
       return [".js", ".ts", ".mjs", ".cjs", ".json"].includes(ext) && isSeederFile(f) && assertSafeToRead(f);
     });
     for (const f of files) {
@@ -775,13 +957,13 @@ var REPO_URL = "https://github.com/mohammed-farhood/qapture";
 var PKG_VERSION = (() => {
   try {
     const candidates = [
-      path6.join(__dirname, "..", "..", "package.json"),
-      path6.join(__dirname, "..", "package.json"),
-      path6.join(__dirname, "package.json")
+      path7.join(__dirname, "..", "..", "package.json"),
+      path7.join(__dirname, "..", "package.json"),
+      path7.join(__dirname, "package.json")
     ];
     for (const p of candidates) {
-      if (fs6.existsSync(p)) {
-        const pkg = JSON.parse(fs6.readFileSync(p, "utf8"));
+      if (fs7.existsSync(p)) {
+        const pkg = JSON.parse(fs7.readFileSync(p, "utf8"));
         if (pkg.version) return pkg.version;
       }
     }
@@ -791,14 +973,14 @@ var PKG_VERSION = (() => {
 })();
 function readTargetPkg(targetDir) {
   try {
-    const raw = fs6.readFileSync(path6.join(targetDir, "package.json"), "utf8");
+    const raw = fs7.readFileSync(path7.join(targetDir, "package.json"), "utf8");
     return JSON.parse(raw);
   } catch {
     return {};
   }
 }
 function hasFile(targetDir, ...names) {
-  return names.some((n) => fs6.existsSync(path6.join(targetDir, n)));
+  return names.some((n) => fs7.existsSync(path7.join(targetDir, n)));
 }
 function detectFrameworkHints(targetDir, pkg) {
   const hints = [];
@@ -835,11 +1017,15 @@ qapture CLI v${PKG_VERSION}
 
 Usage:
   qapture init [target-dir] [--force]   Scaffold config + artifacts into target-dir
+  qapture shots [--port N] [--allow O]   Real screenshots without the browser prompt (macOS)
   qapture version                        Print version
 
 Options:
   --force  Overwrite qa.config.* and qa.preamble.md if they already exist
            (SKILL.md is always refreshed regardless of --force)
+  --port   Port for \`shots\` to listen on (default 7017)
+  --allow  Extra origin \`shots\` will answer, repeatable.
+           Loopback (http://localhost:*) is always allowed.
 
 Docs: ${REPO_URL}
 
@@ -916,6 +1102,79 @@ ${DIVIDER}
 `
   );
 }
+function startShotServer(port, allow) {
+  if (process2.platform !== "darwin") {
+    process2.stderr.write(
+      `
+qapture shots needs macOS \u2014 it drives /usr/sbin/screencapture,
+the binary behind Cmd+Shift+4. On ${process2.platform}, Qapture falls back
+to the browser's own screen capture.
+
+`
+    );
+    process2.exit(1);
+  }
+  const server = createShotServer({ port, allow, verbose: true });
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      process2.stderr.write(
+        `
+Port ${port} is already in use.
+
+  If that is another copy of this helper, you are already running one.
+  Otherwise pick a different port:  npx qapture2 shots --port 7018
+  (and set  shotPort: 7018  in your Qapture config, so the widget looks there)
+
+`
+      );
+    } else {
+      process2.stderr.write(`
+qapture shots failed to start: ${err.message}
+
+`);
+    }
+    process2.exit(1);
+  });
+  server.listen(port, "127.0.0.1", () => {
+    process2.stdout.write(
+      `
+${DIVIDER}
+  qapture shots \u2014 real screenshots, no prompt, no heat
+${DIVIDER}
+
+  Listening   127.0.0.1:${port}  (loopback only \u2014 not reachable from the network)
+  Engine      /usr/sbin/screencapture \u2014 the same one Cmd+Shift+4 uses
+  Answering   http://localhost:*  and  http://127.0.0.1:*
+` + (allow.length ? `              ${allow.join("\n              ")}
+` : `              (add others with --allow https://your-site.example)
+`) + `
+  First run: macOS will ask this terminal for Screen Recording permission.
+  Grant it once. It is never asked again, and no capture pipeline is left
+  running between shots \u2014 that is the whole point of moving off the
+  browser's getDisplayMedia.
+
+  If captures come back as wallpaper with no windows in them, the
+  permission was not granted: System Settings \u2192 Privacy & Security \u2192
+  Screen Recording, tick your terminal, then restart it.
+
+  Leave this running while you test. Ctrl+C to stop.
+${DIVIDER}
+
+`
+    );
+  });
+  const shutdown = () => {
+    process2.stdout.write(`
+  qapture shots stopped.
+
+`);
+    server.close(() => process2.exit(0));
+    setTimeout(() => process2.exit(0), 500).unref();
+  };
+  const proc = globalThis.process;
+  proc.on("SIGINT", shutdown);
+  proc.on("SIGTERM", shutdown);
+}
 function main(argv2) {
   const args = parseArgs(argv2);
   if (args.command === "version") {
@@ -926,16 +1185,20 @@ function main(argv2) {
     printUsage();
     process2.exit(0);
   }
-  const targetDir = path6.resolve(args.dir);
+  if (args.command === "shots") {
+    startShotServer(args.port, args.allow);
+    return;
+  }
+  const targetDir = path7.resolve(args.dir);
   const { force } = args;
-  if (!fs6.existsSync(targetDir)) {
+  if (!fs7.existsSync(targetDir)) {
     process2.stderr.write(`
 Error: target directory does not exist: ${targetDir}
 
 `);
     process2.exit(1);
   }
-  if (!fs6.statSync(targetDir).isDirectory()) {
+  if (!fs7.statSync(targetDir).isDirectory()) {
     process2.stderr.write(`
 Error: ${targetDir} is not a directory
 
@@ -967,10 +1230,10 @@ qapture init \u2014 scanning ${targetDir} ...
     frameworkHints
   });
   const preambleText = genPreambleText({ projectName, frameworkHints });
-  const configPath = path6.join(targetDir, configFilename);
-  const preamblePath = path6.join(targetDir, "qa.preamble.md");
-  const skillPath = path6.join(targetDir, ".claude", "skills", "qapture", "SKILL.md");
-  const agentsMdPath = path6.join(targetDir, "AGENTS.md");
+  const configPath = path7.join(targetDir, configFilename);
+  const preamblePath = path7.join(targetDir, "qa.preamble.md");
+  const skillPath = path7.join(targetDir, ".claude", "skills", "qapture", "SKILL.md");
+  const agentsMdPath = path7.join(targetDir, "AGENTS.md");
   const configResult = writeIfAbsent(configPath, configText, force);
   const preambleResult = writeIfAbsent(preamblePath, preambleText, force);
   writeAlways(skillPath, SKILL_default);