@marver-design/marver 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.10.2 - 2026-08-24
+
+### Fixed
+
+- **`marver shot` renders content frames at their real size.** The verify-loop screenshot
+  (and the file-drop `design/.local/shots/*.request.json` transport) used to capture every
+  frame at the mobile viewport - a 780x1688 crop - so a `Doc layout="wide"` frame came back
+  squeezed and anything past ~1688px tall was invisible to the verifying agent. A shot now
+  sizes a content frame the way the canvas does: its `contentWidth` (760 document / 1280 wide,
+  or a declared `meta.viewport`'s width) at full measured height. Long frames render in full;
+  past a capture-safe height the shot drops to 1x pixel density and, if still enormous, reports
+  `truncated` with a note rather than producing a gigapixel PNG. The `/api/shot` and file-drop
+  results now include `scale` and, when clipped, `truncated`/`note`.
+- **A slow dev server no longer fails a healthy frame.** A frame that hadn't reported ready
+  within 10s was marked `frame failed` / `frame never reported ready (10s)`, hidden behind a red
+  card that only a per-frame click could clear - but the frame was usually fine, just waiting on
+  a slow module response (Vite re-optimizing dependencies, or the box saturated by parallel Live
+  Jam agents). A genuine failure already reports itself immediately, so silence past the deadline
+  now auto-renavigates the frame once on a fresh revision; if it's still loading it stays visible
+  behind a quiet "still loading" pill (with its own reload) instead of a failure. A late ready
+  clears it, and a stale ready from the superseded document is dropped by generation so it can't
+  mark a reloading frame ready.
+
+### Added
+
+- **`marver dev` warns when your instructions predate the installed package.** Upgrading the
+  package doesn't refresh the managed files in `design/` - so a workspace scaffolded on an
+  older version could run the new daemon against an agent contract that predated it (for
+  example, Live Jam armed with no `jam.md` on disk). Dev now prints one line at boot when a
+  managed instruction file is behind the installed version - `instructions predate marver
+  <version> (jam.md, ...) - run: npx marver init` - comparing the on-disk `marver:managed`
+  hashes against what this version ships. Files you edited or detached are never flagged.
+
 ## 0.10.1 - 2026-08-21
 
 ### Added

package/dist/{build-BkckEcZd.mjs → build-zUf_kwKp.mjs}

@@ -1,6 +1,6 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
 import { l as detectHost, r as scanFrames, s as loadConfig } from "./manifest-DIsp3ldB.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DhkR3NdW.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-C1sDewZ3.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/cli.mjs

@@ -39,14 +39,14 @@ function version() {
 }
 const cli = cac(NAME);
 cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "studio | embedded", { default: "studio" }).option("--no-demo", "Skip the demo scene (the demo ships unless this flag is passed)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { init } = await import("./init-D2EQEbV6.mjs");
+	const { init } = await import("./init-DwV0_d9G.mjs");
 	init(resolve(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot reload, comments, Live Jam)"], ["canvas", "Start the local canvas - same as dev"]]) cli.command(name, desc).option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-Bm-R_-gs.mjs");
+	const { dev } = await import("./dev-D2PG6igI.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -56,7 +56,7 @@ for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot
 	await dev(resolve(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-BkckEcZd.mjs");
+	const { buildSite } = await import("./build-zUf_kwKp.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards, opts.allBoards === true);

package/dist/{daemon-B_8BmmSJ.mjs → daemon-BpKBJZee.mjs}

@@ -1,9 +1,9 @@
-import { r as deviceId, t as has } from "./ledger-BgA7nQoH.mjs";
 import { n as replay } from "./events-BMtBvvgU.mjs";
 import { appendEvents, listBoards, readLog } from "./comments-BZBKhKRO.mjs";
 import { n as localProfile } from "./profile-BkiWglVE.mjs";
 import { i as toFrameId } from "./manifest-DIsp3ldB.mjs";
 import { workActivity } from "./work-CLrmY-vQ.mjs";
+import { r as deviceId, t as has } from "./ledger-Bu0BjqIe.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { randomBytes, randomUUID } from "node:crypto";

package/dist/{dev-Bm-R_-gs.mjs → dev-D2PG6igI.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
 import { l as detectHost, s as loadConfig } from "./manifest-DIsp3ldB.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DhkR3NdW.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-C1sDewZ3.mjs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";
@@ -141,6 +141,16 @@ async function dev(root, portFlag) {
 	const port = typeof addr === "object" && addr ? addr.port : picked.port;
 	if (picked.fellBack) console.log(`\n  port ${desiredPort} is in use - serving "${projectName}" on ${port} instead`);
 	console.log(`\n  ${NAME} · ${projectName} → http://localhost:${port}/\n`);
+	try {
+		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
+		const { installedVersion } = await import("./plugin-C1sDewZ3.mjs").then((n) => n.i);
+		const stale = staleManagedInstructions(root);
+		if (stale.length) {
+			const shown = stale.slice(0, 4).join(", ") + (stale.length > 4 ? `, +${stale.length - 4} more` : "");
+			const v = installedVersion();
+			console.log(`  instructions predate ${v ? NAME + " " + v : "the installed version"} (${shown}) - run: npx ${NAME} init\n`);
+		}
+	} catch {}
 	const { loadCollab, syncOnce } = await import("./sync-BJKKmy1n.mjs");
 	if (loadCollab(root)) console.log(`  comments: syncing with the published canvas (design/.local/collab.json)\n`);
 	let syncing = false;
@@ -171,7 +181,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-B_8BmmSJ.mjs");
+		const { startJam } = await import("./daemon-BpKBJZee.mjs");
 		const jam = startJam(root, config.jam, (m) => console.log(m), (board) => server.ws.send("sh:jam-comment", { board }));
 		if (jam) {
 			const close = server.close.bind(server);

package/dist/{init-D2EQEbV6.mjs → init-DwV0_d9G.mjs}

@@ -1,20 +1,9 @@
 import { n as NAME } from "./cli.mjs";
 import { a as writeManifest, c as detectAgent, l as detectHost, o as DEFAULTS, r as scanFrames, u as readJson } from "./manifest-DIsp3ldB.mjs";
+import { MANAGED_PREFIX, enumerateInstructionTemplates, hashBody, managedFile, pkgDir } from "./managed-HwHVNI3h.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createHash } from "node:crypto";
 //#region src/cli/init.ts
-/** Package root = the nearest ancestor holding templates/ (one hop from dist/, two
-*  from src/cli/ - the walk serves both, and tests run init from source). */
-const pkgDir = () => {
-	let dir = dirname(fileURLToPath(import.meta.url));
-	for (let i = 0; i < 4; i++) {
-		if (existsSync(join(dir, "templates"))) return dir;
-		dir = dirname(dir);
-	}
-	return join(dirname(fileURLToPath(import.meta.url)), "..");
-};
 /** Idempotent scaffolder: never overwrites existing files; every host-repo touch prints a diff. */
 function init(root, opts) {
 	const host = detectHost(root);
@@ -57,7 +46,7 @@ function init(root, opts) {
 			rmSync(latest, { force: true });
 			return;
 		}
-		if (current.startsWith(MANAGED_PREFIX)) {
+		if (current.startsWith("<!-- marver:managed ")) {
 			const recorded = current.slice(MANAGED_PREFIX.length).split(" ")[0];
 			const nl = current.indexOf("\n");
 			const currentBody = nl >= 0 ? current.slice(nl + 1) : "";
@@ -75,7 +64,7 @@ function init(root, opts) {
 				}
 				console.warn(`  ~ design/${rel}: you customized it and a newer version exists - your edits are untouched. Merge what you want from design/.local/latest/${rel}`);
 			}
-		} else if (current.startsWith(LEGACY_PREFIX)) {
+		} else if (current.startsWith("<!-- generated by marver init")) {
 			writeFileSync(file, next);
 			rmSync(latest, { force: true });
 			created.push(`design/${rel} (updated)`);
@@ -93,7 +82,7 @@ function init(root, opts) {
 	write("providers.tsx", providersTemplate(host.router, host.toaster, host.routerPkg));
 	writeManaged("AGENTS.md", readFileSync(join(templates, `AGENTS-${opts.mode}.md`), "utf8").replaceAll("{{UI_GUIDANCE}}", uiGuidance(host, noApp(host))).replace(/\{\{NEXT_NOTES\}\}\n?/, host.router === "next" ? NEXT_NOTES : ""));
 	const agentsNow = readFileSync(join(design, "AGENTS.md"), "utf8");
-	if (!agentsNow.startsWith(MANAGED_PREFIX) && !agentsNow.startsWith(LEGACY_PREFIX) && agentsNow.includes("# Design canvas - agent contract") && !agentsNow.includes("## The method (binding)")) console.warn(`  note: design/AGENTS.md predates managed regeneration - if you never edited it, delete it and re-run init to get the current contract (incl. the design/instructions routing).`);
+	if (!agentsNow.startsWith("<!-- marver:managed ") && !agentsNow.startsWith("<!-- generated by marver init") && agentsNow.includes("# Design canvas - agent contract") && !agentsNow.includes("## The method (binding)")) console.warn(`  note: design/AGENTS.md predates managed regeneration - if you never edited it, delete it and re-run init to get the current contract (incl. the design/instructions routing).`);
 	const claudeMd = join(root, "CLAUDE.md");
 	const importLine = "@design/AGENTS.md";
 	if (!existsSync(claudeMd)) {
@@ -118,15 +107,12 @@ function init(root, opts) {
 			created.push("AGENTS.md (updated)");
 		}
 	}
-	const instrRoot = join(templates, "instructions");
-	for (const e of readdirSync(instrRoot, { withFileTypes: true })) if (e.isDirectory()) {
-		for (const f of readdirSync(join(instrRoot, e.name))) if (f.endsWith(".md")) writeManaged(`instructions/${e.name}/${f}`, readFileSync(join(instrRoot, e.name, f), "utf8"));
-	} else if (e.name.endsWith(".md")) writeManaged(`instructions/${e.name}`, readFileSync(join(instrRoot, e.name), "utf8"));
+	for (const { rel, body } of enumerateInstructionTemplates(templates)) writeManaged(rel, body);
 	const setupPath = join(design, "instructions", "setup.md");
 	const setupState = () => {
 		if (!existsSync(setupPath)) return "absent";
 		const s = readFileSync(setupPath, "utf8");
-		if (s.startsWith(MANAGED_PREFIX)) {
+		if (s.startsWith("<!-- marver:managed ")) {
 			const recorded = s.slice(MANAGED_PREFIX.length).split(" ")[0];
 			const nl = s.indexOf("\n");
 			return nl >= 0 && hashBody(s.slice(nl + 1)) === recorded ? "ours-pristine" : "ours-edited";
@@ -136,7 +122,7 @@ function init(root, opts) {
 	const setupWas = setupState();
 	const appJustAppeared = !noApp(host) && (setupWas === "ours-pristine" || setupWas === "ours-edited");
 	if (noApp(host)) {
-		if (setupWas === "ours-pristine" && !readFileSync(setupPath, "utf8").startsWith(MANAGED_PREFIX)) rmSync(setupPath);
+		if (setupWas === "ours-pristine" && !readFileSync(setupPath, "utf8").startsWith("<!-- marver:managed ")) rmSync(setupPath);
 		if (setupWas !== "foreign") writeManaged("instructions/setup.md", SETUP_MD);
 	} else if (setupWas === "ours-pristine") {
 		rmSync(setupPath);
@@ -193,13 +179,6 @@ function init(root, opts) {
 	console.log(`\n  next: npx ${NAME} dev   (or: npx ${NAME} canvas - same thing; canvas on http://localhost:${DEFAULTS.port} by default)\n`);
 	if (!noApp(host)) console.log(`  then, to your agent: "Read design/AGENTS.md. This is our first session - follow design/instructions/welcome.md."\n`);
 }
-const MANAGED_PREFIX = "<!-- marver:managed ";
-const LEGACY_PREFIX = "<!-- generated by marver init";
-const hashBody = (s) => createHash("sha256").update(s).digest("hex");
-/** The marker carries a hash of the generated body: edits are DETECTED, not assumed.
-*  Edit freely - init preserves edits and stages upstream updates for merging.
-*  Deleting the marker line detaches the file from updates entirely. */
-const managedFile = (body) => `${MANAGED_PREFIX}${hashBody(body)} - edit freely: init preserves your edits and stages upstream updates at design/.local/latest/ for you to merge. Delete this line to detach this file from updates entirely. -->\n${body}`;
 /** The host's path aliases, re-rooted one level down for design/tsconfig.json.
 *  "./src/*" becomes "../src/*" so `@/` imports resolve from inside design/. */
 function designPaths(root) {

package/dist/{ledger-BgA7nQoH.mjs → ledger-Bu0BjqIe.mjs}

@@ -1,19 +1,8 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { createHash } from "node:crypto";
 import { homedir, hostname, userInfo } from "node:os";
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
 //#region src/server/jam/device.ts
 /**
 * The device stamp - what makes "device-bound" true for the two files that decide whether

package/dist/managed-HwHVNI3h.mjs

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+//#region src/server/managed.ts
+/**
+* Managed-file identity - the ONE source of truth for the `marver:managed <hash>` marker,
+* shared by `init` (which WRITES managed files) and `dev`'s boot-time staleness probe (which
+* only READS them). Kept side-effect-free on purpose: dev must learn whether the on-disk
+* instructions are behind the installed package WITHOUT importing the mutating init() path.
+*/
+/** The marker records a HASH of the generated body: edits are DETECTED, not assumed. */
+const MANAGED_PREFIX = "<!-- marver:managed ";
+/** Hashless 0.2.2-dev marker: edits are undetectable, so init unconditionally upgrades it. */
+const LEGACY_PREFIX = "<!-- generated by marver init";
+const hashBody = (s) => createHash("sha256").update(s).digest("hex");
+/** Prepend the managed marker to a generated body. Deleting the marker line detaches the
+*  file from updates entirely. */
+const managedFile = (body) => `${MANAGED_PREFIX}${hashBody(body)} - edit freely: init preserves your edits and stages upstream updates at design/.local/latest/ for you to merge. Delete this line to detach this file from updates entirely. -->\n${body}`;
+/** Package root = the nearest ancestor holding templates/ (one hop from dist/, two from
+*  src/** - the walk serves both, and tests run from source). */
+const pkgDir = () => {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 4; i++) {
+		if (existsSync(join(dir, "templates"))) return dir;
+		dir = dirname(dir);
+	}
+	return join(dirname(fileURLToPath(import.meta.url)), "..");
+};
+const templatesDir = () => join(pkgDir(), "templates");
+function classifyManaged(current, shippedBody) {
+	if (current == null) return "absent";
+	if (current.startsWith("<!-- marver:managed ")) {
+		const nl = current.indexOf("\n");
+		if (nl < 0) return "detached";
+		const recorded = current.slice(20).split(" ")[0];
+		if (!/^[0-9a-f]{64}$/.test(recorded)) return "detached";
+		const body = current.slice(nl + 1);
+		const shipped = hashBody(shippedBody);
+		if (hashBody(body) === recorded) return recorded === shipped ? "pristine-current" : "pristine-stale";
+		return recorded === shipped ? "edited-current" : "edited-stale";
+	}
+	if (current.startsWith("<!-- generated by marver init")) return "legacy";
+	return "detached";
+}
+/** The managed INSTRUCTION set init writes, enumerated identically (init.ts): top-level
+*  templates/instructions/*.md plus one level of subdirectory *.md (reference/). setup.md is
+*  the SETUP_MD constant written separately/conditionally - it is not a template file, so it
+*  never appears here. */
+function enumerateInstructionTemplates(templatesRoot) {
+	const instrRoot = join(templatesRoot, "instructions");
+	const out = [];
+	if (!existsSync(instrRoot)) return out;
+	for (const e of readdirSync(instrRoot, { withFileTypes: true })) if (e.isDirectory()) {
+		for (const f of readdirSync(join(instrRoot, e.name))) if (f.endsWith(".md")) out.push({
+			rel: `instructions/${e.name}/${f}`,
+			body: readFileSync(join(instrRoot, e.name, f), "utf8")
+		});
+	} else if (e.name.endsWith(".md") && e.name !== "setup.md") out.push({
+		rel: `instructions/${e.name}`,
+		body: readFileSync(join(instrRoot, e.name), "utf8")
+	});
+	return out;
+}
+const STALE = /* @__PURE__ */ new Set([
+	"absent",
+	"pristine-stale",
+	"edited-stale",
+	"legacy"
+]);
+/**
+* Which managed instruction files on disk are behind the INSTALLED package (distinct from the
+* registry update-check). Returns display names (basenames) of the stale files, AGENTS.md
+* included only when the file is entirely ABSENT (a deleted marker is the documented opt-out,
+* and AGENTS.md is host-substituted so its pristine hash never matches the raw template).
+* Never throws: any read/enumeration failure yields an empty list so a boot can't crash on it.
+*/
+function staleManagedInstructions(root) {
+	try {
+		const design = join(root, "design");
+		const stale = [];
+		for (const { rel, body } of enumerateInstructionTemplates(templatesDir())) {
+			const file = join(design, rel);
+			const current = existsSync(file) ? readFileSync(file, "utf8") : null;
+			if (STALE.has(classifyManaged(current, body))) stale.push(rel.split("/").pop() ?? rel);
+		}
+		if (!existsSync(join(design, "AGENTS.md"))) stale.unshift("AGENTS.md");
+		return stale;
+	} catch {
+		return [];
+	}
+}
+//#endregion
+export { LEGACY_PREFIX, MANAGED_PREFIX, enumerateInstructionTemplates, hashBody, managedFile, pkgDir, staleManagedInstructions };

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

@@ -1,3 +1,4 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 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 { a as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-DIsp3ldB.mjs";
@@ -265,7 +266,7 @@ function apiMiddleware(root, opts = {}) {
 				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 { shootFrame } = await import("./shot-D7I0MCLu.mjs");
 				const r = await shootFrame({
 					root,
 					viewports: opts.viewports ?? {},
@@ -279,7 +280,12 @@ function apiMiddleware(root, opts = {}) {
 					frame: frameId,
 					theme,
 					width: r.width,
-					height: r.height
+					height: r.height,
+					scale: r.scale,
+					...r.truncated ? {
+						truncated: true,
+						note: r.note
+					} : {}
 				});
 			}
 			if (path === "me" && req.method === "GET") return json(res, 200, {
@@ -384,7 +390,7 @@ function apiMiddleware(root, opts = {}) {
 						};
 					});
 					const fresh = appendEvents(dir, cm[1], stamped);
-					const { record } = await import("./ledger-BgA7nQoH.mjs").then((n) => n.n);
+					const { record } = await import("./ledger-Bu0BjqIe.mjs").then((n) => n.n);
 					for (const ev of fresh) if (ev.type === "create" || ev.type === "reply") record(root, cm[1], ev.id);
 					backgroundPush(root);
 					return json(res, 200, { accepted: fresh.length });
@@ -486,6 +492,10 @@ function routesMiddleware(server, clientDir) {
 * firewalled registries degrade to silence. MARVER_NO_UPDATE_CHECK=1 disables it.
 * Published bundles never check anything - viewers are not the owner.
 */
+var update_exports = /* @__PURE__ */ __exportAll({
+	checkUpdate: () => checkUpdate,
+	installedVersion: () => installedVersion
+});
 const TTL = 864e5;
 /** Installed version: walk up from this module to the package's own package.json
 *  (one level from dist/, two from src/server/ - the walk covers both). */
@@ -788,7 +798,7 @@ function marverPlugin(ctx) {
 								});
 								return;
 							}
-							const { shootFrame } = await import("./shot-BRgPaFCs.mjs");
+							const { shootFrame } = await import("./shot-D7I0MCLu.mjs");
 							write(await shootFrame({
 								root,
 								viewports: config.viewports,
@@ -868,4 +878,4 @@ async function tailwind3Css(root) {
 	return null;
 }
 //#endregion
-export { tailwind3Css as n, tailwind4Plugin as r, marverPlugin as t };
+export { update_exports as i, tailwind3Css as n, tailwind4Plugin as r, marverPlugin as t };

package/dist/rolldown-runtime-D7D4PA-g.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/{shot-BRgPaFCs.mjs → shot-D7I0MCLu.mjs}

@@ -34,6 +34,29 @@ function findChrome() {
 	return CHROMES.find((p) => existsSync(p)) ?? null;
 }
 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 vpObj = frame.viewport ? viewports[frame.viewport] : void 0;
+	const fallback = viewports.mobile ?? {
+		width: 390,
+		height: 844
+	};
+	if (cw) {
+		const width = clamp(vpObj?.width ?? cw, 320, 1600);
+		return {
+			width,
+			initialHeight: Math.round(width * .75),
+			fullHeight: true
+		};
+	}
+	const vp = vpObj ?? fallback;
+	return {
+		width: vp.width,
+		initialHeight: vp.height,
+		fullHeight: false
+	};
+}
 /** 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. */
@@ -52,24 +75,27 @@ async function shootFrame(opts) {
 		ok: false,
 		error: `unknown frame "${frameId}" - ids are in design/manifest.json`
 	};
-	const vp = viewports[frame.viewport ?? ""] ?? viewports.mobile ?? {
-		width: 390,
-		height: 844
-	};
+	const plan = planShot(frame, viewports);
 	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)
+		width: plan.width,
+		height: plan.initialHeight,
+		out: join(root, rel),
+		fullHeight: plan.fullHeight
 	});
 	return result.ok ? {
 		ok: true,
 		path: rel,
-		width: vp.width,
-		height: vp.height
+		width: result.width,
+		height: result.height,
+		scale: result.scale,
+		...result.truncated ? {
+			truncated: true,
+			note: result.note
+		} : {}
 	} : result;
 }
 /** One capture at a time: shots are seconds apart at most, and a Chrome per concurrent
@@ -80,7 +106,7 @@ function capture(req) {
 	chain = run;
 	return run;
 }
-async function captureNow({ url, width, height, out, timeoutMs = 3e4 }) {
+async function captureNow({ url, width, height, out, fullHeight = false, timeoutMs = 3e4 }) {
 	const bin = findChrome();
 	if (!bin) return {
 		ok: false,
@@ -172,6 +198,7 @@ async function captureNow({ url, width, height, out, timeoutMs = 3e4 }) {
 				rej(e);
 			}
 		});
+		const sendD = (method, params, ms = 1500) => Promise.race([send(method, params, sessionId), new Promise((_, rej) => setTimeout(() => rej(/* @__PURE__ */ new Error(`${method} timed out`)), ms))]);
 		watchdog = setTimeout(() => {
 			try {
 				chrome.kill("SIGKILL");
@@ -226,9 +253,109 @@ async function captureNow({ url, width, height, out, timeoutMs = 3e4 }) {
 			ok: false,
 			error: `the frame rendered an error - ${frameError}`
 		};
-		const shot = await send("Page.captureScreenshot", { format: "png" }, sessionId);
+		let capW = width, capH = height, scale = 2, 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)`,
+					returnByValue: true
+				}).catch(() => null))?.result?.value;
+				return typeof v === "number" && Number.isFinite(v) ? v : 0;
+			};
+			const lodIdle = async () => {
+				const v = (await sendD("Runtime.evaluate", {
+					expression: `(typeof window.__mvLodBusy==='function')?window.__mvLodBusy():0`,
+					returnByValue: true
+				}).catch(() => null))?.result?.value;
+				return typeof v === "number" ? v === 0 : true;
+			};
+			let measured = 0;
+			const growFit = async (dsf, capCss, deadline) => {
+				let h = Math.max(height, 2e3), prev = -1;
+				for (let i = 0; i < 8 && Date.now() < deadline; i++) {
+					await sendD("Emulation.setDeviceMetricsOverride", {
+						width,
+						height: Math.min(h, capCss),
+						deviceScaleFactor: dsf,
+						mobile: false
+					}).catch(() => {});
+					if (Date.now() >= deadline) break;
+					await sendD("Runtime.evaluate", {
+						expression: "document.fonts.ready.then(()=>true)",
+						awaitPromise: true,
+						returnByValue: true
+					}).catch(() => null);
+					if (Date.now() >= deadline) break;
+					for (let j = 0; j < 10 && Date.now() < deadline && !await lodIdle(); j++) await wait(100);
+					if (Date.now() >= deadline) break;
+					await wait(150);
+					if (Date.now() >= deadline) break;
+					const m = await measureH();
+					if (m > 0) measured = m;
+					const capped = Math.min(h, capCss);
+					if (capped >= capCss) break;
+					if (m > 0 && m <= capped && m === prev) break;
+					prev = m;
+					h = Math.max(m, capped);
+				}
+			};
+			const CAP2 = 8192, CAP1 = 16384;
+			const settleDeadline = Date.now() + 6e3;
+			await growFit(2, CAP2, settleDeadline);
+			if (measured > CAP2) {
+				scale = 1;
+				await growFit(1, CAP1, settleDeadline);
+			}
+			const cap = scale === 2 ? CAP2 : CAP1;
+			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);
+			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);
+			}
+		}
+		const shot = await sendD("Page.captureScreenshot", {
+			format: "png",
+			captureBeyondViewport: true,
+			clip: {
+				x: 0,
+				y: 0,
+				width: capW,
+				height: capH,
+				scale: 1
+			}
+		}, 15e3);
 		writeFileSync(out, Buffer.from(String(shot.data), "base64"));
-		return { ok: true };
+		return {
+			ok: true,
+			width: capW,
+			height: capH,
+			scale,
+			...truncated ? {
+				truncated: true,
+				note
+			} : {}
+		};
 	} catch (err) {
 		return {
 			ok: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "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/content/img-lod.ts

@@ -35,6 +35,12 @@ const schedule = (job: () => Promise<void>): void => {
   pump()
 }
 
+// Decode-idle signal for the headless shot: 0 means no decode is running or queued. The shot
+// (src/server/shot.ts) polls this to know each image's first decode has settled - which pins
+// its aspect-ratio and so stabilizes the frame's measured height - before it measures and
+// captures. Harmless and 0 when there are no LOD images (nothing ever decodes).
+if (typeof window !== 'undefined') (window as { __mvLodBusy?: () => number }).__mvLodBusy = () => active + q.length
+
 interface Item { canvas: HTMLCanvasElement; src: string; bucket: number; token: number }
 const items = new Set<Item>()
 let scale = 0.2      // overview default until the shell primes the settled scale on frame-ready

package/src/client/frame-host/bridge.js

@@ -73,7 +73,9 @@ window.addEventListener('message', (e) => {
 })
 
 if (isHtmlFrame) {
-  const ready = () => post({ type: 'sh:ready', id })
+  // stamp the URL revision (see main.tsx) so the shell can drop a ready from a superseded document
+  const gen = new URLSearchParams(location.search).get('r') ?? ''
+  const ready = () => post({ type: 'sh:ready', id, gen })
   document.readyState === 'loading' ? addEventListener('DOMContentLoaded', ready) : ready()
 }
 

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

@@ -77,7 +77,10 @@ async function boot() {
     for (const W of wrappers.reverse()) if (W != null) tree = createElement(W, null, tree)
 
     createRoot(document.getElementById('root')!).render(createElement(Boundary, null, tree))
-    post({ type: 'sh:ready', id, meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined })
+    // stamp the URL revision so the shell can drop a ready queued by a superseded document (one it
+    // auto-renavigated past) - a WindowProxy survives navigation, so a stale ready could otherwise
+    // mark a reloading frame ready. Mirrors the sh:measure generation guard.
+    post({ type: 'sh:ready', id, gen: params.get('r') ?? '', meta: frameMod.meta && typeof frameMod.meta === 'object' ? frameMod.meta : undefined })
   } catch (err) {
     fail((err as Error).message)
   }

package/src/client/shell/App.tsx

@@ -710,6 +710,11 @@ export function App() {
       const s = useStore.getState()
 
       if (data.type === 'sh:ready') {
+        // a WindowProxy survives navigation, so a ready queued by a SUPERSEDED document (one the
+        // ready-watchdog auto-renavigated past) can arrive here; drop it by generation like
+        // sh:measure does, so a stale ready never marks a reloading frame ready.
+        const gen = el.src.match(/[?&]r=(\d+)/)?.[1] ?? ''
+        if (String(data.gen ?? '') !== gen) return
         s.setStatus(nodeKey, 'ready')
       } else if (data.type === 'sh:error') {
         s.setStatus(nodeKey, 'error', String(data.message ?? 'unknown error'))

package/src/client/shell/canvas/FrameNode.tsx

@@ -7,6 +7,7 @@ import { threadHostKey } from '../keys.ts'
 import { registerFrame, unregisterFrame } from './frame-registry.ts'
 import { primeCameraFor } from './camera-broadcast.ts'
 import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
+import { canAutoReload, shouldArmReadyWatch } from './ready-watch.ts'
 
 export const HEADER = 28
 const SNAP = 12
@@ -47,7 +48,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   // B0.1: no reactive scale subscription - it re-rendered every FrameNode on every
   // pan/zoom tick. gestureScale below measures the world rect (the canonical source,
   // Law G-5); the stored scale is only a never-hit fallback, read lazily at drag time.
-  const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, setGesture, toast } = useStore.getState()
+  const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, reloadFrame, setGesture, toast } = useStore.getState()
   const iframeRef = useRef<HTMLIFrameElement>(null)
   const themeRef = useRef(node.theme)
   // src is frozen at mount: theme changes ride sh:set-theme (never navigation), so
@@ -204,12 +205,40 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
   }, [node.nav])
 
-  // ready timeout: 10s without sh:ready -> error card with reload
+  // Reload the frame, assigning the fresh URL SYNCHRONOUSLY so the live iframe's src is current the
+  // instant a stale sh:ready (queued by the document we just superseded) could be processed - the
+  // App generation guard then drops it against the new src. reloadFrame bumps nav+manifestRev; we
+  // pre-apply the src here and advance navRef so the passive nav effect does not navigate a 2nd time.
+  const reload = (automatic: boolean) => {
+    const before = useStore.getState().nodes.find((x) => x.key === node.key)
+    if (!before || (automatic && !canAutoReload(before))) return
+    reloadFrame(node.key, automatic)
+    const after = useStore.getState().nodes.find((x) => x.key === node.key)
+    const f = useStore.getState().frameFor(node)
+    if (after && f && iframeRef.current) {
+      iframeRef.current.src = frameUrl(f, node.theme)
+      navRef.current = after.nav ?? 0
+    }
+  }
+  // latest-callback ref so the watchdog effect can call the current reload() without taking it as a
+  // dep (an unstable function there would reset the timer every render and starve the retry)
+  const reloadRef = useRef(reload)
+  reloadRef.current = reload
+
+  // ready watchdog: a slow dev server (Vite re-optimizing deps, or the box saturated by parallel
+  // Live Jam agents) can leave boot()'s module fetches unresolved past the deadline - that is a slow
+  // frame, NOT a failed one (a real failure posts sh:error immediately). So the first silent deadline
+  // auto-renavigates ONCE on a fresh rev; a second silence stays 'loading' (never a red error card).
+  // node.nav is a dep so a fresh navigation restarts the full budget; readyRetried flips true on the
+  // retry and bounds it to exactly one.
   useEffect(() => {
-    if (node.status !== 'loading') return
-    const t = setTimeout(() => setStatus(node.key, 'error', 'frame never reported ready (10s)'), 10_000)
+    if (!shouldArmReadyWatch(node, !!frame)) return
+    const t = setTimeout(() => reloadRef.current(true), 10_000)
     return () => clearTimeout(t)
-  }, [node.status, node.key, setStatus])
+    // depend on the frame's stable SIGNATURE, not the manifest object - that object is replaced on
+    // every manifest reconcile, so depending on it would reset the budget on unrelated frames during
+    // heavy Live Jam churn and starve the retry. kind/file still re-arm on a real file swap.
+  }, [node.status, node.readyRetried, node.nav, node.key, node.missing, frame?.kind, frame?.file])
 
   const drag = (e: React.PointerEvent, mode: 'move' | 'e' | 's' | 'se') => {
     e.stopPropagation()
@@ -345,7 +374,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
             <span className="msg">{node.error}</span>
             <span className="dim">{frame.file}</span>
             <span className="row">
-              <button className="sh-no-pan" onClick={() => { setStatus(node.key, 'loading'); iframeRef.current && (iframeRef.current.src = frameUrl(frame, node.theme)) }}>
+              <button className="sh-no-pan" onClick={() => reload(false)}>
                 <ReloadIcon size={12} /> reload
               </button>
               <button className="sh-no-pan" onClick={() => { navigator.clipboard.writeText(`${frame.file}: ${node.error}`); toast('error copied for agent') }}>
@@ -354,6 +383,16 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
             </span>
           </div>
         ) : null}
+        {/* a frame still silent after its one auto-retry: a slow dev server, never a failure. A quiet
+            non-covering pill (not the red card) keeps it honest and offers a manual reload. */}
+        {node.status === 'loading' && node.readyRetried ? (
+          <div className="sh-loading sh-no-pan">
+            <span>still loading</span>
+            <button className="sh-no-pan" onClick={() => reload(false)}>
+              <ReloadIcon size={11} /> reload
+            </button>
+          </div>
+        ) : null}
         <iframe
           ref={bindIframe}
           className="sh-live"

package/src/client/shell/canvas/ready-watch.ts

@@ -0,0 +1,28 @@
+// Readiness-watchdog policy, kept pure so it can be unit-tested apart from the browser-coupled
+// store (which imports Vite virtual modules and can't load under vitest).
+//
+// The frame host posts sh:ready SYNCHRONOUSLY after it renders, so a frame that misses the
+// deadline has not failed - its dev-server module fetches just haven't settled (Vite re-optimizing
+// dependencies, or the box saturated by parallel Live Jam agents). A genuine failure takes the
+// separate immediate sh:error path. So a silent deadline earns exactly ONE automatic re-navigation
+// on a fresh revision; a second silence stays 'loading' forever (never a red failure card).
+
+export interface ReadyNode {
+  status: 'loading' | 'ready' | 'error'
+  readyRetried?: boolean
+  missing?: boolean
+}
+
+/** Arm the 10s watchdog only for a present, still-loading, not-yet-retried frame. A missing or
+ *  absent frame must NOT spend the one-shot allowance - it has no live iframe booting, and would
+ *  otherwise burn its retry before its file even arrives. */
+export function shouldArmReadyWatch(node: ReadyNode, hasFrame: boolean): boolean {
+  return node.status === 'loading' && !node.readyRetried && hasFrame && !node.missing
+}
+
+/** Whether an automatic (watchdog-driven) reload still applies: one shot, and only while the frame
+ *  is still silently loading. A frame that already went ready/error, or already spent its retry,
+ *  is left alone. */
+export function canAutoReload(node: ReadyNode): boolean {
+  return node.status === 'loading' && !node.readyRetried
+}

package/src/client/shell/store.ts

@@ -38,6 +38,10 @@ export interface Node {
    *  frame arrives - an authored size on a temporarily-missing frame is never touched. */
   sizeFallback?: boolean
   status: 'loading' | 'ready' | 'error'; error?: string; missing?: boolean
+  /** the frame's one automatic ready-retry has been spent (a slow dev server must not be reported
+   *  as a failed frame; see canvas/ready-watch.ts). Transient - cleared on any real ready/error and
+   *  on every fresh navigation. */
+  readyRetried?: boolean
 }
 /** A Live Jam notification: a persistent bottom-right glass pill for a Marver
  *  reply. Frame-first: the FRAME is the news (icon + title, blue), Marver + preview below. */
@@ -48,6 +52,7 @@ export const CONFIG: { viewports: Record<string, { width: number; height: number
 
 export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
+import { canAutoReload } from './canvas/ready-watch.ts'
 
 /** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
  *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
@@ -94,7 +99,7 @@ export const bumpManifestRev = () => { manifestRev++ }
 
 export function frameUrl(frame: FrameEntry, theme: string): string {
   return frame.kind === 'html'
-    ? `/${frame.file}?theme=${theme}`
+    ? `/${frame.file}?theme=${theme}&r=${manifestRev}`   // r= carries the generation for the sh:ready guard (static serving ignores it)
     : `${ROUTE}/frame/?id=${encodeURIComponent(frame.id)}&theme=${theme}&r=${manifestRev}`
 }
 
@@ -175,6 +180,7 @@ interface State {
   resizeNode(key: string, w: number, h: number): void
   measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number): void
   setStatus(key: string, status: Node['status'], error?: string): void
+  reloadFrame(key: string, automatic?: boolean): void
   removeNode(key: string): void
   select(key: string | null, additive?: boolean): void
   selectMany(keys: string[]): void
@@ -620,7 +626,7 @@ export const useStore = create<State>((set, get) => {
             n.w = vp?.width ?? d.w
             n.h = vp?.height ?? d.h
           }
-          if (arrived) delete n.sizeFallback
+          if (arrived) { delete n.sizeFallback; n.readyRetried = false }   // a fresh mount earns a fresh allowance
           n.missing = missing
           changed = true
         }
@@ -637,7 +643,7 @@ export const useStore = create<State>((set, get) => {
         if (!f?.contentWidth && n.sizeMode) { delete n.sizeMode; retinted = true }
         // an errored frame whose file IS in the fresh manifest gets one automatic retry
         // on a rev-stamped URL - the "unknown frame id" dead end must self-heal (#20)
-        if (!missing && n.status === 'error') { n.status = 'loading'; n.nav = (n.nav ?? 0) + 1; retinted = true }
+        if (!missing && n.status === 'error') { n.status = 'loading'; n.nav = (n.nav ?? 0) + 1; n.readyRetried = false; retinted = true }
       }
       // auto boards prune deleted frames outright - "auto-managed" must manage both
       // directions (friction log #15). Curated boards keep the explicit card.
@@ -793,7 +799,22 @@ export const useStore = create<State>((set, get) => {
       else scheduleSave()
     },
     setStatus(key, status, error) {
-      set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, status, error } : n)) }))
+      // any real ready/error resets the one-shot retry allowance, so a later manual reload or a
+      // fresh manifest earns its own auto-retry again
+      set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, status, error, readyRetried: false } : n)) }))
+    },
+    // Reload a frame on a fresh rev-stamped URL (dodges a poisoned-cache document, #20). The
+    // watchdog calls this with automatic=true after a silent deadline: it fires at most once per
+    // load (canAutoReload gates it) and marks readyRetried so a second silence never retries and
+    // never becomes an error. A manual reload passes automatic=false, granting a fresh allowance.
+    reloadFrame(key, automatic = false) {
+      const n = get().nodes.find((x) => x.key === key)
+      if (!n) return
+      if (automatic && !canAutoReload(n)) return
+      bumpManifestRev()
+      set((s) => ({ nodes: s.nodes.map((x) => (x.key === key
+        ? { ...x, status: 'loading' as const, error: undefined, nav: (x.nav ?? 0) + 1, readyRetried: automatic }
+        : x)) }))
     },
     // plain select replaces; additive toggles membership. Interact survives only while its
     // frame stays selected.
@@ -884,7 +905,7 @@ export const useStore = create<State>((set, get) => {
       const nodes = s.nodes.map((n) => {
         if (!ids.has(n.frame)) return n
         if (frameIsLeased(n.frame, s)) { pending[n.frame] = revision; return n }
-        return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 }
+        return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1, readyRetried: false }
       })
       set({ nodes, pendingFrameRevisions: pending, ...(s.play ? { playUpdateRevision: revision } : {}) })
     },
@@ -897,7 +918,7 @@ export const useStore = create<State>((set, get) => {
       const pending = { ...s.pendingFrameRevisions }
       for (const id of ids) delete pending[id]
       const nodes = s.nodes.map((n) => apply.has(n.frame)
-        ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 } : n)
+        ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1, readyRetried: false } : n)
       set({ nodes, pendingFrameRevisions: pending })
     },
     setExternalLease(nodeKey, reason, on) {

package/src/client/shell/styles.css

@@ -426,6 +426,14 @@ body.sh-commenting .sh-lean { opacity: 0 }
   border: 1px solid currentColor; background: transparent; color: inherit; border-radius: 999px;
   padding: 4px 10px; cursor: pointer }
 
+/* still-loading pill: a slow (not failed) frame after its one auto-retry. Non-covering, sits above
+   the drag overlay (z2) so its reload button is clickable, and stays out of the frame's content. */
+.sh-loading { position: absolute; left: 8px; bottom: 8px; z-index: 6; display: inline-flex; align-items: center;
+  gap: 8px; padding: 4px 4px 4px 10px; border-radius: 999px; font: 500 11px -apple-system, system-ui, sans-serif;
+  color: var(--card-warn-ink); background: var(--card-warn-bg); box-shadow: 0 1px 4px rgba(0, 0, 0, .16) }
+.sh-loading button { display: inline-flex; align-items: center; gap: 4px; font: 600 11px -apple-system, system-ui, sans-serif;
+  border: 1px solid currentColor; background: transparent; color: inherit; border-radius: 999px; padding: 3px 9px; cursor: pointer }
+
 /* shared icon button (glass surfaces) */
 .sh-ibtn { display: grid; place-items: center; width: 28px; height: 28px; border-radius: 999px;
   border: 0; background: none; color: var(--glass-ink-3); cursor: pointer }

package/templates/instructions/jam.md

@@ -92,6 +92,10 @@ The `result.json` is the universal signal - it works even when you cannot see im
 throw shows the frame's own exception, "the frame rendered an error - ..."; an unreachable
 dev server or missing Chrome says so). So a crashed or blank frame is caught by the JSON
 alone. `"ok":true` means it painted - and THEN the PNG tells you whether it painted *well*.
+The result also reports the exact `width`/`height` captured: a content frame (a `Doc`) is
+shot at its natural width and its FULL height, so a wide layout or a long spec renders in
+full, not cropped. A frame tall enough to hit the capture cap comes back with
+`"truncated":true` and a `note` - split it or shorten it and re-shoot.
 
 (If you DO have a shell - `npx marver shot <scene/frame> [--theme dark]` is the same thing
 in one line, printing the PNG path.)