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

package/dist/{manifest-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.3",
+  "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 }