@marver-design/marver 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,113 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.6.0 - 2026-08-17
+
+Image-heavy boards, done right. A board full of high-resolution screenshots now zooms fast and stays
+crisp, images render in FULL instead of cropped, content frames size themselves to their content, and
+the switcher opens on a tight landing board instead of loading every frame at once.
+
+### Added
+
+- **Client-side image level-of-detail (LOD).** A board of 150+ high-res screenshots used to jank hard
+  on zoom - the real cost was decoded memory, not file size (a 2708x1610 PNG is ~17MB decoded, so 174 of
+  them held ~3GB of bitmaps the browser resampled every frame). Each `Img` now decodes STRAIGHT to its
+  on-screen size via `createImageBitmap` and paints on a canvas; bitmaps freeze during a pan/zoom and
+  re-pick resolution only when the gesture settles (the tldraw pattern). Result on a 174-image board:
+  ~26MB decoded at overview vs ~3GB before (~100x less), lag-free zoom, crisp detail when you stop.
+  Falls back to a plain `img` where `createImageBitmap` is unavailable.
+- **Board ranking and a fast landing board.** Boards carry an `"order"` field; the switcher ranks curated
+  boards by it and always sinks the auto `all-scenes` everything-board to the BOTTOM. A fresh open now
+  lands on the FIRST curated board - a tight, fast board and a good first impression - instead of
+  rendering every frame at once. Rank boards deliberately; the first is what people see first. `order`
+  survives the shell's autosaves.
+
+### Changed
+
+- **Reference images show in FULL.** `Img` no longer cover-crops to a fixed height (that sliced the
+  sides off every screenshot). Each image fills its column at its natural aspect ratio - never cropped,
+  never letterboxed - so same-aspect screenshots line up on their own and the frame auto-heights to fit.
+  Size an image by how many share its `Row` (fewer = bigger), not by a fixed height; `h` is accepted for
+  back-compat but no longer constrains size. A clean inset hairline (grayscale, light + dark) sits on the
+  image's own edge, overriding a screenshot's ragged or baked-in border instead of framing it twice.
+- **Content frames fit their content when you resize.** A manual WIDTH resize now keeps the HEIGHT auto:
+  the frame reflows and refits to show everything, instead of freezing at a stale height (only an explicit
+  device viewport locks it). The content-frame height cap was raised so a long reference doc renders in
+  full rather than clipping, and zoom now reaches 500% for inspecting screenshot detail.
+- **Authoring doctrine updated to match.** The scaffolded instructions now teach sizing images by row
+  grouping instead of cropping, and ranking boards with `order` (first = landing, `all-scenes` is heavy
+  and auto-last).
+
+### Fixed
+
+- **No jiggle on zoom.** An image's display aspect-ratio is pinned on first decode, so an LOD resolution
+  switch changes only the pixels, never the layout box - frames no longer drift as you zoom.
+- **Fast zoom no longer stalls frames.** The LOD re-decode is debounced past the gesture and drops queued
+  work when a new gesture starts, so oscillating zoom-in/out never stacks decode waves and times frames
+  out to a ready-timeout.
+
+## 0.5.0 - 2026-08-15
+
+The performance & fidelity release (SPEC-M5): the canvas stops jiggling. Moving around a board no
+longer swaps between two documents on every pan/zoom - each passive frame renders as a lean DOM
+snapshot that IS what you see, and the real live app takes over the moment you interact with it.
+
+### Added
+
+- **Lean-primary rendering.** Every passive frame shows a **DOM snapshot** - a self-contained static
+  copy of the frame (real DOM + real CSS, zero JavaScript) served in a `sandbox="allow-same-origin"`
+  iframe. It reflows on resize with the browser's own layout engine and carries the app's exact colors
+  (no rasterisation), so panning, zooming, and device-sweeping a board is smooth and pixel-honest. The
+  full live app sits underneath and swaps in instantly when you focus a frame (double-click), or in
+  laser/comment mode. This replaces the earlier screenshot facade, which invented colors and jittered.
+- **Publish parity.** The lean tier now works in published builds (`marver build` → `marver serve`),
+  not just dev - captured client-side from the bundled same-origin frames, no build-time renderer.
+- **Faster first paint.** Leans capture bounded-parallel and viewport-first, so the frames you're
+  looking at appear first and a big board settles in seconds instead of tens of seconds.
+- **Content-frame color families.** Tag a diagram node with a built-in family - `HQ:::blue`,
+  `Carriers:::orange`, `Drivers:::purple` (also `green red gray`) - and it gets a filled, on-brand
+  color with a legible border in both themes, no `classDef` boilerplate. The same six names work in
+  `Md` prose as `:blue[the shipper's world]`, so a sentence and the diagram beside it read as one
+  color language.
+- **`Head :: gloss` diagram labels.** A node label written `Head :: gloss` renders the head bold on
+  top with the gloss lighter and smaller below - a box scans as label-then-detail, no run-on.
+- **Authoring doctrine that ships with the tool.** The scaffolded instructions
+  (`instructions/shape.md`, `instructions/reference/color.md`) now teach an agent these conventions -
+  the `::` label hierarchy, the `:::family` / `:blue[…]` palette, and "pick one family per concept and
+  hold it" - so diagrams and highlighted prose come out consistent by default instead of hand-rolled
+  hex and one-off `classDef`s.
+
+### Changed
+
+- **Sidebar header** shows the humanized repo name (`marver-pilot` → "Marver Pilot", ellipsed if
+  long); the logo links to marver.design.
+- **Sidebar board/scene labels** are humanized - kebab filenames render Title Case (`tms-specs` →
+  "Tms Specs"), dropping the dashes, while an explicit `meta.title` is honored verbatim.
+- **App cursor** is the marver arrowhead - tilted, rounded, small, soft-shadowed, and theme-adaptive
+  (black-on-light / white-on-dark); reverts to a normal pointer in interact/prototype and keeps the
+  pin/crosshair in comment/laser mode.
+- **Copy-file-path shortcut** moved to `Shift+P` (was a mislabeled `C`).
+
+### Fixed
+
+- The canvas "jiggle" - text shifting ~1-2px when you click or zoom a frame - is gone; there is no
+  longer a per-gesture document swap to shift it.
+- Mermaid diagrams no longer pop in/out or flash the wrong theme during zoom (async render is awaited;
+  a diagram's baked colors re-capture on theme change; the cover's color-scheme is pinned to the
+  frame theme, not the viewer's OS).
+- A frame you've scrolled, typed into, or themed re-captures faithfully; agent edits (HMR) drop the
+  stale snapshot and rebuild; slow data that lands shortly after load triggers one bounded re-capture
+  (data that changes much later shows live the moment you focus the frame, and the lean rebuilds when
+  you leave it).
+
+### Known limitations
+
+- Memory targets typical authoring boards (~15-20 frames); dozens of heavy production apps need the
+  bounded-residency milestone. A frame the serializer can't render faithfully (canvas/video/open- or
+  script-created-closed shadow-DOM/nested-iframe/cross-origin-CSS/blocked-CSP/oversized) degrades to
+  live automatically. (One narrow edge: a declarative closed shadow root can't be detected and may
+  render stale - rare in practice.)
+
 ## 0.4.0 - 2026-08-14
 
 The collaboration release (SPEC-M3): the canvas becomes a place where colleagues,

