@marver-design/marver 0.2.0 → 0.2.1

package/README.md

@@ -20,9 +20,9 @@ Then, to your agent:
 - `data-goto="scene/frame"` on any element links frames into a walkable prototype.
 - Uninstall: delete `design/`, remove the dependency. (If `init` patched your tsconfig `exclude`, revert that one line.)
 
-The implementation contract is [SPEC.md](./SPEC.md). Deviations live in [DECISIONS.md](./DECISIONS.md).
+**Next.js**: supported with one caveat - frames render in Vite, outside Next. `next/font` CSS variables are undefined inside frames (give font tokens a fallback chain), `next/image`/`next/link` should be plain `img`/`data-goto` in frames, and Server Components cannot run there. `init` writes the specifics into `design/AGENTS.md` when it detects Next.
 
-; private; TNEP4.
+Implementation contracts (SPEC.md, DECISIONS.md) live in the [GitHub repo](https://github.com/TNEP4/marver).
 
 ## Shortcuts
 

package/dist/{build-D0GnIR4G.mjs → build-BYZDMiIS.mjs}

@@ -1,8 +1,8 @@
 import { r as ROUTE, t as NAME } from "./cli.mjs";
-import { n as loadConfig, r as detectHost } from "./config-DMBEpdEN.mjs";
-import { i as scanFrames, n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DB5t2WUl.mjs";
-import { basename, dirname, join, sep } from "node:path";
+import { a as loadConfig, n as scanFrames, o as detectHost } from "./manifest-CHmKAAtG.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-lVQoABEx.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { build } from "vite";
 import react from "@vitejs/plugin-react";

package/dist/cli.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { cac } from "cac";
-import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 //#region src/client/const.ts
 /** Client-safe constants. The single source - src/cli/name.ts re-exports for node-side code.
 *  Lives under src/client because that is the only source directory shipped in the package. */
@@ -14,16 +16,30 @@ if (major < 22 || major === 22 && minor < 18) {
 	console.error(`${NAME} needs Node >= 22.18 (native TypeScript config loading). You have ${process.versions.node}.`);
 	process.exit(1);
 }
+const emitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+	const opt = rest[0];
+	if (((typeof opt === "object" && opt ? opt.code : rest[1]) ?? (warning && typeof warning === "object" ? warning.code : void 0)) === "MODULE_TYPELESS_PACKAGE_JSON") return;
+	emitWarning(warning, ...rest);
+});
+/** The real installed version - dist/cli.mjs lives one level under the package root. */
+function version() {
+	try {
+		return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+	} catch {
+		return "0.0.0";
+	}
+}
 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").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { init } = await import("./init-DcOy1krf.mjs");
+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-CHUZTYG7.mjs");
 	init(resolve(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 cli.command("dev", "Start the canvas").option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-BK4x3PBr.mjs");
+	const { dev } = await import("./dev-Dt9D4O7Z.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -33,7 +49,7 @@ cli.command("dev", "Start the canvas").option("--root <dir>", "Host repo root",
 	await dev(resolve(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist").option("--boards <names>", "Publish only these boards (comma-separated); the frame filter is applied at build time").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-D0GnIR4G.mjs");
+	const { buildSite } = await import("./build-BYZDMiIS.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards);
@@ -43,7 +59,7 @@ cli.command("build", "Static export → design/.dist").option("--boards <names>"
 	}
 });
 cli.command("serve", "Serve design/.dist (set MARVER_PASSWORD to gate it)").option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default $PORT or 4199)").action(async (opts) => {
-	const { serve } = await import("./serve-BPNmWeJx.mjs");
+	const { serve } = await import("./serve-BvbAbWeK.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -52,7 +68,7 @@ cli.command("serve", "Serve design/.dist (set MARVER_PASSWORD to gate it)").opti
 	serve(resolve(opts.root), port);
 });
 cli.help();
-cli.version("0.1.0");
+cli.version(version());
 cli.parse();
 //#endregion
 export { PKG as n, ROUTE as r, NAME as t };

package/dist/{dev-BK4x3PBr.mjs → dev-Dt9D4O7Z.mjs}

@@ -1,9 +1,9 @@
 import { n as PKG, t as NAME } from "./cli.mjs";
-import { n as loadConfig, r as detectHost } from "./config-DMBEpdEN.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DB5t2WUl.mjs";
+import { a as loadConfig, o as detectHost } from "./manifest-CHmKAAtG.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-lVQoABEx.mjs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createServer, searchForWorkspaceRoot } from "vite";
+import { createLogger, createServer, searchForWorkspaceRoot } from "vite";
 import react from "@vitejs/plugin-react";
 //#region src/server/dev.ts
 /** packageDir = the installed marver package root (dist/cli.js lives one level down). */
@@ -19,7 +19,7 @@ async function dev(root, portFlag) {
 	if (host.tailwind === 4) {
 		const tw = await tailwind4Plugin(root);
 		if (tw) plugins.push(...tw);
-		else console.warn("[marver] tailwindcss v4 detected but @tailwindcss/vite not found in the host - theme classes may be missing.");
+		else console.warn(`[marver] tailwindcss v4 detected but @tailwindcss/vite could not be loaded - utility classes WILL be missing from frames. Fix: npm i -D @tailwindcss/vite (used only by the canvas, never by your app's build).`);
 	}
 	let css;
 	if (host.tailwind === 3) css = await tailwind3Css(root) ?? void 0;
@@ -29,10 +29,21 @@ async function dev(root, portFlag) {
 		config,
 		detectedThemeCss: host.themeCss
 	}));
