@marver-design/marver 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
+
+## 0.3.0 - 2026-08-13
+
+The co-thinking release: the canvas now holds the thinking, not just the screens.
+
+### Added
+
+- **Content frames (SPEC-026).** Specs, Mermaid diagrams, and mood boards as ordinary frames beside UI frames - import `Doc`, `Row`, `Col`, `Space`, `Md`, `Diagram`, `Img` from `@marver-design/marver/content`. Works in a repo with no app at all: idea first, design second.
+  - `Doc` auto-sizes the frame to its content (measurement protocol; auto sizes are session-transient, manual resize and device views still win). Published canvases keep parity.
+  - `Diagram` is first-class Mermaid, lazily loaded - a workspace with no diagrams ships zero mermaid bytes. Source theme overrides are stripped; parse errors show an in-frame card and heal live.
+  - `Md` renders theme-aware markdown; `[label](goto:scene/frame)` links jump the canvas. Raw HTML is inert, images are local-only.
+  - `Img` shows `design/assets/` imagery with captions; `h={n}` cover-crops a mixed-aspect row to one height so it reads aligned.
+  - Zero-external-request boundary: URLs are rejected in diagram source, rendered SVG is sanitized, published builds copy only referenced local assets.
+- **The marver diagram theme.** Full Apple system palette (12 series colors + systemGray ramp, exact HIG light/dark pairs), system font stack, accent-washed nodes by default - a plain flowchart is never gray-on-gray. Label typography rides inside the SVG (measured, not post-styled).
+- **Frame intent.** Content frames declare `intent` (`diagram` | `spec` | `moodboard` | `notes`); the sidebar shows a glyph per row - every row leads with an icon, variant groups carry the flask.
+- **Sidebar tells the canvas's story.** Rows and scene groups order by canvas position, not file order.
+- **The onboarding fork (SPEC-025 amendment).** Both first-session paths - empty repo and existing app - now stop and ask what the highest priority is: think the idea through together on the canvas, or go straight to screens.
+- **Shape & Iterate doctrine.** `instructions/shape.md` (feature-story boards: specs → lo-fi → hi-fi with graduated spacing) and `instructions/iterate.md` (fork-don't-overwrite, letter variants, the archive ritual).
+- **Craft doctrine hardened.** Real assets are binding (Phosphor icons by default, actual brand logos, fetched imagery). Interactive means visibly interactive at every fidelity - cursor + hover on every clickable target, component-library gaps (shadcn on Tailwind v4 ships `cursor: default` buttons) fixed at the design-system base layer.
+
+### Changed
+
+- Markdown typography moved to the HIG scale: 16px body on 1.65, tightened heading tracking, contained Notion-style tables, re-asserted list markers (Tailwind preflight strips them in host apps).
+
+## 0.2.4 - 2026-08-13
+
+- Onboarding as a conversation (SPEC-025): setup flow asks what you're building, proposes a stack (a recommendation, not a requirement), hosted tour canvas as the waiting room, local canvas as the reveal. Two dogfood rounds folded in.
+
+## 0.2.3 - 2026-08-12
+
+- Hardening release: codex P1s (live-JOIN adjacency, same-directory group invariant, tsx-only inference) and a P2 sweep (extractor boundaries, sceneRows dedupe, play-mode chrome fixes, extreme-zoom badge fade).
+
+## 0.2.2 - 2026-08-12
+
+- Update discovery: glass pill + stdout notice + daily registry check (opt out with `MARVER_NO_UPDATE_CHECK=1`). `design/` collision guard on init.
+
+## 0.2.1 - 2026-08-12
+
+- The dogfood friction release: all 23 logged friction issues triaged; bugs fixed.
+
+## 0.2.0 - 2026-08-11
+
+- First public release on npm as `@marver-design/marver`, Apache-2.0. The agent-native design canvas: `design/` folder, live frames from your app's real components, boards, device sweeps, play mode, published canvases with a password gate.

package/README.md

@@ -18,6 +18,7 @@ Then, to your agent:
 - **Boards**: one canvas on screen at a time. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed.
 - **Devices view**: the Devices menu (or hotkeys `1`-`5`) sizes every frame to mobile / tablet / laptop / monitor / tv to sweep your breakpoints; `0` restores your own layout exactly. Widths live in `design/config.ts`.
 - `data-goto="scene/frame"` on any element links frames into a walkable prototype.
+- **Content frames**: specs, Mermaid diagrams, and mood boards live on the same canvas as the screens - import `Doc`, `Md`, `Diagram`, `Img` from `@marver-design/marver/content` and think a feature through *before* any pixels exist. Diagrams ship pre-themed (both modes), content frames auto-size to their content, and everything - devices, play mode, publish - works on them identically. Works in a repo with no app at all: idea first, design second.
 - **Upgrade**: `npm i -D @marver-design/marver@latest && npx marver init`. The canvas tells you when a new version is out (one anonymous registry check per day, cached in `design/.local/`; `MARVER_NO_UPDATE_CHECK=1` disables). Re-running init refreshes the managed files (AGENTS.md, `design/instructions/`) - your edits to them are detected and preserved; when both you and a release changed a file, the fresh version is staged at `design/.local/latest/` for you (or your agent) to merge. Everything else in `design/` is yours and never touched.
 - Uninstall: delete `design/`, remove the dependency. (If `init` patched your tsconfig `exclude`, revert that one line.)
 

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

@@ -1,7 +1,7 @@
-import { r as ROUTE, t as NAME } from "./cli.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 { 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-Crp4CAma.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";
 import { build } from "vite";
@@ -24,6 +24,25 @@ const posix = (p) => p.split(sep).join("/");
 function packageDir() {
 	return join(dirname(fileURLToPath(import.meta.url)), "..");
 }
+/** Static asset references in one module's source (SPEC-026): <Img src="..."> string
+*  literals plus markdown image literals INSIDE TEMPLATE STRINGS (where Md content
+*  lives - prose in comments never counts). Comments are stripped first so a commented
+*  example cannot fail the build. A computed <Img src={...}> fails CLOSED - the build
+*  cannot know what it resolves to, so it must not publish. */
+function scanAssetRefs(src, moduleId) {
+	const templates = [];
+	const stripped = src.replace(/`(?:[^`\\]|\\[\s\S])*`/g, (t) => {
+		templates.push(t);
+		return "``";
+	}).replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/.*$/gm, "$1");
+	if (/<Img\b[^>]*\bsrc\s*=\s*\{/.test(stripped)) throw new Error(`${moduleId}: <Img src={...}> is computed - published builds copy only statically referenced assets. Use a string literal.`);
+	const out = [];
+	for (const m of stripped.matchAll(/<Img\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/g)) out.push(m[1]);
+	for (const tpl of templates) for (const m of tpl.matchAll(/!\[[^\]]*\]\(([^)\s"']+)\)/g)) out.push(m[1]);
+	return out;
+}
+/** Same shape the client's assetUrl accepts: relative, inside design/assets/, no tricks. */
+const isLocalAssetRef = (p) => !!p && !p.includes(":") && !p.startsWith("/") && !p.startsWith("\\") && !p.split("/").some((s) => s === ".." || s === "");
 /** Read every board file; returns name -> parsed json. Bad JSON fails the build loudly. */
 function readBoards(root) {
 	const dir = join(root, "design", "boards");
@@ -208,6 +227,37 @@ async function buildSite(root, boardsFlag) {
 		mkdirSync(dirname(join(outDir, f.file)), { recursive: true });
 		writeFileSync(join(outDir, f.file), html);
 	}
+	const assetsDir = join(root, "design", "assets");
+	const rootP = posix(root);
+	const moduleIds = /* @__PURE__ */ new Set();
+	for (const c of chunks) for (const id of c.moduleIds ?? Object.keys(c.modules ?? {})) moduleIds.add(String(id));
+	const refs = /* @__PURE__ */ new Set();
+	for (const id of moduleIds) {
+		const file = posix(String(id)).split("?")[0];
+		if (file.startsWith("\0") || !file.startsWith("/") || file.includes("/node_modules/")) continue;
+		if (!/\.(tsx|jsx|ts|js|mjs)$/.test(file)) continue;
+		let src;
+		try {
+			src = readFileSync(file, "utf8");
+		} catch {
+			continue;
+		}
+		const rel = file.startsWith(rootP + "/") ? file.slice(rootP.length + 1) : file;
+		for (const r of scanAssetRefs(src, rel)) refs.add(r);
+	}
+	let copiedAssets = 0;
+	const realAssets = existsSync(assetsDir) ? realpathSync(assetsDir) : null;
+	for (const r of refs) {
+		if (!isLocalAssetRef(r)) continue;
+		const srcFile = join(assetsDir, r);
+		if (!existsSync(srcFile)) throw new Error(`design/assets/${r} is referenced by a published frame but does not exist`);
+		const real = posix(realpathSync(srcFile));
+		if (!realAssets || !(real === posix(realAssets) || real.startsWith(posix(realAssets) + "/"))) throw new Error(`design/assets/${r} resolves outside design/assets/ (symlink) - refusing to publish it`);
+		const dest = join(outDir, "design", "assets", r);
+		mkdirSync(dirname(dest), { recursive: true });
+		cpSync(srcFile, dest);
+		copiedAssets++;
+	}
 	let name = basename(root);
 	try {
 		name = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).name ?? name;
@@ -237,6 +287,7 @@ async function buildSite(root, boardsFlag) {
 	console.log(`\n  ${NAME} build → design/.dist`);
 	console.log(`  boards: ${publishedNames.join(", ")}`);
 	console.log(`  frames: ${frames.length}${includeAll ? "" : ` of ${manifest.frames.length} (build-time filter)`}`);
+	if (copiedAssets) console.log(`  assets: ${copiedAssets} referenced file${copiedAssets === 1 ? "" : "s"} from design/assets/ (unreferenced assets never ship)`);
 	if (!includeAll && existsSync(join(root, "public"))) console.log(`  note: the host public/ directory ships in full - the --boards filter covers frames, not public assets`);
 	console.log(`\n  serve it:  npx ${NAME} serve   (set MARVER_PASSWORD to gate it)\n`);
 }

package/dist/cli.mjs

@@ -9,6 +9,13 @@ import { fileURLToPath } from "node:url";
 const NAME = "marver";
 const PKG = "@marver-design/marver";
 const ROUTE = "/__mv";
+/** Content-frame natural widths (SPEC-026): Doc layout -> own-size width.
+*  Shared by the Doc primitive (measurement messages) and the server-side
+*  manifest scan (defaultSize for content frames) - one source, no drift. */
+const CONTENT_WIDTH = {
+	document: 760,
+	wide: 1280
+};
 //#endregion
 //#region src/cli/index.ts
 const [major, minor] = process.versions.node.split(".").map(Number);
@@ -32,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-Di4geblA.mjs");
+	const { init } = await import("./init-DolP_Ld4.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-9-80L5i5.mjs");
+	const { dev } = await import("./dev-C2oTKuXe.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -49,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").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-Bqd6OEsQ.mjs");
+	const { buildSite } = await import("./build-Ckmyci3O.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards);
@@ -59,7 +66,7 @@ cli.command("build", "Static export → design/.dist").option("--boards <names>"
 	}
 });
 cli.command("serve", "Serve design/.dist (set MARVER_PASSWORD to gate it)").option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default $PORT or 4199)").action(async (opts) => {
-	const { serve } = await import("./serve-BvbAbWeK.mjs");
+	const { serve } = await import("./serve-OtA9Nlow.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -71,4 +78,4 @@ cli.help();
 cli.version(version());
 cli.parse();
 //#endregion
-export { PKG as n, ROUTE as r, NAME as t };
+export { ROUTE as i, NAME as n, PKG as r, CONTENT_WIDTH as t };

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

@@ -1,6 +1,6 @@
-import { n as PKG, t as NAME } from "./cli.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 { 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-Crp4CAma.mjs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";
@@ -79,7 +79,9 @@ async function dev(root, portFlag) {
 				"react-dom",
 				"react-dom/client",
 				"react/jsx-runtime",
-				"react/jsx-dev-runtime"
+				"react/jsx-dev-runtime",
+				`${PKG} > marked`,
+				`${PKG} > mermaid`
 			],
 			entries: [join(clientDir, "frame-host", "index.html"), "design/**/*.{tsx,jsx}"]
 		},

package/dist/{init-Di4geblA.mjs → init-DolP_Ld4.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, s as readJson } from "./manifest-mYlO_1Pj.mjs";
+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 { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -248,10 +248,23 @@ searches, then propose. Recommend shadcn/ui + latest Tailwind as the default
 component layer (take their current defaults) - but they are a recommendation,
 not a requirement: if the human prefers another component library, plain CSS,
 or their own design system, that wins. Any React + a real stylesheet works;
-${NAME} adapts to what detection finds. Present the proposal with the
-harness's structured question tool when it has one - short labels, one-line
-trade-offs - closing with "aligned, or tell me what you'd rather use". Then
-STOP again: no further tool calls, end your turn, wait for the nod.
+${NAME} adapts to what detection finds.
+
+Ask the FORK in the same message - it decides everything after the scaffold,
+so it belongs here, before any tunnel. Two questions through the harness's
+structured question tool when it has one (short labels, one-line trade-offs):
+
+1. The stack - closing with "aligned, or tell me what you'd rather use".
+2. How do you want to start?
+   - **Think it through together first** - we co-develop the idea, the
+     workflow, the specs, and the mood/inspiration on the canvas before any
+     pixels. What goes on each screen, what stays out, what the intent is.
+   - **Build me something to react to** - I go heads-down and come back with
+     a first draft of ~4 screens you can play with, and we iterate from there.
+
+Works for any kind of product - a marketing site co-thinks its story and
+inspiration the same way an app co-thinks its workflow. Then STOP: no further
+tool calls, end your turn, wait for both answers.
 
 ## 4. Hand them the tour, then scaffold
 
@@ -304,7 +317,23 @@ configure.md): frames render styled, one app component imports cleanly.
 DESIGN.md comes next, as part of the first draft.
 
 
-## 6. The first draft - make it impressive, then tour
+## 6. The path they chose at the fork
+
+**Chose "think it together"?** No tunnel - the canvas becomes the shared
+thinking surface (instructions/shape.md is the guide). Start
+\`npx ${NAME} dev\`, then seed a feature-story board from what step 2 taught
+you: an intent content frame with their answer restated as problem/goal/
+non-goals, a first-guess workflow diagram (mermaid - your draft of THEIR flow,
+made to be corrected), and a mood frame - fetch real inspiration and brand
+references when you can search (craft.md "Real assets"). Reveal it EARLY with
+the board deep link and iterate together: what belongs on each screen, what
+stays out, what the intent of each step is. Wireframes and the hi-fi draft
+come after the story is agreed - and by then the brief writes itself. Delete
+the generic demo scene once your frames are in.
+
+**Chose "build me something"?** The impressive first draft, below.
+
+## The first draft - make it impressive, then tour
 
 This is the human's first impression of the canvas AND the first draft of their
 product - it sets the direction. Take the time to do it well:

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

@@ -1,3 +1,4 @@
+import { r as PKG, t as CONTENT_WIDTH } from "./cli.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -218,8 +219,29 @@ function extractMeta(src) {
 	if (of) out.of = of;
 	const variant = pick("variant");
 	if (variant) out.variant = variant;
+	const intent = pick("intent");
+	if (intent) out.intent = intent;
 	return out;
 }
+/** Content-frame detection (SPEC-026): LEXICAL by convention - the frame file
+*  itself imports PKG/content (an import specifier scan, so "<Diagram" inside a
+*  string in a UI frame can never misbadge it; barrels/re-exports are not
+*  detected - meta.intent is the taught path and always works). Returns the
+*  inferred intent + natural width, or null for UI frames. */
+const CONTENT_IMPORT = new RegExp(`from\\s+['"]${PKG}/content['"]`);
+const WIDE_DOC = /<Doc\b[^>]*\blayout\s*=\s*["']wide["']/;
+const contentWidthOf = (src) => WIDE_DOC.test(src) ? CONTENT_WIDTH.wide : CONTENT_WIDTH.document;
+function contentScan(src) {
+	if (!CONTENT_IMPORT.test(src)) return null;
+	const count = (re) => (src.match(re) ?? []).length;
+	const diagrams = count(/<Diagram[\s>/]/g);
+	const imgs = count(/<Img[\s>/]/g);
+	const mds = count(/<Md[\s>/]/g);
+	return {
+		intent: diagrams > 0 ? "diagram" : imgs > mds ? "moodboard" : "spec",
+		width: contentWidthOf(src)
+	};
+}
 /** id = path relative to design/, extension dropped, `scenes/` prefix dropped. Always `/`-separated. */
 function toFrameId(designRelPath) {
 	const noExt = designRelPath.split(sep).join("/").replace(FRAME_EXT, "");
@@ -256,12 +278,18 @@ function scanFrames(root) {
 			scene
 		};
 		if (kind === "tsx") {
-			const meta = extractMeta(readFileSync(abs, "utf8"));
+			const src = readFileSync(abs, "utf8");
+			const meta = extractMeta(src);
 			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;
+			const content = contentScan(src);
+			if (content || meta.intent) {
+				entry.intent = meta.intent ?? content.intent;
+				entry.contentWidth = content?.width ?? contentWidthOf(src);
+			}
 		}
 		frames.push(entry);
 	}

package/dist/{plugin-YVpBNTB3.mjs → plugin-Crp4CAma.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-mYlO_1Pj.mjs";
+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 { 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/dist/{serve-BvbAbWeK.mjs → serve-OtA9Nlow.mjs}

@@ -1,4 +1,4 @@
-import { t as NAME } from "./cli.mjs";
+import { n as NAME } from "./cli.mjs";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";
 import { createHmac, randomBytes, scryptSync, timingSafeEqual } from "node:crypto";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.2.4",
+  "version": "0.3.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,
@@ -14,10 +14,12 @@
     "templates",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "CHANGELOG.md"
   ],
   "exports": {
     "./runtime": "./src/client/runtime/index.ts",
+    "./content": "./src/client/content/index.tsx",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -30,6 +32,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^6.0.0",
     "cac": "^7.0.0",
+    "marked": "^16.0.0",
+    "mermaid": "^11.6.0",
     "react-zoom-pan-pinch": "^3.6.1",
     "vite": "^8.0.0",
     "zustand": "^5.0.0"

package/src/client/const.ts

@@ -3,3 +3,8 @@
 export const NAME = 'marver'
 export const PKG = '@marver-design/marver'   // registry identity; bin stays `marver`
 export const ROUTE = '/__mv'
+
+/** Content-frame natural widths (SPEC-026): Doc layout -> own-size width.
+ *  Shared by the Doc primitive (measurement messages) and the server-side
+ *  manifest scan (defaultSize for content frames) - one source, no drift. */
+export const CONTENT_WIDTH: Record<string, number> = { document: 760, wide: 1280 }

package/src/client/content/diagram.tsx

@@ -0,0 +1,96 @@
+/**
+ * The Diagram block - first-class Mermaid (SPEC-026).
+ * Mermaid is marver's dependency behind a dynamic import: a workspace with no
+ * Diagram loads no mermaid bytes. Source-level theme overrides (%%{init}%%,
+ * yaml frontmatter) are stripped so the marver palette always holds; the
+ * rendered SVG is sanitized of external references (strict securityLevel is
+ * not a no-network policy). A parse error renders an in-frame card - never a
+ * blank frame, never a tripped readiness timeout.
+ */
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { FONT_STACK, THEME_CSS, themeVars } from './palette.ts'
+
+let uidSeq = 0
+
+const isDark = () =>
+  document.documentElement.classList.contains('dark') || document.documentElement.dataset.theme === 'dark'
+
+/** Strip yaml frontmatter and %%{...}%% directives - diagram source cannot re-theme itself. */
+export function cleanSource(src: string): string {
+  return src
+    .replace(/^\s*---\r?\n[\s\S]*?\r?\n---\r?\n/, '')
+    .replace(/%%\{[\s\S]*?\}%%/g, '')
+    .trim()
+}
+
+/** 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')
+  const external = (v: string | null) => !!v && !v.trim().startsWith('#') && !v.trim().startsWith('data:')
+  for (const el of [...doc.querySelectorAll('image')]) el.remove()
+  for (const el of [...doc.querySelectorAll('script, foreignObject iframe')]) el.remove()
+  for (const el of [...doc.querySelectorAll('*')]) {
+    for (const attr of ['href', 'xlink:href']) {
+      if (external(el.getAttribute(attr))) el.removeAttribute(attr)
+    }
+  }
+  return new XMLSerializer().serializeToString(doc.documentElement)
+}
+
+export function Diagram({ title, children }: { title?: string; children?: ReactNode }) {
+  const src = 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}`)
+
+  useEffect(() => {
+    let live = true
+    let seq = 0
+    let renderSeq = 0
+    const render = async () => {
+      const mySeq = ++seq
+      try {
+        // the zero-external-request boundary must hold BEFORE render: mermaid's image
+        // shapes fetch their URL during render(), so post-render SVG sanitizing alone
+        // would be too late. Reject ANY URL shape - absolute (scheme://) and
+        // protocol-relative (//host) alike; neither has a place in diagram source.
+        if (/(?:\w+:)?\/\//.test(src)) throw new Error('URLs are not allowed in diagram source - use local design/assets/ images in an Img block instead')
+        const mermaid = (await import('mermaid')).default
+        if (!live || mySeq !== seq) return
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: 'strict',
+          theme: 'base',
+          themeVariables: themeVars(isDark()),
+          themeCSS: THEME_CSS,
+          fontFamily: FONT_STACK,
+        })
+        // unique id per render: mermaid mounts a temp element under it, and a
+        // superseded render must never collide with the one that lands
+        const { svg } = await mermaid.render(`${uid.current}-${++renderSeq}`, src)
+        if (!live || mySeq !== seq || !ref.current) return   // superseded by a newer theme - discard
+        ref.current.innerHTML = sanitizeSvg(svg)
+        setError(null)
+      } catch (e) {
+        if (live && mySeq === seq) setError(String((e as Error)?.message ?? e))
+      }
+    }
+    render()
+    // the bridge mutates <html data-theme>/.dark with no React event - observe and re-render
+    const mo = new MutationObserver(render)
+    mo.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme', 'class'] })
+    return () => { live = false; mo.disconnect() }
+  }, [src])
+
+  return (
+    <figure className="mv-block mv-diagram">
+      {/* the render target stays MOUNTED through errors - a healed source or theme
+          re-render must find its ref alive to clear the card */}
+      {error && <div className="mv-diagram-err"><b>diagram error</b><span>{error}</span><span className="dim">fix the mermaid source - the frame heals live</span></div>}
+      <div className="mv-diagram-svg" ref={ref} style={error ? { display: 'none' } : undefined} />
+      {title && <figcaption>{title}</figcaption>}
+    </figure>
+  )
+}