package/dist/{build-p3xmXU3b.mjs → build-BZaPa2DS.mjs}

@@ -1,6 +1,6 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
-import { a as loadConfig, n as scanFrames, o as detectHost } from "./manifest-DW-T52MM.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-CtQqO5ZZ.mjs";
+import { o as loadConfig, r as scanFrames, s as detectHost } from "./manifest-C8FODq2S.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-wMY9lNf3.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -144,7 +144,11 @@ async function buildSite(root, boardsFlag, allBoardsFlag) {
 	const manifest = scanFrames(root);
 	const allBoards = readBoards(root);
 	const rights = resolvePublish(root, allBoards, boardsFlag, allBoardsFlag);
-	const publishedNames = Object.keys(rights);
+	const boardOrder = (n) => {
+		const o = allBoards[n]?.order;
+		return typeof o === "number" && Number.isFinite(o) ? o : Infinity;
+	};
+	const publishedNames = Object.keys(rights).sort((a, b) => a === "all-scenes" ? 1 : b === "all-scenes" ? -1 : boardOrder(a) - boardOrder(b) || a.localeCompare(b));
 	const includeAll = publishedNames.includes("all-scenes");
 	const boards = {};
 	for (const n of publishedNames) if (allBoards[n]) boards[n] = allBoards[n];
