@marver-design/marver 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,170 @@
 
 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
+
+- **Copy frame as image.** The floating toolbar gains an images-square button
+  (right of Copy path): one click puts the selected frame on the clipboard as
+  a **2x PNG**, rendered by the dev server's headless Chrome - the same picture
+  `marver shot` gives an agent. `i` is the shortcut; `⇧i` (or shift-click)
+  renders at **4x** (a slide is 5120×2880). The icon breathes while the render
+  runs and flashes a check on success, like Copy path. Sized to the node: a
+  frame resized to Laptop copies as Laptop; content frames capture in full;
+  slides are always the 1280×720 artwork. Dev canvases only - a published
+  container has no browser - and one frame at a time.
+- **`marver shot --scale <1-4>`** and `scale=`/`w=`/`h=`/`format=png` on
+  `/api/shot`. A frame too tall for the asked scale steps down (4 → 2 → 1)
+  inside a 16384px-per-side / 64M-pixel capture budget and reports it in
+  `note`; the file name carries the scale actually used (`…@4x.png`), so a
+  4x file always holds 4x pixels.
+- **Render settle.** Every shot (not only content frames) now waits - bounded
+  to 3 s, and again in the final viewport of a full-height capture - for fonts,
+  in-viewport images, LOD decodes, echarts instances and mermaid diagrams before
+  capturing, so a slide with a chart or a photo is never shot half-drawn. Shot
+  file names: a default request keeps its unsuffixed name whatever scale the
+  capture settled on; an explicit scale gets `@4x`, or `@4x-as-2x` when it had
+  to step down, so nothing an agent reads moves and `@4x` never lies.
+
+### Changed
+
+- **Three standing rules for the agent, from dogfooding** (`AGENTS.md`,
+  `boards.md`, `iterate.md`, `jam.md` - refreshed by `marver init`):
+  - **One horizontal band by default.** Every curated board carries a `layout`
+    recipe with the scenes side by side; a second band only when the agent can
+    say why the eye should move down, with a gap that reads as "below". (Without
+    a recipe the shell stacks every scene as its own row.)
+  - **Look sideways.** A pin or a pasted pointer marks where the human noticed
+    a problem, not the only place it lives: the agent checks the board's live
+    sibling frames, fixes the same defect in the same pass and names the frames,
+    or asks in-thread whether to roll it out - never one frame fixed and its
+    siblings left wrong. History (`archive/`, versions) is never a sibling.
+  - **Version the scene before a round.** A round of feedback on a reviewed
+    scene starts with a snapshot, `design/scenes/<scene>-v<N>/`, pinned as its
+    own band on the `archive` board (oldest at the top), with `data-goto`,
+    `goto:` links and `meta.of` re-pointed so the version plays on its own; then
+    the live frames are edited in place and threads answered. One snapshot per
+    round, git commits per version on offer, staging only the round's paths.
+    Rollback is a copy back; the archive is the proof of work.
+
+### Fixed
+
+- **Charts everywhere, not only on slides.** `Chart` now takes its ink and
+  typeface from the frame it sits in (a UI screen's Tailwind colour and font, a
+  Doc's tokens, a Slide's), sizes its type to the context (12px labels in a
+  screen or document, 18px on a slide), paints series labels in that ink with
+  no halo, follows the layout on resize (a chart no longer pins its flex/grid
+  column at mount width), and keys on the option's content so a parent
+  re-render never re-initialises it (a viewer's dataZoom or legend selection
+  survives, and a formatter edit reaches the live chart). Before this a chart
+  in a dark screen or dark spec drew dark-on-dark axis text at slide scale.
+- **Video plays everywhere, not only on slides.** The player used to mount
+  only under the slides-mode contract, so a `Video` in a screen, a spec or a
+  published prototype was a poster forever. Now the poster is the play button
+  wherever the frame is live (interact, play, focus, published); slides keep
+  the auto-mounted player, and leaving interact mode on the canvas disarms a
+  playing clip so the frame goes still again. New: `ratio="9 / 16"` for
+  vertical clips, and `autoplay` for a muted ambient loop (an explicit choice -
+  that frame stays live on the canvas). The player's glyphs are Phosphor
+  (play, pause, speaker, corners). `shape.md` and `craft.md` teach it.
+- **Posters render themselves.** A local clip without `poster` no longer fails
+  the build: marver renders `<clip>.poster.png` beside it from the clip's own
+  first moments (at 0.5 s, past the usual black opening) in the same headless
+  Chrome the shot renderer uses - the dev server on first sight (the frame
+  asks when its conventional poster is missing), `marver build` before assets
+  are copied, and `shot` before a frame's first capture. Posters render on
+  their own capture lane, so a frame's poster never waits behind the shot that
+  needs it. An authored poster always wins; without Chrome the build says
+  exactly which file to add.
+- **A screen with a chart is still a screen.** Importing anything from
+  `@marver-design/marver/content` used to turn the frame into a content
+  document (spec badge, measured height, no device). Content frames are now
+  those that render `Doc`, `Md`, `Diagram` or `Img`; `Chart`, `Video`, `Row`,
+  `Col` and `Space` are shared blocks a screen or a slide uses freely. The
+  block card (padding, hairline, surface) is a document treatment: inside a
+  slide or a screen a block is bare, so charts no longer carry 32px of
+  invisible padding there. `shape.md` and `craft.md` now teach `Chart`.
+- **Dev server behind a symlinked path.** `marver dev` on a repo reached
+  through a symlink (`/tmp` → `/private/tmp`, a linked Dropbox folder) refused
+  to serve its own frames ("outside of Vite serving allow list"); the allow
+  list now carries the realpath too.
+
 ## 0.14.0 - 2026-09-02
 
 ### Added

