@marver-design/marver 0.2.1 → 0.2.3

package/README.md

@@ -18,6 +18,7 @@ Then, to your agent:
 - **Boards**: one canvas on screen at a time. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed.
 - **Devices view**: the Devices menu (or hotkeys `1`-`5`) sizes every frame to mobile / tablet / laptop / monitor / tv to sweep your breakpoints; `0` restores your own layout exactly. Widths live in `design/config.ts`.
 - `data-goto="scene/frame"` on any element links frames into a walkable prototype.
+- **Upgrade**: `npm i -D @marver-design/marver@latest && npx marver init`. The canvas tells you when a new version is out (one anonymous registry check per day, cached in `design/.local/`; `MARVER_NO_UPDATE_CHECK=1` disables). Re-running init refreshes the managed files (AGENTS.md, `design/instructions/`) - your edits to them are detected and preserved; when both you and a release changed a file, the fresh version is staged at `design/.local/latest/` for you (or your agent) to merge. Everything else in `design/` is yours and never touched.
 - Uninstall: delete `design/`, remove the dependency. (If `init` patched your tsconfig `exclude`, revert that one line.)
 
 **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.

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

@@ -1,6 +1,6 @@
 import { r as ROUTE, t as NAME } from "./cli.mjs";
-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 { a as loadConfig, n as scanFrames, o as detectHost } from "./manifest-mYlO_1Pj.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-YVpBNTB3.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/cli.mjs