@@ -164,7 +168,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag) {
 		},
 		boards,
 		names: publishedNames,
-		default: publishedNames[0],
+		default: publishedNames.find((n) => n !== "all-scenes") ?? publishedNames[0],
 		rights
 	};
 	const registryFile = posix(join(clientDir, "frame-host", "registry.ts"));
@@ -250,7 +254,9 @@ async function buildSite(root, boardsFlag, allBoardsFlag) {
 	for (const f of frames.filter((x) => x.kind === "html")) {
 		const src = readFileSync(join(root, f.file), "utf8");
 		const inject = `${frameCss}\n<script type="module" src="/assets/bridge.js?html=1"><\/script>\n`;
-		const html = src.includes("</head>") ? src.replace("</head>", `${inject}</head>`) : inject + src;
+		let html = src.includes("</head>") ? src.replace("</head>", `${inject}</head>`) : inject + src;
+		const shim = `<script>(function(){var a=Element.prototype.attachShadow;if(a)Element.prototype.attachShadow=function(i){if(i&&i.mode==='closed')window.__mvClosedShadow=1;return a.call(this,i)};})();<\/script>`;
+		html = /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (m) => m + shim) : shim + html;
 		mkdirSync(dirname(join(outDir, f.file)), { recursive: true });
 		writeFileSync(join(outDir, f.file), html);
 	}

package/dist/cli.mjs

