@marver-design/marver 0.15.0 → 0.16.1

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { cac } from "cac";
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/client/const.ts
@@ -51,29 +51,40 @@ function version() {
 		return "0.0.0";
 	}
 }
+/** The project root, REAL path. A root reached through a symlink (macOS's /var → /private/var,
+*  a linked projects folder) would be watched under the link while the OS reports events under
+*  the real path - and every frame add, brief edit and config change would go unseen. */
+const resolve$1 = (dir) => {
+	const p = resolve(dir);
+	try {
+		return realpathSync(p);
+	} catch {
+		return p;
+	}
+};
 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-QKNi9gvF.mjs");
-	init(resolve(opts.root), {
+	const { init } = await import("./init-B7YhcN2o.mjs");
+	init(resolve$1(opts.root), {
 		mode: opts.mode === "embedded" ? "embedded" : "studio",
 		demo: opts.demo !== false
 	});
 });
 for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot reload, comments, Live Jam)"], ["canvas", "Start the local canvas - same as dev"]]) cli.command(name, desc).option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-BxCmeU_H.mjs");
+	const { dev } = await import("./dev-DH2W7Ffw.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
 		if (Number.isInteger(n) && n > 0 && n < 65536) port = n;
 		else console.warn(`[${NAME}] ignoring invalid --port "${opts.port}"`);
 	}
