@marver-design/marver 0.13.0 → 0.15.0

package/dist/{shot-Cyv3GN79.mjs → shot-BWhoz6cU.mjs}

@@ -1,6 +1,7 @@
-import { i as ROUTE } from "./cli.mjs";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { a as slideSize, i as ROUTE } from "./cli.mjs";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
 //#region src/server/shot.ts
@@ -35,15 +36,23 @@ function findChrome() {
 }
 const slug = (frameId) => frameId.replace(/\//g, "--");
 const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
-function planShot(frame, viewports) {
-	const cw = typeof frame.contentWidth === "number" && Number.isFinite(frame.contentWidth) && frame.contentWidth > 0 ? frame.contentWidth : void 0;
+const num = (v) => typeof v === "number" && Number.isFinite(v) && v > 0 ? v : void 0;
+function planShot(frame, viewports, override = {}) {
+	const cw = num(frame.contentWidth);
 	const vpObj = frame.viewport ? viewports[frame.viewport] : void 0;
+	const ow = num(override.w), oh = num(override.h);
+	const sl = slideSize(frame);
+	if (sl) return {
+		width: sl.width,
+		initialHeight: sl.height,
+		fullHeight: false
+	};
 	const fallback = viewports.mobile ?? {
 		width: 390,
 		height: 844
 	};
 	if (cw) {
-		const width = clamp(vpObj?.width ?? cw, 320, 1600);
+		const width = clamp(ow ?? vpObj?.width ?? cw, 320, 1600);
 		return {
 			width,
 			initialHeight: Math.round(width * .75),
@@ -51,6 +60,11 @@ function planShot(frame, viewports) {
 		};
 	}
 	const vp = vpObj ?? fallback;
+	if (ow || oh) return {
+		width: clamp(ow ?? vp.width, 120, 3840),
+		initialHeight: clamp(oh ?? vp.height, 80, 2160),
+		fullHeight: false
+	};
 	return {
 		width: vp.width,
 		initialHeight: vp.height,
@@ -61,11 +75,15 @@ function planShot(frame, viewports) {
 *  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;
+	const { root, viewports, frameId, theme, origin, scale = 2, size } = opts;
 	if (!/^[a-z0-9-]+$/i.test(theme)) return {
 		ok: false,
 		error: "invalid theme"
 	};
+	if (!Number.isInteger(scale) || scale < 1 || scale > 4) return {
+		ok: false,
+		error: "invalid scale"
+	};
 	let manifest = {};
 	try {
 		manifest = JSON.parse(readFileSync(join(root, "design", "manifest.json"), "utf8"));
@@ -75,38 +93,99 @@ async function shootFrame(opts) {
 		ok: false,
 		error: `unknown frame "${frameId}" - ids are in design/manifest.json`
 	};
-	const plan = planShot(frame, viewports);
+	const plan = planShot(frame, viewports, size);
+	if (frame.kind !== "html") try {
+		const { scanAssetRefs } = await import("./build-DfuTQZlY.mjs");
+		const { ensurePoster } = await import("./poster-CbpzSzJu.mjs");
+		const refs = scanAssetRefs(readFileSync(join(root, frame.file), "utf8"), frame.file);
+		for (const r of refs) if (r.endsWith(".poster.png")) await ensurePoster(join(root, "design", "assets"), r.slice(0, -11));
+	} catch {}
 	const shotsDir = join(root, "design", ".local", "shots");
 	mkdirSync(shotsDir, { recursive: true });
-	const rel = `design/.local/shots/${slug(frameId)}--${theme}.png`;
+	sweepTemps(shotsDir);
+	const explicit = opts.scale !== void 0;
+	const relFor = (used) => {
+		const tag = !explicit || scale === 2 && used === 2 ? "" : used === scale ? `@${scale}x` : `@${scale}x-as-${used}x`;
+		return `design/.local/shots/${slug(frameId)}--${theme}${tag}.png`;
+	};
+	const tmp = join(shotsDir, `.${slug(frameId)}--${theme}.${randomBytes(6).toString("hex")}.tmp.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: plan.width,
 		height: plan.initialHeight,
-		out: join(root, rel),
-		fullHeight: plan.fullHeight
+		out: tmp,
+		fullHeight: plan.fullHeight,
+		scale
 	});
-	return result.ok ? {
+	if (!result.ok) {
+		rmSync(tmp, { force: true });
+		return result;
+	}
+	const rel = relFor(result.scale);
+	try {
+		try {
+			renameSync(tmp, join(root, rel));
+		} catch (err) {
+			const code = err.code;
+			if (code !== "EEXIST" && code !== "EPERM") throw err;
+			copyFileSync(tmp, join(root, rel));
+		}
+	} catch (err) {
+		return {
+			ok: false,
+			error: `could not write the shot - ${err.message}`
+		};
+	} finally {
+		rmSync(tmp, { force: true });
+	}
+	return {
 		ok: true,
 		path: rel,
 		width: result.width,
 		height: result.height,
 		scale: result.scale,
-		...result.truncated ? {
-			truncated: true,
-			note: result.note
-		} : {}
-	} : result;
+		...result.truncated ? { truncated: true } : {},
+		...result.note ? { note: result.note } : {}
+	};
+}
+/** A crashed process can leave a `.tmp.png` behind; sweep them (older than a minute, so an in-
+*  flight capture in this process is never touched) at the next shot. */
+const sweptAt = /* @__PURE__ */ new Map();
+function sweepTemps(dir) {
+	if (Date.now() - (sweptAt.get(dir) ?? 0) < 6e4) return;
+	sweptAt.set(dir, Date.now());
+	try {
+		for (const f of readdirSync(dir)) {
+			if (!f.endsWith(".tmp.png")) continue;
+			const p = join(dir, f);
+			try {
+				if (Date.now() - statSync(p).mtimeMs > 6e4) rmSync(p, { force: true });
+			} catch {}
+		}
+	} catch {}
 }
-/** 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;
+/** One capture at a time PER LANE: shots are seconds apart at most, and a Chrome per
+*  concurrent request would stampede the machine mid-jam. Posters have their own lane - a
+*  frame being shot may ask for its poster mid-render, and on the shot's lane that request
+*  would wait for the very shot that is waiting for it. */
+const chains = /* @__PURE__ */ new Map();
+function capture(req, lane = "shot") {
+	const run = (chains.get(lane) ?? Promise.resolve()).then(() => captureNow(req), () => captureNow(req));
+	chains.set(lane, run);
 	return run;
 }
-async function captureNow({ url, width, height, out, fullHeight = false, timeoutMs = 3e4 }) {
+/** The capture budget. Chrome's surface tops out near 16384 device px per SIDE, and a bitmap is
+*  also bounded by its AREA: 64M device px (~256 MiB RGBA) is comfortably rendered, encoded and
+*  pasted, where a 3840×2160@4 (133M px) can stall the renderer or the paste target. Both limits
+*  are exported so the tests hold the same numbers. */
+const SURFACE = 16384;
+const AREA = 64e6;
+const fits = (w, h, dsf) => w * dsf <= 16384 && h * dsf <= 16384 && w * h * dsf * dsf <= 64e6;
+/** The tallest CSS height a full-height capture of `width` can hold at `dsf`. */
+const capFor = (width, dsf) => Math.max(1, Math.min(Math.floor(SURFACE / dsf), Math.floor(AREA / (width * dsf * dsf))));
+async function captureNow({ url, width, height, out, fullHeight = false, timeoutMs = 3e4, scale: wantScale = 2, clip }) {
+	let scale = Math.min(4, Math.max(1, Math.round(wantScale)));
+	while (scale > 1 && !fits(width, height, scale)) scale--;
 	const bin = findChrome();
 	if (!bin) return {
 		ok: false,
@@ -199,11 +278,14 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			}
 		});
 		const sendD = (method, params, ms = 1500) => Promise.race([send(method, params, sessionId), new Promise((_, rej) => setTimeout(() => rej(/* @__PURE__ */ new Error(`${method} timed out`)), ms))]);
+		const hardBy = Date.now() + timeoutMs + 15e3;
 		watchdog = setTimeout(() => {
 			try {
 				chrome.kill("SIGKILL");
 			} catch {}
 		}, timeoutMs + 15e3);
+		const RESERVE = 21e3;
+		const discretionary = () => hardBy - RESERVE - Date.now();
 		const { targetId } = await send("Target.createTarget", { url: "about:blank" });
 		const { sessionId } = await send("Target.attachToTarget", {
 			targetId,
@@ -212,7 +294,7 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 		await send("Emulation.setDeviceMetricsOverride", {
 			width,
 			height,
-			deviceScaleFactor: 2,
+			deviceScaleFactor: scale,
 			mobile: false
 		}, sessionId);
 		await send("Page.enable", {}, sessionId);
@@ -238,12 +320,55 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			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 SETTLED = `(() => {
+      if (typeof window.__mvLodBusy === 'function' && window.__mvLodBusy() > 0) return false
+      if (typeof window.__mvPosterBusy === 'function' && window.__mvPosterBusy() > 0) return false
+      const H = window.innerHeight, W = window.innerWidth
+      for (const im of document.images) {
+        if (im.complete) continue
+        const r = im.getBoundingClientRect()
+        if (r.bottom < 0 || r.top > H || r.right < 0 || r.left > W) continue
+        return false
+      }
+      for (const c of document.querySelectorAll('.mv-chart')) if (!c.querySelector('svg, canvas')) return false
+      for (const d of document.querySelectorAll('.mv-diagram')) if (!d.querySelector('.mv-diagram-svg svg, .mv-diagram-err')) return false
+      return true
+    })()`;
+		const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+		const settle = async (budgetMs) => {
+			const total = Math.min(budgetMs, discretionary());
+			if (total <= 0) return false;
+			const by = Date.now() + total;
+			const left = () => Math.max(1, by - Date.now());
+			await sendD("Runtime.evaluate", {
+				expression: `window.postMessage({type:'sh:camera',moving:false,scale:1}, location.origin)`,
+				returnByValue: true
+			}, left()).catch(() => null);
+			await sendD("Runtime.evaluate", {
+				expression: "document.fonts.ready.then(() => true)",
+				awaitPromise: true,
+				returnByValue: true
+			}, left()).catch(() => null);
+			let ok = false;
+			while (Date.now() < by) {
+				if ((await sendD("Runtime.evaluate", {
+					expression: SETTLED,
+					returnByValue: true
+				}, left()).catch(() => null))?.result?.value === true) {
+					ok = true;
+					break;
+				}
+				await wait(Math.min(100, left()));
+			}
+			if (Date.now() < by) await sendD("Runtime.evaluate", {
+				expression: "new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r(true))))",
+				awaitPromise: true,
+				returnByValue: true
+			}, Math.min(1e3, left())).catch(() => null);
+			if (Date.now() < by) await wait(Math.min(ok ? 150 : 250, left()));
+			return ok;
+		};
+		await settle(3e3);
 		const errEval = await send("Runtime.evaluate", {
 			expression: "window.__mvFrameError || \"\"",
 			returnByValue: true
@@ -253,9 +378,8 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			ok: false,
 			error: `the frame rendered an error - ${frameError}`
 		};
-		let capW = width, capH = height, scale = 2, truncated = false, note = "";
+		let capW = width, capH = height, truncated = false, note = "";
 		if (fullHeight) {
-			const wait = (ms) => new Promise((r) => setTimeout(r, ms));
 			const measureH = async () => {
 				const v = (await sendD("Runtime.evaluate", {
 					expression: `Math.ceil((document.querySelector('.mv-doc')||document.getElementById('root')||document.body).getBoundingClientRect().height)`,
@@ -300,46 +424,71 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 					h = Math.max(m, capped);
 				}
 			};
-			const CAP2 = 8192, CAP1 = 16384;
-			const settleDeadline = Date.now() + 6e3;
-			await growFit(2, CAP2, settleDeadline);
-			if (measured > CAP2) {
+			const settleDeadline = Date.now() + Math.max(0, Math.min(6e3, discretionary()));
+			const asked = scale;
+			await growFit(scale, capFor(width, scale), settleDeadline);
+			if (measured > capFor(width, scale) && scale > 2) {
+				scale = 2;
+				await growFit(2, capFor(width, 2), settleDeadline);
+			}
+			if (measured > capFor(width, scale) && scale > 1) {
 				scale = 1;
-				await growFit(1, CAP1, settleDeadline);
+				await growFit(1, capFor(width, 1), settleDeadline);
 			}
-			const cap = scale === 2 ? CAP2 : CAP1;
+			const cap = capFor(width, scale);
 			capW = width;
 			if (measured > cap) {
 				capH = cap;
 				truncated = true;
 				note = `frame is ${measured}px tall; captured the top ${cap}px - split it or reduce its height`;
 			} else capH = clamp(measured || height, 80, cap);
+			if (scale < asked && !truncated) note = `frame is ${measured}px tall - too tall for ${asked}x, captured at ${scale}x`;
 			await sendD("Emulation.setDeviceMetricsOverride", {
 				width: capW,
 				height: capH,
 				deviceScaleFactor: scale,
 				mobile: false
 			}, 5e3);
-			if (Date.now() < settleDeadline) {
-				await sendD("Runtime.evaluate", {
-					expression: `window.postMessage({type:'sh:camera',moving:false,scale:1}, location.origin)`,
-					returnByValue: true
-				}).catch(() => null);
-				await wait(300);
-				for (let j = 0; j < 20 && Date.now() < settleDeadline && !await lodIdle(); j++) await wait(100);
-				await sendD("Runtime.evaluate", {
-					expression: "document.fonts.ready.then(()=>true)",
-					awaitPromise: true,
-					returnByValue: true
-				}).catch(() => null);
+			await wait(Math.min(300, Math.max(0, discretionary())));
+			await settle(Math.max(1200, settleDeadline - Date.now()));
+			const m2 = await measureH();
+			if (m2 > capH) {
+				if (m2 <= cap) capH = m2;
+				else {
+					capH = cap;
+					truncated = true;
+					note = `frame is ${m2}px tall; captured the top ${cap}px - split it or reduce its height`;
+				}
+				await sendD("Emulation.setDeviceMetricsOverride", {
+					width: capW,
+					height: capH,
+					deviceScaleFactor: scale,
+					mobile: false
+				}, 5e3);
+				await settle(600);
 			}
 		}
+		let capX = 0, capY = 0;
+		if (clip) {
+			const box = (await sendD("Runtime.evaluate", {
+				expression: `(() => { const el = document.querySelector(${JSON.stringify(clip)}); if (!el) return null; const b = el.getBoundingClientRect(); return { x: b.x, y: b.y, w: b.width, h: b.height } })()`,
+				returnByValue: true
+			}, 2e3).catch(() => null))?.result?.value;
+			if (!box || box.w < 1 || box.h < 1) return {
+				ok: false,
+				error: `nothing to capture at "${clip}"`
+			};
+			capX = Math.max(0, Math.floor(box.x));
+			capY = Math.max(0, Math.floor(box.y));
+			capW = Math.max(1, Math.round(box.w));
+			capH = Math.max(1, Math.round(box.h));
+		}
 		const shot = await sendD("Page.captureScreenshot", {
 			format: "png",
 			captureBeyondViewport: true,
 			clip: {
-				x: 0,
-				y: 0,
+				x: capX,
+				y: capY,
 				width: capW,
 				height: capH,
 				scale: 1
@@ -351,10 +500,8 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 			width: capW,
 			height: capH,
 			scale,
-			...truncated ? {
-				truncated: true,
-				note
-			} : {}
+			...truncated ? { truncated: true } : {},
+			...note ? { note } : {}
 		};
 	} catch (err) {
 		return {
@@ -378,4 +525,4 @@ async function captureNow({ url, width, height, out, fullHeight = false, timeout
 	}
 }
 //#endregion
-export { shootFrame };
+export { capture, findChrome, shootFrame };

package/dist/{shot-DkkwuCZ2.mjs → shot-By1AItpD.mjs}

@@ -8,12 +8,13 @@ import { readDevInfo } from "./work-CLrmY-vQ.mjs";
 * 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>]`);
+	if (!frame) throw new Error(`name the frame: ${NAME} shot <scene/frame> [--theme <name>] [--scale 1-4]`);
 	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 } : {}
+		...opts.theme ? { theme: opts.theme } : {},
+		...opts.scale != null ? { scale: String(opts.scale) } : {}
 	});
 	let res;
 	try {

package/docs/live-jam.md

@@ -0,0 +1,177 @@
+# Live Jam
+
+Tag `@marver` in a canvas comment while `npx marver dev` is running. The dev server spawns
+your own coding-agent CLI headless with that one job, the frame lights up with a working
+glow, the agent edits the real frame source, and its reply lands back in the same thread.
+No round trip to the terminal. Marver ships no AI: the agent that acts is the one you
+already run and pay for.
+
+## It arms itself
+
+Live Jam is on by default (since 0.9.0). Marver speaks seven agent CLIs - `claude`,
+`codex`, `cursor`, `droid` (Factory), `opencode`, `grok`, and `pi` - which also covers the
+apps built on them: Factory drives `droid`, Cursor drives `cursor-agent`, Conductor drives
+`claude`. Marver looks for one in this order:
+
+1. **The tool running the process wins.** Most CLIs export env markers into what they spawn
+   (`CLAUDECODE` for Claude Code, `CODEX_SANDBOX` for Codex, `CURSOR_AGENT` for Cursor,
+   `OPENCODE` for opencode, `PI_CODING_AGENT` for pi), and `marver init` is usually run by
+   the agent itself. That is evidence, not a guess. droid and grok set no marker in the
+   shells they spawn, so this step cannot see them - name them in config or let PATH decide.
+2. **Otherwise, whatever is on PATH**, in the order above - `claude` first.
+
+That second step is a guess, so the answer is made visible rather than clever: `init` prints
+the agent it chose and writes it into `design/config.ts` in plain sight, and `marver dev`
+names it at boot (`jam: on (claude)`). One word to correct, once per repo.
+
+The candidate has to be executable on `PATH` under its bare name, because the daemon spawns
+it without a shell. A shell alias or function is invisible to it. Cursor is the one agent
+whose binary differs from its config name: marver spawns `cursor-agent`, never the bare
+`agent` - both Cursor and grok install an `agent` name, so the short one is a coin flip.
+
+With no agent CLI installed, jam stays off and both `init` and `marver dev` say so instead
+of going quiet. Workspaces created before 0.9.0 need no re-init; they resolve the same way
+at every dev boot.
+
+## The config block
+
+```ts
+// design/config.ts
+jam: { agent: "claude", concurrency: 6 },
+```
+
+| Key | Default | What it does |
+|---|---|---|
+| `agent` | detected | The CLI the daemon spawns: `"claude"`, `"codex"`, `"cursor"`, `"droid"`, `"opencode"`, `"grok"`, or `"pi"` |
+| `concurrency` | `6` | Frames worked on at once (1-16). The same frame never gets two agents |
+| `subagents` | `true` | Inside one job, fan out one subagent per frame |
+
+Shorthands: `jam: "codex"` names the agent and takes the rest of the defaults, `jam: true`
+is the default block, and **`jam: false` is the off switch**.
+
+A named agent is never quietly swapped for another. If `jam.agent` names something marver
+cannot spawn, or names a CLI that is not on PATH, Live Jam turns off with a printed reason
+rather than answering your comments with a tool you did not choose. A `design/config.ts`
+that fails to parse also leaves jam off, since it may have been the file that said
+`jam: false`.
+
+## What the agent may do
+
+Be clear-eyed about what this is. The real protection is not a sandbox - it is that the
+agent doing the work is **your own**, running on **your machine**, and **every change it
+makes is a diff you review** before anything is resolved. On top of that, marver removes the
+one tool that would turn a prompt-injected comment into silent damage: an unrestricted
+**shell**. Each CLI is spawned so the model can read and edit files but cannot open a shell
+(or, for Codex and Cursor, only a shell the OS sandbox contains and cuts off from the
+network):
+
+| | How it is spawned |
+|---|---|
+| **Claude Code** | `claude -p --permission-mode acceptEdits` with an allowlist of Read, Edit, Write, Glob, Grep, WebSearch, WebFetch - and `--disallowedTools Bash`, so there is no shell |
+| **Codex** | `codex exec -s workspace-write`, its own OS sandbox, which bounds what commands touch and blocks network egress, but still lets the model run shell commands |
+| **Cursor** | `cursor-agent -p --sandbox enabled --trust` - cursor's print mode carries a shell, so like Codex it runs inside the OS sandbox (verified: network egress is blocked); `--trust` only answers the workspace-trust prompt for the repo you already run `marver dev` in, and `--force` is never passed |
+| **droid** | `droid exec --auto low` for file edits, with `--disabled-tools` removing the shell (`Execute`), the delegation tools (`Task`, missions), and the Slack/connector tools |
+| **opencode** | `opencode run --pure` (no external plugins) with a per-run DEFAULT-DENY `OPENCODE_PERMISSION` grant - read/edit/search/web/task allowed by name, everything else (bash included) denied - never its all-approving `--auto` flag |
+| **grok** | `grok -p --tools read_file,search_replace,list_dir,grep,todo_write` - an ALLOWLIST of read/edit tools only, so the shell, web, and subagents are simply absent (a deny-list is a footgun: it can miss a tool's real name); `--permission-mode acceptEdits` auto-applies the edits |
+| **pi** | `pi -p --tools read,edit,write,grep,find,ls --no-extensions --no-skills` - pi has no runtime permission system, so the tool allowlist IS the jail, and bash is not on it |
+
+The honest limits: file tools that take a path (Read/Edit/Write, and their equivalents) are
+not themselves jailed to `design/` - on the CLIs without an OS sandbox they can, if a
+comment talks the model into it, touch a file elsewhere in the repo or the machine. And Web
+access, where a CLI keeps it, can carry data outward. This is the same boundary Claude Code
+has always run under, and it is why the two rules above still do the real work: it is your
+agent, and you review the diff. Do not point Live Jam at a repo, or run it on a machine, you
+would not hand that same agent directly.
+
+Web access stays on where the CLI offers it (Claude Code, Codex, opencode): reference sites
+and real brand SVGs are how a frame stops looking like a placeholder. The agent never
+resolves a thread; you do that after reviewing.
+
+The missing sense that no-shell used to cost - "does my frame actually RENDER?" - is a
+server capability instead, rendered in the machine's own headless Chrome (no bundled
+browser, CDP over Node's built-in WebSocket) and written as a PNG under
+`design/.local/shots/`. Two transports reach it, because the no-shell jail rules out the
+obvious one:
+
+- **The file-drop inbox** (works for every agent, including Claude Code, which has no shell
+  and whose WebFetch refuses localhost). The agent writes
+  `design/.local/shots/<slug>.request.json` with `{"frame":"<id>","theme":"<t>"}`; the dev
+  server renders and writes `<slug>.result.json` with the PNG path or an error, which the
+  agent Reads.
+- **`npx marver shot <frame> [--scale 1-4]`** / `GET /api/shot?frame=<id>&theme=<t>&scale=<n>`
+  for humans and shell-ful agents - the same renderer, one line. Default 2x; `--scale 4` for a
+  print-quality still (a slide comes back 5120×2880). A frame too tall for the asked scale steps
+  down and says so in `note`; the file name carries the scale actually used (`…@4x.png`).
+  The canvas's **copy as image** (`i` / `⇧i`, the images-square toolbar button) is this same
+  renderer with `format=png`, so what a designer pastes and what an agent shoots is one picture.
+
+The generated jam instructions tell every agent to shoot and LOOK before replying "done".
+A frame that never mounts, or a dev server that isn't reachable, comes back as an honest
+`{"ok":false,"error":...}` carrying the real cause - never a blank that reads as success.
+
+One prerequisite marver cannot arrange: **the CLI has to be logged in** (`droid` and
+`cursor-agent login` and `grok login` each have their own flow; opencode and pi can also
+read provider API keys from the environment). An unauthenticated CLI fails the job; the
+daemon retries once, then replies that it could not finish - the dev log and
+`design/.local/jam-logs/` say why.
+
+## The trust boundary
+
+Only comments written on the owner's machine can start work. A mention becomes eligible
+solely by way of the local dev server's owner-gated endpoint (a CSRF double-submit cookie
+plus an Origin allowlist), which appends it to `design/.local/jam-ledger`. The daemon runs
+a job only for an event id that is already in that ledger, so a drive-by comment on a
+published canvas cannot trigger one, and neither can a collaborator comment that arrived
+through `marver comments sync`.
+
+The ledger and the job journal both carry a device stamp, because gitignore is a convention
+and not provenance: a repo can force-add its own `.local/`. Jam state that arrived with a
+clone is read as absent. The stamp is derived from the machine rather than stored, so
+marver still writes nothing outside `design/`.
+
+The larger caution is unchanged and worth stating plainly: `marver dev` imports and executes
+`design/config.ts`, so running a dev server in a repo you do not trust is already running
+that repo's code. Live Jam adds no new hole to that; it does not make it safe.
+
+## Provenance
+
+Every jam reply is stamped with who acted: your dev user, the harness that ran, and the
+model when the agent names one. Claude Code, Cursor, droid, grok, and pi report their model
+in the stream; `codex exec` and `opencode run` report none, so their replies carry the
+harness without a model rather than a guessed one.
+
+## Parallelism
+
+Two knobs stack, and they are not the same thing. `jam.concurrency` is how many jobs the
+daemon runs at once - different frames, different comments. `jam.subagents` is fan-out
+*inside* one job, one subagent per frame, which is what makes a five-frame ask land
+together instead of in series. Claude Code, Codex, and opencode fan out (opencode's
+subagents verifiably inherit the jail); pi has no subagent tool, and droid and grok have
+theirs removed in the spawn itself (`--disabled-tools Task`, `--no-subagents`) until a
+child is proven to inherit the parent's confinement. Their jobs simply run the frames in
+sequence - the prompt only ever says the agent MAY fan out.
+
+Two honest caveats in the same spirit as the config-execution one above: cursor's own
+permission rules (`~/.cursor/cli-config.json`, a repo's `.cursor/cli.json`) and a repo's
+own `opencode.json` agent block can widen what those CLIs allow - that is your
+configuration speaking, and marver does not override it.
+
+## When a mention does nothing
+
+- **It has to be your machine, your repo, with `marver dev` running.** That is the trust
+  boundary above, working as intended.
+- **The first boot after upgrading to 0.9.0 rebaselines the job journal**, because an
+  existing journal predates the device stamp. Any `@marver` left unprocessed while the
+  server was down is marked seen instead of run. Re-comment to pick it up.
+- **Check the boot line.** `marver dev` prints `jam: on (<agent>)` when it is armed, and
+  prints the reason when it is not.
+- **Read the raw run log.** Every job's full agent output lands in
+  `design/.local/jam-logs/` (last 10 kept) - an auth failure or permission refusal
+  explains itself there. The generated `design/instructions/jam.md` carries the full
+  troubleshooting drill, written for your agent to run: it checks the boot line, the log,
+  and the CLI's own headless auth, fixes what belongs to the workspace, and files what
+  belongs to marver at [github.com/TNEP4/marver/issues](https://github.com/TNEP4/marver/issues) -
+  with the patch, when it found one while debugging.
+
+`npx marver comments list --open --json` reads the same threads without the live loop, for
+catching up or for a one-off answer.