@marver-design/marver 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.17.0 - 2026-09-04
+
+### Added
+
+- **Shots in batch.** `npx marver shot a b c`, `--scene <name>` or `--all` render many
+  frames as ONE operation: one headless browser, several frames at a time inside it
+  (`MARVER_SHOT_CONCURRENCY`, default up to 6 sized to the machine). `POST /api/shots`
+  and the jam inbox (`{"scene":...}`, `{"frames":[...]}`, `{"all":true}`) take the same
+  ask; every frame answers for itself (`results[]`, in the order asked). Measured on a
+  31-frame canvas: 65 s of one-at-a-time calls becomes 8 s; a 5-frame scene, 10 s
+  becomes 2 s; a single shot, 2.1 s becomes 1.05 s.
+- A capture that ran out of settle budget says so: `unsettled: true` and a note, instead
+  of a silently half-drawn PNG.
+
+### Fixed
+
+- **A shot's Chrome could outlive the server** - Ctrl-C, a closed terminal or `kill -9`
+  mid-shot left a headless copy of the user's own Chrome running for ever, and on macOS
+  such a ghost can swallow every link the machine opens. The browser is now driven over
+  Chrome's debugging pipe, so it dies with the server however the server dies, and none
+  exists between shots. The first `marver dev` after upgrading kills the ghosts and
+  removes the profiles earlier versions left in the temp dir.
+- Chrome starts and opens tabs several times faster: a stale `--disable-gpu` flag was
+  costing ~0.5 s per start and per tab.
+
+## 0.16.1 - 2026-09-03
+
+### Added
+
+- **Titles.** Boards, folders and scenes can be called anything - "MVP", "UI",
+  "Checkout (v2) 🛒". Rename in the sidebar (scenes too, now) edits a `title`;
+  the file name, folder key and scene directory stay the slug agents address.
+  No title = the Title-Cased slug, as before. Stored on the board JSON, the
+  `_folders.json` entry and the brief's YAML front matter; shown everywhere the
+  object is named and carried by the manifest and `npx marver boards`.
+
+### Fixed
+
+- **Drops land where the seam shows.** A board grabbed by its icon and dragged
+  between two folder boards landed after the folder; releases in blank space did
+  nothing. The resolver now reads the pointer against the rendered rows, the
+  release applies the seam on screen, and a release outside the panel cancels.
+- A project reached through a symlink (macOS `/var`, a linked projects folder)
+  lost its live updates; the CLI now resolves the root's real path.
+
+### Changed
+
+- `boards/rename` takes `{ from, to?, title?, baseHash? }` (title-only, CAS);
+  new `scenes/rename { scene, title }`; `sh:scenes` relabels scenes without
+  re-keying iframes.
+
 ## 0.16.0 - 2026-09-03
 
 ### Added

package/README.md

@@ -40,7 +40,7 @@ Frames appear on the canvas the moment the files land. That's the loop.
 
 ## The canvas
 
