@marver-design/marver 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 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-BrCl9hJS.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-BtSGAm2h.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";
@@ -250,7 +250,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-DdeU-Jst.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-BrCl9hJS.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-DdeU-Jst.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-BtSGAm2h.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-BtSGAm2h.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
@@ -110,6 +110,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;
@@ -373,6 +377,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 +401,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 +426,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 +442,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"
+						},
+						{
+							tag: "script",
+							attrs: { type: "module" },
+							children: `import '${VIRTUAL_THEME}'`,
+							injectTo: "head-prepend"
 						},
-						injectTo: "head-prepend"
-					}]
+						{
+							tag: "script",
+							attrs: {
+								type: "module",
+								src: bridge
+							},
+							injectTo: "head-prepend"
+						}
+					]
 				};
 			}
 		},
@@ -444,9 +472,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 +508,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.5.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}`)

package/src/client/content/index.tsx

@@ -9,7 +9,11 @@
  */
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { CONTENT_WIDTH } from '../const.ts'
-import { assetUrl, renderMarkdown } from './md.ts'
+import { assetUrl, renderMarkdown, FAMILIES } from './md.ts'
+
+// D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
+const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
+  `.mv-md .mv-c-${f}{color:${c.light}}.dark .mv-md .mv-c-${f},[data-theme="dark"] .mv-md .mv-c-${f}{color:${c.dark}}`).join('\n')
 
 export { Diagram } from './diagram.tsx'
 
@@ -106,7 +110,7 @@ function ensureStyles() {
   stylesIn = true
   const el = document.createElement('style')
   el.id = 'mv-content-css'
-  el.textContent = CSS
+  el.textContent = CSS + '\n' + FAMILY_CSS
   document.head.appendChild(el)
 }
 

package/src/client/content/md.ts

@@ -8,6 +8,19 @@ import { Marked } from 'marked'
 
 const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
 
+/** D3: named color families for inline Md - the SAME families the diagrams use, so prose and
+ *  the diagram beside it speak one color language. Theme pairs (light/dark). Bound to classes,
+ *  never raw HTML (raw HTML stays inert). Used by the `:family[text]` extension + the frame CSS. */
+export const FAMILIES: Record<string, { light: string; dark: string }> = {
+  blue:   { light: '#0088FF', dark: '#3B9DFF' },
+  orange: { light: '#F5820A', dark: '#FF9F33' },
+  purple: { light: '#B32BC8', dark: '#D34FE8' },
+  green:  { light: '#1FA34A', dark: '#34C759' },
+  red:    { light: '#E5342B', dark: '#FF453A' },
+  gray:   { light: '#8B95A3', dark: '#7D8794' },
+}
+const FAMILY_RE = new RegExp(`^:(${Object.keys(FAMILIES).join('|')})\\[([^\\]\\n]+)\\]`)
+
 /** Relative design/assets/ path -> served URL; null for anything else (fail closed).
  *  Decodes BEFORE validating (a %2e%2e must not sneak past the ".." check) and
  *  re-encodes per segment, so the validated path is the path the browser requests. */
@@ -45,6 +58,22 @@ const marked = new Marked({
   },
 })
 
+// D3: `:blue[shipper's world]` -> a family-colored span (inline markdown inside still parses).
+marked.use({
+  extensions: [{
+    name: 'mvcolor',
+    level: 'inline',
+    start(src: string) { return src.match(/:(?:blue|orange|purple|green|red|gray)\[/)?.index },
+    tokenizer(this: any, src: string) {
+      const m = FAMILY_RE.exec(src)
+      if (m) return { type: 'mvcolor', raw: m[0], family: m[1], tokens: this.lexer.inlineTokens(m[2]) }
+    },
+    renderer(this: any, token: any) {
+      return `<span class="mv-c-${token.family}">${this.parser.parseInline(token.tokens)}</span>`
+    },
+  }],
+})
+
 export function renderMarkdown(src: string): string {
   return marked.parse(src, { async: false }) as string
 }

package/src/client/content/palette.ts

@@ -25,6 +25,12 @@ export const THEME_CSS = `
   .nodeLabel, .cluster-label { font-weight: 600; line-height: 1.4; }
   .nodeLabel p, .edgeLabel p, .label p { margin: 0; }
   .edgeLabel, .edgeLabel .label { font-weight: 500; }
+  /* D1 head/gloss hierarchy: a "Head :: gloss" label renders as two paragraphs -
+     bold head (the strong from the markdown), lighter/smaller gloss below. */
+  .nodeLabel p + p, .cluster-label p + p {
+    font-weight: 400; font-size: 0.84em; opacity: 0.68;
+    letter-spacing: 0; margin-top: 3px;
+  }
 `
 
 /** Mermaid themeVariables for one mode. Base theme + these = the marver look. */

package/src/client/frame-host/bridge.js

@@ -4,6 +4,15 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
 const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 const id = new URLSearchParams(location.search).get('id') ?? location.pathname
 
+// SPEC-M5: the shell serialises this frame's DOM (same origin) for the lean facade. Open shadow roots
+// are walkable, but a CLOSED root is invisible after the fact - flag it at creation so the serialiser
+// degrades the frame (keeps it live) instead of shipping a lean copy missing its shadow content.
+const _attachShadow = Element.prototype.attachShadow
+if (_attachShadow) Element.prototype.attachShadow = function (init) {
+  if (init && init.mode === 'closed') window.__mvClosedShadow = true
+  return _attachShadow.call(this, init)
+}
+
 // theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
 const setTheme = (theme) => {
   document.documentElement.dataset.theme = theme
@@ -32,6 +41,8 @@ window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: St
 window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, message: `unhandled rejection: ${e.reason}` }))
 
 window.addEventListener('message', (e) => {
+  // commands come from the SHELL (parent) only - embedded app content must not flip the theme
+  if (e.source !== window.parent || window.parent === window) return
   if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
 })
 