@@ -39,14 +39,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-Ck8z-HiD.mjs");
+	const { init } = await import("./init-DsCUmlCW.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-DZi1yRhn.mjs");
+	const { dev } = await import("./dev-DaPQ9xA5.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -56,7 +56,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 (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-p3xmXU3b.mjs");
+	const { buildSite } = await import("./build-BZaPa2DS.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards, opts.allBoards === true);

package/dist/{dev-DZi1yRhn.mjs → dev-DaPQ9xA5.mjs}

@@ -1,20 +1,57 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
-import { a as loadConfig, o as detectHost } from "./manifest-DW-T52MM.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-CtQqO5ZZ.mjs";
-import { dirname, join } from "node:path";
+import { o as loadConfig, s as detectHost } from "./manifest-C8FODq2S.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-wMY9lNf3.mjs";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";
 import react from "@vitejs/plugin-react";
+import { createServer as createServer$1 } from "node:net";
 //#region src/server/dev.ts
 /** packageDir = the installed marver package root (dist/cli.js lives one level down). */
 function packageDir() {
 	return join(dirname(fileURLToPath(import.meta.url)), "..");
 }
+const portFree = (p) => new Promise((res) => {
+	const s = createServer$1();
+	s.once("error", () => res(false));
+	s.once("listening", () => s.close(() => res(true)));
+	s.listen(p, "127.0.0.1");
+});
+/** C1: a deterministic per-project port in [5200,5399] derived from the root path. Two projects
+*  never collide, and the same project always lands on the same port across restarts. */
+const projectPort = (root) => {
+	let h = 0;
+	for (let i = 0; i < root.length; i++) h = Math.imul(h, 31) + root.charCodeAt(i) | 0;
+	return 5200 + Math.abs(h) % 200;
+};
+/** Pick the port to serve on: the desired one if free, else a DETERMINISTIC per-project fallback -
+*  never a silent next-free drift, which made a bookmarked tab silently serve a DIFFERENT project. */
+async function pickPort(root, desired) {
+	if (await portFree(desired)) return {
+		port: desired,
+		fellBack: false
+	};
+	let p = projectPort(root);
+	for (let i = 0; i < 200; i++) {
+		if (p !== desired && await portFree(p)) return {
+			port: p,
+			fellBack: true
+		};
+		p = 5200 + (p - 5200 + 1) % 200;
+	}
+	return {
+		port: desired,
+		fellBack: true
+	};
+}
 async function dev(root, portFlag) {
 	const config = await loadConfig(root);
 	const host = detectHost(root);
 	const pkgDir = packageDir();
 	const clientDir = join(pkgDir, "src", "client");
+	const projectName = basename(root);
+	const desiredPort = portFlag ?? (config.port !== 5199 ? config.port : void 0) ?? projectPort(root);
+	const picked = await pickPort(root, desiredPort);
 	const plugins = [react()];
 	if (host.tailwind === 4) {
 		const tw = await tailwind4Plugin(root);
@@ -46,7 +83,7 @@ async function dev(root, portFlag) {
 		customLogger: logger,
 		plugins,
 		server: {
-			port: portFlag ?? config.port,
+			port: picked.port,
 			strictPort: false,
 			fs: { allow: [.../* @__PURE__ */ new Set([
 				root,
@@ -66,7 +103,17 @@ async function dev(root, portFlag) {
 				"**/dist/**",
 				"**/build/**",
 				"**/out/**",
-				"**/coverage/**"
+				"**/coverage/**",
+				"**/.gstack/**",
+				"**/.git/**",
+				"**/.playwright-mcp/**"
+			] },
+			warmup: { clientFiles: [
+				join(clientDir, "frame-host", "main.tsx"),
+				join(clientDir, "frame-host", "bridge.js"),
+				join(clientDir, "content", "index.tsx"),
+				join(clientDir, "content", "diagram.tsx"),
+				join(clientDir, "content", "md.ts")
 			] }
 		},
 		resolve: {
@@ -82,7 +129,8 @@ async function dev(root, portFlag) {
 				"react/jsx-runtime",
 				"react/jsx-dev-runtime",
 				`${PKG} > marked`,
-				`${PKG} > mermaid`
+				`${PKG} > mermaid`,
+				`${PKG} > html-to-image`
 			],
 			entries: [join(clientDir, "frame-host", "index.html"), "design/**/*.{tsx,jsx}"]
 		},
@@ -90,8 +138,9 @@ async function dev(root, portFlag) {
 	});
 	await server.listen();
 	const addr = server.httpServer?.address();
-	const port = typeof addr === "object" && addr ? addr.port : config.port;
-	console.log(`\n  ${NAME} canvas → http://localhost:${port}/\n`);
+	const port = typeof addr === "object" && addr ? addr.port : picked.port;
+	if (picked.fellBack) console.log(`\n  port ${desiredPort} is in use - serving "${projectName}" on ${port} instead`);
+	console.log(`\n  ${NAME} · ${projectName} → http://localhost:${port}/\n`);
 	const { loadCollab, syncOnce } = await import("./sync-CkBk-tUk.mjs").then((n) => n.a);
 	if (loadCollab(root)) console.log(`  comments: syncing with the published canvas (design/.local/collab.json)\n`);
 	let syncing = false;

package/dist/{init-Ck8z-HiD.mjs → init-DsCUmlCW.mjs}

@@ -1,5 +1,5 @@
 import { n as NAME } from "./cli.mjs";
-import { i as DEFAULTS, n as scanFrames, o as detectHost, r as writeManifest, s as readJson } from "./manifest-DW-T52MM.mjs";
+import { a as DEFAULTS, c as readJson, i as writeManifest, r as scanFrames, s as detectHost } from "./manifest-C8FODq2S.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";

package/dist/{manifest-DW-T52MM.mjs → manifest-C8FODq2S.mjs}

@@ -247,6 +247,31 @@ function toFrameId(designRelPath) {
 	const noExt = designRelPath.split(sep).join("/").replace(FRAME_EXT, "");
 	return noExt.startsWith("scenes/") ? noExt.slice(7) : noExt;
 }
+/**
+* A7: which frames does a changed `design/**` file affect? Manifest + directory conventions,
+* NOT a module-graph walk (deterministic, cheap, may over-reload but never misses a
+* conventionally-affected frame). Returns:
+*   null  -> uncontrolled: leave to default Vite HMR (src/** deps, theme.css, config, assets)
+*   []    -> controlled but affects no current frame (e.g. a layout in an empty dir)
+*   [ids] -> controlled: the shell drives a rev-stamped reload of these frames
+*/
+function affectedFrameIds(absFile, root, manifest) {
+	const design = join(root, "design");
+	if (absFile !== design && !absFile.startsWith(design + sep)) return null;
+	const rel = relative(design, absFile).split(sep).join("/");
+	const name = rel.split("/").pop() ?? rel;
+	const designRel = `design/${rel}`;
+	const tsxFrames = manifest.frames.filter((f) => f.kind === "tsx");
+	if (name === "theme.css") return null;
+	if (rel === "providers.tsx" || rel === "providers.jsx") return tsxFrames.map((f) => f.id);
+	if (/(^|\/)(_layout\.(tsx|jsx)|_fixtures\.(ts|tsx|js|jsx|json))$/.test(rel)) {
+		const prefix = `design/${rel.slice(0, rel.length - name.length)}`;
+		return tsxFrames.filter((f) => f.file.startsWith(prefix)).map((f) => f.id);
+	}
+	const direct = manifest.frames.find((f) => f.file === designRel);
+	if (direct) return [direct.id];
+	return null;
+}
 function walk(dir, out = []) {
 	if (!existsSync(dir)) return out;
 	for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -399,4 +424,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, readJson as s, hash as t };
+export { DEFAULTS as a, readJson as c, writeManifest as i, hash as n, loadConfig as o, scanFrames as r, detectHost as s, affectedFrameIds as t };

package/dist/{plugin-CtQqO5ZZ.mjs → plugin-wMY9lNf3.mjs}

@@ -1,7 +1,7 @@
 import { i as ROUTE, n as NAME, r as PKG } from "./cli.mjs";
-import { n as scanFrames, r as writeManifest, t as hash } from "./manifest-DW-T52MM.mjs";
+import { i as writeManifest, n as hash, r as scanFrames, t as affectedFrameIds } from "./manifest-C8FODq2S.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 //#region src/server/api.ts
@@ -79,9 +79,15 @@ function apiMiddleware(root) {
 				mkdirSync(boardsDir, { recursive: true });
 				return json(res, 200, readdirSync(boardsDir).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp")).map((f) => {
 					const content = readFileSync(join(boardsDir, f), "utf8");
+					let order;
+					try {
+						const o = JSON.parse(content)?.order;
+						if (typeof o === "number" && Number.isFinite(o)) order = o;
+					} catch {}
 					return {
 						name: f.replace(/\.json$/, ""),
-						sha256: hash(content)
+						sha256: hash(content),
+						order
 					};
 				}));
 			}
@@ -110,6 +116,10 @@ function apiMiddleware(root) {
 					} catch {
 						return json(res, 400, { error: "malformed JSON" });
 					}
+					if (body.mustExist && !existsSync(p)) return json(res, 409, {
+						error: "board no longer exists on disk",
+						gone: true
+					});
 					const current = existsSync(p) ? readFileSync(p, "utf8") : "";
 					if (current && body.baseHash !== hash(current)) {
 						let disk = null;
@@ -123,6 +133,11 @@ function apiMiddleware(root) {
 						});
 					}
 					mkdirSync(boardsDir, { recursive: true });
+					const incoming = body.board;
+					if (incoming && typeof incoming === "object" && incoming.order === void 0 && current) try {
+						const o = JSON.parse(current).order;
+						if (typeof o === "number" && Number.isFinite(o)) incoming.order = o;
+					} catch {}
 					const next2 = JSON.stringify(body.board, null, 2) + "\n";
 					atomicWrite(p, next2);
 					return json(res, 200, { sha256: hash(next2) });
@@ -373,6 +388,20 @@ const VIRTUAL_CONFIG = "virtual:sh-config";
 const VIRTUAL_DATA = "virtual:sh-data";
 function marverPlugin(ctx) {
 	const { root, clientDir, config } = ctx;
+	let manifest = scanFrames(root);
+	let devServer = null;
+	const bootId = String(process.hrtime.bigint());
+	let invRev = 0;
+	const pendingInv = /* @__PURE__ */ new Set();
+	const flushInv = debounce(() => {
+		if (!devServer || !pendingInv.size) return;
+		const frameIds = [...pendingInv];
+		pendingInv.clear();
+		devServer.ws.send("sh:frame-invalidated", {
+			frameIds,
+			revision: `${bootId}:${++invRev}`
+		});
+	}, 120);
 	/** Theme resolution: design/theme.css wrapper > configured > detected > empty (spec §5.4). */
 	const themeFile = () => {
 		const wrapper = join(root, "design", "theme.css");
@@ -383,6 +412,7 @@ function marverPlugin(ctx) {
 	};
 	return {
 		name: "marver",
+		enforce: "pre",
 		resolveId(id) {
 			if (id === VIRTUAL_THEME) return themeFile() ?? "\0virtual:sh-theme.css";
 			if (id === VIRTUAL_CONFIG) return "\0virtual:sh-config";
@@ -407,7 +437,8 @@ function marverPlugin(ctx) {
 					themes: config.themes,
 					zoomSpeed: config.zoomSpeed,
 					noTheme: themeFile() == null,
-					setup: setupPending
+					setup: setupPending,
+					projectName: basename(root)
 				})}`;
 			}
 			if (id === "\0virtual:sh-data") return "export default null";
@@ -422,19 +453,27 @@ function marverPlugin(ctx) {
 				const bridge = "/@fs/" + join(clientDir, "frame-host", "bridge.js").split("\\").join("/") + "?html=1";
 				return {
 					html,
-					tags: [{
-						tag: "script",
-						attrs: { type: "module" },
-						children: `import '${VIRTUAL_THEME}'`,
-						injectTo: "head-prepend"
-					}, {
-						tag: "script",
-						attrs: {
-							type: "module",
-							src: bridge
+					tags: [
+						{
+							tag: "script",
+							children: `(function(){var a=Element.prototype.attachShadow;if(a)Element.prototype.attachShadow=function(i){if(i&&i.mode==='closed')window.__mvClosedShadow=1;return a.call(this,i)};})();`,
+							injectTo: "head-prepend"
 						},
-						injectTo: "head-prepend"
-					}]
+						{
+							tag: "script",
+							attrs: { type: "module" },
+							children: `import '${VIRTUAL_THEME}'`,
+							injectTo: "head-prepend"
+						},
+						{
+							tag: "script",
+							attrs: {
+								type: "module",
+								src: bridge
+							},
+							injectTo: "head-prepend"
+						}
+					]
 				};
 			}
 		},
@@ -444,9 +483,16 @@ function marverPlugin(ctx) {
 		* Edits to loaded frames keep normal HMR (modules present + file exists → pass through).
 		*/
 		handleHotUpdate(hctx) {
-			if (![join(root, "design", "scenes"), join(root, "design", "components")].some((w) => hctx.file.startsWith(w))) return;
-			if (!existsSync(hctx.file)) return [];
-			if (hctx.modules.length === 0) return [];
+			const affected = affectedFrameIds(hctx.file, root, manifest);
+			if (affected === null) {
+				if ([join(root, "design", "scenes"), join(root, "design", "components")].some((w) => hctx.file.startsWith(w)) && !existsSync(hctx.file)) return [];
+				return;
+			}
+			if (affected.length) {
+				for (const id of affected) pendingInv.add(id);
+				flushInv();
+			}
+			return [];
 		},
 		configureServer(server) {
 			server.middlewares.use((req, res, next) => {
@@ -473,8 +519,9 @@ function marverPlugin(ctx) {
 			});
 			server.middlewares.use(apiMiddleware(root));
 			server.middlewares.use(routesMiddleware(server, clientDir));
+			devServer = server;
 			const regen = debounce(() => {
-				const manifest = scanFrames(root);
+				manifest = scanFrames(root);
 				if (writeManifest(root, manifest)) server.ws.send("sh:manifest", manifest);
 			}, 150);
 			const watched = [join(root, "design", "scenes"), join(root, "design", "components")];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "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,
@@ -33,6 +33,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^6.0.0",
     "cac": "^7.0.0",
+    "html-to-image": "^1.11.13",
     "marked": "^16.0.0",
     "mermaid": "^11.6.0",
     "react-zoom-pan-pinch": "^3.6.1",

package/src/client/content/diagram.tsx

@@ -23,6 +23,50 @@ export function cleanSource(src: string): string {
     .trim()
 }
 
+/** flowchart/graph is where classDef + markdown-string labels both apply; other diagram
+ *  types (sequence, pie, ...) don't take the family/hierarchy sugar. */
+function isFlowchart(src: string): boolean {
+  const first = src.split('\n').find((l) => l.trim())?.trim() ?? ''
+  return /^(flowchart|graph)\b/.test(first)
+}
+
+// D1: head/gloss auto-hierarchy. An agent writes a natural `Head :: gloss` label and marver
+// renders the head BOLD on top with the gloss on a lighter, smaller line below - no backticks,
+// no `**`, no `<br>` to hand-author. It expands the label into a mermaid markdown string (bold
+// head, blank line -> a second <p> the THEME_CSS styles down). ` :: ` (spaced double colon) is
+// the token: rare in prose, and distinct from the `:::family` class tag (no spaces, three colons).
+const GLOSS = ' :: '
+export function withLabelHierarchy(src: string): string {
+  if (!isFlowchart(src)) return src
+  return src.replace(/"([^"\n]*?)"/g, (m, body: string) => {
+    const at = body.indexOf(GLOSS)
+    if (at < 0 || body.startsWith('`')) return m           // no token, or already a markdown string
+    const head = body.slice(0, at).trim()
+    const gloss = body.slice(at + GLOSS.length).trim()
+    if (!head || !gloss) return m
+    const bhead = /[*`]/.test(head) ? head : `**${head}**`  // don't double-bold a hand-marked head
+    return `"\`${bhead}\n\n${gloss}\`"`                     // "`**Head**⏎⏎gloss`"
+  })
+}
+
+// D2: named family fills - the SAME colour language as the Md `:blue[...]` families, so an agent
+// tags a node `HQ:::blue` with zero classDef boilerplate and prose + diagram read as one palette.
+const DIAGRAM_FAMILIES: Record<string, string> = {
+  blue: 'fill:#0088FF,stroke:#0066CC,color:#fff',
+  orange: 'fill:#F5820A,stroke:#C96A08,color:#fff',
+  purple: 'fill:#B32BC8,stroke:#8F22A0,color:#fff',
+  green: 'fill:#1FA34A,stroke:#178139,color:#fff',
+  red: 'fill:#E5342B,stroke:#B71C13,color:#fff',
+  gray: 'fill:#E5E5EA,stroke:#C7C7CC,color:#1C1C1E',
+}
+/** Append the family classDefs to flowchart/graph diagrams (classDef is a flowchart feature).
+ *  Unused defs are harmless; `X:::blue` resolves them regardless of position. */
+export function withFamilies(src: string): string {
+  if (!isFlowchart(src)) return src
+  const defs = Object.entries(DIAGRAM_FAMILIES).map(([n, s]) => `classDef ${n} ${s}`).join('\n')
+  return `${src}\n${defs}`
+}
+
 /** Remove external URL references from rendered SVG (images, links, href attrs). */
 export function sanitizeSvg(svg: string): string {
   const doc = new DOMParser().parseFromString(svg, 'image/svg+xml')
@@ -38,9 +82,9 @@ export function sanitizeSvg(svg: string): string {
 }
 
 export function Diagram({ title, children }: { title?: string; children?: ReactNode }) {
-  const src = cleanSource(
+  const src = withFamilies(withLabelHierarchy(cleanSource(
     typeof children === 'string' ? children : Array.isArray(children) ? children.join('') : String(children ?? ''),
-  )
+  )))
   const ref = useRef<HTMLDivElement>(null)
   const [error, setError] = useState<string | null>(null)
   const uid = useRef(`mv-mmd-${++uidSeq}`)