-- **Frames, scenes, boards.** Frames are screens, scenes group them (`design/scenes/<scene>/<frame>.tsx`), boards arrange them. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed. Right-click any board, scene, or frame in the sidebar to copy its path - the exact string to paste to your agent - and rename or drag-reorder boards from there too. Boards can live in folders: right-click the Boards header (or its `+`) for a new one, name it inline, drag boards in and out and folders among boards; agents do the same by writing `"folder": "<name>"` on a board and `design/boards/_folders.json` for empty or ranked folders (`npx marver boards` prints the tree). Every object takes a one-sentence `description` (project in `design/config.ts`, boards and folders in their JSON, a scene's first `_brief.md` line, `meta.description` on a frame) and `design/manifest.json` carries them all - a new agent session orients in one read.
+- **Frames, scenes, boards.** Frames are screens, scenes group them (`design/scenes/<scene>/<frame>.tsx`), boards arrange them. Agents write `design/boards/<name>.json` (a frame list is enough); switch boards at the top of the sidebar. `all-scenes` is auto-managed. Right-click any board, scene, or frame in the sidebar to copy its path - the exact string to paste to your agent - and rename or drag-reorder boards from there too. Boards can live in folders: right-click the Boards header (or its `+`) for a new one, name it inline, drag boards in and out (the seam shows exactly where a release lands) and folders among boards; agents do the same by writing `"folder": "<name>"` on a board and `design/boards/_folders.json` for empty or ranked folders (`npx marver boards` prints the tree). Boards, folders and scenes take a `title` - any name you like, "MVP", "UI", "Checkout (v2) 🛒" - while their file, key and directory stay the slug agents address; Rename in the sidebar edits the title. Every object takes a one-sentence `description` (project in `design/config.ts`, boards and folders in their JSON, a scene's first `_brief.md` line, `meta.description` on a frame) and `design/manifest.json` carries them all - a new agent session orients in one read.
 - **Devices view.** Hotkeys `1`-`5` (or the Devices menu) size every frame to mobile / tablet / laptop / monitor / tv to sweep your breakpoints; `0` restores your own layout exactly. Widths live in `design/config.ts`.
 - **Prototype links.** `data-goto="scene/frame"` on any element links frames into a walkable prototype - across boards, too.
 - **Five ways to view a board.** The canvas (frames on a plane), the board (the same, tidy), **present** (`p`: a full-screen clickable walkthrough - `data-goto` navigates, arrows step, `[` / `]` cycle variants, laser, comments, theme and device pickers in the toolbar), **focus** (one frame as a document - the reading preset for specs), and **slides** (a deck). A published board names its landing view; a frame deep link opens straight into it.
@@ -84,7 +84,7 @@ The trust boundary is hard: only comments written on the owner's machine trigger
 
 ## Working state
 
-The same glow, driven from the terminal. When your agent takes a request, it creates the frame files first, pins them on a board, and runs `npx marver work start <scene/frame ...>` - you see the work land on the canvas in seconds, watch it shimmer while subagents build in parallel, and see it settle on `work done`. Marks self-expire, so a crashed agent never leaves a frame glowing. And `npx marver shot <scene/frame> [--scale 4]` renders one frame headless to a PNG, so the agent can look at what it built before it says it is done - the same picture you get from the canvas's copy-as-image.
+The same glow, driven from the terminal. When your agent takes a request, it creates the frame files first, pins them on a board, and runs `npx marver work start <scene/frame ...>` - you see the work land on the canvas in seconds, watch it shimmer while subagents build in parallel, and see it settle on `work done`. Marks self-expire, so a crashed agent never leaves a frame glowing. And `npx marver shot --scene <scene>` (or `<scene/frame ...>`, `--all`; `[--scale 4]`) renders frames headless to PNGs - a whole scene in one browser, several frames at a time - so the agent can look at what it built before it says it is done - the same picture you get from the canvas's copy-as-image.
 
 ## Commands
 
@@ -97,8 +97,8 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 | `npx marver share …` | The roster (owner): `add <who> [--role]` · `remove` · `block` / `unblock` · `general <mode>` · `list` · `requests` · `explain <who>` · `who` |
 | `npx marver comments …` | The agent's queue: `connect <url>` · `sync` · `list` · `reply` · `resolve` · `invite <email>` · `revoke <email>` |
 | `npx marver work …` | Working glow from the terminal: `start <scene/frame …>` · `done … \| --all` · `list` |
-| `npx marver shot <frame> [--scale 1-4]` | Render one frame headless and print the PNG path (needs `dev` running); 2x by default |
-| `npx marver boards [--json]` | The sidebar as the files say it is: folders, boards in reading order with `order` and description, the landing board |
+| `npx marver shot <frame ...> \| --scene <name> \| --all [--scale 1-4] [--json]` | Render frames headless and print the PNG paths (needs `dev` running); a scene is one browser, several frames at a time; 2x by default |
+| `npx marver boards [--json]` | The sidebar as the files say it is: folders, boards in reading order with their title, `order` and description, the landing board |
 
 ## Shortcuts
 

package/dist/{boards-BdG1TJwU.mjs → boards-BmxcT3Lc.mjs}

@@ -25,7 +25,16 @@ const readDescription = (v) => {
 	if (typeof v !== "string") return void 0;
 	return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
 };
+const readTitle = (v) => {
+	if (typeof v !== "string") return void 0;
+	return Array.from(v.replace(/[\u0000-\u001f\u007f]/g, " ").trim().replace(/\s+/g, " ")).slice(0, 120).join("").trim() || void 0;
+};
 const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
+/** A folder's title and description, present only when set. */
+const folderExtras = (it) => ({
+	...it.title ? { title: it.title } : {},
+	...it.description ? { description: it.description } : {}
+});
 /** The registry file's shape. Returns the rows, or a string naming what is wrong - a
 *  malformed registry is an ERROR the human must fix (silently reading it as empty would
 *  let the next drag overwrite their folders), while a missing file is simply no folders. */
@@ -42,10 +51,12 @@ function parseFolders(raw) {
 		if (seen.has(name)) return `folder "${name}" is listed twice`;
 		seen.add(name);
 		const o = f.order;
+		const t = readTitle(f.title);
 		const d = readDescription(f.description);
 		out.push({
 			name,
 			...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
+			...t ? { title: t } : {},
 			...d ? { description: d } : {}
 		});
 	}
@@ -53,13 +64,15 @@ function parseFolders(raw) {
 }
 /** Sidebar order from the files. Root: boards with no folder + every folder (registered
 *  or implied by a board), ranked by `order` then kind (board before folder) then name.
-*  Inside a folder: its boards by `order` then name. Unranked sorts after ranked. */
+*  Inside a folder: its boards by `order` then name. Unranked sorts after ranked. A folder's
+*  title and description ride on its item (they live in the registry a tree write rewrites);
+*  a board's title stays with its row - it lives in the board's own file. */
 function buildTree(boards, folders) {
 	const folderOrder = /* @__PURE__ */ new Map();
-	const folderDesc = /* @__PURE__ */ new Map();
+	const folderMeta = /* @__PURE__ */ new Map();
 	for (const f of folders) if (isBoardName(f.name) && !folderOrder.has(f.name)) {
 		folderOrder.set(f.name, f.order);
-		if (f.description) folderDesc.set(f.name, f.description);
+		folderMeta.set(f.name, folderExtras(f));
 	}
 	const members = /* @__PURE__ */ new Map();
 	const rootBoards = [];
@@ -87,7 +100,7 @@ function buildTree(boards, folders) {
 			kind: "folder",
 			name,
 			boards: (members.get(name) ?? []).sort(byRank).map((b) => b.name),
-			...folderDesc.has(name) ? { description: folderDesc.get(name) } : {}
+			...folderMeta.get(name) ?? {}
 		},
 		order
 	}))];