@@ -32,14 +32,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-CHUZTYG7.mjs");
+	const { init } = await import("./init-ClhCgn4v.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-Dt9D4O7Z.mjs");
+	const { dev } = await import("./dev-9-80L5i5.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -49,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-BYZDMiIS.mjs");
+	const { buildSite } = await import("./build-Bqd6OEsQ.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards);

package/dist/{dev-Dt9D4O7Z.mjs → dev-9-80L5i5.mjs}

@@ -1,6 +1,6 @@
 import { n as PKG, t as NAME } from "./cli.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 { a as loadConfig, o as detectHost } from "./manifest-mYlO_1Pj.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-YVpBNTB3.mjs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";

package/dist/init-ClhCgn4v.mjs

@@ -0,0 +1,358 @@
+import { t as NAME } from "./cli.mjs";
+import { i as DEFAULTS, n as scanFrames, o as detectHost, r as writeManifest, s as readJson } from "./manifest-mYlO_1Pj.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);
+	const design = join(root, "design");
+	const templates = join(pkgDir(), "templates");
+	const created = [];
+	const fileHas = (rel, needle) => {
+		try {
+			return readFileSync(join(design, rel), "utf8").includes(needle);
+		} catch {
+			return false;
+		}
+	};
+	const marverShaped = fileHas("config.ts", "marver") || fileHas("AGENTS.md", "agent contract");
+	if (existsSync(design) && !marverShaped && readdirSync(design).some((f) => !f.startsWith("."))) {
+		console.error(`
+[${NAME}] design/ already exists in this repo and does not look like a ${NAME} workspace.
+         Refusing to merge into it - your files and ${NAME}'s would interleave, and
+         "uninstall = delete design/" would stop being safe.
+
+         Move or rename the existing design/ folder, then re-run \`npx ${NAME} init\`.
+         (If you need marver to live in a differently-named folder, say so at
+         github.com/TNEP4/marver - a --dir flag is planned.)`);
+		process.exit(1);
+	}
+	const write = (rel, content) => {
+		const file = join(design, rel);
+		if (existsSync(file)) return;
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, content);
+		created.push(`design/${rel}`);
+	};
+	const writeManaged = (rel, body) => {
+		const file = join(design, rel);
+		const next = managedFile(body);
+		const latest = join(design, ".local", "latest", rel);
+		if (!existsSync(file)) return write(rel, next);
+		const current = readFileSync(file, "utf8");
+		if (current === next) {
+			rmSync(latest, { force: true });
+			return;
+		}
+		if (current.startsWith(MANAGED_PREFIX)) {
+			const recorded = current.slice(MANAGED_PREFIX.length).split(" ")[0];
+			const nl = current.indexOf("\n");
+			const currentBody = nl >= 0 ? current.slice(nl + 1) : "";
+			if (nl >= 0 && hashBody(currentBody) === recorded) {
+				writeFileSync(file, next);
+				rmSync(latest, { force: true });
+				created.push(`design/${rel} (updated)`);
+			} else if (recorded !== hashBody(body)) {
+				mkdirSync(dirname(latest), { recursive: true });
+				writeFileSync(latest, body);
+				if (nl >= 0) {
+					const tmp = file + ".tmp";
+					writeFileSync(tmp, managedFile(body).split("\n")[0] + "\n" + currentBody);
+					renameSync(tmp, file);
+				}
+				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)) {
+			writeFileSync(file, next);
+			rmSync(latest, { force: true });
+			created.push(`design/${rel} (updated)`);
+		} else if (current !== body) {
+			rmSync(latest, { force: true });
+			console.warn(`  note: design/${rel} exists without a marver marker - left untouched. If you did not author it, delete it and re-run init to restore the managed version.`);
+		}
+	};
+	write("config.ts", configTemplate(opts.mode));
+	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 - 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));
+	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).`);
+	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"));
+	const setupPath = join(design, "instructions", "setup.md");
+	const ourSetup = () => {
+		try {
+			const s = readFileSync(setupPath, "utf8");
+			return s.startsWith("# Setup required") && s.includes("marver init");
+		} catch {
+			return false;
+		}
+	};
+	if (noApp(host)) {
+		if (!existsSync(setupPath)) write("instructions/setup.md", SETUP_MD);
+	} else if (existsSync(setupPath) && ourSetup()) {
+		rmSync(setupPath);
+		console.log(`  - design/instructions/setup.md removed (app detected - setup complete)`);
+	}
+	write("tsconfig.json", existsSync(join(root, "tsconfig.json")) ? readFileSync(join(templates, "design-tsconfig.json"), "utf8").replace("{{PATHS}}", designPaths(root)) : STANDALONE_TSCONFIG);
+	write(".gitignore", ".local/\n.dist/\n");
+	write("scenes/_layout.tsx", readFileSync(join(templates, "root-layout.tsx"), "utf8"));
+	if (!existsSync(join(design, "boards"))) {
+		mkdirSync(join(design, "boards"), { recursive: true });
+		writeFileSync(join(design, "boards", ".gitkeep"), "");
+		created.push("design/boards/");
+	}
+	if (opts.demo && !existsSync(join(design, "scenes", "demo"))) {
+		cpSync(join(templates, "demo"), join(design, "scenes", "demo"), { recursive: true });
+		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 - 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 ─────────────────────────────────────────────────────┐
+  │ No framework, no theme CSS, no component library. ${NAME} builds      │
+  │ frames from YOUR components - with none, designs get thrown away.     │
+  │                                                                       │
+  │ Setup instructions: design/instructions/setup.md. Set up the app,     │
+  │ re-run init, and that file removes itself. AGENTS.md carries a STOP   │
+  │ so your agent does not design against components that do 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" : ""}`);
+	if (!noApp(host) && !existsSync(join(design, "DESIGN.md"))) console.log(`\n  note: design/DESIGN.md (the brand doc) does not exist yet - have your agent create it from the app's tokens (instructions/brand.md, Path A) to reach the idle state.`);
+	console.log(`\n  next: npx ${NAME} dev   (canvas on http://localhost:${DEFAULTS.port} by default)\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 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) {
+	const hostPaths = readJson(join(root, "tsconfig.json"))?.compilerOptions?.paths;
+	if (!hostPaths || typeof hostPaths !== "object") return "";
+	const rerooted = {};
+	for (const [alias, targets] of Object.entries(hostPaths)) {
+		if (!Array.isArray(targets)) continue;
+		rerooted[alias] = targets.map((t) => typeof t === "string" ? t.startsWith("./") ? `../${t.slice(2)}` : `../${t}` : t);
+	}
+	if (!Object.keys(rerooted).length) return "";
+	return `,\n    // the host's aliases, re-rooted (inherited paths resolve against the WRONG dir)\n    "paths": ${JSON.stringify(rerooted)}`;
+}
+/** 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).
+*  The STOP branch fires only on the same condition that creates SETUP.md - an app
+*  without Tailwind (plain React + CSS) gets guidance, never a dead pointer. */
+function uiGuidance(host, isNoApp) {
+	if (isNoApp) return `STOP - this repo has no app yet. Read design/instructions/setup.md before designing anything.`;
+	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 `Use the app's existing components and stylesheets (import them directly); there is no Tailwind or component library detected - extract shared pieces into design/components/.`;
+}
+const SETUP_MD = `# Setup required - this repo has no app yet
+
+> This file exists because \`${NAME} init\` ran in a repo with no framework, no theme
+> CSS, and no component library. It disappears automatically: set up the app, re-run
+> \`npx ${NAME} init\`, and init deletes this file and regenerates AGENTS.md against
+> the real stack. While this file exists, DO NOT design.
+
+${NAME} builds frames from YOUR components and YOUR theme. With none, frames become
+hand-rolled CSS that shares nothing with the future app and cannot be promoted into
+it later - work that gets thrown away.
+
+## Do this first
+
+For a web app or marketing site, the blessed stack. NOTE: create-next-app refuses a
+non-empty directory (this repo already holds design/ and a package.json), so
+scaffold into a temp dir and merge:
+
+\`\`\`bash
+npx create-next-app@latest app-scaffold --ts --tailwind --app --src-dir --yes
+# move everything from app-scaffold/ up to the repo root EXCEPT its package.json;
+# merge app-scaffold/package.json's dependencies+scripts into the existing one,
+# then: rm -rf app-scaffold && npm install
+npx shadcn@latest init
+\`\`\`
+
+shadcn's flags change between versions - if a flag errors or it prompts despite
+--yes, answer the prompts with its defaults. Any React + CSS setup works; the
+point is that components and a theme EXIST.
+
+## Then
+
+\`\`\`bash
+npx ${NAME} init
+\`\`\`
+
+init is idempotent: it fills in what it now detects (theme wrapper, providers, a
+shadcn-aware AGENTS.md), deletes this file, and you design from real parts.
+`;
+/** 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;
+	const raw = readFileSync(file, "utf8");
+	try {
+		let next;
+		if (/"exclude"\s*:/.test(raw)) next = raw.replace(/("exclude"\s*:\s*\[)/, "$1\"design\", ");
+		else {
+			const at = firstJsonBrace(raw);
+			if (at < 0) throw new Error("no object brace found");
+			next = raw.slice(0, at + 1) + "\n  \"exclude\": [\"design\"]," + raw.slice(at + 1);
+		}
+		if (next === raw) throw new Error("no anchor matched");
+		writeFileSync(file, next);
+		console.log(`\n  patched tsconfig.json (the only host file touched):`);
+		console.log(`    + "design" added to "exclude"  (revert this line to fully uninstall)`);
+	} catch {
+		console.warn(`  could not patch tsconfig.json - add "design" to its "exclude" yourself.`);
+	}
+}
+/** Index of the first `{` outside //, /* *\/ comments and strings (tsconfig is JSONC). */
+function firstJsonBrace(src) {
+	let inLine = false, inBlock = false, inStr = false;
+	for (let i = 0; i < src.length; i++) {
+		const c = src[i], n = src[i + 1];
+		if (inLine) {
+			if (c === "\n") inLine = false;
+			continue;
+		}
+		if (inBlock) {
+			if (c === "*" && n === "/") {
+				inBlock = false;
+				i++;
+			}
+			continue;
+		}
+		if (inStr) {
+			if (c === "\\") i++;
+			else if (c === "\"") inStr = false;
+			continue;
+		}
+		if (c === "/" && n === "/") {
+			inLine = true;
+			i++;
+			continue;
+		}
+		if (c === "/" && n === "*") {
+			inBlock = true;
+			i++;
+			continue;
+		}
+		if (c === "\"") {
+			inStr = true;
+			continue;
+		}
+		if (c === "{") return i;
+	}
+	return -1;
+}
+const configTemplate = (mode) => `// ${NAME} config - OPTIONAL. Delete this file and everything still works on defaults.
+// Theme lives in design/theme.css (it imports your app's real stylesheet) - not here.
+// Sharp edges (native Node TS import): erasable syntax only (no enums/namespaces),
+// relative imports need extensions, tsconfig paths are ignored here.
+export default {
+  mode: ${JSON.stringify(mode)},
+  // Device widths for frames and the Devices view. Rename, retune, or uncomment tv.
+  viewports: {
+    mobile: { width: 390, height: 844 },
+    tablet: { width: 768, height: 1024 },
+    laptop: { width: 1280, height: 800 },
+    monitor: { width: 1920, height: 1080 },
+    // tv: { width: 3840, height: 2160 },
+  },
+  themes: ["light", "dark"],
+  port: ${DEFAULTS.port},
+  // Canvas zoom feel: 1 = default, 1.2 = 20% faster, 0.8 = 20% slower.
+  // zoomSpeed: 1,
+  // Publishing (\`${NAME} build\` + \`${NAME} serve\`): gate identity + branding footer.
+  // name/logo default to the host package.json name and design/logo.svg (then public/).
+  // branding is the small "Powered by Marver.design" line under the gate. Marver is
+  // free, and that line is how it spreads - we'd love it if you leave it on, but it
+  // is yours to remove, no strings: share: { branding: false }.
+  // share: { name: "My App", logo: "design/logo.svg", branding: true },
+}
+`;
+const themeWrapper = (relCss, v4) => `/* ${NAME} theme wrapper - imports the app's real theme; the app's own build never sees design/. */
+@import "${relCss}";
+${v4 ? `@source "./";\n` : ""}`;
+function providersTemplate(router, toaster, routerPkg = "react-router-dom") {
+	const imports = [`import type { ReactNode } from 'react'`];
+	let open = "", close = "";
+	if (router === "react-router") {
+		imports.push(`import { MemoryRouter } from '${routerPkg}'`);
+		open += "<MemoryRouter>";
+		close = "</MemoryRouter>" + close;
+	}
+	let toasterEl = "";
+	if (toaster === "sonner") {
+		imports.push(`import { Toaster } from 'sonner'`);
+		toasterEl = "<Toaster />";
+	}
+	if (toaster === "react-hot-toast") {
+		imports.push(`import { Toaster } from 'react-hot-toast'`);
+		toasterEl = "<Toaster />";
+	}
+	return `// Mock contexts wrapped around every frame. Scaffolded by ${NAME} init from what it detected - yours to edit.
+${imports.join("\n")}
+
+export default function Providers({ children }: { children: ReactNode }) {
+  return (
+    ${open || "<>"}
+      {children}
+      ${toasterEl}
+    ${close || "</>"}
+  )
+}
+`;
+}
+//#endregion
+export { init };

