@marver-design/marver 0.9.0 → 0.10.1

package/dist/{manifest-DJHU7qfu.mjs → manifest-DIsp3ldB.mjs}

@@ -138,15 +138,46 @@ function firstExisting(root, candidates) {
 * evidence rather than a guess. Whatever wins must still be on PATH - the daemon has to
 * spawn it.
 */
-/** Ordered by preference when a machine has both installed and neither is running us. */
-const AGENTS = ["claude", "codex"];
+/** Ordered by preference when a machine has several installed and none is running us. */
+const AGENTS = [
+	"claude",
+	"codex",
+	"cursor",
+	"droid",
+	"opencode",
+	"grok",
+	"pi"
+];
 /** Env vars each CLI sets in the processes it spawns. Deliberately NOT CODEX_HOME or
 *  ANTHROPIC_API_KEY: those are configuration a human exports by hand, not evidence that
-*  the tool is running right now. */
+*  the tool is running right now. (opencode's `AGENT=1` and pi's `AI_AGENT` are skipped
+*  for the same reason in reverse - too generic to prove WHICH tool is running.)
+*  droid and grok set no marker at all in the shells they spawn (verified against the
+*  grok-build source and droid 0.200.0), so they are found by PATH order only. */
 const MARKERS = {
 	claude: ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"],
-	codex: ["CODEX_SANDBOX", "CODEX_THREAD_ID"]
+	codex: ["CODEX_SANDBOX", "CODEX_THREAD_ID"],
+	cursor: ["CURSOR_AGENT"],
+	droid: [],
+	opencode: ["OPENCODE", "OPENCODE_PID"],
+	grok: [],
+	pi: ["PI_CODING_AGENT", "PI_SESSION_ID"]
 };
+/** The executable each agent name maps to. Only cursor differs: its CLI installs BOTH
+*  `cursor-agent` and a bare `agent` - and grok's installer symlinks `agent` too, so the
+*  short name is a coin flip on a machine with both. The long name is unambiguous. */
+const AGENT_BIN = {
+	claude: "claude",
+	codex: "codex",
+	cursor: "cursor-agent",
+	droid: "droid",
+	opencode: "opencode",
+	grok: "grok",
+	pi: "pi"
+};
+/** The valid `jam.agent` values as an English list - one string, so every surface
+*  (config warning, init note, dev boot line) names the same set and none goes stale. */
+const AGENT_NAMES = `${AGENTS.slice(0, -1).map((a) => `"${a}"`).join(", ")}, or "${AGENTS[AGENTS.length - 1]}"`;
 /** Is `cmd` an executable FILE on PATH? A direct stat per PATH entry - no spawn, no shell,
 *  so this is safe to call on every dev boot. Two deliberate narrowings, both in service of
 *  "found means spawnable", because arming an agent that cannot run is worse than staying off:
@@ -183,8 +214,8 @@ function onPath(cmd, env = process.env) {
 *  that line names the tool it actually is. One word to correct, once per repo. */
 function detectAgent(env = process.env) {
 	const running = AGENTS.find((a) => MARKERS[a].some((k) => env[k]));
-	if (running && onPath(running, env)) return running;
-	return AGENTS.find((a) => onPath(a, env));
+	if (running && onPath(AGENT_BIN[running], env)) return running;
+	return AGENTS.find((a) => onPath(AGENT_BIN[a], env));
 }
 //#endregion
 //#region src/server/config.ts
@@ -278,15 +309,16 @@ const plainObject = (v) => {
 *  claim every @marver mention, fail it, and never retry. */
 function resolveAgent(named) {
 	if (named === void 0) return detectAgent() ?? "no-agent";
-	if (named !== "claude" && named !== "codex") {
-		console.warn(`[marver] design/config.ts: jam.agent ${show(named)} is not an agent marver can spawn - Live Jam is off. Use "claude" or "codex".`);
+	if (typeof named !== "string" || !Object.hasOwn(AGENT_BIN, named)) {
+		console.warn(`[marver] design/config.ts: jam.agent ${show(named)} is not an agent marver can spawn - Live Jam is off. Use ${AGENT_NAMES}.`);
 		return "bad-agent";
 	}
-	if (!onPath(named)) {
-		console.warn(`[marver] design/config.ts names jam.agent "${named}", which is not on PATH - Live Jam is off until it is installed.`);
+	const agent = named;
+	if (!onPath(AGENT_BIN[agent])) {
+		console.warn(`[marver] design/config.ts names jam.agent "${agent}", but \`${AGENT_BIN[agent]}\` is not on PATH - Live Jam is off until it is installed.`);
 		return "bad-agent";
 	}
-	return named;
+	return agent;
 }
 /** Resolve the jam block. Live Jam is ON by default: an absent or partial `jam` resolves
 *  to whatever agent CLI this machine has, so a fresh workspace jams with nothing
@@ -564,4 +596,4 @@ function writeManifest(root, manifest) {
 }
 const hash = (s) => createHash("sha256").update(s).digest("hex");
 //#endregion
-export { DEFAULTS as a, detectHost as c, writeManifest as i, readJson as l, hash as n, loadConfig as o, scanFrames as r, detectAgent as s, affectedFrameIds as t };
+export { writeManifest as a, detectAgent as c, toFrameId as i, detectHost as l, hash as n, DEFAULTS as o, scanFrames as r, loadConfig as s, affectedFrameIds as t, readJson as u };

package/dist/{plugin-BrBWk2Qn.mjs → plugin-DhkR3NdW.mjs}

@@ -1,7 +1,7 @@
 import { i as ROUTE, n as NAME, r as PKG } from "./cli.mjs";
 import { n as localProfile, t as isConnected } from "./profile-BkiWglVE.mjs";
-import { i as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-DJHU7qfu.mjs";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
+import { a as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-DIsp3ldB.mjs";
+import { copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
@@ -82,7 +82,7 @@ function contained(target, base) {
 		return false;
 	}
 }
-function apiMiddleware(root) {
+function apiMiddleware(root, opts = {}) {
 	const boardsDir = join(root, "design", "boards");
 	const boardPath = (name) => {
 		if (!BOARD_NAME.test(name)) return null;
@@ -90,6 +90,31 @@ function apiMiddleware(root) {
 		const p = resolve(boardsDir, `${name}.json`);
 		return contained(p, boardsDir) ? p : null;
 	};
+	const validName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
+	const underRoot = (dir) => {
+		try {
+			const rr = realpathSync(root);
+			const rd = realpathSync(dir);
+			return rd === rr || rd.startsWith(rr + sep);
+		} catch {
+			return false;
+		}
+	};
+	const notSymlink = (p) => {
+		try {
+			return !existsSync(p) || !lstatSync(p).isSymbolicLink();
+		} catch {
+			return false;
+		}
+	};
+	const nodeExists = (p) => {
+		try {
+			lstatSync(p);
+			return true;
+		} catch {
+			return false;
+		}
+	};
 	try {
 		for (const f of readdirSync(boardsDir)) if (f.endsWith(".tmp")) rmSync(join(boardsDir, f), { force: true });
 	} catch {}
@@ -115,6 +140,72 @@ function apiMiddleware(root) {
 					};
 				}));
 			}
+			if (path === "boards/rename" && req.method === "POST") {
+				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
+				const raw = await readBody(req);
+				if (raw == null) return json(res, 400, { error: "body too large or unreadable" });
+				let parsed;
+				try {
+					parsed = JSON.parse(raw);
+				} catch {
+					return json(res, 400, { error: "malformed JSON" });
+				}
+				if (!parsed || typeof parsed !== "object") return json(res, 400, { error: "expected an object" });
+				const { from, to } = parsed;
+				if (!validName(from) || !validName(to)) return json(res, 400, { error: "invalid board name" });
+				if (to === "all-scenes" || from === "all-scenes" || to === from) return json(res, 400, { error: "invalid rename" });
+				if (!underRoot(boardsDir)) return json(res, 400, { error: "boards directory escapes the project" });
+				const fromPath = boardPath(from), toPath = boardPath(to);
+				if (!fromPath || !toPath) return json(res, 400, { error: "invalid board name" });
+				if (!existsSync(fromPath)) return json(res, 404, { error: `board "${from}" does not exist` });
+				if (!notSymlink(fromPath)) return json(res, 400, { error: "refusing to rename a symlinked board file" });
+				if (isConnected(root)) return json(res, 409, { error: "disconnect before renaming boards - comment sync is board-keyed" });
+				if (existsSync(join(root, "design", "comments", `${from}.jsonl`))) return json(res, 409, { error: "rename a board before commenting on it - this board has threads" });
+				if (nodeExists(toPath)) return json(res, 409, { error: `a board named "${to}" already exists` });
+				try {
+					linkSync(fromPath, toPath);
+				} catch (err) {
+					const code = err.code;
+					if (code === "EEXIST") return json(res, 409, { error: `a board named "${to}" already exists` });
+					if (code !== "EPERM" && code !== "ENOSYS" && code !== "ENOTSUP" && code !== "EOPNOTSUPP") throw err;
+					if (nodeExists(toPath)) return json(res, 409, { error: `a board named "${to}" already exists` });
+					renameSync(fromPath, toPath);
+					return json(res, 200, { name: to });
+				}
+				rmSync(fromPath);
+				return json(res, 200, { name: to });
+			}
+			if (path === "boards/reorder" && req.method === "POST") {
+				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
+				const raw = await readBody(req);
+				if (raw == null) return json(res, 400, { error: "body too large or unreadable" });
+				let parsed;
+				try {
+					parsed = JSON.parse(raw);
+				} catch {
+					return json(res, 400, { error: "malformed JSON" });
+				}
+				if (!parsed || typeof parsed !== "object") return json(res, 400, { error: "expected an object" });
+				const order = parsed.order;
+				if (!Array.isArray(order) || order.length < 1 || order.length > 200) return json(res, 400, { error: "invalid order" });
+				if (!order.every(validName) || order.some((n) => n === "all-scenes")) return json(res, 400, { error: "invalid board name in order" });
+				if (new Set(order).size !== order.length) return json(res, 400, { error: "duplicate board in order" });
+				if (!underRoot(boardsDir)) return json(res, 400, { error: "boards directory escapes the project" });
+				for (let i = 0; i < order.length; i++) {
+					const p = boardPath(order[i]);
+					if (!p || !existsSync(p) || !notSymlink(p)) continue;
+					let obj;
+					try {
+						obj = JSON.parse(readFileSync(p, "utf8"));
+					} catch {
+						continue;
+					}
+					if (!obj || typeof obj !== "object") continue;
+					obj.order = i;
+					atomicWrite(p, JSON.stringify(obj, null, 2) + "\n");
+				}
+				return json(res, 200, { ok: true });
+			}
 			const boardMatch = /^boards\/([^/]+)$/.exec(path);
 			if (boardMatch) {
 				const p = boardPath(boardMatch[1]);
@@ -167,6 +258,30 @@ function apiMiddleware(root) {
 					return json(res, 200, { sha256: hash(next2) });
 				}
 			}
+			if (path === "shot" && req.method === "GET") {
+				const { readDevInfo } = await import("./work-CLrmY-vQ.mjs");
+				const token = readDevInfo(root)?.token;
+				if (!ownerGated(req) && !(token && req.headers["x-mv-work"] === token)) return json(res, 403, { error: "forbidden" });
+				const frameId = url.searchParams.get("frame") ?? "";
+				const theme = url.searchParams.get("theme") ?? "light";
+				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
+				const { shootFrame } = await import("./shot-BRgPaFCs.mjs");
+				const r = await shootFrame({
+					root,
+					viewports: opts.viewports ?? {},
+					frameId,
+					theme,
+					origin
+				});
+				if (!r.ok) return json(res, r.error.startsWith("unknown frame") ? 404 : r.error === "invalid theme" ? 400 : 503, { error: r.error });
+				return json(res, 200, {
+					path: r.path,
+					frame: frameId,
+					theme,
+					width: r.width,
+					height: r.height
+				});
+			}
 			if (path === "me" && req.method === "GET") return json(res, 200, {
 				user: localProfile(root),
 				role: "owner",
@@ -565,7 +680,15 @@ function marverPlugin(ctx) {
 					}));
 				});
 			});
-			server.middlewares.use(apiMiddleware(root));
+			const listeningOrigin = () => {
+				const a = server.httpServer?.address();
+				if (!a || typeof a === "string") return null;
+				return `http://${a.family === "IPv6" ? a.address === "::" ? "[::1]" : `[${a.address}]` : a.address === "0.0.0.0" ? "127.0.0.1" : a.address}:${a.port}`;
+			};
+			server.middlewares.use(apiMiddleware(root, {
+				viewports: config.viewports,
+				origin: listeningOrigin
+			}));
 			server.middlewares.use(routesMiddleware(server, clientDir));
 			devServer = server;
 			const regen = debounce(() => {
@@ -630,6 +753,71 @@ function marverPlugin(ctx) {
 				});
 				server.httpServer?.once("close", () => watcher.close());
 			} catch {}
+			try {
+				const inbox = join(root, "design", ".local", "shots");
+				mkdirSync(inbox, { recursive: true });
+				const origin = listeningOrigin;
+				const inFlight = /* @__PURE__ */ new Set();
+				const processRequest = (file) => {
+					if (!file.endsWith(".request.json") || inFlight.has(file)) return;
+					const reqPath = join(inbox, file);
+					if (!existsSync(reqPath)) return;
+					inFlight.add(file);
+					setTimeout(async () => {
+						try {
+							let spec;
+							try {
+								spec = JSON.parse(readFileSync(reqPath, "utf8"));
+							} catch {
+								return;
+							}
+							const base = file.replace(/\.request\.json$/, "");
+							const resultPath = join(inbox, `${base}.result.json`);
+							const frameId = typeof spec.frame === "string" ? spec.frame : "";
+							const theme = typeof spec.theme === "string" ? spec.theme : "light";
+							const o = origin();
+							const write = (r) => {
+								try {
+									writeFileSync(resultPath, JSON.stringify(r, null, 2));
+								} catch {}
+							};
+							if (!o) {
+								write({
+									ok: false,
+									error: "dev server has no address yet - retry"
+								});
+								return;
+							}
+							const { shootFrame } = await import("./shot-BRgPaFCs.mjs");
+							write(await shootFrame({
+								root,
+								viewports: config.viewports,
+								frameId,
+								theme,
+								origin: o
+							}));
+							try {
+								rmSync(reqPath, { force: true });
+							} catch {}
+						} finally {
+							inFlight.delete(file);
+						}
+					}, 60);
+				};
+				const inboxWatcher = watch(inbox, { persistent: false }, (_e, file) => {
+					if (file) processRequest(file);
+				});
+				const sweep = setInterval(() => {
+					try {
+						for (const f of readdirSync(inbox)) processRequest(f);
+					} catch {}
+				}, 1e3);
+				sweep.unref?.();
+				server.httpServer?.once("close", () => {
+					inboxWatcher.close();
+					clearInterval(sweep);
+				});
+			} catch {}
 		}
 	};
 }

