@marver-design/marver 0.2.2 → 0.2.3

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-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-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-ClhCgn4v.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";
@@ -112,7 +112,7 @@ function init(root, opts) {
 		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") : STANDALONE_TSCONFIG);
+	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"))) {
@@ -140,6 +140,7 @@ function init(root, opts) {
   └───────────────────────────────────────────────────────────────────────┘`);
 	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`);
 }
@@ -150,6 +151,19 @@ 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).
@@ -174,14 +188,21 @@ it later - work that gets thrown away.
 
 ## Do this first
 
-For a web app or marketing site, the blessed stack:
+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 . --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.
+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
 

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.3",
   "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>
   )

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

@@ -90,6 +90,42 @@ export const canvasCtl = {
   zoom100() { canvasCtl.zoomTo(1) },
 }
 
+/** Variant-group captions (SPEC-023 §4): "Landing · 3 variants" above each group with
+ *  2+ members on this board. World-space (scales with the canvas); min screen size via
+ *  --sh-inv. Groups with one lone member on a curated board keep the badge, no caption. */
+function GroupCaptions() {
+  const nodes = useStore((s) => s.nodes)
+  const manifest = useStore((s) => s.manifest)
+  const selection = useStore((s) => s.selection)
+  if (!manifest) return null
+  const byId = new Map(manifest.frames.map((f) => [f.id, f]))   // O(F+N), not O(F*N) per drag
+  const groups = new Map<string, { x: number; y: number; ids: Set<string>; keys: string[] }>()
+  for (const n of nodes) {
+    if (n.missing) continue
+    const f = byId.get(n.frame)
+    if (!f?.variantGroup) continue
+    const g = groups.get(f.variantGroup)
+    if (!g) groups.set(f.variantGroup, { x: n.x, y: n.y, ids: new Set([n.frame]), keys: [n.key] })
+    else { g.x = Math.min(g.x, n.x); g.y = Math.min(g.y, n.y); g.ids.add(n.frame); g.keys.push(n.key) }
+  }
+  return (
+    <>
+      {[...groups.entries()].filter(([, g]) => g.ids.size > 1).map(([id, g]) => {
+        const allOn = g.keys.every((k) => selection.includes(k))
+        return (
+          <div key={id} className={`sh-gcaption sh-no-pan${allOn ? ' on' : ''}`}
+            style={{ transform: `translate(${g.x}px, ${g.y}px) translateY(calc(-100% - clamp(4px, 8px * var(--sh-inv, 1), 40px)))` }}
+            title="Select all variants"
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={() => { useStore.getState().selectMany(g.keys); canvasCtl.fitNodes(g.keys) }}>
+            {id.split('/').map((s) => s[0].toUpperCase() + s.slice(1)).join(' / ')} · {g.ids.size} variants
+          </div>
+        )
+      })}
+    </>
+  )
+}
+
 export function Canvas() {
   const nodes = useStore((s) => s.nodes)
   const gesture = useStore((s) => s.gesture)
@@ -119,18 +155,28 @@ export function Canvas() {
       }
       ref.current.setTransform(px - x * scale, py - y * scale, scale, 320, 'easeOut')
     }
-    canvasCtl.fitNode = (key: string) => {
-      const n = useStore.getState().nodes.find((x) => x.key === key)
-      if (n) fitRect(n.x, n.y, n.w, n.h + HEADER, true)
-    }
     const fitKeys = (keys: string[], focus: boolean) => {
+      const st = useStore.getState()
       const sel = new Set(keys)
-      const ns = useStore.getState().nodes.filter((n) => sel.has(n.key))
+      const ns = st.nodes.filter((n) => sel.has(n.key))
       if (!ns.length) return
-      const x0 = Math.min(...ns.map((n) => n.x)), y0 = Math.min(...ns.map((n) => n.y))
+      let x0 = Math.min(...ns.map((n) => n.x)), y0 = Math.min(...ns.map((n) => n.y))
       const x1 = Math.max(...ns.map((n) => n.x + n.w)), y1 = Math.max(...ns.map((n) => n.y + n.h + HEADER))
+      // grouped frames carry chrome OUTSIDE their box (badge left, caption above) -
+      // fit must include that envelope or the variant text lands under the sidebar.
+      // Screen-clamped sizes need a scale estimate first: one pre-pass, then pad.
+      if (ns.some((n) => st.frameFor(n)?.variantGroup)) {
+        const el = wrap()
+        if (el) {
+          const p = insets(el)
+          const s1 = Math.max(0.05, Math.min(1, (el.clientWidth - p.left - p.right) / (x1 - x0), (el.clientHeight - p.top - p.bottom) / (y1 - y0)))
+          x0 -= Math.max(140, 44 / s1)   // badge letter+name column (min 44 screen px)
+          y0 -= Math.max(64, 36 / s1)    // caption line above the group
+        }
+      }
       fitRect(x0, y0, x1 - x0, y1 - y0, focus)
     }