+	const logger = createLogger("info");
+	const noise = (msg) => /Sourcemap for .*node_modules.*points to/.test(msg);
+	const warnBase = logger.warn.bind(logger);
+	const warnOnceBase = logger.warnOnce.bind(logger);
+	logger.warn = (msg, opts) => {
+		if (!noise(msg)) warnBase(msg, opts);
+	};
+	logger.warnOnce = (msg, opts) => {
+		if (!noise(msg)) warnOnceBase(msg, opts);
+	};
 	const server = await createServer({
 		configFile: false,
 		root,
 		css,
+		customLogger: logger,
 		plugins,
 		server: {
 			port: portFlag ?? config.port,
@@ -46,7 +57,15 @@ async function dev(root, portFlag) {
 				"**/design/manifest.json",
 				"**/design/boards/**",
 				"**/design/.local/**",
-				"**/design/.dist/**"
+				"**/design/.dist/**",
+				"**/.next/**",
+				"**/.turbo/**",
+				"**/.vercel/**",
+				"**/.output/**",
+				"**/dist/**",
+				"**/build/**",
+				"**/out/**",
+				"**/coverage/**"
 			] }
 		},
 		resolve: {

package/dist/{init-DcOy1krf.mjs → init-CHUZTYG7.mjs}

@@ -1,7 +1,7 @@
 import { t as NAME } from "./cli.mjs";
-import { r as detectHost, t as DEFAULTS } from "./config-DMBEpdEN.mjs";
-import { dirname, join, relative } from "node:path";
+import { i as DEFAULTS, n as scanFrames, o as detectHost, r as writeManifest } from "./manifest-CHmKAAtG.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/cli/init.ts
 const pkgDir = () => join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -22,10 +22,19 @@ function init(root, opts) {
 	if (host.themeCss) {
 		const relCss = relative(design, join(root, host.themeCss)).split("\\").join("/");
 		write("theme.css", themeWrapper(relCss, host.tailwind === 4));
-	} else console.warn(`[${NAME}] no theme CSS detected - set \`theme\` in design/config.ts when you have one.`);
+	} else console.warn(`[${NAME}] no theme CSS detected - create design/theme.css importing your app's stylesheet when you have one (or set \`theme\` in design/config.ts).`);
 	write("providers.tsx", providersTemplate(host.router, host.toaster, host.routerPkg));
-	write("AGENTS.md", readFileSync(join(templates, `AGENTS-${opts.mode}.md`), "utf8").replaceAll("{{UI_ALIAS}}", host.shadcn?.uiAlias ?? "@/components/ui"));
-	write("tsconfig.json", readFileSync(join(templates, "design-tsconfig.json"), "utf8"));
+	const agents = AGENTS_MARKER + "\n" + readFileSync(join(templates, `AGENTS-${opts.mode}.md`), "utf8").replaceAll("{{UI_GUIDANCE}}", uiGuidance(host)).replace(/\{\{NEXT_NOTES\}\}\n?/, host.router === "next" ? NEXT_NOTES : "");
+	const agentsPath = join(design, "AGENTS.md");
+	if (!existsSync(agentsPath)) write("AGENTS.md", agents);
+	else {
+		const current = readFileSync(agentsPath, "utf8");
+		if (current.startsWith(AGENTS_MARKER) && current !== agents) {
+			writeFileSync(agentsPath, agents);
+			created.push("design/AGENTS.md (regenerated - detected stack changed)");
+		}
+	}
+	write("tsconfig.json", existsSync(join(root, "tsconfig.json")) ? readFileSync(join(templates, "design-tsconfig.json"), "utf8") : STANDALONE_TSCONFIG);
 	write(".gitignore", ".local/\n.dist/\n");
 	write("scenes/_layout.tsx", readFileSync(join(templates, "root-layout.tsx"), "utf8"));
 	if (!existsSync(join(design, "boards"))) {
@@ -38,14 +47,61 @@ function init(root, opts) {
 		created.push("design/scenes/demo/ (3 frames)");
 	}
 	if (host.tsconfigSweepsDesign) patchTsconfigExclude(root);
+	writeManifest(root, scanFrames(root));
 	console.log(`\n${NAME} initialized (${opts.mode} mode). Created:`);
 	for (const f of created) console.log(`  + ${f}`);
-	if (host.router === "next") console.log(`\n  note: Next.js support is partial until M3 - HTML frames and next-free components work today.`);
+	if (host.router === "next") console.log(`\n  note: Next.js support is partial - frames render outside Next, so next/font, next/image and Server Components do not exist inside them (details in design/AGENTS.md).`);
+	if (noApp(host)) console.warn(`
+  ┌─ NO APP DETECTED ─────────────────────────────────────────────────────┐
+  │ This repo has no framework, no theme CSS, and no component library.   │
+  │ ${NAME} builds frames from YOUR components - with none, frames become │
+  │ hand-rolled CSS that cannot be promoted into an app later.            │
+  │                                                                       │
+  │ Set up the app first, then re-run init (it is idempotent and will     │
+  │ fill in what it detects). For a web app or site:                      │
+  │   npx create-next-app@latest . --ts --tailwind --app --src-dir        │
+  │   npx shadcn@latest init                                              │
+  │                                                                       │
+  │ design/AGENTS.md was generated with a STOP instruction so your agent  │
+  │ does not design against a component library that does not exist.     │
+  └───────────────────────────────────────────────────────────────────────┘`);
 	console.log(`\n  commit design/ - only .local/ is ignored`);
 	console.log(`  uninstall = delete design/, remove the ${NAME} dependency${host.tsconfigSweepsDesign ? ", revert the \"design\" line in tsconfig exclude" : ""}`);
 	console.log(`\n  next: npx ${NAME} dev   (canvas on http://localhost:${DEFAULTS.port} by default)\n`);
-	console.log(`  then, to your agent: "Read design/AGENTS.md. Build an onboarding scene - welcome, form, done - mobile-first, using our components."\n`);
+	if (!noApp(host)) console.log(`  then, to your agent: "Read design/AGENTS.md. Build an onboarding scene - welcome, form, done - mobile-first, using our components."\n`);
+}
+const AGENTS_MARKER = "<!-- generated by marver init from the detected stack; re-running init regenerates this file when detection changes. Made edits you want to keep? Delete this line and init will never touch the file again. -->";
+/** No framework, no theme, no component alias = nothing to build frames FROM. */
+const noApp = (host) => !host.router && !host.tailwind && !host.shadcn && !host.themeCss;
+/** The UI line of AGENTS.md, matched to what detection actually found (friction log #1). */
+function uiGuidance(host) {
+	if (host.shadcn) return `Use the app's UI: import from ${host.shadcn.uiAlias}; style with the app's Tailwind classes.`;
+	if (host.tailwind) return `Style with the app's Tailwind classes and design tokens; there is no detected component library - extract shared pieces into design/components/.`;
+	return `STOP - this repo has no component library, no Tailwind, and no theme. Frames built from hand-rolled CSS cannot be promoted into an app later. Ask the human to set up the app first (framework + styling), then re-run \`npx ${NAME} init\` so this contract regenerates against the real stack.`;
 }
+/** Next.js frames render OUTSIDE Next - say concretely what that means (friction log #10/#11). */
+const NEXT_NOTES = `- Next.js caveats (frames render in Vite, outside Next):
+  next/font does not exist here - CSS variables it injects (e.g. --font-geist-sans) are
+  undefined in frames, so give every font token a real fallback chain in the app's CSS:
+  --font-sans: var(--font-geist-sans, ui-sans-serif, system-ui, sans-serif).
+  next/image and next/link render as plain img/a via shims at best - prefer <img> and
+  data-goto in frames. Server Components and server actions cannot run: frames are
+  client components importing client components.
+`;
+const STANDALONE_TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["."]
+}
+`;
 function patchTsconfigExclude(root) {
 	const file = join(root, "tsconfig.json");
 	if (!existsSync(file)) return;

package/dist/manifest-CHmKAAtG.mjs

@@ -0,0 +1,298 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
+//#region src/server/detect.ts
+function readJson(file) {
+	try {
+		return JSON.parse(stripJsonComments(readFileSync(file, "utf8")));
+	} catch {
+		return null;
+	}
+}
+function stripJsonComments(s) {
+	let out = "", inStr = false, inLine = false, inBlock = false;
+	for (let i = 0; i < s.length; i++) {
+		const c = s[i], n = s[i + 1];
+		if (inLine) {
+			if (c === "\n") {
+				inLine = false;
+				out += c;
+			}
+			continue;
+		}
+		if (inBlock) {
+			if (c === "*" && n === "/") {
+				inBlock = false;
+				i++;
+			}
+			continue;
+		}
+		if (inStr) {
+			out += c;
+			if (c === "\\") {
+				out += n ?? "";
+				i++;
+			} else if (c === "\"") inStr = false;
+			continue;
+		}
+		if (c === "\"") {
+			inStr = true;
+			out += c;
+			continue;
+		}
+		if (c === "/" && n === "/") {
+			inLine = true;
+			i++;
+			continue;
+		}
+		if (c === "/" && n === "*") {
+			inBlock = true;
+			i++;
+			continue;
+		}
+		out += c;
+	}
+	let res = "", inS = false;
+	for (let i = 0; i < out.length; i++) {
+		const c = out[i];
+		if (inS) {
+			res += c;
+			if (c === "\\") {
+				res += out[i + 1] ?? "";
+				i++;
+			} else if (c === "\"") inS = false;
+			continue;
+		}
+		if (c === "\"") {
+			inS = true;
+			res += c;
+			continue;
+		}
+		if (c === ",") {
+			let j = i + 1;
+			while (j < out.length && /\s/.test(out[j])) j++;
+			if (out[j] === "}" || out[j] === "]") continue;
+		}
+		res += c;
+	}
+	return res;
+}
+function detectHost(root) {
+	const pkg = readJson(join(root, "package.json")) ?? {};
+	const deps = {
+		...pkg.dependencies,
+		...pkg.devDependencies
+	};
+	const twRange = deps["tailwindcss"];
+	const tailwind = !twRange ? null : /(^|[^\d])4\./.test(twRange) || twRange.startsWith("^4") || twRange.startsWith("~4") ? 4 : 3;
+	const router = deps["next"] ? "next" : deps["react-router"] || deps["react-router-dom"] ? "react-router" : null;
+	const routerPkg = deps["react-router-dom"] ? "react-router-dom" : "react-router";
+	const toaster = deps["sonner"] ? "sonner" : deps["react-hot-toast"] ? "react-hot-toast" : null;
+	let shadcn = null;
+	const comp = readJson(join(root, "components.json"));
+	if (comp?.tailwind?.css) shadcn = {
+		themeCss: comp.tailwind.css,
+		uiAlias: comp.aliases?.ui ?? "@/components/ui"
+	};
+	const themeCss = shadcn?.themeCss && existsSync(join(root, shadcn.themeCss)) ? shadcn.themeCss : firstExisting(root, [
+		"src/index.css",
+		"src/styles/theme.css",
+		"src/styles/globals.css",
+		"src/app/globals.css",
+		"app/globals.css",
+		"src/globals.css",
+		"src/style.css",
+		"styles/globals.css"
+	]);
+	const ts = readJson(join(root, "tsconfig.json"));
+	const include = ts?.include;
+	const exclude = ts?.exclude ?? [];
+	const sweeps = ts != null && !exclude.some((e) => e === "design" || e.startsWith("design/")) && (!include || include.some((i) => i === "." || i.startsWith("**") || i.startsWith("design")));
+	return {
+		tailwind,
+		router,
+		routerPkg,
+		toaster,
+		shadcn,
+		themeCss,
+		tsconfigSweepsDesign: !!sweeps
+	};
+}
+function firstExisting(root, candidates) {
+	for (const c of candidates) if (existsSync(join(root, c))) return c;
+	return null;
+}
+//#endregion
+//#region src/server/config.ts
+const DEFAULTS = {
+	mode: "studio",
+	theme: null,
+	viewports: {
+		mobile: {
+			width: 390,
+			height: 844
+		},
+		tablet: {
+			width: 768,
+			height: 1024
+		},
+		laptop: {
+			width: 1280,
+			height: 800
+		},
+		monitor: {
+			width: 1920,
+			height: 1080
+		}
+	},
+	themes: ["light", "dark"],
+	port: 5199,
+	zoomSpeed: 1,
+	share: { branding: true }
+};
+/** Load design/config.ts via native TS import (Node >= 22.18). Missing or broken fields fall back to defaults. */
+async function loadConfig(root) {
+	const file = join(root, "design", "config.ts");
+	if (!existsSync(file)) return { ...DEFAULTS };
+	try {
+		const user = (await import(`${pathToFileURL(file).href}?t=${Date.now()}`)).default ?? {};
+		return {
+			...DEFAULTS,
+			...user,
+			viewports: validViewports(user.viewports) ?? DEFAULTS.viewports,
+			themes: Array.isArray(user.themes) && user.themes.length ? user.themes.map(String) : DEFAULTS.themes,
+			port: validPort(user.port) ?? DEFAULTS.port,
+			zoomSpeed: validZoom(user.zoomSpeed) ?? DEFAULTS.zoomSpeed,
+			share: {
+				branding: user.share?.branding !== false,
+				name: typeof user.share?.name === "string" ? user.share.name : void 0,
+				logo: typeof user.share?.logo === "string" ? user.share.logo : void 0
+			}
+		};
+	} catch (err) {
+		console.error(`[marver] design/config.ts failed to load, using defaults:\n  ${err.message}`);
+		return { ...DEFAULTS };
+	}
+}
+const validDim = (n) => typeof n === "number" && Number.isFinite(n) && n >= 1 && n <= 2e4;
+function validPort(n) {
+	return typeof n === "number" && Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+}
+function validZoom(n) {
+	return typeof n === "number" && Number.isFinite(n) && n >= .1 && n <= 10 ? n : null;
+}
+function validViewports(v) {
+	if (!v || typeof v !== "object") return null;
+	const out = {};
+	for (const [k, val] of Object.entries(v)) {
+		const vp = val;
+		if (validDim(vp?.width) && validDim(vp?.height)) out[k] = {
+			width: Math.round(vp.width),
+			height: Math.round(vp.height)
+		};
+	}
+	return Object.keys(out).length ? out : null;
+}
+//#endregion
+//#region src/server/manifest.ts
+const FRAME_EXT = /\.(tsx|jsx|html)$/;
+const RESERVED_SCENES = /* @__PURE__ */ new Set(["components", "screens"]);
+/** Extract `export const meta = {...}` with literal string values only. Anything else is silently omitted (spec §6). */
+function extractMeta(src) {
+	const m = /export\s+const\s+meta\s*=\s*\{([\s\S]*?)\}/.exec(src);
+	if (!m) return {};
+	const body = m[1];
+	const pick = (key) => {
+		const r = new RegExp(`${key}\\s*:\\s*(['"\`])([^'"\`]*)\\1`).exec(body);
+		return r ? r[2] : void 0;
+	};
+	const out = {};
+	const title = pick("title");
+	if (title) out.title = title;
+	const viewport = pick("viewport");
+	if (viewport) out.viewport = viewport;
+	const theme = pick("theme");
+	if (theme) out.theme = theme;
+	return out;
+}
+/** id = path relative to design/, extension dropped, `scenes/` prefix dropped. Always `/`-separated. */
+function toFrameId(designRelPath) {
+	const noExt = designRelPath.split(sep).join("/").replace(FRAME_EXT, "");
+	return noExt.startsWith("scenes/") ? noExt.slice(7) : noExt;
+}
+function walk(dir, out = []) {
+	if (!existsSync(dir)) return out;
+	for (const e of readdirSync(dir, { withFileTypes: true })) {
+		if (e.name.startsWith(".")) continue;
+		const p = join(dir, e.name);
+		if (e.isDirectory()) walk(p, out);
+		else out.push(p);
+	}
+	return out;
+}
+function scanFrames(root) {
+	const design = join(root, "design");
+	const frames = [];
+	for (const base of ["scenes", "components"]) for (const abs of walk(join(design, base))) {
+		const name = abs.split(sep).pop();
+		if (name.startsWith("_") || !FRAME_EXT.test(name)) continue;
+		const rel = relative(design, abs).split(sep).join("/");
+		const id = toFrameId(rel);
+		const scene = id.includes("/") ? id.split("/")[0] : "";
+		if (base === "scenes" && RESERVED_SCENES.has(scene)) {
+			console.error(`[marver] scene "${scene}" is a reserved name - "${rel}" skipped. Rename the scene.`);
+			continue;
+		}
+		const kind = name.endsWith(".html") ? "html" : "tsx";
+		const entry = {
+			id,
+			file: `design/${rel}`,
+			kind,
+			scene
+		};
+		if (kind === "tsx") {
+			const meta = extractMeta(readFileSync(abs, "utf8"));
+			if (meta.title) entry.title = meta.title;
+			if (meta.viewport) entry.viewport = meta.viewport;
+			if (meta.theme) entry.theme = meta.theme;
+		}
+		frames.push(entry);
+	}
+	const extRank = (file) => file.endsWith(".tsx") ? 0 : file.endsWith(".jsx") ? 1 : 2;
+	frames.sort((a, b) => a.id.localeCompare(b.id) || extRank(a.file) - extRank(b.file) || a.file.localeCompare(b.file));
+	const seen = /* @__PURE__ */ new Map();
+	const deduped = frames.filter((f) => {
+		const prev = seen.get(f.id);
+		if (prev) {
+			console.error(`[marver] duplicate frame id "${f.id}" (${prev} vs ${f.file}) - keeping ${prev}.`);
+			return false;
+		}
+		seen.set(f.id, f.file);
+		return true;
+	});
+	frames.length = 0;
+	frames.push(...deduped);
+	const sceneCounts = /* @__PURE__ */ new Map();
+	for (const f of frames) sceneCounts.set(f.scene, (sceneCounts.get(f.scene) ?? 0) + 1);
+	return {
+		frames,
+		scenes: [...sceneCounts.entries()].map(([name, n]) => ({
+			name,
+			frames: n
+		})).sort((a, b) => a.name.localeCompare(b.name))
+	};
+}
+/** Write design/manifest.json only when content changed. Returns the manifest either way. */
+function writeManifest(root, manifest) {
+	const file = join(root, "design", "manifest.json");
+	const next = JSON.stringify(manifest, null, 2) + "\n";
+	const prev = existsSync(file) ? readFileSync(file, "utf8") : "";
+	if (hash(prev) === hash(next)) return false;
+	mkdirSync(join(root, "design"), { recursive: true });
+	writeFileSync(file, next);
+	return true;
+}
+const hash = (s) => createHash("sha256").update(s).digest("hex");
+//#endregion
+export { loadConfig as a, DEFAULTS as i, scanFrames as n, detectHost as o, writeManifest as r, hash as t };

package/dist/{plugin-DB5t2WUl.mjs → plugin-lVQoABEx.mjs}

@@ -1,107 +1,8 @@
 import { r as ROUTE } from "./cli.mjs";
-import { join, relative, resolve, sep } from "node:path";
+import { n as scanFrames, r as writeManifest, t as hash } from "./manifest-CHmKAAtG.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
-import { createHash, randomBytes } from "node:crypto";
-//#region src/server/manifest.ts
-const FRAME_EXT = /\.(tsx|jsx|html)$/;
-const RESERVED_SCENES = /* @__PURE__ */ new Set(["components", "screens"]);
-/** Extract `export const meta = {...}` with literal string values only. Anything else is silently omitted (spec §6). */
-function extractMeta(src) {
-	const m = /export\s+const\s+meta\s*=\s*\{([\s\S]*?)\}/.exec(src);
-	if (!m) return {};
-	const body = m[1];
-	const pick = (key) => {
-		const r = new RegExp(`${key}\\s*:\\s*(['"\`])([^'"\`]*)\\1`).exec(body);
-		return r ? r[2] : void 0;
-	};
-	const out = {};
-	const title = pick("title");
-	if (title) out.title = title;
-	const viewport = pick("viewport");
-	if (viewport) out.viewport = viewport;
-	const theme = pick("theme");
-	if (theme) out.theme = theme;
-	return out;
-}
-/** id = path relative to design/, extension dropped, `scenes/` prefix dropped. Always `/`-separated. */
-function toFrameId(designRelPath) {
-	const noExt = designRelPath.split(sep).join("/").replace(FRAME_EXT, "");
-	return noExt.startsWith("scenes/") ? noExt.slice(7) : noExt;
-}
-function walk(dir, out = []) {
-	if (!existsSync(dir)) return out;
-	for (const e of readdirSync(dir, { withFileTypes: true })) {
-		if (e.name.startsWith(".")) continue;
-		const p = join(dir, e.name);
-		if (e.isDirectory()) walk(p, out);
-		else out.push(p);
-	}
-	return out;
-}
-function scanFrames(root) {
-	const design = join(root, "design");
-	const frames = [];
-	for (const base of ["scenes", "components"]) for (const abs of walk(join(design, base))) {
-		const name = abs.split(sep).pop();
-		if (name.startsWith("_") || !FRAME_EXT.test(name)) continue;
-		const rel = relative(design, abs).split(sep).join("/");
-		const id = toFrameId(rel);
-		const scene = id.includes("/") ? id.split("/")[0] : "";
-		if (base === "scenes" && RESERVED_SCENES.has(scene)) {
-			console.error(`[marver] scene "${scene}" is a reserved name - "${rel}" skipped. Rename the scene.`);
-			continue;
-		}
-		const kind = name.endsWith(".html") ? "html" : "tsx";
-		const entry = {
-			id,
-			file: `design/${rel}`,
-			kind,
-			scene
-		};
-		if (kind === "tsx") {
-			const meta = extractMeta(readFileSync(abs, "utf8"));
-			if (meta.title) entry.title = meta.title;
-			if (meta.viewport) entry.viewport = meta.viewport;
-			if (meta.theme) entry.theme = meta.theme;
-		}
-		frames.push(entry);
-	}
-	const extRank = (file) => file.endsWith(".tsx") ? 0 : file.endsWith(".jsx") ? 1 : 2;
-	frames.sort((a, b) => a.id.localeCompare(b.id) || extRank(a.file) - extRank(b.file) || a.file.localeCompare(b.file));
-	const seen = /* @__PURE__ */ new Map();
-	const deduped = frames.filter((f) => {
-		const prev = seen.get(f.id);
-		if (prev) {
-			console.error(`[marver] duplicate frame id "${f.id}" (${prev} vs ${f.file}) - keeping ${prev}.`);
-			return false;
-		}
-		seen.set(f.id, f.file);
-		return true;
-	});
-	frames.length = 0;
-	frames.push(...deduped);
-	const sceneCounts = /* @__PURE__ */ new Map();
-	for (const f of frames) sceneCounts.set(f.scene, (sceneCounts.get(f.scene) ?? 0) + 1);
-	return {
-		frames,
-		scenes: [...sceneCounts.entries()].map(([name, n]) => ({
-			name,
-			frames: n
-		})).sort((a, b) => a.name.localeCompare(b.name))
-	};
-}
-/** Write design/manifest.json only when content changed. Returns the manifest either way. */
-function writeManifest(root, manifest) {
-	const file = join(root, "design", "manifest.json");
-	const next = JSON.stringify(manifest, null, 2) + "\n";
-	const prev = existsSync(file) ? readFileSync(file, "utf8") : "";
-	if (hash(prev) === hash(next)) return false;
-	mkdirSync(join(root, "design"), { recursive: true });
-	writeFileSync(file, next);
-	return true;
-}
-const hash = (s) => createHash("sha256").update(s).digest("hex");
-//#endregion
+import { join, resolve, sep } from "node:path";
+import { randomBytes } from "node:crypto";
 //#region src/server/api.ts
 const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
 const BODY_LIMIT = 1e6;
@@ -188,7 +89,7 @@ function apiMiddleware(root) {
 				const p = boardPath(boardMatch[1]);
 				if (!p) return json(res, 400, { error: "invalid board name" });
 				if (req.method === "GET") {
-					if (!existsSync(p)) return json(res, 404, { error: "not found" });
+					if (!existsSync(p)) return json(res, 200, { board: null });
 					const content = readFileSync(p, "utf8");
 					try {
 						return json(res, 200, {
@@ -275,6 +176,7 @@ function routesMiddleware(server, clientDir) {
 		try {
 			const html = await server.transformIndexHtml(req.url ?? "/", page(dir));
 			res.setHeader("content-type", "text/html");
+			res.setHeader("cache-control", "no-store");
 			res.end(html);
 		} catch (err) {
 			res.statusCode = 500;
@@ -306,7 +208,7 @@ function marverPlugin(ctx) {
 		},
 		load(id) {
 			if (id === "\0virtual:sh-theme.css") {
-				console.warn("[marver] no theme detected - frames render unstyled. Set `theme` in design/config.ts.");
+				console.warn("[marver] no theme detected - frames render unstyled. Create design/theme.css importing your app's stylesheet (or set `theme` in design/config.ts).");
 				return "/* marver: no theme configured */";
 			}
 			if (id === "\0virtual:sh-config") return `export default ${JSON.stringify({
@@ -354,6 +256,13 @@ function marverPlugin(ctx) {
 			if (hctx.modules.length === 0) return [];
 		},
 		configureServer(server) {
+			server.middlewares.use((req, res, next) => {
+				if (req.url && req.url.includes("/frame-host/registry.ts")) {
+					const orig = res.setHeader.bind(res);
+					res.setHeader = ((name, value) => orig(name, String(name).toLowerCase() === "cache-control" ? "no-cache" : value));
+				}
+				next();
+			});
 			server.middlewares.use(apiMiddleware(root));
 			server.middlewares.use(routesMiddleware(server, clientDir));
 			const regen = debounce(() => {
@@ -362,8 +271,39 @@ function marverPlugin(ctx) {
 			}, 150);
 			const watched = [join(root, "design", "scenes"), join(root, "design", "components")];
 			const inScope = (file) => watched.some((w) => file.startsWith(w));
-			server.watcher.on("add", (f) => inScope(f) && regen());
-			server.watcher.on("unlink", (f) => inScope(f) && regen());
+			const themeModules = () => {
+				const f = themeFile();
+				if (!f) return [];
+				const out = [];
+				const seen = /* @__PURE__ */ new Set();
+				const walk = (mod) => {
+					if (!mod || seen.has(mod)) return;
+					seen.add(mod);
+					out.push(mod);
+					for (const im of mod.clientImportedModules ?? mod.importedModules ?? []) if (String(im.id ?? "").split("?")[0].endsWith(".css")) walk(im);
+				};
+				for (const mod of server.moduleGraph.getModulesByFile(f) ?? []) walk(mod);
+				return out;
+			};
+			const pushTheme = debounce(() => {
+				for (const mod of themeModules()) server.reloadModule(mod).catch(() => {});
+			}, 150);
+			const rescanTheme = () => {
+				for (const mod of themeModules()) server.moduleGraph.invalidateModule(mod);
+				pushTheme();
+			};
+			server.watcher.on("add", (f) => {
+				if (inScope(f)) {
+					regen();
+					rescanTheme();
+				}
+			});
+			server.watcher.on("unlink", (f) => {
+				if (inScope(f)) {
+					regen();
+					rescanTheme();
+				}
+			});
 			server.watcher.on("change", (f) => inScope(f) && /\.(tsx|jsx)$/.test(f) && regen());
 			writeManifest(root, scanFrames(root));
 			const boardsDir = join(root, "design", "boards");
@@ -397,15 +337,18 @@ function debounce(fn, ms) {
 		t = setTimeout(() => fn(...a), ms);
 	});
 }
-/** Extra vite plugin when the host runs Tailwind v4: use their own @tailwindcss/vite. */
+/** Extra vite plugin when the host runs Tailwind v4. The host's own @tailwindcss/vite
+*  wins (version-matched to their tailwindcss); the fallback is marver's bundled copy -
+*  Next.js hosts use @tailwindcss/postcss and never have the vite plugin (the blessed
+*  stack would otherwise render every frame without its utility classes). */
 async function tailwind4Plugin(root) {
-	try {
-		const mod = await import(join(root, "node_modules", "@tailwindcss", "vite", "dist", "index.mjs"));
+	const factories = [() => import(join(root, "node_modules", "@tailwindcss", "vite", "dist", "index.mjs")), () => import("@tailwindcss/vite")];
+	for (const load of factories) try {
+		const mod = await load();
 		const result = (mod.default ?? mod)();
 		return Array.isArray(result) ? result : [result];
-	} catch {
-		return null;
-	}
+	} catch {}
+	return null;
 }
 /** Tailwind v3: inline PostCSS config extending the host's tailwind config with design/ globs. Host files untouched. */
 async function tailwind3Css(root) {
@@ -434,4 +377,4 @@ async function tailwind3Css(root) {
 	return null;
 }
 //#endregion
-export { scanFrames as i, tailwind3Css as n, tailwind4Plugin as r, marverPlugin as t };
+export { tailwind3Css as n, tailwind4Plugin as r, marverPlugin as t };

package/dist/{serve-BPNmWeJx.mjs → serve-BvbAbWeK.mjs}

@@ -1,6 +1,6 @@
 import { t as NAME } from "./cli.mjs";
-import { extname, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { extname, isAbsolute, join, relative, resolve } from "node:path";
 import { createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 //#region src/server/serve.ts
@@ -115,6 +115,13 @@ function serve(root, portFlag) {
 		}
 	});
 	const port = portFlag ?? (Number(process.env.PORT) || 4199);
+	server.on("error", (err) => {
+		if (err.code === "EADDRINUSE") {
+			console.error(`[${NAME}] port ${port} is already in use - another \`${NAME} serve\` still running? Stop it, or pass --port <n>.`);
+			process.exit(1);
+		}
+		throw err;
+	});
 	server.listen(port, () => {
 		console.log(`\n  ${NAME} serving design/.dist → http://localhost:${port}/`);
 		console.log(verifier ? "  gate: ON (MARVER_PASSWORD set)\n" : "  gate: off - set MARVER_PASSWORD to require a password\n");

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components. The tool ships no AI - your coding agent is the designer.",
   "type": "module",
   "private": false,
   "license": "Apache-2.0",
   "bin": {
-    "marver": "./dist/cli.mjs"
+    "marver": "dist/cli.mjs"
   },
   "files": [
     "dist",
@@ -27,6 +27,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^6.0.0",
     "cac": "^7.0.0",
     "react-zoom-pan-pinch": "^3.6.1",
@@ -56,4 +57,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

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

@@ -4,9 +4,15 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
 const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 const id = new URLSearchParams(location.search).get('id') ?? location.pathname
 
+// theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
+const setTheme = (theme) => {
+  document.documentElement.dataset.theme = theme
+  document.documentElement.classList.toggle('dark', theme === 'dark')
+}
+
 if (isHtmlFrame) {
   const theme = new URLSearchParams(location.search).get('theme')
-  if (theme) document.documentElement.dataset.theme = theme
+  if (theme) setTheme(theme)
 }
 
 document.addEventListener('click', (e) => {
@@ -23,7 +29,7 @@ window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: St
 window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, message: `unhandled rejection: ${e.reason}` }))
 
 window.addEventListener('message', (e) => {
-  if (e?.data?.type === 'sh:set-theme') document.documentElement.dataset.theme = e.data.theme
+  if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
 })
 
 if (isHtmlFrame) {

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

@@ -12,7 +12,11 @@ import { frameFile, frames, layoutChain, layouts, providers } from './registry.t
 const params = new URLSearchParams(location.search)
 const id = params.get('id') ?? ''
 const theme = params.get('theme') ?? 'light'
+// Both signals, always: [data-theme] for token systems keyed on the attribute, and the
+// `dark` class for Tailwind/shadcn (`@custom-variant dark (&:is(.dark *))` never sees a
+// data attribute). The bridge applies the same pair on sh:set-theme.
 document.documentElement.dataset.theme = theme
+document.documentElement.classList.toggle('dark', theme === 'dark')
 
 const post = (msg: Record<string, unknown>) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 
@@ -47,7 +51,9 @@ async function boot() {
     await import('virtual:sh-theme' as string)
 
     const fileKey = frameFile(id)
-    if (!fileKey) return fail(`unknown frame id "${id}"`)
+    // Honest copy: the id usually IS valid on disk - this document's frame registry is
+    // what's stale (file just added/renamed, or the dev server restarted). See #20.
+    if (!fileKey) return fail(`frame "${id}" is not in this canvas's registry yet - the file was likely just added or renamed. The canvas should recover on its own; if this card persists, reload it.`)
 
     const frameMod: any = await frames[fileKey]()
     const Frame = frameMod.default

package/src/client/shell/App.tsx

@@ -115,6 +115,18 @@ function SelectionBar() {
   const node = useStore((s) => s.nodes.find((n) => n.key === s.selection[s.selection.length - 1]))
   const frame = useStore((s) => (node ? s.frameFor(node) : undefined))
   const nodes = useStore((s) => s.nodes)
+  // measured width feeds the viewport clamp below; a callback ref because the bar
+  // mounts/unmounts with the selection (an effect with [] would miss remounts)
+  const [barW, setBarW] = useState(0)
+  const roRef = useRef<ResizeObserver | null>(null)
+  const barRef = (el: HTMLDivElement | null) => {
+    roRef.current?.disconnect()
+    roRef.current = null
+    if (el) {
+      roRef.current = new ResizeObserver(() => setBarW(el.offsetWidth))
+      roRef.current.observe(el)
+    }
+  }
   if (!node || !frame || node.missing) return null
   // anchor: centered over the bounding box of ALL selected frames, above the topmost
   const selNodes = nodes.filter((n) => selection.includes(n.key))
@@ -135,14 +147,21 @@ function SelectionBar() {
       .map((k) => { const n = st.nodes.find((x) => x.key === k); return n ? st.frameFor(n) : undefined })
       .filter((f): f is NonNullable<typeof f> => !!f)
   }
+  // centered over the selection's bounding box, then CLAMPED into the viewport: the
+  // controls for a selected frame must stay reachable when its top edge is panned
+  // off-screen, and must never drift off the sides (friction log #23)
+  const centerX = `calc(var(--sh-tx, 0px) + var(--sh-s, 1) * ${(bx0 + bx1) / 2}px)`
+  const rawTop = `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - 52px)`
   return (
     <div
       className="sh-ctx"
+      ref={barRef}
       style={{
-        // centered over the selection's bounding box; translateX keeps it centered at any width
-        left: `calc(var(--sh-tx, 0px) + var(--sh-s, 1) * ${(bx0 + bx1) / 2}px)`,
-        top: `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - 52px)`,
-        transform: 'translateX(-50%)',
+        left: barW
+          ? `clamp(8px, calc(${centerX} - ${Math.round(barW / 2)}px), calc(100vw - ${barW + 8}px))`
+          : centerX,
+        top: `clamp(8px, ${rawTop}, calc(100vh - 52px))`,
+        transform: barW ? undefined : 'translateX(-50%)',
       }}
     >
       {multi && <>
@@ -623,7 +642,7 @@ export function App() {
 
       <PlayOverlay />
 
-      {CONFIG.noTheme && <div className="sh-banner">no theme configured - frames render unstyled (design/config.ts → theme)</div>}
+      {CONFIG.noTheme && <div className="sh-banner">no theme configured - frames render unstyled. Create design/theme.css importing your app's stylesheet (or set theme in design/config.ts)</div>}
 
       <div className="sh-toasts">
         {toasts.map((t) => <div key={t.id} className="sh-toast"><CheckIcon size={12} /> {t.text}</div>)}

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

@@ -47,6 +47,15 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     fileRef.current = sig
   }, [frame?.kind, frame?.file])
 
+  // shell-requested renavigation (store bumps node.nav): reload on a FRESH rev-stamped
+  // URL - the errored document's own URL may be poisoned by cache (friction log #20)
+  const navRef = useRef(node.nav ?? 0)
+  useEffect(() => {
+    if ((node.nav ?? 0) === navRef.current) return
+    navRef.current = node.nav ?? 0
+    if (frame && iframeRef.current) iframeRef.current.src = frameUrl(frame, node.theme)
+  }, [node.nav])
+
   // ready timeout (spec §7): 10s without sh:ready -> error card with reload
   useEffect(() => {
     if (node.status !== 'loading') return

package/src/client/shell/store.ts

@@ -17,6 +17,9 @@ export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
   /** RESOLVED theme (what renders): themeUser ?? frame meta.theme ?? viewTheme. */
   theme: string
+  /** Renavigation nonce: bumped when the shell wants this iframe on a FRESH URL
+   *  (errored frame whose file is back in the manifest). Never persisted. */
+  nav?: number
   /** Explicit per-frame override, set by scoped theme actions; cleared by a global set.
    *  The only theme value that persists into the board file. */
   themeUser?: string
@@ -42,10 +45,16 @@ const HEADER = 28
 let toastSeq = 0
 const nodeKey = () => 'n_' + Math.random().toString(36).slice(2, 8)
 
+/** Manifest revision - bumps whenever a manifest lands (boot, switch, sh:manifest).
+ *  Stamped into frame URLs so a changed frame set mints genuinely NEW iframe URLs:
+ *  the browser can never revive a pre-change document from cache (friction log #20). */
+let manifestRev = 0
+export const bumpManifestRev = () => { manifestRev++ }
+
 export function frameUrl(frame: FrameEntry, theme: string): string {
   return frame.kind === 'html'
     ? `/${frame.file}?theme=${theme}`
-    : `${ROUTE}/frame/?id=${encodeURIComponent(frame.id)}&theme=${theme}`
+    : `${ROUTE}/frame/?id=${encodeURIComponent(frame.id)}&theme=${theme}&r=${manifestRev}`
 }
 
 /** The global view theme: the user's sticky preference, applied across boards and
@@ -148,6 +157,7 @@ export const useStore = create<State>((set, get) => {
         raw = await mRes.json().catch(() => undefined)
       }
       if (raw === undefined || raw === null || typeof raw !== 'object') return null
+      bumpManifestRev()                        // fresh manifest → fresh iframe URLs
       const manifest: Manifest = {
         frames: (Array.isArray(raw?.frames) ? raw.frames : [])
           .filter((f: any) => f && typeof f.id === 'string' && typeof f.file === 'string'),
@@ -164,9 +174,12 @@ export const useStore = create<State>((set, get) => {
       if (DATA) loaded = DATA.boards[boardName] ? { board: DATA.boards[boardName], sha256: 'published' } : 'fresh'
       else {
         const res = await fetch(`${ROUTE}/api/boards/${boardName}`)
-        if (res.ok) loaded = await res.json()
-        else if (res.status === 404) loaded = 'fresh'
-        else loaded = null                     // only 404 means "fresh board"; anything else must not commit an empty canvas
+        if (res.ok) {
+          const body = await res.json()
+          loaded = body?.board == null ? 'fresh' : body   // board:null = not materialized yet
+        }
+        else if (res.status === 404) loaded = 'fresh'    // older servers still 404 fresh boards
+        else loaded = null                     // anything else must not commit an empty canvas
       }
       if (loaded === null) return null
       if (loaded !== 'fresh') {
@@ -210,6 +223,16 @@ export const useStore = create<State>((set, get) => {
         if (typeof board?.deviceView === 'string' && CONFIG.viewports[board.deviceView]) deviceView = board.deviceView
         if (board?.baseLayout && typeof board.baseLayout === 'object') baseLayout = board.baseLayout
       }
+      // auto-managed goes both ways (friction log #15): an auto board gains new frames
+      // AND sheds deleted ones. Tombstone cards are a curated-board concept (spec §7).
+      // Pruning at load DIRTIES the board (dev only) so the file on disk sheds the
+      // tombstones too - otherwise a recreated frame id resurrects its stale node.
+      let prunedAtLoad = false
+      if (boardAuto) {
+        const before = nodes.length
+        nodes = nodes.filter((n) => !n.missing)
+        prunedAtLoad = !DATA && nodes.length !== before
+      }
       // frames not on the board yet → auto boards only (a curated board shows exactly its list)
       if (boardAuto) {
         const placed = new Set(nodes.map((n) => n.frame))
@@ -234,8 +257,9 @@ export const useStore = create<State>((set, get) => {
         const placedAll = tidy(nodes.map((n) => ({ key: n.key, scene: sceneOf(n.frame), w: n.w, h: n.h + HEADER })))
         for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
       }
-      // dirty: false - the committed state matches disk by construction
-      return { manifest, nodes, boardHash, boardAuto, deviceView, baseLayout, selection: [], dirty: false }
+      // dirty matches disk by construction - except when load-time pruning changed the
+      // node set; callers see dirty:true and schedule the save that persists the prune
+      return { manifest, nodes, boardHash, boardAuto, deviceView, baseLayout, selection: [], dirty: prunedAtLoad }
     } catch { return null }
   }
 
@@ -255,6 +279,7 @@ export const useStore = create<State>((set, get) => {
       if (get().board !== boardName || editRev !== revAtStart) return false
       const live = get().manifest             // a WS manifest update may have landed mid-fetch
       set(next)
+      if (next.dirty) scheduleSave()          // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
       return true
     },
@@ -280,10 +305,12 @@ export const useStore = create<State>((set, get) => {
       ++loadSeq                                // invalidate any in-flight boot of the old board
       const live = get().manifest              // a WS manifest update may have landed mid-load
       set({ board: name, interact: null, ...next })
+      if (next.dirty) scheduleSave()           // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
     },
 
     applyManifest(m) {
+      bumpManifestRev()                        // frame set changed → new iframes get fresh URLs
       const { nodes, toast, boardAuto } = get()
       const known = new Set(nodes.map((n) => n.frame))
       const next = [...nodes]
@@ -313,8 +340,28 @@ export const useStore = create<State>((set, get) => {
         const f = m.frames.find((x) => x.id === n.frame)
         const want = n.themeUser ?? f?.theme ?? get().viewTheme
         if (n.theme !== want) { n.theme = want; 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 }
       }
-      set({ manifest: m, nodes: changed || retinted ? [...next] : next, ...(changed ? { dirty: true, baseLayout: nextBase } : {}) })
+      // auto boards prune deleted frames outright - "auto-managed" must manage both
+      // directions (friction log #15). Curated boards keep the explicit card (spec §7).
+      let final = next
+      if (boardAuto) {
+        final = next.filter((n) => !n.missing)
+        const dropped = next.length - final.length
+        if (dropped) {
+          changed = true
+          toast(dropped === 1 ? 'removed 1 deleted frame' : `removed ${dropped} deleted frames`)
+        }
+      }
+      set((s) => ({
+        manifest: m,
+        nodes: changed || retinted ? [...final] : final,
+        selection: s.selection.filter((k) => final.some((n) => n.key === k)),
+        interact: s.interact && final.some((n) => n.key === s.interact) ? s.interact : null,
+        ...(changed ? { dirty: true, baseLayout: nextBase } : {}),
+      }))
       if (changed) scheduleSave()
     },
 

package/templates/AGENTS-embedded.md

@@ -11,7 +11,14 @@ Never run or talk to the canvas tool; read and write files only.
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu, hotkeys 0-5) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
-- Use the app's UI: import from {{UI_ALIAS}}; style with the app's Tailwind classes.
+- VERSIONS are sibling frames too - the scene is the surface, each frame one direction:
+  design/scenes/landing/a-terminal.tsx, landing/b-editorial.tsx, landing/c-product.tsx.
+  Layout and the sidebar follow frame-id order, so variants named under one scene with
+  a-/b-/c- prefixes stay adjacent and ordered through tidy and every device view.
+  Never spread versions across scenes (terminal/landing, editorial/landing) - they
+  interleave with everything else and the comparison falls apart.
+- {{UI_GUIDANCE}}
+{{NEXT_NOTES}}
 - Navigation: put data-goto="scene/frame" on any element. That is the whole prototype system.
   In play mode (the human presses P) frames swap in place inside one device - design flows
   as complete graphs: every screen a data-goto points at should itself link somewhere or be
@@ -34,7 +41,8 @@ Never run or talk to the canvas tool; read and write files only.
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before exploring.
+- design/manifest.json lists every frame (id, file, scene, title) - read it before
+  exploring. `init` writes the first one; `marver dev` keeps it fresh.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -62,7 +70,10 @@ lays it out, and keeps it tidy:
 ```
 
 - The same frame may appear on many boards, or twice on one board (e.g. two widths:
-  add `"w"`/`"h"` on a node to pin a size).
+  add `"w"`/`"h"` on a node to pin a size, `"x"`/`"y"` to place it - e.g. a comparison
+  row: same `y`, increasing `x`). Know that the human's tidy (`t`) and device views
+  re-layout in frame-id order, so id ordering is the durable arrangement; explicit
+  coordinates are for one-off setups.
 - `auto: false` boards show exactly their list. The `all-scenes` board is auto-managed -
   never write it.
 - Use boards for comparisons: version A vs B vs C of a flow, side by side.

package/templates/AGENTS-studio.md

@@ -11,7 +11,14 @@ Never run or talk to the canvas tool; read and write files only.
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu, hotkeys 0-5) to check responsiveness.
 - States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
-- Use the app's UI: import from {{UI_ALIAS}}; style with the app's Tailwind classes.
+- VERSIONS are sibling frames too - the scene is the surface, each frame one direction:
+  design/scenes/landing/a-terminal.tsx, landing/b-editorial.tsx, landing/c-product.tsx.
+  Layout and the sidebar follow frame-id order, so variants named under one scene with
+  a-/b-/c- prefixes stay adjacent and ordered through tidy and every device view.
+  Never spread versions across scenes (terminal/landing, editorial/landing) - they
+  interleave with everything else and the comparison falls apart.
+- {{UI_GUIDANCE}}
+{{NEXT_NOTES}}
 - Navigation: put data-goto="scene/frame" on any element. That is the whole prototype system.
   In play mode (the human presses P) frames swap in place inside one device - design flows
   as complete graphs: every screen a data-goto points at should itself link somewhere or be
@@ -33,7 +40,8 @@ Never run or talk to the canvas tool; read and write files only.
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before exploring.
+- design/manifest.json lists every frame (id, file, scene, title) - read it before
+  exploring. `init` writes the first one; `marver dev` keeps it fresh.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -62,7 +70,10 @@ lays it out, and keeps it tidy:
 ```
 
 - The same frame may appear on many boards, or twice on one board (e.g. two widths:
-  add `"w"`/`"h"` on a node to pin a size).
+  add `"w"`/`"h"` on a node to pin a size, `"x"`/`"y"` to place it - e.g. a comparison
+  row: same `y`, increasing `x`). Know that the human's tidy (`t`) and device views
+  re-layout in frame-id order, so id ordering is the durable arrangement; explicit
+  coordinates are for one-off setups.
 - `auto: false` boards show exactly their list. The `all-scenes` board is auto-managed -
   never write it.
 - Use boards for comparisons: version A vs B vs C of a flow, side by side.

package/dist/config-DMBEpdEN.mjs

@@ -1,132 +0,0 @@
-import { join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
-import { pathToFileURL } from "node:url";
-//#region src/server/detect.ts
-function readJson(file) {
-	try {
-		return JSON.parse(stripJsonComments(readFileSync(file, "utf8")));
-	} catch {
-		return null;
-	}
-}
-function stripJsonComments(s) {
-	return s.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1").replace(/,\s*([}\]])/g, "$1");
-}
-function detectHost(root) {
-	const pkg = readJson(join(root, "package.json")) ?? {};
-	const deps = {
-		...pkg.dependencies,
-		...pkg.devDependencies
-	};
-	const twRange = deps["tailwindcss"];
-	const tailwind = !twRange ? null : /(^|[^\d])4\./.test(twRange) || twRange.startsWith("^4") || twRange.startsWith("~4") ? 4 : 3;
-	const router = deps["next"] ? "next" : deps["react-router"] || deps["react-router-dom"] ? "react-router" : null;
-	const routerPkg = deps["react-router-dom"] ? "react-router-dom" : "react-router";
-	const toaster = deps["sonner"] ? "sonner" : deps["react-hot-toast"] ? "react-hot-toast" : null;
-	let shadcn = null;
-	const comp = readJson(join(root, "components.json"));
-	if (comp?.tailwind?.css) shadcn = {
-		themeCss: comp.tailwind.css,
-		uiAlias: comp.aliases?.ui ?? "@/components/ui"
-	};
-	const themeCss = shadcn?.themeCss && existsSync(join(root, shadcn.themeCss)) ? shadcn.themeCss : firstExisting(root, [
-		"src/index.css",
-		"src/styles/theme.css",
-		"src/styles/globals.css",
-		"src/app/globals.css",
-		"app/globals.css",
-		"src/globals.css",
-		"src/style.css",
-		"styles/globals.css"
-	]);
-	const ts = readJson(join(root, "tsconfig.json"));
-	const include = ts?.include;
-	const exclude = ts?.exclude ?? [];
-	const sweeps = ts != null && !exclude.some((e) => e === "design" || e.startsWith("design/")) && (!include || include.some((i) => i === "." || i === "**/*" || i.startsWith("design")));
-	return {
-		tailwind,
-		router,
-		routerPkg,
-		toaster,
-		shadcn,
-		themeCss,
-		tsconfigSweepsDesign: !!sweeps
-	};
-}
-function firstExisting(root, candidates) {
-	for (const c of candidates) if (existsSync(join(root, c))) return c;
-	return null;
-}
-//#endregion
-//#region src/server/config.ts
-const DEFAULTS = {
-	mode: "studio",
-	theme: null,
-	viewports: {
-		mobile: {
-			width: 390,
-			height: 844
-		},
-		tablet: {
-			width: 768,
-			height: 1024
-		},
-		laptop: {
-			width: 1280,
-			height: 800
-		},
-		monitor: {
-			width: 1920,
-			height: 1080
-		}
-	},
-	themes: ["light", "dark"],
-	port: 5199,
-	zoomSpeed: 1,
-	share: { branding: true }
-};
-/** Load design/config.ts via native TS import (Node >= 22.18). Missing or broken fields fall back to defaults. */
-async function loadConfig(root) {
-	const file = join(root, "design", "config.ts");
-	if (!existsSync(file)) return { ...DEFAULTS };
-	try {
-		const user = (await import(`${pathToFileURL(file).href}?t=${Date.now()}`)).default ?? {};
-		return {
-			...DEFAULTS,
-			...user,
-			viewports: validViewports(user.viewports) ?? DEFAULTS.viewports,
-			themes: Array.isArray(user.themes) && user.themes.length ? user.themes.map(String) : DEFAULTS.themes,
-			port: validPort(user.port) ?? DEFAULTS.port,
-			zoomSpeed: validZoom(user.zoomSpeed) ?? DEFAULTS.zoomSpeed,
-			share: {
-				branding: user.share?.branding !== false,
-				name: typeof user.share?.name === "string" ? user.share.name : void 0,
-				logo: typeof user.share?.logo === "string" ? user.share.logo : void 0
-			}
-		};
-	} catch (err) {
-		console.error(`[marver] design/config.ts failed to load, using defaults:\n  ${err.message}`);
-		return { ...DEFAULTS };
-	}
-}
-const validDim = (n) => typeof n === "number" && Number.isFinite(n) && n >= 1 && n <= 2e4;
-function validPort(n) {
-	return typeof n === "number" && Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
-}
-function validZoom(n) {
-	return typeof n === "number" && Number.isFinite(n) && n >= .1 && n <= 10 ? n : null;
-}
-function validViewports(v) {
-	if (!v || typeof v !== "object") return null;
-	const out = {};
-	for (const [k, val] of Object.entries(v)) {
-		const vp = val;
-		if (validDim(vp?.width) && validDim(vp?.height)) out[k] = {
-			width: Math.round(vp.width),
-			height: Math.round(vp.height)
-		};
-	}
-	return Object.keys(out).length ? out : null;
-}
-//#endregion
-export { loadConfig as n, detectHost as r, DEFAULTS as t };