-	await dev(resolve(opts.root), port);
+	await dev(resolve$1(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("--embed-seeds", "Copy comment history INTO the web root (identifying - every event carries its author's email)").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-DfuTQZlY.mjs");
+	const { buildSite } = await import("./build-B4yPgFNF.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, opts.embedSeeds === true);
+		await buildSite(resolve$1(opts.root), boards, opts.allBoards === true, opts.embedSeeds === true);
 	} catch (err) {
 		console.error(`[${NAME}] build failed: ${err.message}`);
 		process.exit(1);
@@ -86,12 +97,12 @@ cli.command("serve", "Serve design/.dist (set MARVER_PASSWORD to gate it)").opti
 		const n = Number(opts.port);
 		if (Number.isInteger(n) && n > 0 && n < 65536) port = n;
 	}
-	serve(resolve(opts.root), port);
+	serve(resolve$1(opts.root), port);
 });
 cli.command("comments <action> [value]", "Comment collaboration: connect <url> · sync · list · reply <thread> · resolve <thread> · invite <email> · revoke <email>").option("--root <dir>", "Host repo root", { default: "." }).option("--token <token>", "connect: the canvas's MARVER_CLI_TOKEN (default $MARVER_CLI_TOKEN) - the identity-mode path").option("--invite <token>", "connect: claim this invite instead of signing in").option("--canvas-password <password>", "connect: the canvas gate password (default $MARVER_PASSWORD or prompt)").option("--email <email>", "connect: account email (skips the prompt)").option("--password <password>", "connect: account password (skips the prompt - mind your shell history)").option("--name <name>", "connect --invite: display name for the new account").option("--open", "list: only unresolved threads").option("--json", "list: machine-readable output").option("--board <board>", "scope to one board").option("--body <text>", "reply: the reply text").option("--addressed-in <frame>", "resolve: the variant frame that answered the feedback").action(async (action, value, opts) => {
-	const { commentsCommand } = await import("./comments-DHB_8BRa.mjs");
+	const { commentsCommand } = await import("./comments-oYcZ3cE-.mjs");
 	try {
-		await commentsCommand(resolve(opts.root), action, value, opts);
+		await commentsCommand(resolve$1(opts.root), action, value, opts);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);
@@ -100,7 +111,7 @@ cli.command("comments <action> [value]", "Comment collaboration: connect <url>
 cli.command("share <action> [value]", "Sharing roster (owner): add <who> · remove <who> · block/unblock <email> · general <mode> · list · requests · explain <who> · who").option("--root <dir>", "Host repo root", { default: "." }).option("--role <role>", "add / requests --approve: view (default) or comment").option("--expires <iso>", "add: expiry timestamp, e.g. 2026-12-31T00:00:00Z").option("--approve <email>", "requests: approve this pending request (canvas-wide in v1)").option("--decline <email>", "requests: decline this pending request (silent to the asker)").option("--json", "list: machine-readable output").action(async (action, value, opts) => {
 	const { shareCommand } = await import("./share-Gqo_Ygqw.mjs");
 	try {
-		await shareCommand(resolve(opts.root), action, value, opts);
+		await shareCommand(resolve$1(opts.root), action, value, opts);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);
@@ -109,7 +120,16 @@ cli.command("share <action> [value]", "Sharing roster (owner): add <who> · remo
 cli.command("work <action> [...frames]", "Working state on the canvas: start <scene/frame ...> · done <scene/frame ...> | --all · list").option("--root <dir>", "Host repo root", { default: "." }).option("--ttl <minutes>", "start: minutes before the glow self-expires (default 10, max 30)").option("--all", "done: clear every working frame").action(async (action, frames, opts) => {
 	const { workCommand } = await import("./work-lzC-lPY0.mjs");
 	try {
-		await workCommand(resolve(opts.root), action, frames ?? [], opts);
+		await workCommand(resolve$1(opts.root), action, frames ?? [], opts);
+	} catch (err) {
+		console.error(`[${NAME}] ${err.message}`);
+		process.exit(1);
+	}
+});
+cli.command("boards", "The sidebar as files: every folder and board in reading order, the landing board, the registry").option("--root <dir>", "Host repo root", { default: "." }).option("--json", "The tree as JSON ({ tree, landing, registry })").action(async (opts) => {
+	const { boardsCommand } = await import("./boards-PuVzw5Wp.mjs");
+	try {
+		boardsCommand(resolve$1(opts.root), opts);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);
@@ -118,7 +138,7 @@ cli.command("work <action> [...frames]", "Working state on the canvas: start <sc
 cli.command("shot <frame>", "Render one frame headless and print the PNG path (needs `dev` running)").option("--root <dir>", "Host repo root", { default: "." }).option("--theme <name>", "Theme to render (default: light)").option("--scale <n>", "Device pixels per CSS px, 1-4 (default: 2; 4 for print-quality stills)").action(async (frame, opts) => {
 	const { shotCommand } = await import("./shot-By1AItpD.mjs");
 	try {
-		await shotCommand(resolve(opts.root), frame, opts);
+		await shotCommand(resolve$1(opts.root), frame, opts);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);

package/dist/{daemon-DalgvoA9.mjs → daemon-Bbh_jmui.mjs}

@@ -1,7 +1,7 @@
 import { n as replay } from "./events-B3LBn74P.mjs";
 import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
 import { n as localProfile } from "./profile-BjAPAJSb.mjs";
-import { i as toFrameId } from "./manifest-BzxSMoDB.mjs";
+import { i as toFrameId } from "./manifest-CaslQIAO.mjs";
 import { workActivity } from "./work-CLrmY-vQ.mjs";
 import { r as deviceId, t as has } from "./ledger-Bu0BjqIe.mjs";
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, writeSync } from "node:fs";

package/dist/{dev-BxCmeU_H.mjs → dev-DH2W7Ffw.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
-import { l as detectHost, s as loadConfig } from "./manifest-BzxSMoDB.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DJyjmQeh.mjs";
+import { l as detectHost, s as loadConfig } from "./manifest-CaslQIAO.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BeBGu3gH.mjs";
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -257,7 +257,7 @@ async function dev(root, portFlag) {
 	console.log(`\n  ${NAME} · ${projectName} → http://localhost:${port}/\n`);
 	try {
 		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
-		const { installedVersion } = await import("./plugin-DJyjmQeh.mjs").then((n) => n.i);
+		const { installedVersion } = await import("./plugin-BeBGu3gH.mjs").then((n) => n.i);
 		const stale = staleManagedInstructions(root);
 		if (stale.length) {
 			const shown = stale.slice(0, 4).join(", ") + (stale.length > 4 ? `, +${stale.length - 4} more` : "");
@@ -295,7 +295,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-DalgvoA9.mjs");
+		const { startJam } = await import("./daemon-Bbh_jmui.mjs");
 		const jam = startJam(root, config.jam, (m) => console.log(m), (board) => server.ws.send("sh:jam-comment", { board }));
 		if (jam) {
 			const close = server.close.bind(server);

package/dist/{init-QKNi9gvF.mjs → init-B7YhcN2o.mjs}

@@ -1,8 +1,8 @@
 import { n as NAME } from "./cli.mjs";
-import { a as writeManifest, c as detectAgent, l as detectHost, o as DEFAULTS, r as scanFrames, u as readJson } from "./manifest-BzxSMoDB.mjs";
+import { a as writeManifest, c as detectAgent, l as detectHost, n as scanFrames, o as DEFAULTS, u as readJson } from "./manifest-CaslQIAO.mjs";
 import { MANAGED_PREFIX, enumerateInstructionTemplates, hashBody, managedFile, pkgDir } from "./managed-HwHVNI3h.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 //#region src/cli/init.ts
 /** Idempotent scaffolder: never overwrites existing files; every host-repo touch prints a diff. */
 function init(root, opts) {
@@ -221,7 +221,7 @@ function init(root, opts) {
 		created.push("design/scenes/demo/ (3 frames)");
 	}
 	if (host.tsconfigSweepsDesign) patchTsconfigExclude(root);
-	writeManifest(root, scanFrames(root));
+	writeManifest(root, scanFrames(root, { name: basename(root) }));
 	console.log(`\n${NAME} initialized (${opts.mode} mode). Created:`);
 	for (const f of created) console.log(`  + ${f}`);
 	if (host.router === "next") console.log(`\n  note: Next.js support is partial - frames render outside Next, so next/font, next/image and Server Components do not exist inside them (details in design/AGENTS.md).`);
@@ -540,6 +540,9 @@ const configTemplate = (mode, jamAgent) => `// ${NAME} config - OPTIONAL. Delete
 // relative imports need extensions, tsconfig paths are ignored here.
 export default {
   mode: ${JSON.stringify(mode)},
+  // One sentence on what this product is and for whom. It lands in design/manifest.json
+  // as the project's description - the first thing a new agent session reads.
+  // description: "Analytics for indie SaaS - the founder's Monday-morning read",
   // Device widths for frames and the Devices view. Rename, retune, or uncomment tv.
   viewports: {
     mobile: { width: 390, height: 844 },

package/dist/{manifest-BzxSMoDB.mjs → manifest-CaslQIAO.mjs}

@@ -1,8 +1,9 @@
 import { r as PKG, t as CONTENT_WIDTH } from "./cli.mjs";
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { a as listBoardFiles, d as flatten, f as isBoardName, g as hash, m as readTitle, n as checkBoardsDir, p as readDescription, r as checkRealDirs, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { delimiter, isAbsolute, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
-import { createHash } from "node:crypto";
+import { randomBytes } from "node:crypto";
 //#region src/server/detect.ts
 function readJson(file) {
 	try {
@@ -261,6 +262,7 @@ async function loadConfig(root) {
 			themes: Array.isArray(user.themes) && user.themes.length ? user.themes.map(String) : DEFAULTS.themes,
 			port: validPort(user.port) ?? DEFAULTS.port,
 			zoomSpeed: validZoom(user.zoomSpeed) ?? DEFAULTS.zoomSpeed,
+			description: readDescription(user.description),
 			share: {
 				branding: user.share?.branding !== false,
 				name: typeof user.share?.name === "string" ? user.share.name : void 0,
@@ -379,8 +381,8 @@ function extractMeta(src) {
 	if (!m) return {};
 	const body = m[1];
 	const pick = (key) => {
-		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(['"\`])([^'"\`]*)\\1`).exec(body);
-		return r ? r[2] : void 0;
+		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(?:'([^'\\n]*)'|"([^"\\n]*)"|\`([^\`\\n]*)\`)\\s*(?=[,}\\n]|$)`).exec(body);
+		return r ? r[1] ?? r[2] ?? r[3] : void 0;
 	};
 	const pickBool = (key) => {
 		const r = new RegExp(`(?:^|[{,])\\s*${key}\\s*:\\s*(true|false)\\b`).exec(body);
@@ -401,6 +403,8 @@ function extractMeta(src) {
 	if (intent) out.intent = intent;
 	const slide = pickBool("slide");
 	if (slide !== void 0) out.slide = slide;
+	const description = readDescription(pick("description"));
+	if (description) out.description = description;
 	return out;
 }
 /** Content-frame detection: LEXICAL by convention - the frame file itself imports
@@ -473,7 +477,159 @@ function walk(dir, out = []) {
 	}
 	return out;
 }
-function scanFrames(root) {
+/** The YAML front matter at the top of a markdown file, read flat: `key: value` scalars,
+*  quoted (JSON-style double quotes, or single quotes with '' for one) or bare. `end` is the
+*  line the body starts at (0 = no block; an unclosed block swallows the file). */
+function frontMatter(lines) {
+	const fields = {};
+	if (lines[0]?.trim() !== "---") return {
+		fields,
+		end: 0
+	};
+	let close = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+	if (close < 0) close = lines.length;
+	for (const l of lines.slice(1, close)) {
+		const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(l.trim());
+		if (!m) continue;
+		let v = m[2].trim();
+		if (v.startsWith("\"")) try {
+			v = String(JSON.parse(v));
+		} catch {
+			v = v.replace(/^"|"$/g, "");
+		}
+		else if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) v = v.slice(1, -1).replace(/''/g, "'");
+		fields[m[1]] = v;
+	}
+	return {
+		fields,
+		end: Math.min(close + 1, lines.length)
+	};
+}
+/** A scene's title is `title` in its `_brief.md` front matter; its description is the first
+*  non-blank line after the block (a leading `#` stripped) - no new file. */
+function sceneBrief(root, scene) {
+	if (!scene) return {};
+	const rel = `design/scenes/${scene}/_brief.md`;
+	const abs = join(root, ...rel.split("/"));
+	if (!existsSync(abs)) return {};
+	let title, description;
+	try {
+		const lines = readFileSync(abs, "utf8").replace(/^\uFEFF/, "").split(/\r?\n/);
+		const fm = frontMatter(lines);
+		title = readTitle(fm.fields.title);
+		const line = lines.slice(fm.end).map((l) => l.trim()).find((l) => l);
+		description = readDescription(line?.replace(/^#+\s*/, ""));
+	} catch {}
+	return {
+		brief: rel,
+		...title ? { title } : {},
+		...description ? { description } : {}
+	};
+}
+/** Write a scene's title into its brief's front matter - only that line changes; the body,
+*  every other field and the file's own line endings are kept. No brief yet = a front-matter-only
+*  brief. An empty title removes the line, and the file when nothing else is in it. The write
+*  is atomic (temp + rename); a symlinked scene directory or brief, or a front matter block
+*  that never closes, is refused untouched - the brief is the agent's document, never rewritten
+*  from a guess. Returns the error, or null. */
+function setSceneTitle(root, scene, title) {
+	const design = join(root, "design"), scenes = join(design, "scenes"), dir = join(scenes, scene);
+	const de = checkRealDirs(root, [
+		[design, "design"],
+		[scenes, "design/scenes"],
+		[dir, `design/scenes/${scene}`]
+	]);
+	if (de) return de;
+	try {
+		if (!lstatSync(dir).isDirectory()) return `"${scene}" is not a scene directory`;
+	} catch {
+		return `scene "${scene}" does not exist`;
+	}
+	const file = join(dir, "_brief.md");
+	let had = false;
+	try {
+		if (!lstatSync(file).isFile()) return `design/scenes/${scene}/_brief.md is not a regular file - refusing to write it`;
+		had = true;
+	} catch {}
+	const text = had ? readFileSync(file, "utf8") : "";
+	const bom = text.startsWith("") ? "" : "";
+	const raw = text.slice(bom.length);
+	const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+	const lines = raw.split(/\r?\n/);
+	const fm = frontMatter(lines);
+	if (fm.end === lines.length && lines[0]?.trim() === "---" && !lines.slice(1).some((l) => l.trim() === "---")) return `design/scenes/${scene}/_brief.md: the front matter never closes - fix the file`;
+	const line = title ? [`title: ${JSON.stringify(title)}`] : [];
+	let out;
+	if (fm.end === 0) {
+		if (!title) return null;
+		out = [
+			"---",
+			...line,
+			"---",
+			...raw.trim() ? ["", ...lines] : [""]
+		];
+	} else {
+		const close = Math.max(1, fm.end - 1);
+		const kept = lines.slice(1, close).filter((l) => !/^title\s*:/.test(l.trim()));
+		const body = lines.slice(fm.end);
+		out = kept.length || title ? [
+			"---",
+			...line,
+			...kept,
+			"---",
+			...body
+		] : body;
+	}
+	if (!out.join("").trim()) {
+		if (had) rmSync(file);
+		return null;
+	}
+	const tmp = join(dir, `.brief-${randomBytes(6).toString("hex")}.tmp`);
+	try {
+		writeFileSync(tmp, bom + out.join(eol));
+		renameSync(tmp, file);
+	} catch (err) {
+		rmSync(tmp, { force: true });
+		throw err;
+	}
+	return null;
+}
+/** The sidebar as files say it is, for the manifest: folders in root order, boards in
+*  reading order with their folder and description. A boards dir we may not read (symlink)
+*  or a malformed registry yields nothing here - the API and the build say why; the
+*  orientation file must never fail to write. */
+function scanBoards(root) {
+	const dir = join(root, "design", "boards");
+	if (checkBoardsDir(root, dir)) return {};
+	const reg = readRegistry(dir);
+	if (reg.state === "malformed") return {};
+	const rows = listBoardFiles(dir).boards.map((b) => ({
+		name: b.name,
+		...boardFields(b.json, isBoardName)
+	}));
+	const tree = buildTree(rows, reg.folders);
+	const folderOf = /* @__PURE__ */ new Map();
+	for (const it of tree) if (it.kind === "folder") for (const b of it.boards) folderOf.set(b, it.name);
+	const folders = tree.filter((it) => it.kind === "folder").map((it) => ({
+		name: it.name,
+		...it.title ? { title: it.title } : {},
+		...it.description ? { description: it.description } : {}
+	}));
+	const boards = flatten(tree).map((name) => {
+		const r = rows.find((x) => x.name === name);
+		return {
+			name,
+			...folderOf.has(name) ? { folder: folderOf.get(name) } : {},
+			...r?.title ? { title: r.title } : {},
+			...r?.description ? { description: r.description } : {}
+		};
+	});
+	return {
+		...folders.length ? { folders } : {},
+		...boards.length ? { boards } : {}
+	};
+}
+function scanFrames(root, project) {
 	const design = join(root, "design");
 	const frames = [];
 	for (const base of ["scenes", "components"]) for (const abs of walk(join(design, base))) {
@@ -502,6 +658,7 @@ function scanFrames(root) {
 			if (meta.of) entry.variantGroup = meta.of;
 			if (meta.variant) entry.variant = meta.variant;
 			if (meta.slide) entry.slide = true;
+			if (meta.description) entry.description = meta.description;
 			const content = contentScan(src);
 			if (content || meta.intent) {
 				entry.intent = meta.intent ?? content.intent;
@@ -527,12 +684,19 @@ function scanFrames(root) {
 	inferVariantGroups(frames);
 	const sceneCounts = /* @__PURE__ */ new Map();
 	for (const f of frames) sceneCounts.set(f.scene, (sceneCounts.get(f.scene) ?? 0) + 1);
+	const scenes = [...sceneCounts.entries()].map(([name, n]) => ({
+		name,
+		frames: n,
+		...sceneBrief(root, name)
+	})).sort((a, b) => a.name.localeCompare(b.name));
 	return {
-		frames,
-		scenes: [...sceneCounts.entries()].map(([name, n]) => ({
-			name,
-			frames: n
-		})).sort((a, b) => a.name.localeCompare(b.name))
+		...project && (project.name || project.description) ? { project: {
+			...project.name ? { name: project.name } : {},
+			...project.description ? { description: project.description } : {}
+		} } : {},
+		...scanBoards(root),
+		scenes,
+		frames
 	};
 }
 /** Variant groups. A group = 2+ frames in one DIRECTORY whose basenames
@@ -614,6 +778,5 @@ function writeManifest(root, manifest) {
 	writeFileSync(file, next);
 	return true;
 }
-const hash = (s) => createHash("sha256").update(s).digest("hex");
 //#endregion
-export { writeManifest as a, detectAgent as c, toFrameId as i, detectHost as l, hash as n, DEFAULTS as o, scanFrames as r, loadConfig as s, affectedFrameIds as t, readJson as u };
+export { writeManifest as a, detectAgent as c, toFrameId as i, detectHost as l, scanFrames as n, DEFAULTS as o, setSceneTitle as r, loadConfig as s, affectedFrameIds as t, readJson as u };