@marver-design/marver 0.14.0 → 0.16.0

package/dist/{plugin-BsmG5i2X.mjs → plugin-BXyezwfN.mjs}

@@ -1,13 +1,13 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { i as ROUTE, n as NAME, r as PKG } from "./cli.mjs";
+import { a as nodeExists, c as FOLDERS_FILE, f as readDescription, i as listBoardFiles, m as hash, n as checkBoardsDir, o as readRegistry, p as validateWire, r as isRegularFile, s as BOARD_NAME, t as boardFields } from "./boards-BdG1TJwU.mjs";
 import { n as localProfile, t as isConnected } from "./profile-BjAPAJSb.mjs";
-import { a as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-DvOmglFp.mjs";
-import { copyFileSync, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
+import { i as writeManifest, n as scanFrames, o as loadConfig, t as affectedFrameIds } from "./manifest-CpbsqQ_v.mjs";
+import { copyFileSync, existsSync, linkSync, 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";
 //#region src/server/api.ts
-const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
 const BODY_LIMIT = 1e6;
 const CSRF_MAX_AGE = 2592e3;
 /** Read one cookie value off the request. */
@@ -85,37 +85,18 @@ function contained(target, base) {
 }
 function apiMiddleware(root, opts = {}) {
 	const boardsDir = join(root, "design", "boards");
+	const foldersPath = join(boardsDir, FOLDERS_FILE);
 	const boardPath = (name) => {
-		if (!BOARD_NAME.test(name)) return null;
+		if (!validName(name)) return null;
+		if (checkBoardsDir(root, boardsDir)) return null;
 		mkdirSync(boardsDir, { recursive: true });
 		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;
-		}
-	};
+	const dirError = () => checkBoardsDir(root, boardsDir);
+	const notSymlink = (p) => !nodeExists(p) || isRegularFile(p);
+	const nodeExists$1 = nodeExists;
 	try {
 		for (const f of readdirSync(boardsDir)) if (f.endsWith(".tmp")) rmSync(join(boardsDir, f), { force: true });
 	} catch {}
@@ -144,20 +125,24 @@ function apiMiddleware(root, opts = {}) {
 				return json(res, 200, { boards: {} });
 			}
 			if (path === "boards" && req.method === "GET") {
+				const de = dirError();
+				if (de) return json(res, 422, { error: de });
 				mkdirSync(boardsDir, { recursive: true });
-				return json(res, 200, readdirSync(boardsDir).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp")).map((f) => {
-					const content = readFileSync(join(boardsDir, f), "utf8");
-					let order;
-					try {
-						const o = JSON.parse(content)?.order;
-						if (typeof o === "number" && Number.isFinite(o)) order = o;
-					} catch {}
-					return {
-						name: f.replace(/\.json$/, ""),
-						sha256: hash(content),
-						order
-					};
-				}));
+				return json(res, 200, listBoardFiles(boardsDir).boards.map((b) => ({
+					name: b.name,
+					sha256: b.sha256,
+					...boardFields(b.json, validName)
+				})));
+			}
+			if (path === "folders" && req.method === "GET") {
+				const de = dirError();
+				if (de) return json(res, 422, { error: de });
+				const reg = readRegistry(boardsDir);
+				if (reg.state === "malformed") return json(res, 422, { error: reg.error });
+				return json(res, 200, {
+					folders: reg.folders,
+					sha256: reg.sha256
+				});
 			}
 			if (path === "boards/rename" && req.method === "POST") {
 				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
@@ -173,21 +158,24 @@ function apiMiddleware(root, opts = {}) {
 				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 de = dirError();
+					if (de) return json(res, 400, { error: de });
+				}
 				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` });
+				if (nodeExists$1(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` });
+					if (nodeExists$1(toPath)) return json(res, 409, { error: `a board named "${to}" already exists` });
 					renameSync(fromPath, toPath);
 					return json(res, 200, { name: to });
 				}
