@marver-design/marver 0.2.2 → 0.2.4

package/dist/{build-CNoXE13J.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-DiDJA9n-.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-3h9pXEzp.mjs");
+	const { init } = await import("./init-Di4geblA.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-Blyy4jOL.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-CNoXE13J.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-Blyy4jOL.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-DiDJA9n-.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-3h9pXEzp.mjs → init-Di4geblA.mjs}

@@ -1,5 +1,5 @@
 import { t as NAME } from "./cli.mjs";
-import { i as DEFAULTS, n as scanFrames, o as detectHost, r as writeManifest } from "./manifest-CHmKAAtG.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";
@@ -98,21 +98,40 @@ function init(root, opts) {
 		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;
+	const setupState = () => {
+		if (!existsSync(setupPath)) return "absent";
+		const s = readFileSync(setupPath, "utf8");
+		if (s.startsWith(MANAGED_PREFIX)) {
+			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";
 		}
+		return s.startsWith("# Setup required") && s.includes("marver init") ? "ours-pristine" : "foreign";
 	};
+	const setupWas = setupState();
+	const appJustAppeared = !noApp(host) && (setupWas === "ours-pristine" || setupWas === "ours-edited");
 	if (noApp(host)) {
-		if (!existsSync(setupPath)) write("instructions/setup.md", SETUP_MD);
-	} else if (existsSync(setupPath) && ourSetup()) {
+		if (setupWas === "ours-pristine" && !readFileSync(setupPath, "utf8").startsWith(MANAGED_PREFIX)) rmSync(setupPath);
+		if (setupWas !== "foreign") writeManaged("instructions/setup.md", SETUP_MD);
+	} else if (setupWas === "ours-pristine") {
 		rmSync(setupPath);
 		console.log(`  - design/instructions/setup.md removed (app detected - setup complete)`);
+	} else if (setupWas === "ours-edited") console.log(`  - design/instructions/setup.md: app detected, but you customized the file - delete it yourself when setup is done`);
+	const rootTsconfig = existsSync(join(root, "tsconfig.json"));
+	const tsconfigNow = () => rootTsconfig ? readFileSync(join(templates, "design-tsconfig.json"), "utf8").replace("{{PATHS}}", designPaths(root)) : STANDALONE_TSCONFIG;
+	write("tsconfig.json", tsconfigNow());
+	if (appJustAppeared) {
+		const refresh = (rel, noAppPristine, next) => {
+			try {
+				if (!noAppPristine.includes(next) && noAppPristine.includes(readFileSync(join(design, rel), "utf8"))) {
+					writeFileSync(join(design, rel), next);
+					created.push(`design/${rel} (updated for the detected app)`);
+				}
+			} catch {}
+		};
+		refresh("providers.tsx", [providersTemplate(null, null), providersTemplate(null, host.toaster, host.routerPkg)], providersTemplate(host.router, host.toaster, host.routerPkg));
+		refresh("tsconfig.json", [STANDALONE_TSCONFIG], tsconfigNow());
 	}
-	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"))) {
@@ -134,14 +153,16 @@ function init(root, opts) {
   │ 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.   │
+  │ Setup instructions: design/instructions/setup.md. Your agent will     │
+  │ ask what you are building, propose a stack, set it up with you, and   │
+  │ re-run init - that file then removes itself. AGENTS.md points there   │
+  │ so nothing gets designed 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`);
+	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";
@@ -150,13 +171,26 @@ const hashBody = (s) => createHash("sha256").update(s).digest("hex");
 *  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 (isNoApp) return `Setup required - this repo has no app yet: read design/instructions/setup.md and follow it 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/.`;
@@ -169,28 +203,141 @@ const SETUP_MD = `# Setup required - this repo has no app yet
 > 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.
+hand-rolled CSS that shares nothing with the future app - throwaway work. So the
+first session sets up the stack - TOGETHER with the human. The stack is their
+decision; your job is a good recommendation and a smooth setup. Narrate every step
+in one plain line as you go - and tell the story, not the machinery: this file is
+stage directions, never read it aloud to the human ("setup.md says...", "step 2
+requires..."). Voice rules and the structured-question guidance live in
+instructions/welcome.md - read that section before you say anything.
+
+## 1. Greet and explain
+
+Tell the human the repo is empty and that this is a perfect starting point. Then
+the pitch, ~4 sentences in your own words (source: instructions/welcome.md): we design
+in real code; the theme, components, and screens made while designing ARE the
+app's building blocks; by the time the design is agreed most of the UI work
+exists, and building the product means plugging functionality in; the goal is
+alignment on look and feel across themes and devices first.
+
+## 2. Ask what they are building - STOP
+
+Two questions, one message (use the harness's structured question tool if it
+has one):
+
+1. "In a sentence or two - what are we building?"
+2. "Any intuition for the look? Colors, mood, UI style - a sentence like
+   'minimalist, glass UI, witty copy' steers everything. 'Surprise me' is a
+   fine answer."
+
+Then STOP: no further tool calls, end your turn, resume only after the human
+replies. (The one exception: the human explicitly asked for unattended
+execution - then assume something reasonable, mark it UNCONFIRMED, surface it
+first.)
 
-## Do this first
+## 3. Propose the stack - STOP
 
-For a web app or marketing site, the blessed stack:
+From their answer, recommend a framework with one line of reasoning each:
+
+- Marketing site, content, SEO -> latest Next.js.
+- App-like, interactive, client-heavy -> latest React Router.
+- Their answer points somewhere else? Recommend that instead, and say why.
+
+If you can search the web, verify current major versions first - one or two
+searches, then propose. Recommend shadcn/ui + latest Tailwind as the default
+component layer (take their current defaults) - but they are a recommendation,
+not a requirement: if the human prefers another component library, plain CSS,
+or their own design system, that wins. Any React + a real stylesheet works;
+${NAME} adapts to what detection finds. Present the proposal with the
+harness's structured question tool when it has one - short labels, one-line
+trade-offs - closing with "aligned, or tell me what you'd rather use". Then
+STOP again: no further tool calls, end your turn, wait for the nod.
+
+## 4. Hand them the tour, then scaffold
+
+The setup and first draft take real minutes; the human should spend them
+learning the canvas, not watching a terminal. The moment the stack is agreed,
+send them to the ${NAME} tour - a published canvas we host, built to be
+explored: https://tour.marver.design - password \`welcome\`. Tell them it teaches
+selection, devices, themes, variants, and play mode from inside the canvas,
+and that it ends by sending them back to check on you. (Unreachable from this
+machine? Say so and skip it - never stall on it.) Then get to work.
+
+NOTE: scaffolders refuse non-empty directories (this repo already holds design/
+and a package.json - the one you likely created with \`npm init -y\` to install
+${NAME} into), so scaffold into a temp dir and merge. The Next.js lane - adapt
+the same shape to whatever stack was agreed:
 
 \`\`\`bash
-npx create-next-app@latest . --ts --tailwind --app --src-dir
+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
 \`\`\`
 
-Any React + CSS setup works; the point is that components and a theme EXIST.
+Scaffolder flags drift between versions (create-next-app and shadcn both) - if
+a flag errors or a prompt appears despite --yes, accept the tool's defaults.
+
+Known scaffold bug if shadcn was agreed (hit on every create-next-app + shadcn
+run so far): shadcn's
+init rewrites the theme CSS's \`@theme inline\` block and leaves
+\`--font-sans: var(--font-sans)\` - self-referential, resolves to nothing, and
+the app silently renders in the browser's default font. After shadcn init,
+open the theme CSS and bind every font token to a variable that actually
+exists (e.g. \`--font-sans: var(--font-geist-sans)\` under Next); check
+--font-heading and friends for the same circularity.
 
-## Then
+Then START the dev server and
+confirm the starter page renders before moving on. Unsure about the stack's
+conventions? Fetch its docs.
+
+## 5. Re-run init
 
 \`\`\`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.
+init is idempotent: it detects the real stack, deletes this file, and
+regenerates AGENTS.md against reality. Verify the wiring (instructions/
+configure.md): frames render styled, one app component imports cleanly.
+DESIGN.md comes next, as part of the first draft.
+
+
+## 6. The first draft - make it impressive, then tour
+
+This is the human's first impression of the canvas AND the first draft of their
+product - it sets the direction. Take the time to do it well:
+
+- If you can search the web, spend a few minutes understanding the domain from
+  step 2's answer; write design/DESIGN.md. The human's look intuition from
+  step 2 is the north star - honor it literally. If they said "surprise me",
+  commit to a direction and name it in one sentence at the reveal.
+- Build ~4 frames of THEIR product - not lorem, not filler. Hold them to the
+  craft bar: instructions/craft.md and instructions/reference/slop.md are
+  binding here. Responsive, working in BOTH themes, linked with data-goto so
+  play mode flows.
+- UNDERWHELMING IS THE FAILURE MODE. A restrained concept executed thinly
+  reads as a wireframe, however careful the type. Every frame needs presence -
+  scale, contrast, color, one real visual moment - and the human should feel
+  the direction before they read a word. Write the copy like it ships:
+  specific, confident, witty where the brand allows, never placeholder. This
+  first draft is the product's first impression AND ${NAME}'s - go above and
+  beyond.
+- Delete the generic demo scene (design/scenes/demo/) once your frames are in -
+  it exists to show YOU the file shapes, not to impress anyone.
+- Create a curated board for them (instructions/boards.md) containing every
+  frame the flow visits.
+- Offer a divergence: "want a variant of <frame> exploring a different
+  direction?" - one a-/b- pair teaches the variant workflow better than any
+  explanation.
+
+This first draft skips the written-brief ceremony (the human just told you what
+they are building) but never the quality bar. Then THE REVEAL: start
+\`npx ${NAME} dev\` and give the guided tour from instructions/welcome.md -
+by now the human has played with the hosted tour, so keep it short and let
+their own product carry it. End with the deep link using the PRINTED port -
+\`http://localhost:<port>/#/b/<board>\`, never the bare root URL.
 `;
 /** 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):

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-DiDJA9n-.mjs → plugin-YVpBNTB3.mjs}

@@ -1,5 +1,5 @@
 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-CHmKAAtG.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 { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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,

package/src/client/shell/App.tsx

@@ -6,19 +6,20 @@ import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { enterPlay, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
-import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, XIcon, deviceIcon } from './icons.tsx'
+import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
 
 let booted = false                             // survives Fast Refresh; see the boot effect
 
 /** One collapsible scene group in the sidebar. `held` marks a scene that contains a
  *  selected frame - a quiet secondary wash so ancestry survives collapsing the group. */
-function SceneGroup({ name, count, held, children }: { name: string; count: number; held: boolean; children: ReactNode }) {
+function SceneGroup({ name, count, held, onPick, children }: { name: string; count: number; held: boolean; onPick?: () => void; children: ReactNode }) {
   const [open, setOpen] = useState(true)
   return (
     <div>
       <button className={`it${held ? ' held' : ''}`} onClick={() => setOpen(!open)}>
         <CaretIcon size={11} className="tw" style={{ transform: open ? undefined : 'rotate(-90deg)' }} />
-        <span>{cap(name) || '(root)'}</span>
+        {/* the NAME selects every frame in the scene; the caret/row still collapses */}
+        <span onClick={(e) => { if (!onPick) return; e.stopPropagation(); onPick() }}>{cap(name) || '(root)'}</span>
         <small>{count}</small>
       </button>
       {open && children}
@@ -151,7 +152,15 @@ function SelectionBar() {
   // 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)`
+  // a grouped frame carries a caption above it - clear it EXACTLY, in screen terms:
+  // frame top - the caption offset (8px screen, world-capped) - the caption's height
+  // (screen-clamped 12..18px font) - the bar. Gate on the TOP edge of the selection,
+  // not the last-selected frame: a mixed selection whose topmost frames are variants
+  // still has a caption to clear (codex final review P2).
+  const capAtTop = selNodes.some((n) => n.y === by0 && useStore.getState().frameFor(n)?.variantGroup)
+  const rawTop = capAtTop
+    ? `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - clamp(4px * var(--sh-s, 1), 8px, 40px * var(--sh-s, 1)) - (clamp(12px, 17px * var(--sh-s, 1), 18px) * 1.4) - 44px)`
+    : `calc(var(--sh-ty, 0px) + var(--sh-s, 1) * ${by0}px - 52px)`
   return (
     <div
       className="sh-ctx"
@@ -633,18 +642,71 @@ export function App() {
             <div className="hd" style={{ marginTop: 10 }}>Scenes</div>
             {scenes.map((sc) => (
               <SceneGroup key={sc.name} name={sc.name} count={sc.frames}
-                held={frames.some((f) => f.scene === sc.name && selFrames.has(f.id))}>
-                {frames.filter((f) => f.scene === sc.name).map((f) => {
-                  const n = nodes.find((x) => x.frame === f.id && !x.missing) ?? nodes.find((x) => x.frame === f.id)
-                  const on = !!n && selection.includes(n.key)
-                  return (
-                    <div key={f.id} className={`sub${on ? ' on' : ''}`} onClick={(e) => {
-                      if (!n) return
-                      select(n.key, e.shiftKey)
-                      if (!e.shiftKey) canvasCtl.fitNode(n.key)
-                    }}>{cap(f.id.split('/').slice(1).join('/') || f.id)}</div>
-                  )
-                })}
+                held={frames.some((f) => f.scene === sc.name && selFrames.has(f.id))}
+                onPick={() => {
+                  const keys = nodes.filter((n) => frames.some((f) => f.scene === sc.name && f.id === n.frame) && !n.missing).map((n) => n.key)
+                  if (!keys.length) return
+                  useStore.getState().selectMany(keys)
+                  canvasCtl.fitNodes(keys)
+                }}>
+                {(() => {
+                  // variant groups render as ONE surface row with A/B/C chips (SPEC-023 §5)
+                  const sceneFrames = frames.filter((f) => f.scene === sc.name)
+                  const nodeFor = (id: string) => nodes.find((x) => x.frame === id && !x.missing) ?? nodes.find((x) => x.frame === id)
+                  const go = (id: string, shift: boolean) => {
+                    const n = nodeFor(id)
+                    if (!n) return
+                    select(n.key, shift)
+                    if (!shift) canvasCtl.fitNode(n.key)
+                  }
+                  const seen = new Set<string>()
+                  const rows: ReactNode[] = []
+                  for (const f of sceneFrames) {
+                    if (f.variantGroup && !seen.has(f.variantGroup)) {
+                      seen.add(f.variantGroup)
+                      const members = sceneFrames.filter((m) => m.variantGroup === f.variantGroup)
+                        .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''))
+                      if (members.length > 1) {
+                        const rel = f.variantGroup === sc.name ? 'Variants'
+                          : cap(f.variantGroup.slice(sc.name.length + 1).replace(/-/g, ' '))
+                        const memberKeys = members.map((m) => nodeFor(m.id)?.key).filter((k): k is string => !!k)
+                        const allOn = memberKeys.length > 0 && memberKeys.every((k) => selection.includes(k))
+                        // held = SOME member active (same quiet wash as scene headers) - the
+                        // group participates without claiming full selection
+                        const held = !allOn && memberKeys.some((k) => selection.includes(k) || useStore.getState().interact === k)
+                        // group header: click selects EVERY variant (the quick compare-and-test grab)
+                        rows.push(
+                          <div key={`g:${f.variantGroup}`} className={`sub vgroup${allOn ? ' on' : ''}${held ? ' held' : ''}`}
+                            title="Select all variants"
+                            onClick={() => { useStore.getState().selectMany(memberKeys); canvasCtl.fitNodes(memberKeys) }}>
+                            <span className="glabel">{rel}</span>
+                            <VariantsIcon size={14} className="gicon" />
+                          </div>,
+                        )
+                        // one row per variant: [letter chip] + name, individually selectable
+                        for (const m of members) {
+                          const n = nodeFor(m.id)
+                          const on = !!n && selection.includes(n.key)
+                          const nm = m.title ?? cap((m.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' '))
+                          rows.push(
+                            <div key={m.id} className={`sub vrow${on ? ' on' : ''}`} onClick={(e) => go(m.id, e.shiftKey)}>
+                              <span className={`chip${on ? ' on' : ''}`}>{(m.variant ?? '?').toUpperCase()}</span><span className="nm">{nm}</span>
+                            </div>,
+                          )
+                        }
+                        continue
+                      }
+                    } else if (f.variantGroup) continue
+                    const n = nodeFor(f.id)
+                    const on = !!n && selection.includes(n.key)
+                    rows.push(
+                      <div key={f.id} className={`sub${on ? ' on' : ''}`} onClick={(e) => go(f.id, e.shiftKey)}>
+                        {cap(f.id.split('/').slice(1).join('/') || f.id)}
+                      </div>,
+                    )
+                  }
+                  return rows
+                })()}
               </SceneGroup>
             ))}
             {frames.length === 0 && <div className="sub dim">no frames yet - ask your agent<br />(design/AGENTS.md)</div>}

package/src/client/shell/Play.tsx

@@ -174,6 +174,28 @@ function PlayInner() {
   }
   const restart = () => { const list = playList(); if (list.length) goTo(list[0]) }
 
+  /** Variant siblings of the CURRENT frame present on this board (SPEC-023 §6): the
+   *  review question is "which direction is better on THIS screen" - switch in place,
+   *  device and theme preserved, each variant's own data-goto links drive after. */
+  const variantList = () => {
+    const s = useStore.getState()
+    const cur = s.manifest?.frames.find((f) => f.id === s.play?.at)
+    if (!cur?.variantGroup) return []
+    const onBoard = new Set(s.nodes.filter((n) => !n.missing).map((n) => n.frame))
+    if (!onBoard.has(cur.id)) return []              // off-board frame: no coherent control
+    return (s.manifest?.frames ?? [])
+      .filter((f) => f.variantGroup === cur.variantGroup && f.kind === 'tsx' && onBoard.has(f.id))
+      .sort((a, b) => (a.variant ?? '').localeCompare(b.variant ?? ''))
+  }
+  const switchVariant = (dir: 1 | -1) => {
+    const p = useStore.getState().play
+    if (!p) return
+    const vs = variantList()
+    if (vs.length < 2) return
+    const i = vs.findIndex((f) => f.id === p.at)
+    goTo(vs[(i + dir + vs.length) % vs.length].id)
+  }
+
   // history restores + walk: swap the stage silently (no sh:stage-at back) and track here
   useEffect(() => {
     playCtl.setAt = (at: string) => {
@@ -251,6 +273,8 @@ function PlayInner() {
     if (key === 'Escape') { exit(); return }
     if (key === 'ArrowRight') { step(1); return }
     if (key === 'ArrowLeft') { step(-1); return }
+    if (key === '[') { switchVariant(-1); return }
+    if (key === ']') { switchVariant(1); return }
     if (key === 'r') { restart(); return }
     if (key === 'h') { chromeRef.current === 'hidden' ? setChrome('open') : hideAll(); return }
     if (/^Digit[1-9]$/.test(code)) {
@@ -313,6 +337,7 @@ function PlayInner() {
   const names = Object.keys(CONFIG.viewports)
   const list = playList()
   const pos = list.indexOf(play.at)
+  const variants = variantList()
 
   // whole-pixel wrapper + per-axis scale so the iframe lands exactly on its edges -
   // fractional sizes left subpixel seams glowing at the corners on dark frames
@@ -393,6 +418,17 @@ function PlayInner() {
         <Tip inv label={<><b>Next frame</b><span className="k">→</span></>}>
           <button onClick={() => step(1)}><ArrowRightIcon size={14} /></button>
         </Tip>
+        {variants.length > 1 && <>
+          <i className="sep" />
+          <span className="vname">{(() => { const c = variants.find((v) => v.id === play.at); return c ? (c.title ?? (c.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' ')) : '' })()}</span>
+          {variants.map((v) => (
+            <Tip inv key={v.id} label={<><b>{v.title ?? v.id}</b><span className="k">[ ]</span></>}>
+              <button className={`vchip${v.id === play.at ? ' on' : ''}`} onClick={() => goTo(v.id)}>
+                {(v.variant ?? '?').toUpperCase()}
+              </button>
+            </Tip>
+          ))}
+        </>}
       </div>
     </div>
   )