@marver-design/marver 0.10.1 → 0.11.0

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

@@ -1,7 +1,8 @@
 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 { basename, dirname, join } from "node:path";
+import { i as detectHost, n as loadConfig } from "./config-t9coJ-Pq.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-vE7sxEeT.mjs";
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";
 import react from "@vitejs/plugin-react";
@@ -44,6 +45,106 @@ async function pickPort(root, desired) {
 		fellBack: true
 	};
 }
+/**
+* What the dev server must never hand out, however deep in the repo it sits.
+*
+* `marver dev` puts the whole repository on the web so frames can import from it.
+* The collaboration credential no longer lives in there - it moved to
+* ~/.marver/canvases/ precisely because guarding it here could not be finished -
+* but design/.local still holds the local profile and whatever a previous version
+* left behind, and none of that is anybody's business but the author's.
+*
+* Vite's own defaults are restated rather than assumed. `fs.deny` REPLACES the
+* default list, so an array containing only our own rule quietly re-exposes
+* `.env`, private keys, `.npmrc` and `.git` - a much larger hole than the one
+* being closed, opened by closing it. Kept as an exported constant so a test can
+* hold both halves.
+*/
+const FS_DENY = [
+	".env",
+	".env.*",
+	"*.{crt,pem,key,p12,pfx,cer,der}",
+	".npmrc",
+	".yarnrc.yml",
+	"**/.git/**",
+	".dev.vars",
+	".dev.vars.*",
+	"**/design/.local/**"
+];
+/**
+* The half of the credential guard that globs cannot do.
+*
+* `fs.deny` matches the REQUEST path, lexically, and then Vite stats and streams
+* whatever that path resolves to. So a repository containing
+* `leak.json -> design/.local/anything` serves that file at `/leak.json` to any
+* authored frame that asks - the deny rule never sees the name it is looking for.
+* Verified against a real dev server before this existed.
+*
+* More patterns cannot fix that; only resolving can. This runs BEFORE Vite's own
+* middlewares (a `configureServer` hook that does not return a function is
+* installed first) and refuses any request whose real file lands inside
+* design/.local, whatever route it took to get there.
+*
+* "Whatever route" means every place Vite would look, not just the project root.
+* `public/` is mapped onto `/`, so `public/leak.json -> ../design/.local/x` is
+* served at `/leak.json` - and Vite skips its own deny checks entirely for public
+* files, so that spelling was reachable even with the root candidate guarded.
+* Each candidate is resolved; if any lands in design/.local, the request is
+* refused.
+*
+* The boundary this does NOT claim: a repository that can write symlinks can also
+* write `design/config.ts`, which `marver dev` imports and RUNS in this process
+* before any of the above exists. Running `dev` on a repository you do not trust
+* hands it your machine long before it hands it a file, so a symlink is not the
+* interesting way in. What this closes is the frame-in-a-trusted-repo case: a
+* component that runs in the browser, same-origin, that can only ask for URLs and
+* cannot create a file to ask for.
+*/
+function denyLocalSecrets(root) {
+	const guardedAt = join(root, "design", ".local");
+	const publicAt = join(root, "public");
+	const inside = (real, dir) => {
+		const rel = relative(dir, real);
+		return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+	};
+	return {
+		name: "marver:deny-local-secrets",
+		configureServer(server) {
+			server.middlewares.use((req, res, next) => {
+				let pathname;
+				try {
+					pathname = decodeURIComponent((req.url ?? "/").split("?")[0].split("#")[0]);
+				} catch {
+					return next();
+				}
+				const rel = "." + (pathname.startsWith("/") ? pathname : `/${pathname}`);
+				const derived = (base) => [
+					base,
+					`${base}.html`,
+					join(base, "index"),
+					join(base, "index.html")
+				];
+				const candidates = pathname.startsWith("/@fs/") ? derived(pathname.slice(4)) : [...derived(resolve(root, rel)), ...derived(resolve(publicAt, rel))];
+				let guarded;
+				try {
+					guarded = realpathSync(guardedAt);
+				} catch {
+					return next();
+				}
+				if (!candidates.some((c) => {
+					try {
+						return inside(realpathSync(c), guarded);
+					} catch {
+						return false;
+					}
+				})) return next();
+				res.statusCode = 403;
+				res.setHeader("content-type", "text/plain; charset=utf-8");
+				res.end("design/.local holds this canvas's credentials and is never served");
+			});
+		}
+	};
+}
 async function dev(root, portFlag) {
 	const config = await loadConfig(root);
 	const host = detectHost(root);
@@ -52,7 +153,7 @@ async function dev(root, portFlag) {
 	const projectName = basename(root);
 	const desiredPort = portFlag ?? (config.port !== 5199 ? config.port : void 0) ?? projectPort(root);
 	const picked = await pickPort(root, desiredPort);
-	const plugins = [react()];
+	const plugins = [denyLocalSecrets(root), react()];
 	if (host.tailwind === 4) {
 		const tw = await tailwind4Plugin(root);
 		if (tw) plugins.push(...tw);
@@ -85,11 +186,14 @@ async function dev(root, portFlag) {
 		server: {
 			port: picked.port,
 			strictPort: false,
-			fs: { allow: [.../* @__PURE__ */ new Set([
-				root,
-				pkgDir,
-				searchForWorkspaceRoot(root)
-			])] },
+			fs: {
+				allow: [.../* @__PURE__ */ new Set([
+					root,
+					pkgDir,
+					searchForWorkspaceRoot(root)
+				])],
+				deny: FS_DENY
+			},
 			watch: { ignored: [
 				"**/design/manifest.json",
 				"**/design/boards/**",
@@ -141,8 +245,18 @@ 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`);
-	const { loadCollab, syncOnce } = await import("./sync-BJKKmy1n.mjs");
-	if (loadCollab(root)) console.log(`  comments: syncing with the published canvas (design/.local/collab.json)\n`);
+	try {
+		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
+		const { installedVersion } = await import("./update-DuWDj5nR.mjs").then((n) => n.r);
+		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-DELGomPk.mjs").then((n) => n.o);
+	if (loadCollab(root)) console.log(`  comments: syncing with the published canvas\n`);
 	let syncing = false;
 	const tick = async () => {
 		if (syncing) return;
@@ -171,7 +285,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-B_8BmmSJ.mjs");
+		const { startJam } = await import("./daemon-DSmaS453.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-BSclDg4I.mjs}

@@ -1,20 +1,10 @@
 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 { a as readJson, i as detectHost, r as detectAgent, t as DEFAULTS } from "./config-t9coJ-Pq.mjs";
+import { a as writeManifest, r as scanFrames } from "./manifest-C2tzkNaC.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 +47,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 +65,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 +83,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 +108,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 +123,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 +180,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/manifest-C2tzkNaC.mjs

@@ -0,0 +1,233 @@
+import { r as PKG, t as CONTENT_WIDTH } from "./cli.mjs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { createHash } 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. */
+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(`(?:^|[{,])\\s*${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;
+	const of = pick("of");
+	if (of) out.of = of;
+	const variant = pick("variant");
+	if (variant) out.variant = variant;
+	const intent = pick("intent");
+	if (intent) out.intent = intent;
+	return out;
+}
+/** Content-frame detection: LEXICAL by convention - the frame file
+*  itself imports PKG/content (an import specifier scan, so "<Diagram" inside a
+*  string in a UI frame can never misbadge it; barrels/re-exports are not
+*  detected - meta.intent is the taught path and always works). Returns the
+*  inferred intent + natural width, or null for UI frames. */
+const CONTENT_IMPORT = new RegExp(`from\\s+['"]${PKG}/content['"]`);
+const WIDE_DOC = /<Doc\b[^>]*\blayout\s*=\s*["']wide["']/;
+const contentWidthOf = (src) => WIDE_DOC.test(src) ? CONTENT_WIDTH.wide : CONTENT_WIDTH.document;
+function contentScan(src) {
+	if (!CONTENT_IMPORT.test(src)) return null;
+	const count = (re) => (src.match(re) ?? []).length;
+	const diagrams = count(/<Diagram[\s>/]/g);
+	const imgs = count(/<Img[\s>/]/g);
+	const mds = count(/<Md[\s>/]/g);
+	return {
+		intent: diagrams > 0 ? "diagram" : imgs > mds ? "moodboard" : "spec",
+		width: contentWidthOf(src)
+	};
+}
+/** 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;
+}
+/**
+* A7: which frames does a changed `design/**` file affect? Manifest + directory conventions,
+* NOT a module-graph walk (deterministic, cheap, may over-reload but never misses a
+* conventionally-affected frame). Returns:
+*   null  -> uncontrolled: leave to default Vite HMR (src/** deps, theme.css, config, assets)
+*   []    -> controlled but affects no current frame (e.g. a layout in an empty dir)
+*   [ids] -> controlled: the shell drives a rev-stamped reload of these frames
+*/
+function affectedFrameIds(absFile, root, manifest) {
+	const design = join(root, "design");
+	if (absFile !== design && !absFile.startsWith(design + sep)) return null;
+	const rel = relative(design, absFile).split(sep).join("/");
+	const name = rel.split("/").pop() ?? rel;
+	const designRel = `design/${rel}`;
+	const tsxFrames = manifest.frames.filter((f) => f.kind === "tsx");
+	if (name === "theme.css") return null;
+	if (rel === "providers.tsx" || rel === "providers.jsx") return tsxFrames.map((f) => f.id);
+	if (/(^|\/)(_layout\.(tsx|jsx)|_fixtures\.(ts|tsx|js|jsx|json))$/.test(rel)) {
+		const prefix = `design/${rel.slice(0, rel.length - name.length)}`;
+		return tsxFrames.filter((f) => f.file.startsWith(prefix)).map((f) => f.id);
+	}
+	const direct = manifest.frames.find((f) => f.file === designRel);
+	if (direct) return [direct.id];
+	return null;
+}
+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 src = readFileSync(abs, "utf8");
+			const meta = extractMeta(src);
+			if (meta.title) entry.title = meta.title;
+			if (meta.viewport) entry.viewport = meta.viewport;
+			if (meta.theme) entry.theme = meta.theme;
+			if (meta.of) entry.variantGroup = meta.of;
+			if (meta.variant) entry.variant = meta.variant;
+			const content = contentScan(src);
+			if (content || meta.intent) {
+				entry.intent = meta.intent ?? content.intent;
+				entry.contentWidth = content?.width ?? contentWidthOf(src);
+			}
+		}
+		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);
+	inferVariantGroups(frames);
+	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))
+	};
+}
+/** Variant groups. A group = 2+ frames in one DIRECTORY whose basenames
+*  are letter-prefixed (`a-terminal`), or frames declaring `meta.of`. Group id = the
+*  directory's id prefix (or meta.of); variant key = the letter (or meta.variant).
+*  Nested directories scope alternatives inside a busy scene (checkout/payment/a-card).
+*  States (empty.tsx, error.tsx) never letter-prefix, so they never misgroup.
+*  Mutates entries in place: only frames whose group materializes keep the fields. */
+function inferVariantGroups(frames) {
+	const dirOf = (id) => {
+		const i = id.lastIndexOf("/");
+		return i >= 0 ? id.slice(0, i) : "";
+	};
+	const candidates = /* @__PURE__ */ new Map();
+	for (const f of frames) {
+		if (f.kind !== "tsx") {
+			delete f.variantGroup;
+			delete f.variant;
+			continue;
+		}
+		let group = f.variantGroup;
+		let key = f.variant;
+		if (!group) {
+			const base = f.id.slice(f.id.lastIndexOf("/") + 1);
+			const m = /^([a-z])-.+$/.exec(base);
+			if (!m) continue;
+			group = dirOf(f.id);
+			if (!group) continue;
+			key = key ?? m[1];
+		} else if (!key) {
+			const m = /^([a-z])-.+$/.exec(f.id.slice(f.id.lastIndexOf("/") + 1));
+			if (!m) {
+				console.warn(`[marver] ${f.file} declares of:"${group}" but no variant key (add meta.variant or a letter prefix) - not grouped.`);
+				delete f.variantGroup;
+				delete f.variant;
+				continue;
+			}
+			key = m[1];
+		}
+		f.variantGroup = group;
+		f.variant = key;
+		candidates.set(group, [...candidates.get(group) ?? [], f]);
+	}
+	for (const [group, members] of candidates) {
+		if (new Set(members.map((m) => dirOf(m.id))).size > 1) {
+			console.warn(`[marver] group "${group}" spans directories - variants must be siblings; not grouped.`);
+			for (const m of members) {
+				delete m.variantGroup;
+				delete m.variant;
+			}
+			continue;
+		}
+		const seen = /* @__PURE__ */ new Set();
+		const kept = [];
+		for (const m of members.sort((a, b) => (a.variant ?? "").localeCompare(b.variant ?? ""))) {
+			if (seen.has(m.variant)) {
+				console.warn(`[marver] duplicate variant "${m.variant}" in group "${group}" (${m.file}) - not grouped.`);
+				delete m.variantGroup;
+				delete m.variant;
+				continue;
+			}
+			seen.add(m.variant);
+			kept.push(m);
+		}
+		if (kept.length < 2) for (const m of kept) {
+			delete m.variantGroup;
+			delete m.variant;
+		}
+	}
+	for (const f of frames) if (f.variant && !f.variantGroup) delete f.variant;
+}
+/** 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 { writeManifest as a, toFrameId as i, hash as n, scanFrames as r, affectedFrameIds as t };