package/README.md

@@ -40,11 +40,13 @@ 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.
 - **Content frames.** Specs, Mermaid diagrams, mood boards, and slides live on the same canvas as the screens - import `Doc`, `Md`, `Diagram`, `Img`, `Slide`, `Chart`, `Video` from `@marver-design/marver/content` and think a feature through before any pixels exist. Works in a repo with no app at all: idea first, design second.
+- **Charts and video in any frame.** `Chart` (Apache ECharts, SVG, still at rest) inherits the ink, typeface and accent of whatever frame it sits in - a Tailwind dashboard, a dark spec, a slide - sizes its type to the context and follows the layout on resize. `Video` is poster-first everywhere: click to play wherever the frame is live, `autoplay` for an ambient loop, `ratio` for vertical clips; omit the poster and marver renders one from the clip. A screen with a chart or a clip is still a screen.
+- **Copy as image.** Select a frame, press `i` - a 2x PNG of it lands on the clipboard, rendered by the same headless Chrome that serves `marver shot`; `⇧i` for 4x (a slide is 5120×2880). Paste into Slack, a doc, or a chat with your agent.
 
 ## Slides
 
@@ -82,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>` renders one frame headless to a PNG, so the agent can look at what it built before it says it is done.
+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.
 
 ## Commands
 
@@ -95,7 +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>` | Render one frame headless and print the PNG path (needs `dev` running) |
+| `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
 
@@ -108,7 +111,7 @@ The same glow, driven from the terminal. When your agent takes a request, it cre
 
 **Board & chrome** - `t` tidy · `d` toggle light/dark for the board · `⌘\` (ctrl+\) collapse/open sidebar.
 
-**Selection** - click selects · shift+click (canvas or sidebar) builds a multi-selection · `⌘A` selects every frame on the board · `⇧P` copies the selected frames' paths (board, frame, and file) · double-click enters interact mode (`esc` or click outside leaves) · drag the title bar to move, edges to resize (widths snap to devices).
+**Selection** - click selects · shift+click (canvas or sidebar) builds a multi-selection · `⌘A` selects every frame on the board · `⇧P` copies the selected frames' paths (board, frame, and file) · `i` copies the selected frame to the clipboard as a 2x PNG (`⇧i` for 4x; also the images-square button in the floating toolbar - dev canvases only, the renderer is the dev server's headless Chrome) · double-click enters interact mode (`esc` or click outside leaves) · drag the title bar to move, edges to resize (widths snap to devices).
 
 **Modes** - `c` comment mode · `l` laser mode · `⇧C` hide/show comment pins · `⇧L` laser comment (spotlight a thread's element) · `p` play (present, or slides on a slides board) · `h` hide all chrome.
 

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 };