@marver-design/marver 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.16.0 - 2026-09-03
+
+### Added
+
+- **Board folders.** The sidebar's boards can live in folders, one level deep.
+  Right-click the Boards header (or its `+`) for a new folder and name it
+  inline - what you type becomes a slug ("Old stuff" → `old-stuff`, shown "Old
+  Stuff"); right-click a board for **Move to new folder** (the folder takes the
+  board's slot, the input has focus) or **Move to top level**; right-click a
+  folder to **Rename** or **Delete** it (its boards go back to the top level -
+  folders organise, never own). Moving into an existing folder is a **drag**:
+  the board drag-and-drop now lands boards inside folders (drop on the folder
+  row), in any slot inside one, back out to the root (or the left gutter of a
+  folder's rows), and drags folders among boards. A click collapses a folder; the
+  choice is remembered per browser. The folder holding the active board keeps
+  the ancestor wash so its home stays visible collapsed.
+- **Folders are files, for agents too.** `"folder": "<name>"` on a board file
+  puts it in a folder (`order` ranks it among its folder siblings);
+  `design/boards/_folders.json` names empty folders and ranks folders at the
+  root. A folder two boards name exists without the registry. The landing
+  board is the first board in sidebar order, folders included. **`npx marver
+  boards`** prints the sidebar as the files say it is (folders, boards in
+  reading order with their `order`, the landing board; `--json` for the tree),
+  so an agent looks before it organises. The agent contract and
+  `instructions/boards.md` carry the grammar, every move (create, file in,
+  move out, rank, rename, delete) as a file edit, and a nudge to group
+  proactively past six or eight boards.
+- **Published bundles** carry the folder tree of the published boards only; a
+  folder with nothing published never reaches the bundle. The published
+  sidebar shows folders read-only.
+- **Descriptions - purpose notes on every object, for agents.** One optional
+  `description` (one sentence: what it is for, its state) on the project
+  (`description` in `design/config.ts`), a board (its JSON - preserved by
+  autosave and by sidebar drags like `order`/`folder`), a folder (its
+  `_folders.json` entry - it rides along through renames), a scene (the first
+  non-blank line of its `_brief.md`, `#` stripped, front matter skipped - no
+  new file) and a frame
+  (`meta.description`). `design/manifest.json` becomes the orientation file it
+  was meant to be: `project`, `folders`, `boards` (sidebar order, with folder
+  and description), `scenes` (with description and brief path) and `frames`
+  (with description). `marver dev` regenerates it on board and brief edits too,
+  and broadcasts `sh:manifest` only when the frames changed - a description
+  edit never re-keys the live iframes. Published bundles ship descriptions of
+  published things only (brief paths only with source revealed). `marver
+  boards` prints them. Editing `description` in `design/config.ts` under `dev`
+  refreshes the manifest live (the rest of the config still needs a restart).
+  The agent contract teaches: write it at creation, keep it true, fix what your
+  session made false before it ends (the review walk ends on it). Nothing
+  renders in the canvas.
+- `export const meta` picks a literal even when the prose holds the other
+  quote (`"the buyer's path"`), and refuses a computed value (`"Draft" + phase`)
+  instead of taking its literal half.
+
+### Changed
+
+- `POST /__mv/api/boards/reorder` takes the WHOLE tree (`{ tree, base }`) in
+  place of `{ order }`: root boards as strings, folders as `{ folder, boards }`,
+  plus the sha256 the client last saw for every board it names and for the
+  registry. The server preflights every named board (present, a regular file,
+  well-formed, unchanged) BEFORE writing anything - a 409 names the stale
+  boards and the shell re-reads and replays its move once, so an agent's
+  concurrent `folder` edit and a human's drag can never silently erase each
+  other. It answers the new hashes, and the shell's autosave of the active
+  board keeps its CAS token current - a reorder no longer reboots the board
+  you are editing. `GET /__mv/api/boards` gains `folder`; `GET
+  /__mv/api/folders` is new.
+- Board enumeration (dev API, build, `--all-boards`) counts only regular files
+  on the board-name grammar: `_folders.json`, temp files and symlinks are never
+  boards - the build fails closed on a symlinked board. A malformed
+  `_folders.json` is a 422 the sidebar toasts (and a build error), never a
+  silently empty registry the next drag would overwrite.
+- The sidebar re-reads its list on a coalesced `sh:boards` broadcast (any add,
+  write or delete under `design/boards/`), so agent-written boards and folders
+  show in under half a second instead of the 8 s poll.
+
 ## 0.15.0 - 2026-09-02
 
 ### 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.
+- **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.
 - **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.
@@ -98,6 +98,7 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 | `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 |
 
 ## Shortcuts
 

package/dist/boards-6hKVW42a.mjs

@@ -0,0 +1,57 @@
+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 { join } from "node:path";
+//#region src/cli/boards.ts
+/**
+* `marver boards` - the sidebar as the agent sees it: every folder and board in reading
+* order, from the files (no dev server needed). One call answers "what folders exist, what
+* is in them, what ranks where" before the agent writes `folder` on a board or edits
+* `design/boards/_folders.json`. `--json` gives the tree shape the shell uses.
+*/
+function boardsCommand(root, opts) {
+	const dir = join(root, "design", "boards");
+	const de = checkBoardsDir(root, dir);
+	if (de) throw new Error(de);
+	const { boards, skipped } = listBoardFiles(dir);
+	const reg = readRegistry(dir);
+	if (reg.state === "malformed") throw new Error(reg.error);
+	const rows = boards.map((b) => ({
+		name: b.name,
+		...boardFields(b.json, isBoardName)
+	}));
+	const tree = buildTree(rows, reg.folders);
+	const hasAll = boards.some((b) => b.name === "all-scenes");
+	if (opts.json) {
+		console.log(JSON.stringify({
+			tree,
+			boards: rows.filter((r) => r.name !== "all-scenes"),
+			landing: flatten(tree)[0] ?? (hasAll ? "all-scenes" : null),
+			registry: reg.state === "ok" ? "design/boards/_folders.json" : null
+		}, null, 2));
+		return;
+	}
+	if (!tree.length && !hasAll) {
+		console.log("no boards yet - design/boards/ is empty");
+		return;
+	}
+	const order = (n) => {
+		const o = rows.find((r) => r.name === n)?.order;
+		return o === void 0 ? "" : `  order ${o}`;
+	};
+	const desc = (d) => d ? `  - ${d}` : "";
+	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)}`);
+			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)}`);
+		if (!it.boards.length) console.log("  (empty)");
+	}
+	if (hasAll) console.log("all-scenes  (auto, always last)");
+	const landing = flatten(tree)[0];
+	if (landing) console.log(`\nlanding board: ${landing}`);
+	console.log(`registry: ${reg.state === "ok" ? "design/boards/_folders.json" : "none (no empty or ranked folders yet)"}`);
+	if (skipped.length) console.log(`skipped (not regular files): ${skipped.join(", ")}`);
+}
+//#endregion
+export { boardsCommand };

package/dist/boards-BdG1TJwU.mjs

@@ -0,0 +1,267 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join, sep } from "node:path";
+import { createHash } from "node:crypto";
+//#region src/server/hash.ts
+/** sha256 hex of a string - the CAS token for board files, the registry, the manifest. */
+const hash = (s) => createHash("sha256").update(s).digest("hex");
+//#endregion
+//#region src/shared/board-tree.ts
+/**
+* Board folders - the pure tree shared by the sidebar, the dev API, the build and the
+* tests. Files are the truth: a board says which folder it sits in (`folder` on the
+* board file, ranked among its siblings by `order`), and `design/boards/_folders.json`
+* says which folders exist and where they rank at the root. One level only: folders
+* hold boards, never folders. `all-scenes` never enters the tree - callers pin it last.
+*/
+/** The on-disk name grammar shared by boards and folders (a board name is a filename). */
+const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const isBoardName = (n) => typeof n === "string" && n.length >= 1 && n.length <= 64 && BOARD_NAME.test(n);
+/** The folder registry beside the boards - underscore = infrastructure, never a board. */
+const FOLDERS_FILE = "_folders.json";
+/** Is this basename in design/boards/ a board file? `_folders.json`, temp files and any
+*  off-grammar name are not - every lister (dev API, build, watcher) shares this rule. */
+const isBoardFile = (f) => f.endsWith(".json") && isBoardName(f.slice(0, -5));
+const readDescription = (v) => {
+	if (typeof v !== "string") return void 0;
+	return v.trim().replace(/\s+/g, " ").slice(0, 300) || void 0;
+};
+const rank = (o) => typeof o === "number" && Number.isFinite(o) ? o : Infinity;
+/** 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. */
+function parseFolders(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "expected an object";
+	const { version, folders } = raw;
+	if (version !== void 0 && version !== 1) return `unsupported version ${String(version)}`;
+	if (!Array.isArray(folders)) return "expected a \"folders\" array";
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const f of folders) {
+		const name = f?.name;
+		if (!isBoardName(name)) return "a folder needs a name - lowercase letters, numbers and dashes";
+		if (seen.has(name)) return `folder "${name}" is listed twice`;
+		seen.add(name);
+		const o = f.order;
+		const d = readDescription(f.description);
+		out.push({
+			name,
+			...typeof o === "number" && Number.isFinite(o) ? { order: o } : {},
+			...d ? { description: d } : {}
+		});
+	}
+	return out;
+}
+/** 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. */
+function buildTree(boards, folders) {
+	const folderOrder = /* @__PURE__ */ new Map();
+	const folderDesc = /* @__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);
+	}
+	const members = /* @__PURE__ */ new Map();
+	const rootBoards = [];
+	for (const b of boards) {
+		if (!isBoardName(b.name) || b.name === "all-scenes") continue;
+		const folder = isBoardName(b.folder) ? b.folder : void 0;
+		if (!folder) {
+			rootBoards.push(b);
+			continue;
+		}
+		if (!folderOrder.has(folder)) folderOrder.set(folder, void 0);
+		const list = members.get(folder) ?? [];
+		list.push(b);
+		members.set(folder, list);
+	}
+	const byRank = (a, b) => rank(a.order) - rank(b.order) || a.name.localeCompare(b.name);
+	const root = [...rootBoards.map((b) => ({
+		item: {
+			kind: "board",
+			name: b.name
+		},
+		order: b.order
+	})), ...[...folderOrder].map(([name, order]) => ({
+		item: {
+			kind: "folder",
+			name,
+			boards: (members.get(name) ?? []).sort(byRank).map((b) => b.name),
+			...folderDesc.has(name) ? { description: folderDesc.get(name) } : {}
+		},
+		order
+	}))];
+	root.sort((a, b) => rank(a.order) - rank(b.order) || (a.item.kind === b.item.kind ? 0 : a.item.kind === "board" ? -1 : 1) || a.item.name.localeCompare(b.item.name));
+	return root.map((r) => r.item);
+}
+/** Every board in reading order - the order the switchers and the landing pick use. */
+function flatten(tree) {
+	const out = [];
+	for (const it of tree) if (it.kind === "board") out.push(it.name);
+	else out.push(...it.boards);
+	return out;
+}
+function validateWire(wire) {
+	if (!Array.isArray(wire)) return "invalid tree";
+	const boards = /* @__PURE__ */ new Set(), folders = /* @__PURE__ */ new Set();
+	const board = (n) => {
+		if (!isBoardName(n) || n === "all-scenes") return "invalid board name in tree";
+		if (boards.has(n)) return `board "${n}" appears twice`;
+		boards.add(n);
+		return null;
+	};
+	for (const w of wire) {
+		if (typeof w === "string") {
+			const e = board(w);
+			if (e) return e;
+			continue;
+		}
+		if (!w || typeof w !== "object" || Array.isArray(w)) return "invalid tree item";
+		const { folder, boards: kids, description } = w;
+		if (!isBoardName(folder)) return "invalid folder name in tree";
+		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);
+		if (!Array.isArray(kids)) return "invalid folder in tree";
+		for (const k of kids) {
+			const e = board(k);
+			if (e) return e;
+		}
+	}
+	if (boards.size > 200 || folders.size > 50) return "tree too large";
+	return null;
+}
+//#endregion
+//#region src/server/boards.ts
+/**
+* Reading design/boards/ safely - the one enumerator the dev API, the build and the tests
+* share. Only REGULAR files on the board-name grammar count as boards (a symlink, dangling or
+* live, could read or publish JSON from outside the project - it is skipped, and reported so
+* the build can fail closed). The folder registry is read the same way: absent = no folders,
+* malformed = an error the human must fix, never a silently empty registry.
+*/
+/** Does realpath(dir) stay inside realpath(root)? A symlinked design/boards can't escape. */
+function underRoot(root, dir) {
+	try {
+		const rr = realpathSync(root);
+		const rd = realpathSync(dir);
+		return rd === rr || rd.startsWith(rr + sep);
+	} catch {
+		return false;
+	}
+}
+/** Is design/boards a directory we may read and write? It must not be a symlink at all (a
+*  link to the repo root would list package.json as a board and let a tree write rewrite
+*  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"]]) {
+		try {
+			if (lstatSync(p).isSymbolicLink()) return `${label} must be a real directory, not a symlink`;
+		} catch {
+			return null;
+		}
+		if (!underRoot(root, p)) return `${label} escapes the project`;
+	}
+	return null;
+}
+/** A regular file (lstat: a symlink is never followed, a dangling one is not "absent"). */
+const isRegularFile = (p) => {
+	try {
+		return lstatSync(p).isFile();
+	} catch {
+		return false;
+	}
+};
+/** Is there ANY node at p (a dangling symlink counts)? */
+const nodeExists = (p) => {
+	try {
+		lstatSync(p);
+		return true;
+	} catch {
+		return false;
+	}
+};
+/** Every board file: name, raw content, hash, and its JSON (null when malformed). `skipped`
+*  names the entries that looked like boards but were not regular files. */
+function listBoardFiles(boardsDir) {
+	const boards = [], skipped = [];
+	if (!existsSync(boardsDir)) return {
+		boards,
+		skipped
+	};
+	for (const f of readdirSync(boardsDir)) {
+		if (!isBoardFile(f)) continue;
+		const file = join(boardsDir, f);
+		if (!isRegularFile(file)) {
+			skipped.push(f);
+			continue;
+		}
+		const content = readFileSync(file, "utf8");
+		let json = null;
+		try {
+			json = JSON.parse(content);
+		} catch {}
+		boards.push({
+			name: f.slice(0, -5),
+			file,
+			content,
+			sha256: hash(content),
+			json
+		});
+	}
+	return {
+		boards,
+		skipped
+	};
+}
+/** The author-owned sidebar fields off a board's JSON, leniently. */
+function boardFields(json, validName) {
+	const o = json;
+	const description = readDescription(o?.description);
+	return {
+		...typeof o?.order === "number" && Number.isFinite(o.order) ? { order: o.order } : {},
+		...validName(o?.folder) ? { folder: o.folder } : {},
+		...description ? { description } : {}
+	};
+}
+/** The folder registry. `sha256` is the CAS token a tree write must echo (null = "there was
+*  no file"), so a write can never silently replace a registry it never saw. */
+function readRegistry(boardsDir) {
+	const p = join(boardsDir, FOLDERS_FILE);
+	if (!nodeExists(p)) return {
+		state: "absent",
+		folders: [],
+		sha256: null
+	};
+	if (!isRegularFile(p)) return {
+		state: "malformed",
+		error: `design/boards/${FOLDERS_FILE} must be a regular file, not a symlink`,
+		sha256: null
+	};
+	const content = readFileSync(p, "utf8");
+	let raw;
+	try {
+		raw = JSON.parse(content);
+	} catch {
+		return {
+			state: "malformed",
+			error: `design/boards/${FOLDERS_FILE} is not valid JSON - fix the file`,
+			sha256: hash(content)
+		};
+	}
+	const parsed = parseFolders(raw);
+	if (typeof parsed === "string") return {
+		state: "malformed",
+		error: `design/boards/${FOLDERS_FILE}: ${parsed}`,
+		sha256: hash(content)
+	};
+	return {
+		state: "ok",
+		folders: parsed,
+		sha256: hash(content)
+	};
+}
+//#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 };

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

@@ -1,7 +1,8 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
-import { l as detectHost, r as scanFrames, s as loadConfig } from "./manifest-BzxSMoDB.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-DJyjmQeh.mjs";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+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 { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createHash, randomBytes } from "node:crypto";
@@ -148,22 +149,67 @@ function resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag) {
 		reveal
 	};
 }
-/** Read every board file; returns name -> parsed json. Bad JSON fails the build loudly. */
+/** Read every board file; returns name -> parsed json. Bad JSON fails the build loudly, and so
+*  does a board-named entry that is not a regular file (a symlink could publish JSON from
+*  outside the project - the build fails closed rather than skipping it quietly). */
 function readBoards(root) {
 	const dir = join(root, "design", "boards");
+	const de = checkBoardsDir(root, dir);
+	if (de) throw new Error(de);
+	const { boards, skipped } = listBoardFiles(dir);
+	if (skipped.length) throw new Error(`design/boards/${skipped[0]} is not a regular file (a symlinked board cannot be published)`);
 	const out = {};
-	if (!existsSync(dir)) return out;
-	for (const f of readdirSync(dir)) {
-		if (!f.endsWith(".json")) continue;
-		const name = f.replace(/\.json$/, "");
-		try {
-			out[name] = JSON.parse(readFileSync(join(dir, f), "utf8"));
-		} catch {
-			throw new Error(`design/boards/${f} is not valid JSON`);
-		}
+	for (const b of boards) {
+		if (b.json === null) throw new Error(`design/boards/${b.name}.json is not valid JSON`);
+		out[b.name] = b.json;
 	}
 	return out;
 }
+/** Switcher order = the sidebar's reading order: the folder tree over the PUBLISHED boards only
+*  (a folder left with no published board drops out - its name never reaches the bundle),
+*  flattened depth-first; all-scenes always LAST (it is the expensive everything-board, never
+*  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")
+	})), folders).filter((it) => it.kind === "board" || it.boards.length > 0);
+	return {
+		tree,
+		names: [...flatten(tree), ...published.includes("all-scenes") ? ["all-scenes"] : []]
+	};
+}
+/** The bundle's manifest: the published frames, and descriptions of published things ONLY -
+*  the project's, the published scenes' (their brief path only when source is revealed),
+*  the published boards' and the folders those sit in. No unpublished name or sentence. */
+function publishedManifest(manifest, pubFrames, publishedNames, strip) {
+	const pubScenes = new Set(pubFrames.map((f) => f.scene));
+	const pubBoardSet = new Set(publishedNames);
+	const pubBoards = (manifest.boards ?? []).filter((b) => pubBoardSet.has(b.name));
+	const pubFolderSet = new Set(pubBoards.map((b) => b.folder).filter(Boolean));
+	const pubFolders = (manifest.folders ?? []).filter((f) => pubFolderSet.has(f.name));
+	return {
+		...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 }) => ({
+			name,
+			frames: pubFrames.filter((f) => f.scene === name).length,
+			...description ? { description } : {},
+			...brief && !strip ? { brief } : {}
+		})),
+		frames: pubFrames
+	};
+}
+/** The folder registry: absent = no folders (boards still imply theirs); malformed fails the build. */
+function readFolders(root) {
+	const reg = readRegistry(join(root, "design", "boards"));
+	if (reg.state === "malformed") throw new Error(reg.error);
+	return reg.folders;
+}
 /**
 * The generated registry with OPAQUE keys - the source strip's half of the
 * bundle (01-sharing §6.2). Object keys are string literals that survive
@@ -267,18 +313,17 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 	const pkgDir = packageDir();
 	const clientDir = join(pkgDir, "src", "client");
 	const outDir = join(root, "design", ".dist");
-	const manifest = scanFrames(root);
+	const manifest = scanFrames(root, {
+		name: config.share.name || basename(root),
+		description: config.description
+	});
 	const allBoards = readBoards(root);
 	const policy = resolvePolicy(root, allBoards, boardsFlag, allBoardsFlag);
 	const rights = Object.fromEntries(Object.entries(policy.boards).map(([n, p]) => [n, p.max]));
 	const strip = !policy.reveal.source;
 	const buildSalt = randomBytes(16).toString("hex");
 	const opaquePath = (id, ext) => `__mv/f/mv${createHash("sha256").update(buildSalt).update(id).digest("hex").slice(0, 12)}${ext}`;
-	const boardOrder = (n) => {
-		const o = allBoards[n]?.order;
-		return typeof o === "number" && Number.isFinite(o) ? o : Infinity;
-	};
-	const publishedNames = Object.keys(rights).sort((a, b) => a === "all-scenes" ? 1 : b === "all-scenes" ? -1 : boardOrder(a) - boardOrder(b) || a.localeCompare(b));
+	const { tree, names: publishedNames } = publishedTree(Object.keys(rights), allBoards, readFolders(root));
 	const includeAll = publishedNames.includes("all-scenes");
 	const boards = {};
 	for (const n of publishedNames) if (allBoards[n]) boards[n] = allBoards[n];
@@ -288,17 +333,10 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 		for (const b of Object.values(boards)) for (const node of Array.isArray(b?.nodes) ? b.nodes : []) if (typeof node?.frame === "string") wanted.add(node.frame);
 		frames = manifest.frames.filter((f) => wanted.has(f.id));
 	}
-	const pubFrames = strip ? frames.map((f) => ({
+	const pubManifest = publishedManifest(manifest, strip ? frames.map((f) => ({
 		...f,
 		file: opaquePath(f.id, f.kind === "html" ? ".html" : "")
-	})) : frames;
-	const pubManifest = {
-		frames: pubFrames,
-		scenes: [...new Set(pubFrames.map((f) => f.scene))].sort().map((name) => ({
-			name,
-			frames: pubFrames.filter((f) => f.scene === name).length
-		}))
-	};
+	})) : frames, publishedNames, strip);
 	for (const n of publishedNames) {
 		const pb = policy.boards[n];
 		if (pb?.type !== "slides" && pb?.open !== "slides") continue;
@@ -330,6 +368,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag, embedSeeds) {
 		manifest: pubManifest,
 		boards,
 		names: publishedNames,
+		tree,
 		default: publishedNames.find((n) => n !== "all-scenes") ?? publishedNames[0],
 		rights,
 		policy: {
@@ -461,7 +500,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-CbpzSzJu.mjs");
+		const { ensurePoster } = await import("./poster-DOY7pax8.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

@@ -53,14 +53,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-QKNi9gvF.mjs");
+	const { init } = await import("./init-BQIpIpIv.mjs");
 	init(resolve(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-CdcIuhZJ.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -70,7 +70,7 @@ for (const [name, desc] of [["dev", "Start the local canvas (everything on: hot
 	await dev(resolve(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--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-Ct0iMoSi.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);
@@ -89,7 +89,7 @@ cli.command("serve", "Serve design/.dist (set MARVER_PASSWORD to gate it)").opti
 	serve(resolve(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);
 	} catch (err) {
@@ -115,6 +115,15 @@ cli.command("work <action> [...frames]", "Working state on the canvas: start <sc
 		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");
+	try {
+		boardsCommand(resolve(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");
 	try {

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