@@ -40,10 +51,23 @@ if (isHtmlFrame) {
   document.readyState === 'loading' ? addEventListener('DOMContentLoaded', ready) : ready()
 }
 
-// pinch inside a frame must not zoom the parent PAGE (wheel events here belong to the
-// iframe's document, so the shell's blocker cannot see them). Keyboard cmd +/- untouched.
-window.addEventListener('wheel', (e) => { if (e.ctrlKey || e.metaKey) e.preventDefault() }, { passive: false })
+// B0.2 wheel ownership. A frame is either the interact/play target (the APP owns wheel -
+// its own scroll) or passive (laser/comment/plain view - the CANVAS owns wheel). Wheel
+// events land in the iframe's document, so the shell can't see them: when passive we
+// forward them to the shell, when interactive we leave them for the app (only blocking
+// the browser's own ctrl/meta page pinch-zoom). preventing here is mandatory - the parent
+// gets the forwarded message too late to cancel the iframe's own scroll.
+let interactiveOn = false
+window.addEventListener('wheel', (e) => {
+  if (interactiveOn) { if (e.ctrlKey || e.metaKey) e.preventDefault(); return }
+  e.preventDefault()
+  e.stopImmediatePropagation()
+  post({ type: 'sh:wheel', id, deltaX: e.deltaX, deltaY: e.deltaY, deltaMode: e.deltaMode,
+    ctrlKey: e.ctrlKey, metaKey: e.metaKey, clientX: e.clientX, clientY: e.clientY })
+}, { capture: true, passive: false })
 document.addEventListener('gesturestart', (e) => e.preventDefault())
+// a nested scroll container hitting its boundary must not chain into the shell page
+document.documentElement.style.overscrollBehavior = 'contain'
 
 // ---- laser mode + element picking (SPEC-M3 §5, §7) ----------------------------------
 // Laser: one injected stylesheet, outline only (zero layout shift), depth-based hue -
@@ -91,6 +115,15 @@ const COPIED_HTML = `<svg width="12" height="12" viewBox="0 0 256 256" fill="cur
 let laserOn = false, pickOn = false, hoverEl = null, labelEl = null
 const modeActive = () => laserOn || pickOn
 
+// A6: report transient laser/comment engagement (pointer inside this frame AND a mode on) so the
+// shell leases the frame - a hot update to it then defers until the pointer leaves or the mode
+// ends, instead of yanking the user mid-inspect/mid-comment.
+let pointerInside = false
+const reportInteraction = () => post({ type: 'sh:interaction', id, laser: pointerInside && laserOn, comment: pointerInside && pickOn })
+document.addEventListener('mouseover', () => { if (!pointerInside) { pointerInside = true; reportInteraction() } })
+document.addEventListener('mouseout', (e) => { if (!e.relatedTarget) { pointerInside = false; reportInteraction() } })
+window.addEventListener('blur', () => { if (pointerInside) { pointerInside = false; reportInteraction() } })
+
 // laser and pick are independent looks over shared hover machinery: the stylesheet
 // is regenerated on every flip so each mode contributes exactly its own rules
 const applyModes = () => {
@@ -258,8 +291,10 @@ window.addEventListener('message', (e) => {
   const m = e?.data
   if (!m || typeof m !== 'object') return
   // independent toggles - each mode contributes its own rules, applyModes composes
-  if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes() }
-  if (m.type === 'sh:pick') { pickOn = !!m.on; applyModes() }
+  if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes(); reportInteraction() }
+  if (m.type === 'sh:pick') { pickOn = !!m.on; applyModes(); reportInteraction() }
+  // B0.2: interact/play target owns its own wheel; passive frames forward it to the canvas
+  if (m.type === 'sh:interactive') { interactiveOn = !!m.on }
   if (m.type === 'sh:copy-ok') showCopied(m.seq)
   if (m.type === 'sh:resolve-anchors' && Array.isArray(m.anchors)) {
     const rects = m.anchors.slice(0, 200).map((a) => {