package/dist/{manifest-CHmKAAtG.mjs → manifest-mYlO_1Pj.mjs}

@@ -204,7 +204,7 @@ function extractMeta(src) {
 	if (!m) return {};
 	const body = m[1];
 	const pick = (key) => {
-		const r = new RegExp(`${key}\\s*:\\s*(['"\`])([^'"\`]*)\\1`).exec(body);
+		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(['"\`])([^'"\`]*)\\1`).exec(body);
 		return r ? r[2] : void 0;
 	};
 	const out = {};
@@ -214,6 +214,10 @@ function extractMeta(src) {
 	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;
 	return out;
 }
 /** id = path relative to design/, extension dropped, `scenes/` prefix dropped. Always `/`-separated. */
@@ -256,6 +260,8 @@ function scanFrames(root) {
 			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;
 		}
 		frames.push(entry);
 	}
@@ -273,6 +279,7 @@ function scanFrames(root) {
 	});
 	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 {
@@ -283,6 +290,75 @@ function scanFrames(root) {
 		})).sort((a, b) => a.name.localeCompare(b.name))
 	};
 }
+/** Variant groups (SPEC-023 §1). 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");
@@ -295,4 +371,4 @@ function writeManifest(root, manifest) {
 }
 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 };
+export { loadConfig as a, DEFAULTS as i, scanFrames as n, detectHost as o, writeManifest as r, readJson as s, hash as t };

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

@@ -1,7 +1,8 @@
-import { r as ROUTE } from "./cli.mjs";
-import { n as scanFrames, r as writeManifest, t as hash } from "./manifest-CHmKAAtG.mjs";
+import { n as PKG, r as ROUTE, t as NAME } from "./cli.mjs";
+import { n as scanFrames, r as writeManifest, t as hash } from "./manifest-mYlO_1Pj.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 //#region src/server/api.ts
 const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
@@ -185,6 +186,73 @@ function routesMiddleware(server, clientDir) {
 	};
 }
 //#endregion
+//#region src/server/update.ts
+/**
+* Update discovery - dev only, and deliberately boring about privacy: one anonymous
+* registry metadata GET per day (the same request `npm view` makes), cached in
+* design/.local/, nothing sent beyond the request itself. Offline, slow, or
+* firewalled registries degrade to silence. MARVER_NO_UPDATE_CHECK=1 disables it.
+* Published bundles never check anything - viewers are not the owner.
+*/
+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). */
+function installedVersion() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 4; i++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+			if (pkg.name === "@marver-design/marver") return pkg.version;
+		} catch {}
+		dir = dirname(dir);
+	}
+	return null;
+}
+/** Strictly-newer numeric compare; anything non-numeric (prerelease tags) compares false. */
+const newer = (a, b) => {
+	const pa = a.split(".").map((n) => parseInt(n, 10));
+	const pb = b.split(".").map((n) => parseInt(n, 10));
+	for (let i = 0; i < 3; i++) {
+		const x = pa[i] ?? 0, y = pb[i] ?? 0;
+		if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+		if (x !== y) return x > y;
+	}
+	return false;
+};
+/** The latest published version when strictly newer than installed, else null. Never throws. */
+async function checkUpdate(root) {
+	if (process.env.MARVER_NO_UPDATE_CHECK) return null;
+	const current = installedVersion();
+	if (!current) return null;
+	const latest = await latestVersion(root);
+	return latest && newer(latest, current) ? latest : null;
+}
+async function latestVersion(root) {
+	const cacheFile = join(root, "design", ".local", "update-check.json");
+	const wellFormed = (v) => typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v);
+	try {
+		const c = JSON.parse(readFileSync(cacheFile, "utf8"));
+		const age = Date.now() - c.checkedAt;
+		if (typeof c.checkedAt === "number" && age >= 0 && age < TTL) return wellFormed(c.latest) ? c.latest : null;
+	} catch {}
+	let latest = null;
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PKG)}/latest`, { signal: AbortSignal.timeout(3e3) });
+		if (res.ok) {
+			const v = (await res.json())?.version;
+			if (wellFormed(v)) latest = v;
+		}
+	} catch {}
+	try {
+		mkdirSync(join(root, "design", ".local"), { recursive: true });
+		writeFileSync(cacheFile, JSON.stringify({
+			checkedAt: Date.now(),
+			latest
+		}) + "\n");
+	} catch {}
+	return latest;
+}
+//#endregion
 //#region src/server/plugin.ts
 const VIRTUAL_THEME = "virtual:sh-theme";
 const VIRTUAL_CONFIG = "virtual:sh-config";
@@ -211,12 +279,23 @@ function marverPlugin(ctx) {
 				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({
-				viewports: config.viewports,
-				themes: config.themes,
-				zoomSpeed: config.zoomSpeed,
-				noTheme: themeFile() == null
-			})}`;
+			if (id === "\0virtual:sh-config") {
+				const setupPending = (() => {
+					try {
+						const s = readFileSync(join(root, "design", "instructions", "setup.md"), "utf8");
+						return s.startsWith("# Setup required") && s.includes("marver init");
+					} catch {
+						return false;
+					}
+				})();
+				return `export default ${JSON.stringify({
+					viewports: config.viewports,
+					themes: config.themes,
+					zoomSpeed: config.zoomSpeed,
+					noTheme: themeFile() == null,
+					setup: setupPending
+				})}`;
+			}
 			if (id === "\0virtual:sh-data") return "export default null";
 		},
 		/** HTML frames: inject theme + bridge into any design/**.html Vite serves.
@@ -263,6 +342,21 @@ function marverPlugin(ctx) {
 				}
 				next();
 			});
+			const update = checkUpdate(root).catch(() => null);
+			update.then((latest) => {
+				if (latest) console.log(`\n  update: ${PKG} ${latest} is out (installed ${installedVersion() ?? "?"}) → npm i -D ${PKG}@latest && npx ${NAME} init\n`);
+			});
+			server.middlewares.use((req, res, next) => {
+				if (new URL(req.url ?? "/", "http://x").pathname !== `/__mv/api/update`) return next();
+				update.then((latest) => {
+					res.setHeader("content-type", "application/json");
+					res.setHeader("cache-control", "no-store");
+					res.end(JSON.stringify({
+						latest,
+						current: installedVersion()
+					}));
+				});
+			});
 			server.middlewares.use(apiMiddleware(root));
 			server.middlewares.use(routesMiddleware(server, clientDir));
 			const regen = debounce(() => {