@@ -117,8 +130,9 @@ function validateWire(wire) {
 			continue;
 		}
 		if (!w || typeof w !== "object" || Array.isArray(w)) return "invalid tree item";
-		const { folder, boards: kids, description } = w;
+		const { folder, boards: kids, title, description } = w;
 		if (!isBoardName(folder)) return "invalid folder name in tree";
+		if (title !== void 0 && (typeof title !== "string" || Array.from(title).length > 120)) return "invalid folder title";
 		if (description !== void 0 && (typeof description !== "string" || description.length > 300)) return "invalid folder description";
 		if (folders.has(folder)) return `folder "${folder}" appears twice`;
 		folders.add(folder);
@@ -155,8 +169,14 @@ function underRoot(root, dir) {
 *  it; a link outside would publish foreign JSON) and must resolve inside the root. Absent
 *  is fine (no boards yet). Returns the error, or null. */
 function checkBoardsDir(root, boardsDir) {
-	const design = join(boardsDir, "..");
-	for (const [p, label] of [[design, "design"], [boardsDir, "design/boards"]]) {
+	return checkRealDirs(root, [[join(boardsDir, ".."), "design"], [boardsDir, "design/boards"]]);
+}
+/** Every EXISTING path in `dirs` (root-down order) must be a real directory inside the root -
+*  a symlinked `design` with no boards dir yet would otherwise be followed by the mkdir that
+*  creates it; a symlinked `design/scenes` would let a brief write land outside the project.
+*  An absent one ends the walk (nothing beneath it exists either). Returns the error, or null. */
+function checkRealDirs(root, dirs) {
+	for (const [p, label] of dirs) {
 		try {
 			if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
 		} catch {
@@ -216,13 +236,16 @@ function listBoardFiles(boardsDir) {
 		skipped
 	};
 }
-/** The author-owned sidebar fields off a board's JSON, leniently. */
+/** The author-owned sidebar fields off a board's JSON, leniently: rank, folder, the title
+*  humans see, the sentence agents read. */
 function boardFields(json, validName) {
 	const o = json;
+	const title = readTitle(o?.title);
 	const description = readDescription(o?.description);
 	return {
 		...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
 		...validName(o?.folder) ? { folder: o.folder } : {},
+		...title ? { title } : {},
 		...description ? { description } : {}
 	};
 }
@@ -264,4 +287,4 @@ function readRegistry(boardsDir) {
 	};
 }
 //#endregion
-export { nodeExists as a, FOLDERS_FILE as c, isBoardName as d, readDescription as f, listBoardFiles as i, buildTree as l, hash as m, checkBoardsDir as n, readRegistry as o, validateWire as p, isRegularFile as r, BOARD_NAME as s, boardFields as t, flatten as u };
+export { listBoardFiles as a, BOARD_NAME as c, flatten as d, isBoardName as f, hash as g, validateWire as h, isRegularFile as i, FOLDERS_FILE as l, readTitle as m, checkBoardsDir as n, nodeExists as o, readDescription as p, checkRealDirs as r, readRegistry as s, boardFields as t, buildTree as u };

package/dist/{boards-6hKVW42a.mjs → boards-PuVzw5Wp.mjs}

@@ -1,4 +1,4 @@
-import { d as isBoardName, i as listBoardFiles, l as buildTree, n as checkBoardsDir, o as readRegistry, t as boardFields, u as flatten } from "./boards-BdG1TJwU.mjs";
+import { a as listBoardFiles, d as flatten, f as isBoardName, n as checkBoardsDir, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
 import { join } from "node:path";
 //#region src/cli/boards.ts
 /**
@@ -37,14 +37,19 @@ function boardsCommand(root, opts) {
 		const o = rows.find((r) => r.name === n)?.order;
 		return o === void 0 ? "" : `  order ${o}`;
 	};
+	const title = (t) => t ? `  "${t}"` : "";
 	const desc = (d) => d ? `  - ${d}` : "";
+	const boardLine = (n) => {
+		const r = rows.find((x) => x.name === n);
+		return `${n}${title(r?.title)}${order(n)}${desc(r?.description)}`;
+	};
 	for (const it of tree) {
 		if (it.kind === "board") {
-			console.log(`${it.name}${order(it.name)}${desc(rows.find((r) => r.name === it.name)?.description)}`);
+			console.log(boardLine(it.name));
 			continue;
 		}
-		console.log(`${it.name}/  (folder, ${it.boards.length} board${it.boards.length === 1 ? "" : "s"}${reg.folders.some((f) => f.name === it.name) ? "" : ", implied by its boards - not in _folders.json"})${desc(it.description)}`);
-		for (const b of it.boards) console.log(`  ${b}${order(b)}${desc(rows.find((r) => r.name === b)?.description)}`);
+		console.log(`${it.name}/${title(it.title)}  (folder, ${it.boards.length} board${it.boards.length === 1 ? "" : "s"}${reg.folders.some((f) => f.name === it.name) ? "" : ", implied by its boards - not in _folders.json"})${desc(it.description)}`);
+		for (const b of it.boards) console.log(`  ${boardLine(b)}`);
 		if (!it.boards.length) console.log("  (empty)");
 	}
 	if (hasAll) console.log("all-scenes  (auto, always last)");

package/dist/{build-Ct0iMoSi.mjs → build-D_g53Bp2.mjs}

@@ -1,7 +1,7 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
-import { i as listBoardFiles, l as buildTree, n as checkBoardsDir, o as readRegistry, u as flatten } from "./boards-BdG1TJwU.mjs";
-import { c as detectHost, n as scanFrames, o as loadConfig } from "./manifest-CpbsqQ_v.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BXyezwfN.mjs";
+import { a as listBoardFiles, d as flatten, f as isBoardName, n as checkBoardsDir, s as readRegistry, t as boardFields, u as buildTree } from "./boards-BmxcT3Lc.mjs";
+import { l as detectHost, n as scanFrames, s as loadConfig } from "./manifest-CaslQIAO.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-D2msH1cj.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -171,11 +171,9 @@ function readBoards(root) {
 *  the landing). `names[0]` is where `/` opens. Folder names of published boards are structure,
 *  like board names: they ship. */
 function publishedTree(published, allBoards, folders) {
-	const field = (n, k) => allBoards[n]?.[k];
 	const tree = buildTree(published.filter((n) => n !== "all-scenes").map((n) => ({
 		name: n,
-		order: field(n, "order"),
-		folder: field(n, "folder")
+		...boardFields(allBoards[n], isBoardName)
 	})), folders).filter((it) => it.kind === "board" || it.boards.length > 0);
 	return {
 		tree,
@@ -195,9 +193,10 @@ function publishedManifest(manifest, pubFrames, publishedNames, strip) {
 		...manifest.project ? { project: manifest.project } : {},
 		...pubFolders.length ? { folders: pubFolders } : {},
 		...pubBoards.length ? { boards: pubBoards } : {},
-		scenes: manifest.scenes.filter((s) => pubScenes.has(s.name)).map(({ name, description, brief }) => ({
+		scenes: manifest.scenes.filter((s) => pubScenes.has(s.name)).map(({ name, title, description, brief }) => ({
 			name,
 			frames: pubFrames.filter((f) => f.scene === name).length,
+			...title ? { title } : {},
 			...description ? { description } : {},
 			...brief && !strip ? { brief } : {}
 		})),
@@ -364,11 +363,16 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 			"slides"
 		].includes(p.open);
 	});
+	const titles = Object.fromEntries(publishedNames.flatMap((n) => {
+		const t = boardFields(allBoards[n], isBoardName).title;
+		return t ? [[n, t]] : [];
+	}));
 	const data = {
 		manifest: pubManifest,
 		boards,
 		names: publishedNames,
 		tree,
+		...Object.keys(titles).length ? { titles } : {},
 		default: publishedNames.find((n) => n !== "all-scenes") ?? publishedNames[0],
 		rights,
 		policy: {
@@ -500,7 +504,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	const realAssets = existsSync(assetsDir) ? realpathSync(assetsDir) : null;
 	for (const r of refs) {
 		if (!isLocalAssetRef(r) || !r.endsWith(".poster.png") || existsSync(join(assetsDir, r))) continue;
-		const { ensurePoster } = await import("./poster-DOY7pax8.mjs");
+		const { ensurePoster } = await import("./poster-BEjUcQP3.mjs");
 		const g = await ensurePoster(assetsDir, r.slice(0, -11));
 		if (!g.ok) throw new Error(`design/assets/${r}: ${g.error}`);
 		console.log(`  poster: rendered design/assets/${r} (${g.width}×${g.height})`);

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-BQIpIpIv.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-CdcIuhZJ.mjs");
+	const { dev } = await import("./dev-LnIISva5.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-Ct0iMoSi.mjs");
+	const { buildSite } = await import("./build-D_g53Bp2.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-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,25 +120,25 @@ 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-6hKVW42a.mjs");
+	const { boardsCommand } = await import("./boards-PuVzw5Wp.mjs");
 	try {
-		boardsCommand(resolve(opts.root), opts);
+		boardsCommand(resolve$1(opts.root), opts);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);
 	}
 });
-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");
+cli.command("shot [...frames]", "Render frames headless and print the PNG paths (needs `dev` running): ids, --scene <name> or --all").option("--root <dir>", "Host repo root", { default: "." }).option("--scene <name>", "Every frame of one scene").option("--all", "Every frame of the canvas").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)").option("--json", "Print the results as JSON ({ results: [...] }) instead of paths").action(async (frames, opts) => {
+	const { shotCommand } = await import("./shot-BzQ0PXKH.mjs");
 	try {
-		await shotCommand(resolve(opts.root), frame, opts);
+		await shotCommand(resolve$1(opts.root), frames, opts);
 	} catch (err) {
 		console.error(`[${NAME}] ${err.message}`);
 		process.exit(1);

package/dist/{daemon-Cb4JjpgL.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 { r as toFrameId } from "./manifest-CpbsqQ_v.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-CdcIuhZJ.mjs → dev-LnIISva5.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
-import { c as detectHost, o as loadConfig } from "./manifest-CpbsqQ_v.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BXyezwfN.mjs";
+import { l as detectHost, s as loadConfig } from "./manifest-CaslQIAO.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-D2msH1cj.mjs";
 import { realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -255,9 +255,14 @@ async function dev(root, portFlag) {
 	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`);
+	setTimeout(async () => {
+		try {
+			await (await import("./shot-DlmTO8AF.mjs")).sweepGhosts((m) => console.log(`  ${m}`));
+		} catch {}
+	}, 0);
 	try {
 		const { staleManagedInstructions } = await import("./managed-HwHVNI3h.mjs");
-		const { installedVersion } = await import("./plugin-BXyezwfN.mjs").then((n) => n.i);
+		const { installedVersion } = await import("./plugin-D2msH1cj.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 +300,7 @@ async function dev(root, portFlag) {
 		});
 	}
 	if (config.jam) {
-		const { startJam } = await import("./daemon-Cb4JjpgL.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-BQIpIpIv.mjs → init-B7YhcN2o.mjs}

@@ -1,5 +1,5 @@
 import { n as NAME } from "./cli.mjs";
-import { a as DEFAULTS, c as detectHost, i as writeManifest, l as readJson, n as scanFrames, s as detectAgent } from "./manifest-CpbsqQ_v.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 { basename, dirname, join, relative } from "node:path";

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

@@ -1,8 +1,9 @@
 import { r as PKG, t as CONTENT_WIDTH } from "./cli.mjs";
-import { d as isBoardName, f as readDescription, i as listBoardFiles, l as buildTree, m as hash, n as checkBoardsDir, o as readRegistry, t as boardFields, u as flatten } from "./boards-BdG1TJwU.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 { randomBytes } from "node:crypto";
 //#region src/server/detect.ts
 function readJson(file) {
 	try {
@@ -476,29 +477,123 @@ function walk(dir, out = []) {
 	}
 	return out;
 }
-/** A scene's description is the first non-blank line of its `_brief.md` (a leading `#`
-*  stripped, a YAML front-matter block skipped) - no new file. */
+/** 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 description;
+	let title, description;
 	try {
-		const lines = readFileSync(abs, "utf8").split(/\r?\n/).map((l) => l.trim());
-		let i = 0;
-		if (lines[0] === "---") {
-			i = lines.indexOf("---", 1) + 1;
-			if (i === 0) i = lines.length;
-		}
-		const line = lines.slice(i).find((l) => l);
+		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
@@ -517,14 +612,16 @@ function scanBoards(root) {
 	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 d = rows.find((r) => r.name === name)?.description;
+		const r = rows.find((x) => x.name === name);
 		return {
 			name,
 			...folderOf.has(name) ? { folder: folderOf.get(name) } : {},
-			...d ? { description: d } : {}
+			...r?.title ? { title: r.title } : {},
+			...r?.description ? { description: r.description } : {}
 		};
 	});
 	return {
@@ -682,4 +779,4 @@ function writeManifest(root, manifest) {
 	return true;
 }
 //#endregion
-export { DEFAULTS as a, detectHost as c, writeManifest as i, readJson as l, scanFrames as n, loadConfig as o, toFrameId as r, detectAgent as s, affectedFrameIds as t };
+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 };