+    canvasCtl.fitNode = (key: string) => fitKeys([key], true)
     canvasCtl.fitNodes = (keys: string[]) => fitKeys(keys, true)
     canvasCtl.fitAll = () => fitKeys(useStore.getState().nodes.map((n) => n.key), false)
     canvasCtl.zoomTo = (target: number) => {
@@ -177,7 +223,7 @@ export function Canvas() {
     if (!el) return
     const down = (e: PointerEvent) => {
       const t = e.target as HTMLElement | null
-      if (t?.closest('.sh-node')) return
+      if (t?.closest('.sh-node') || t?.closest('.sh-gcaption')) return
       const s = useStore.getState()
       if (s.selection.length || s.interact) s.select(null)
     }
@@ -277,6 +323,7 @@ export function Canvas() {
     >
       <TransformComponent wrapperClass="sh-canvas" contentClass="sh-content">
         <div id="sh-world">
+          <GroupCaptions />
           {nodes.map((n) => <FrameNode key={n.key} node={n} />)}
         </div>
       </TransformComponent>

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

@@ -1,5 +1,5 @@
 import { memo, useEffect, useRef } from 'react'
-import { frameUrl, useStore, CONFIG, type Node } from '../store.ts'
+import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
 import { CopyIcon, ReloadIcon, XIcon } from '../icons.tsx'
 
 export const HEADER = 28
@@ -148,6 +148,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     )
   }
 
+  // variant badge (SPEC-023 §4): letter + name floating LEFT of the frame, outside the
+  // artwork, world-anchored (scales with zoom) with a screen-space minimum via --sh-inv
+  const variantName = frame.title
+    ?? cap((frame.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' '))
+
   return (
     <div
       className={`sh-node${selected ? ' sel' : ''}${interact ? ' interact' : ''}`}
@@ -155,6 +160,14 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
       style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER }}
       data-node={node.key}
     >
+      {frame.variantGroup && (
+        <div className="sh-vbadge sh-no-pan" title={`${frame.variantGroup} · variant ${frame.variant?.toUpperCase()} - click to select`}
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={(e) => { select(node.key, e.shiftKey) }}>
+          <b>{frame.variant?.toUpperCase()}</b>
+          <span>{variantName}</span>
+        </div>
+      )}
       <div className="sh-node-head sh-no-pan" onPointerDown={(e) => drag(e, 'move')} title={frame.file}>
         <span className="id sh-no-pan">{frame.title ?? frame.id}</span>
         <span className="dim sh-no-pan">{Math.round(node.w)} · {node.theme}</span>

package/src/client/shell/icons.tsx

@@ -44,6 +44,8 @@ export const CardsThreeIcon = icon(<path d="M208,88H48a16,16,0,0,0-16,16v96a16,1
 export const FrameCornersIcon = icon(<path d="M160 48h40a8 8 0 0 1 8 8v40M208 160v40a8 8 0 0 1-8 8h-40M96 208H56a8 8 0 0 1-8-8v-40M48 96V56a8 8 0 0 1 8-8h40" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" strokeLinejoin="round" />)
 export const ArrowLeftIcon = icon(<path d="M224,128a8,8,0,0,1-8,8H59.31l58.35,58.34a8,8,0,0,1-11.32,11.32l-72-72a8,8,0,0,1,0-11.32l72-72a8,8,0,0,1,11.32,11.32L59.31,120H216A8,8,0,0,1,224,128Z" />)
 export const ArrowRightIcon = icon(<path d="M221.66,133.66l-72,72a8,8,0,0,1-11.32-11.32L196.69,136H40a8,8,0,0,1,0-16H196.69L138.34,61.66a8,8,0,0,1,11.32-11.32l72,72A8,8,0,0,1,221.66,133.66Z" />)
+/** Variants/experimentation mark: the flask (Phosphor). */
+export const VariantsIcon = icon(<path d="M223.45,208.19,168,101.11V40h8a8,8,0,0,0,0-16H80a8,8,0,0,0,0,16h8v61.11L32.55,208.19A16,16,0,0,0,46.86,232H209.14a16,16,0,0,0,14.31-23.81ZM102.13,108.5A8,8,0,0,0,104,103.35V40h48v63.35a8,8,0,0,0,1.87,5.15L179.36,157c-11.71,2.87-26.5.66-44.16-6.64-14.08-5.82-27.34-8.53-39.66-8.16ZM46.86,216,84.36,143.6c11.68-2.9,26.47-.68,44.13,6.61,13.09,5.42,25.36,8.11,36.65,8.11a67.86,67.86,0,0,0,22.53-3.72L209.14,216Z" />)
 export const CardsIcon = icon(<path d="M184,72H40A16,16,0,0,0,24,88V200a16,16,0,0,0,16,16H184a16,16,0,0,0,16-16V88A16,16,0,0,0,184,72Zm0,128H40V88H184V200ZM232,56V176a8,8,0,0,1-16,0V56H64a8,8,0,0,1,0-16H216A16,16,0,0,1,232,56Z" />)
 /** Viewport-name -> device glyph; unknown custom names fall back to the generic Devices. */
 export function deviceIcon(name: string | null, size = 14) {