package/dist/shot-BRgPaFCs.mjs

@@ -0,0 +1,254 @@
+import { i as ROUTE } from "./cli.mjs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+//#region src/server/shot.ts
+/**
+* Frame screenshots without a dependency - the system's own Chrome, driven over CDP
+* (Node 22 ships a WebSocket client, so this is ~zero cost).
+*
+* This exists for Live Jam's verify loop: a jam agent has no shell (deliberately - the job
+* packet carries untrusted text), so "look at what you built" must be a capability the dev
+* server provides, not a command the agent runs. The /api/shot endpoint calls this; the
+* `marver shot` CLI and a plain WebFetch both reach that endpoint.
+*
+* Readiness is DETERMINISTIC, not a sleep: poll until #root (or body, for html frames) has
+* children, then wait for fonts. A frame that never mounts fails with the page's own
+* exception text - which is exactly what the agent needs to fix it.
+*/
+const CHROMES = [
+	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+	"/Applications/Chromium.app/Contents/MacOS/Chromium",
+	"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+	"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+	"/usr/bin/google-chrome-stable",
+	"/usr/bin/google-chrome",
+	"/usr/bin/chromium",
+	"/usr/bin/chromium-browser"
+];
+/** The browser binary to drive, or null. MARVER_CHROME overrides; otherwise first known install. */
+function findChrome() {
+	const env = process.env.MARVER_CHROME;
+	if (env) return existsSync(env) ? env : null;
+	return CHROMES.find((p) => existsSync(p)) ?? null;
+}
+const slug = (frameId) => frameId.replace(/\//g, "--");
+/** Resolve a frame from the manifest and screenshot it - the shared core behind BOTH
+*  transports (the HTTP /api/shot endpoint and the file-drop inbox), so they validate and
+*  name output identically. `origin` is the dev server's own base URL. */
+async function shootFrame(opts) {
+	const { root, viewports, frameId, theme, origin } = opts;
+	if (!/^[a-z0-9-]+$/i.test(theme)) return {
+		ok: false,
+		error: "invalid theme"
+	};
+	let manifest = {};
+	try {
+		manifest = JSON.parse(readFileSync(join(root, "design", "manifest.json"), "utf8"));
+	} catch {}
+	const frame = (manifest.frames ?? []).find((f) => f.id === frameId);
+	if (!frame) return {
+		ok: false,
+		error: `unknown frame "${frameId}" - ids are in design/manifest.json`
+	};
+	const vp = viewports[frame.viewport ?? ""] ?? viewports.mobile ?? {
+		width: 390,
+		height: 844
+	};
+	const shotsDir = join(root, "design", ".local", "shots");
+	mkdirSync(shotsDir, { recursive: true });
+	const rel = `design/.local/shots/${slug(frameId)}--${theme}.png`;
+	const result = await capture({
+		url: frame.kind === "html" ? `${origin}/${frame.file}?theme=${encodeURIComponent(theme)}` : `${origin}${ROUTE}/frame/?id=${encodeURIComponent(frameId)}&theme=${encodeURIComponent(theme)}`,
+		width: vp.width,
+		height: vp.height,
+		out: join(root, rel)
+	});
+	return result.ok ? {
+		ok: true,
+		path: rel,
+		width: vp.width,
+		height: vp.height
+	} : result;
+}
+/** One capture at a time: shots are seconds apart at most, and a Chrome per concurrent
+*  request would stampede the machine mid-jam. */
+let chain = Promise.resolve();
+function capture(req) {
+	const run = chain.then(() => captureNow(req), () => captureNow(req));
+	chain = run;
+	return run;
+}
+async function captureNow({ url, width, height, out, timeoutMs = 3e4 }) {
+	const bin = findChrome();
+	if (!bin) return {
+		ok: false,
+		error: "no Chrome/Chromium found - install one or set MARVER_CHROME to a browser binary"
+	};
+	const profile = mkdtempSync(join(tmpdir(), "mv-shot-"));
+	const chrome = spawn(bin, [
+		"--headless=new",
+		"--disable-gpu",
+		"--hide-scrollbars",
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--disable-extensions",
+		`--user-data-dir=${profile}`,
+		"--remote-debugging-port=0",
+		"about:blank"
+	], { stdio: [
+		"ignore",
+		"ignore",
+		"pipe"
+	] });
+	let ws = null;
+	let watchdog;
+	try {
+		const wsUrl = await new Promise((resolve, reject) => {
+			let buf = "";
+			const to = setTimeout(() => reject(/* @__PURE__ */ new Error("the browser did not expose devtools in time")), 15e3);
+			chrome.stderr?.on("data", (d) => {
+				buf += d;
+				const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
+				if (m) {
+					clearTimeout(to);
+					resolve(m[1]);
+				}
+			});
+			chrome.on("error", (e) => {
+				clearTimeout(to);
+				reject(e);
+			});
+			chrome.on("exit", () => {
+				clearTimeout(to);
+				reject(/* @__PURE__ */ new Error("the browser exited before exposing devtools"));
+			});
+		});
+		ws = new WebSocket(wsUrl);
+		await new Promise((res, rej) => {
+			ws.onopen = () => res();
+			ws.onerror = () => rej(/* @__PURE__ */ new Error("devtools socket failed"));
+		});
+		let seq = 0;
+		const pending = /* @__PURE__ */ new Map();
+		let lastException = "";
+		const failPending = (why) => {
+			for (const [id, cb] of pending) {
+				pending.delete(id);
+				cb({ error: { message: why } });
+			}
+		};
+		ws.onclose = () => failPending("devtools socket closed");
+		ws.onerror = () => failPending("devtools socket error");
+		ws.onmessage = (e) => {
+			let m;
+			try {
+				m = JSON.parse(String(e.data));
+			} catch {
+				return;
+			}
+			if (m.id && pending.has(m.id)) {
+				pending.get(m.id)(m);
+				pending.delete(m.id);
+			}
+			if (m.method === "Runtime.exceptionThrown") {
+				const d = m.params?.exceptionDetails;
+				lastException = String(d?.exception?.description ?? d?.text ?? "").split("\n")[0];
+			}
+		};
+		const send = (method, params = {}, sessionId) => new Promise((res, rej) => {
+			const id = ++seq;
+			pending.set(id, (m) => m.error ? rej(/* @__PURE__ */ new Error(`${method}: ${m.error.message}`)) : res(m.result));
+			try {
+				ws.send(JSON.stringify({
+					id,
+					method,
+					params,
+					sessionId
+				}));
+			} catch (e) {
+				pending.delete(id);
+				rej(e);
+			}
+		});
+		watchdog = setTimeout(() => {
+			try {
+				chrome.kill("SIGKILL");
+			} catch {}
+		}, timeoutMs + 15e3);
+		const { targetId } = await send("Target.createTarget", { url: "about:blank" });
+		const { sessionId } = await send("Target.attachToTarget", {
+			targetId,
+			flatten: true
+		});
+		await send("Emulation.setDeviceMetricsOverride", {
+			width,
+			height,
+			deviceScaleFactor: 2,
+			mobile: false
+		}, sessionId);
+		await send("Page.enable", {}, sessionId);
+		await send("Runtime.enable", {}, sessionId);
+		const nav = await send("Page.navigate", { url }, sessionId);
+		if (nav?.errorText && nav.errorText !== "net::ERR_ABORTED") return {
+			ok: false,
+			error: `could not load the frame (${nav.errorText}) - is the dev server reachable at ${new URL(url).origin}?`
+		};
+		const t0 = Date.now();
+		let ready = false;
+		while (Date.now() - t0 < timeoutMs) {
+			if ((await send("Runtime.evaluate", {
+				expression: `(() => { const el = document.getElementById('root') ?? document.body; return !!el && el.childElementCount > 0 && document.readyState !== 'loading' })()`,
+				returnByValue: true
+			}, sessionId).catch(() => null))?.result?.value) {
+				ready = true;
+				break;
+			}
+			await new Promise((r2) => setTimeout(r2, 150));
+		}
+		if (!ready) return {
+			ok: false,
+			error: `the frame never rendered${lastException ? ` - the page threw: ${lastException}` : " (no exception surfaced - is the dev server reachable from this machine?)"}`
+		};
+		await send("Runtime.evaluate", {
+			expression: "document.fonts.ready.then(() => true)",
+			awaitPromise: true,
+			returnByValue: true
+		}, sessionId).catch(() => null);
+		await new Promise((r2) => setTimeout(r2, 250));
+		const errEval = await send("Runtime.evaluate", {
+			expression: "window.__mvFrameError || \"\"",
+			returnByValue: true
+		}, sessionId).catch(() => null);
+		const frameError = typeof errEval?.result?.value === "string" ? errEval.result.value : "";
+		if (frameError) return {
+			ok: false,
+			error: `the frame rendered an error - ${frameError}`
+		};
+		const shot = await send("Page.captureScreenshot", { format: "png" }, sessionId);
+		writeFileSync(out, Buffer.from(String(shot.data), "base64"));
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			error: err.message
+		};
+	} finally {
+		if (watchdog) clearTimeout(watchdog);
+		try {
+			ws?.close();
+		} catch {}
+		chrome.kill("SIGKILL");
+		chrome.once("exit", () => {
+			try {
+				rmSync(profile, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+		});
+	}
+}
+//#endregion
+export { shootFrame };

package/dist/shot-DkkwuCZ2.mjs

@@ -0,0 +1,29 @@
+import { n as NAME } from "./cli.mjs";
+import { readDevInfo } from "./work-CLrmY-vQ.mjs";
+//#region src/cli/shot.ts
+/**
+* `marver shot <scene/frame>` - render one frame headless and print the PNG path.
+*
+* The shell-ful agents' door into the same verify loop jam teaches: build, shoot, LOOK.
+* Thin wrapper over the dev server's /api/shot (shot.ts has the capture story).
+*/
+async function shotCommand(root, frame, opts) {
+	if (!frame) throw new Error(`name the frame: ${NAME} shot <scene/frame> [--theme <name>]`);
+	const info = readDevInfo(root);
+	if (!info) throw new Error(`\`${NAME} dev\` is not running in this repo (design/.local/dev.json not found) - start it first.`);
+	const qs = new URLSearchParams({
+		frame,
+		...opts.theme ? { theme: opts.theme } : {}
+	});
+	let res;
+	try {
+		res = await fetch(`http://localhost:${info.port}/__mv/api/shot?${qs}`, { headers: { "x-mv-work": info.token } });
+	} catch {
+		throw new Error(`could not reach \`${NAME} dev\` on port ${info.port} - is it still running?`);
+	}
+	const data = await res.json().catch(() => ({}));
+	if (!res.ok || !data.path) throw new Error(data.error ?? `shot failed (${res.status})`);
+	console.log(data.path);
+}
+//#endregion
+export { shotCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/frame-host/main.tsx

@@ -20,7 +20,14 @@ document.documentElement.classList.toggle('dark', theme === 'dark')
 
 const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 
+// A render failure posts sh:error to the shell, but a HEADLESS screenshot has no shell to
+// hear it - so also stamp the error on the document, where the shot capture can read it.
+// This is what lets `marver shot` / the file-drop result report "the frame crashed" to an
+// agent that cannot see the PNG (only the JSON), instead of a clean-looking ok:true.
+const markError = (message: string) => { (window as any).__mvFrameError = message }
+
 function fail(message: string) {
+  markError(message)
   post({ type: 'sh:error', id, message })
   document.getElementById('root')!.innerHTML =
     `<div style="font-family:ui-monospace,monospace;font-size:12px;padding:16px;color:#b42318">
@@ -35,7 +42,7 @@ const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt
 class Boundary extends Component<{ children: ReactNode }, { err: Error | null }> {
   state = { err: null as Error | null }
   static getDerivedStateFromError(err: Error) { return { err } }
-  componentDidCatch(err: Error) { post({ type: 'sh:error', id, message: err.message }) }
+  componentDidCatch(err: Error) { markError(err.message); post({ type: 'sh:error', id, message: err.message }) }
   render() {
     if (!this.state.err) return this.props.children
     return createElement('div', { style: { fontFamily: 'ui-monospace,monospace', fontSize: 12, padding: 16, color: '#b42318' } },