@@ -205,25 +193,104 @@ function apiMiddleware(root, opts = {}) {
 					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;
+				const { tree, base } = parsed;
+				const bad = validateWire(tree);
+				if (bad) return json(res, 400, { error: bad });
+				const b = base;
+				if (!b || typeof b !== "object" || !b.boards || typeof b.boards !== "object" || b.folders !== null && typeof b.folders !== "string") return json(res, 400, { error: "expected base hashes" });
+				{
+					const de = dirError();
+					if (de) return json(res, 400, { error: de });
+				}
+				const reg = readRegistry(boardsDir);
+				if (reg.state === "malformed") return json(res, 422, { error: reg.error });
+				if (reg.sha256 !== b.folders) return json(res, 409, {
+					error: "folders changed on disk",
+					stale: [FOLDERS_FILE]
+				});
+				const unseen = listBoardFiles(boardsDir).boards.map((x) => x.name).filter((n) => !(n in b.boards));
+				if (unseen.length) return json(res, 409, {
+					error: "boards changed on disk",
+					stale: unseen
+				});
+				const plan = [];
+				const stale = [];
+				const consider = (name, order, folder) => {
+					const p = boardPath(name);
+					if (!p || !isRegularFile(p)) {
+						stale.push(name);
+						return null;
+					}
+					const content = readFileSync(p, "utf8");
+					if (b.boards[name] !== hash(content)) {
+						stale.push(name);
+						return null;
+					}
 					let obj;
 					try {
-						obj = JSON.parse(readFileSync(p, "utf8"));
+						obj = JSON.parse(content);
 					} catch {
+						return `board "${name}" is not valid JSON - fix the file`;
+					}
+					if (!obj || typeof obj !== "object" || Array.isArray(obj)) return `board "${name}" is not a JSON object - fix the file`;
+					plan.push({
+						name,
+						path: p,
+						obj,
+						order,
+						folder
+					});
+					return null;
+				};
+				const folders = [];
+				for (const [i, it] of tree.entries()) {
+					if (typeof it === "string") {
+						const e = consider(it, i, null);
+						if (e) return json(res, 422, { error: e });
 						continue;
 					}
-					if (!obj || typeof obj !== "object") continue;
-					obj.order = i;
-					atomicWrite(p, JSON.stringify(obj, null, 2) + "\n");
+					const description = readDescription(it.description);
+					folders.push({
+						name: it.folder,
+						order: i,
+						...description ? { description } : {}
+					});
+					for (const [j, kid] of it.boards.entries()) {
+						const e = consider(kid, j, it.folder);
+						if (e) return json(res, 422, { error: e });
+					}
+				}
+				if (stale.length) return json(res, 409, {
+					error: "boards changed on disk",
+					stale
+				});
+				const sha256 = {};
+				for (const w of plan) {
+					if (w.obj.order === w.order && (w.folder ? w.obj.folder === w.folder : w.obj.folder === void 0)) continue;
+					w.obj.order = w.order;
+					if (w.folder) w.obj.folder = w.folder;
+					else delete w.obj.folder;
+					const next = JSON.stringify(w.obj, null, 2) + "\n";
+					atomicWrite(w.path, next);
+					sha256[w.name] = hash(next);
 				}
-				return json(res, 200, { ok: true });
+				mkdirSync(boardsDir, { recursive: true });
+				let foldersSha = null;
+				if (folders.length) {
+					const next = JSON.stringify({
+						version: 1,
+						folders
+					}, null, 2) + "\n";
+					atomicWrite(foldersPath, next);
+					foldersSha = hash(next);
+				} else rmSync(foldersPath, { force: true });
+				return json(res, 200, {
+					ok: true,
+					sha256: {
+						boards: sha256,
+						folders: foldersSha
+					}
+				});
 			}
 			const boardMatch = /^boards\/([^/]+)$/.exec(path);
 			if (boardMatch) {
@@ -268,9 +335,11 @@ function apiMiddleware(root, opts = {}) {
 					}
 					mkdirSync(boardsDir, { recursive: true });
 					const incoming = body.board;
-					if (incoming && typeof incoming === "object" && incoming.order === void 0 && current) try {
-						const o = JSON.parse(current).order;
-						if (typeof o === "number" && Number.isFinite(o)) incoming.order = o;
+					if (incoming && typeof incoming === "object" && current) try {
+						const disk = JSON.parse(current);
+						if (incoming.order === void 0 && typeof disk.order === "number" && Number.isFinite(disk.order)) incoming.order = disk.order;
+						if (incoming.folder === void 0 && validName(disk.folder)) incoming.folder = disk.folder;
+						if (incoming.description === void 0 && readDescription(disk.description)) incoming.description = disk.description;
 					} catch {}
 					const next2 = JSON.stringify(body.board, null, 2) + "\n";
 					atomicWrite(p, next2);
@@ -283,27 +352,59 @@ function apiMiddleware(root, opts = {}) {
 				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 scale = url.searchParams.has("scale") ? Number(url.searchParams.get("scale")) : void 0;
+				const dim = (k) => {
+					const v = Math.round(Number(url.searchParams.get(k)));
+					return url.searchParams.has(k) && Number.isFinite(v) ? v : void 0;
+				};
+				const size = {
+					w: dim("w"),
+					h: dim("h")
+				};
+				const asPng = url.searchParams.get("format") === "png";
 				const origin = opts.origin?.() ?? `http://${req.headers.host ?? "localhost"}`;
-				const { shootFrame } = await import("./shot-kbR_xzJH.mjs");
+				const { shootFrame } = await import("./shot-CwmHO5T4.mjs");
 				const r = await shootFrame({
 					root,
 					viewports: opts.viewports ?? {},
 					frameId,
 					theme,
-					origin
+					origin,
+					scale,
+					size
 				});
-				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, {
+				if (!r.ok) return json(res, r.error.startsWith("unknown frame") ? 404 : r.error.startsWith("invalid ") ? 400 : 503, { error: r.error });
+				const summary = {
 					path: r.path,
 					frame: frameId,
 					theme,
 					width: r.width,
 					height: r.height,
 					scale: r.scale,
-					...r.truncated ? {
-						truncated: true,
-						note: r.note
-					} : {}
+					...r.truncated ? { truncated: true } : {},
+					...r.note ? { note: r.note } : {}
+				};
+				if (!asPng) return json(res, 200, summary);
+				const png = readFileSync(join(root, r.path));
+				res.writeHead(200, {
+					"content-type": "image/png",
+					"content-length": png.length,
+					"cache-control": "no-store",
+					"x-mv-shot": Buffer.from(JSON.stringify(summary)).toString("base64url")
+				});
+				return res.end(png);
+			}
+			if (path === "poster" && req.method === "GET") {
+				if (!ownerGated(req)) return json(res, 403, { error: "forbidden" });
+				const src = url.searchParams.get("src") ?? "";
+				const { ensurePoster, isLocalClip } = await import("./poster-DOY7pax8.mjs");
+				const { isLocalAssetRef } = await import("./build-Ct0iMoSi.mjs");
+				if (!isLocalAssetRef(src) || !isLocalClip(src)) return json(res, 400, { error: "src must be a clip under design/assets/" });
+				const r = await ensurePoster(join(root, "design", "assets"), src);
+				if (!r.ok) return json(res, r.error.includes("does not exist") ? 404 : 503, { error: r.error });
+				return json(res, 200, {
+					path: `design/assets/${src}.poster.png`,
+					generated: r.generated
 				});
 			}
 			if (path === "me" && req.method === "GET") return json(res, 200, {
@@ -579,7 +680,12 @@ const VIRTUAL_CONFIG = "virtual:sh-config";
 const VIRTUAL_DATA = "virtual:sh-data";
 function marverPlugin(ctx) {
 	const { root, clientDir, config } = ctx;
-	let manifest = scanFrames(root);
+	let project = {
+		name: config.share.name || basename(root),
+		description: config.description
+	};
+	const projectInfo = () => project;
+	let manifest = scanFrames(root, projectInfo());
 	let devServer = null;
 	const bootId = String(process.hrtime.bigint());
 	let invRev = 0;
@@ -720,9 +826,13 @@ function marverPlugin(ctx) {
 			}));
 			server.middlewares.use(routesMiddleware(server, clientDir));
 			devServer = server;
+			let framesKey = JSON.stringify(manifest.frames);
 			const regen = debounce(() => {
-				manifest = scanFrames(root);
-				if (writeManifest(root, manifest)) server.ws.send("sh:manifest", manifest);
+				manifest = scanFrames(root, projectInfo());
+				const changed = writeManifest(root, manifest);
+				const key = JSON.stringify(manifest.frames);
+				if (changed && key !== framesKey) server.ws.send("sh:manifest", manifest);
+				framesKey = key;
 			}, 150);
 			const watched = [join(root, "design", "scenes"), join(root, "design", "components")];
 			const inScope = (file) => watched.some((w) => file.startsWith(w));
@@ -759,14 +869,31 @@ function marverPlugin(ctx) {
 					rescanTheme();
 				}
 			});
-			server.watcher.on("change", (f) => inScope(f) && /\.(tsx|jsx)$/.test(f) && regen());
-			writeManifest(root, scanFrames(root));
+			server.watcher.on("change", (f) => inScope(f) && (/\.(tsx|jsx)$/.test(f) || f.endsWith("_brief.md")) && regen());
+			const configFile = join(root, "design", "config.ts");
+			server.watcher.on("change", (f) => {
+				if (f !== configFile) return;
+				loadConfig(root).then((c) => {
+					project = {
+						name: c.share.name || basename(root),
+						description: c.description
+					};
+					regen();
+				}).catch(() => {});
+			});
+			writeManifest(root, manifest);
 			const boardsDir = join(root, "design", "boards");
 			try {
 				mkdirSync(boardsDir, { recursive: true });
 				const timers = /* @__PURE__ */ new Map();
+				let listTimer;
 				const watcher = watch(boardsDir, (_event, file) => {
 					if (!file || !file.endsWith(".json")) return;
+					clearTimeout(listTimer);
+					listTimer = setTimeout(() => {
+						server.ws.send("sh:boards", {});
+						regen();
+					}, 150);
 					clearTimeout(timers.get(file));
 					timers.set(file, setTimeout(() => {
 						timers.delete(file);
@@ -817,7 +944,7 @@ function marverPlugin(ctx) {
 								});
 								return;
 							}
-							const { shootFrame } = await import("./shot-kbR_xzJH.mjs");
+							const { shootFrame } = await import("./shot-CwmHO5T4.mjs");
 							write(await shootFrame({
 								root,
 								viewports: config.viewports,

package/dist/poster-DOY7pax8.mjs

@@ -0,0 +1,143 @@
+import { capture, findChrome } from "./shot-CwmHO5T4.mjs";
+import { constants, copyFileSync, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+//#region src/server/poster.ts
+/**
+* Video posters, generated: a local clip without an authored poster gets one rendered
+* from its own first moments - the same headless Chrome the shot renderer drives, no
+* ffmpeg. The convention is `<clip>.poster.png` beside the clip in design/assets/, and
+* the Video primitive reaches for that name whenever `poster` is omitted, so the dev
+* server (on demand, when the frame first asks) and `marver build` (before assets are
+* copied - a published canvas never ships a poster-less video) produce one file both
+* agree on. An authored poster always wins: this only runs when the file is missing.
+*
+* The frame is taken at min(0.5s, half the duration) - the first frame of most clips is
+* black or a fade. The page is a file:// document holding the clip as a file:// <video>,
+* so nothing has to be served; readiness is the video element appearing in #root once
+* the seek lands, which is the shot renderer's own readiness rule.
+*/
+/** The conventional poster path for a local clip reference (relative to design/assets/). */
+const posterNameFor = (src) => `${src}.poster.png`;
+/** Is this a video reference the generator handles (a local design-asset clip)? The same
+*  grammar the client's assetUrl accepts: relative, forward slashes only, no dot segments. */
+const isLocalClip = (src) => !/^https?:\/\//.test(src) && /\.(mp4|webm|mov|m4v|ogv)$/i.test(src) && !src.includes("\\") && !src.includes(":") && !src.startsWith("/") && !src.split("/").some((seg) => seg === ".." || seg === "." || seg === "");
+/** realpath(p) is base or inside it. */
+const inside = (p, base) => {
+	try {
+		const r = realpathSync(p);
+		return r === base || r.startsWith(base + sep);
+	} catch {
+		return false;
+	}
+};
+const PAGE = (video) => `<!doctype html><html><head><meta charset="utf-8"><style>
+html,body{margin:0;background:#000}#root video{display:block}
+</style></head><body><div id="root"></div><script>
+(function(){
+  var v = document.createElement('video');
+  v.muted = true; v.playsInline = true; v.preload = 'auto'; v.src = ${JSON.stringify(video)};
+  var done = false;
+  function show(){ if (done) return; done = true;
+    var w = Math.min(1920, v.videoWidth || 1280), h = Math.round(w * ((v.videoHeight || 720) / (v.videoWidth || 1280)));
+    v.width = w; v.height = h; v.style.width = w + 'px'; v.style.height = h + 'px';
+    document.getElementById('root').appendChild(v) }
+  v.addEventListener('loadedmetadata', function(){
+    var t = Math.min(0.5, (isFinite(v.duration) ? v.duration : 1) / 2);
+    v.addEventListener('seeked', show, { once: true });
+    v.currentTime = t; });
+  v.addEventListener('error', function(){ window.__mvFrameError = 'the clip could not be decoded by this browser (' + (v.error && v.error.code) + ')' ; document.getElementById('root').appendChild(document.createElement('i')) });
+  setTimeout(function(){ if (!done && v.readyState >= 2) show() }, 4000);
+})();
+<\/script></body></html>`;
+/** Render `<clip>.poster.png` for a clip under design/assets/. Idempotent: an existing
+*  poster (authored or generated) is left alone. */
+async function ensurePoster(assetsDir, src) {
+	if (!isLocalClip(src)) return {
+		ok: false,
+		error: `not a local clip: ${src}`
+	};
+	const clip = join(assetsDir, src);
+	const out = join(assetsDir, posterNameFor(src));
+	if (existsSync(out)) return {
+		ok: true,
+		path: out,
+		width: 0,
+		height: 0,
+		generated: false
+	};
+	if (!existsSync(clip)) return {
+		ok: false,
+		error: `design/assets/${src} does not exist`
+	};
+	let realAssets;
+	try {
+		realAssets = realpathSync(assetsDir);
+	} catch {
+		return {
+			ok: false,
+			error: "design/assets/ does not exist"
+		};
+	}
+	if (!inside(clip, realAssets)) return {
+		ok: false,
+		error: `design/assets/${src} resolves outside design/assets/ - not rendered`
+	};
+	if (!inside(dirname(out), realAssets)) return {
+		ok: false,
+		error: `design/assets/${dirname(src)} resolves outside design/assets/ - not rendered`
+	};
+	if (!findChrome()) return {
+		ok: false,
+		error: `no Chrome/Chromium found to render a poster for ${src} - add poster="..." on the <Video>, or install Chrome`
+	};
+	const dir = mkdtempSync(join(tmpdir(), "mv-poster-"));
+	const page = join(dir, "poster.html");
+	writeFileSync(page, PAGE(pathToFileURL(realpathSync(clip)).href));
+	const tmp = join(dirname(out), `.${basename(out)}.${randomBytes(6).toString("hex")}.tmp`);
+	try {
+		const r = await capture({
+			url: pathToFileURL(page).href,
+			width: 1920,
+			height: 1080,
+			scale: 1,
+			out: tmp,
+			fullHeight: false,
+			clip: "#root video",
+			timeoutMs: 2e4
+		}, "poster");
+		if (!r.ok) return {
+			ok: false,
+			error: `could not render a poster for ${basename(src)} - ${r.error}`
+		};
+		try {
+			copyFileSync(tmp, out, constants.COPYFILE_EXCL);
+		} catch (err) {
+			if (err.code === "EEXIST") return {
+				ok: true,
+				path: out,
+				width: r.width,
+				height: r.height,
+				generated: false
+			};
+			throw err;
+		}
+		return {
+			ok: true,
+			path: out,
+			width: r.width,
+			height: r.height,
+			generated: true
+		};
+	} finally {
+		rmSync(tmp, { force: true });
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+export { ensurePoster, isLocalClip };

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 {