@marver-design/marver 0.15.0 → 0.16.0

package/src/client/shell/store.ts

@@ -12,6 +12,8 @@ import shData from 'virtual:sh-data'
  *  is where `/` opens - never a synthesized aggregate of a filtered build. */
 const DATA: {
   manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string
+  /** the sidebar's folder tree over the published boards (0.16.0 bundles; older ones have none) */
+  tree?: TreeItem[]
   /** publish.json v2: per-board artifact type + open/lock, and the reveal flags. */
   policy?: { boards: Record<string, { type?: string; open?: string; lock?: boolean }>; reveal?: { structure?: boolean; source?: boolean }; lockedShell?: boolean }
 } | null = shData
@@ -123,19 +125,42 @@ export const modeAllowed = (board: string, mode: 'present' | 'focus' | 'slides')
 export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
 import { canAutoReload } from './canvas/ready-watch.ts'
+import { buildTree, flatten, toWire, type TreeItem } from '../../shared/board-tree.ts'
 
-/** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
- *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
+/** The CAS tokens a tree write echoes: the sha256 of every board file as last seen, and of
+ *  the folder registry (null = there was no file). */
+export interface TreeBase { boards: Record<string, string>; folders: string | null }
+export interface TreeSnapshot { tree: TreeItem[]; base: TreeBase }
+
+/** The sidebar tree: root boards and folders in rank order, each folder's boards inside
+ *  (shared/board-tree.ts), plus the hashes it was built from. `all-scenes` is not in it - it
+ *  is pinned last by the callers. Throws on transport failure and on a malformed registry
+ *  (the server's 422 message) - callers keep their last known tree. */
+export async function fetchBoardTree(): Promise<TreeSnapshot> {
+  if (DATA) return { tree: DATA.tree ?? DATA.names.filter((n) => n !== 'all-scenes').map((n) => ({ kind: 'board', name: n })), base: { boards: {}, folders: null } }
+  const [boards, reg] = await Promise.all([
+    fetch(`${ROUTE}/api/boards`).then((r) => r.json()) as Promise<{ name: string; sha256: string; order?: number; folder?: string }[]>,
+    fetch(`${ROUTE}/api/folders`).then(async (r) => {
+      const j = await r.json() as { folders?: { name: string; order?: number }[]; sha256?: string | null; error?: string }
+      if (!r.ok) throw new Error(j?.error ?? `folders ${r.status}`)
+      return j
+    }),
+  ])
+  return {
+    tree: buildTree(boards, reg.folders ?? []),
+    base: { boards: Object.fromEntries(boards.map((b) => [b.name, b.sha256])), folders: reg.sha256 ?? null },
+  }
+}
+
+/** Board names for switchers: the sidebar's reading order (folders flattened depth-first) and
+ *  the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
  *  Throws on transport failure - callers keep their last known list. */
 export async function fetchBoardNames(): Promise<string[]> {
   if (DATA) return DATA.names
-  const list: { name: string; order?: number }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
-  const curated = list
-    .filter((b) => b.name !== 'all-scenes')
-    .sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || a.name.localeCompare(b.name))
-    .map((b) => b.name)
-  return [...curated, 'all-scenes']
+  return [...flatten((await fetchBoardTree()).tree), 'all-scenes']
 }
+/** Does the switcher carry the auto `all-scenes` board? Always in dev; published only when it shipped. */
+export const HAS_ALL_SCENES = !DATA || DATA.names.includes('all-scenes')
 /** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
 export const boardLabel = (n: string) => humanize(n)
 
@@ -280,7 +305,7 @@ interface State {
   resizeSelected(name: string | null): void
   switchBoard(name: string): Promise<void>
   renameBoard(from: string, to: string): Promise<{ ok: boolean; error?: string }>
-  reorderBoards(order: string[]): Promise<boolean>
+  arrangeBoards(tree: TreeItem[], base: TreeBase): Promise<{ ok: true } | { ok: false; stale: boolean; error?: string }>
   pulsePath(): void
   copyFrameImage(scale: 2 | 4): void
   setScale(s: number): void
@@ -317,8 +342,18 @@ export const useStore = create<State>((set, get) => {
   let editRev = 0                                    // bumps per edit; a stale save response may never clear dirty over a newer edit
   let loadSeq = 0                                    // stale boot() responses never overwrite a newer board
   let switchSeq = 0                                  // last click wins when board switches race
-  let renameLock = false                             // while a board file is being renamed, autosave must not fire against the OLD name (a mustExist PUT would 409-gone and clear dirty, losing the in-flight edit)
-  const scheduleSave = () => { editRev++; if (renameLock) return; clearTimeout(saveTimer); saveTimer = setTimeout(() => get().save(), 500) }
+  // While a board file is being renamed or rewritten by a structural write (rename, the
+  // sidebar's tree arrange), autosave must not fire against it (a mustExist PUT would
+  // 409-gone and clear dirty, losing the in-flight edit; a stale baseHash would 409 and
+  // reload). A COUNT, not a flag: two holders never release each other. Structural writes
+  // also run one at a time through `structChain`, so a rename can never interleave a
+  // tree write on the same file.
+  let saveHolds = 0
+  const holdSaves = () => { saveHolds++; clearTimeout(saveTimer) }
+  const releaseSaves = () => { if (--saveHolds === 0 && get().dirty) scheduleSave() }
+  let structChain: Promise<unknown> = Promise.resolve()
+  const structural = <T,>(fn: () => Promise<T>): Promise<T> => { const p = structChain.then(fn, fn); structChain = p.catch(() => {}); return p }
+  const scheduleSave = () => { editRev++; if (saveHolds > 0) return; clearTimeout(saveTimer); saveTimer = setTimeout(() => get().save(), 500) }
 
   // One cancelable, BOARD-SCOPED reflow after content measurements settle.
   // The captured board name is the generation guard - a debounce surviving a board
@@ -616,43 +651,66 @@ export const useStore = create<State>((set, get) => {
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
     },
 
-    async renameBoard(from, to) {
-      const active = from === get().board
-      // Renaming the ACTIVE board renames its file out from under the autosave. Flush any
-      // pending write FIRST (switchBoard's pattern), so a mustExist PUT never races the move.
-      if (active) {
-        let ok = true
-        for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
-        if (get().dirty) return { ok: false, error: 'unsaved changes - try again' }
-        // hold autosave across the round-trip: an edit landing mid-rename must NOT save to the
-        // old name (a mustExist PUT would 409-gone and clear dirty, losing the edit)
-        renameLock = true
-        clearTimeout(saveTimer)
-      }
-      // Release the lock and resume autosave. Re-read the LIVE board, not the captured `active`:
-      // a board switch may have completed while we awaited, so only the board that is STILL
-      // `from` gets renamed to `to` in state (a switched-away board keeps its own name/nodes).
-      const release = () => { if (active) { renameLock = false; if (get().dirty) scheduleSave() } }
-      let res: Response
-      try { res = await postOwner('boards/rename', { from, to }) }
-      catch { release(); return { ok: false, error: 'could not reach the dev server' } }
-      if (!res.ok) {
-        release()
-        const e = await res.json().catch(() => ({} as { error?: string }))
-        return { ok: false, error: e?.error ?? `rename failed (${res.status})` }
-      }
-      // Content is byte-identical after a file move, so boardHash still matches for the next
-      // autosave; only the name (and the URL, via the board-change subscription) changes. Set
-      // the new name BEFORE releasing the lock so a resumed save targets `to`.
-      if (active && get().board === from) set({ board: to })
-      release()
-      return { ok: true }
+    renameBoard(from, to) {
+      return structural(async () => {
+        const active = from === get().board
+        // Renaming the ACTIVE board renames its file out from under the autosave. Flush any
+        // pending write FIRST (switchBoard's pattern), so a mustExist PUT never races the move.
+        if (active) {
+          let ok = true
+          for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
+          if (get().dirty) return { ok: false, error: 'unsaved changes - try again' }
+          // hold autosave across the round-trip: an edit landing mid-rename must NOT save to the
+          // old name (a mustExist PUT would 409-gone and clear dirty, losing the edit)
+          holdSaves()
+        }
+        // Release the hold and resume autosave. Re-read the LIVE board, not the captured `active`:
+        // a board switch may have completed while we awaited, so only the board that is STILL
+        // `from` gets renamed to `to` in state (a switched-away board keeps its own name/nodes).
+        try {
+          let res: Response
+          try { res = await postOwner('boards/rename', { from, to }) }
+          catch { return { ok: false, error: 'could not reach the dev server' } }
+          if (!res.ok) {
+            const e = await res.json().catch(() => ({} as { error?: string }))
+            return { ok: false, error: e?.error ?? `rename failed (${res.status})` }
+          }
+          // Content is byte-identical after a file move, so boardHash still matches for the next
+          // autosave; only the name (and the URL, via the board-change subscription) changes. Set
+          // the new name BEFORE releasing the hold so a resumed save targets `to`.
+          if (active && get().board === from) set({ board: to })
+          return { ok: true }
+        } finally { if (active) releaseSaves() }   // whatever happened, autosave resumes
+      })
     },
 
-    async reorderBoards(order) {
-      let res: Response
-      try { res = await postOwner('boards/reorder', { order }) } catch { return false }
-      return res.ok
+    // The whole sidebar tree in one write: order, membership, the folders themselves. The
+    // write rewrites the ACTIVE board's file too (its `order`/`folder`), so it runs like a
+    // rename: flush the pending autosave first, hold autosave across the round-trip, then
+    // advance boardHash to the hash the server answered - the autosave's CAS token stays
+    // true and the watcher's echo is filtered as our own. `base` carries the hashes the
+    // sidebar last saw; a 409 (`stale`) means someone else wrote first - refetch and replay.
+    arrangeBoards(tree, base) {
+      return structural(async () => {
+        let ok = true
+        for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
+        if (get().dirty) return { ok: false as const, stale: false, error: 'unsaved changes - try again' }
+        holdSaves()
+        try {
+          // the active board's hash is freshest in the store (an autosave may have landed since
+          // the sidebar looked); every other board's is the sidebar's
+          const active = get().board
+          const boards = { ...base.boards, ...(get().boardHash && base.boards[active] !== undefined ? { [active]: get().boardHash } : {}) }
+          let res: Response
+          try { res = await postOwner('boards/reorder', { tree: toWire(tree), base: { boards, folders: base.folders } }) }
+          catch { return { ok: false as const, stale: false, error: 'could not reach the dev server' } }
+          const body = await res.json().catch(() => ({} as { error?: string; sha256?: { boards?: Record<string, string> } }))
+          if (!res.ok) return { ok: false as const, stale: res.status === 409, error: body?.error }
+          const sha = body?.sha256?.boards?.[get().board]
+          if (sha) set({ boardHash: sha })
+          return { ok: true as const }
+        } finally { releaseSaves() }   // whatever happened, autosave resumes
+      })
     },
 
     applyManifest(m) {
@@ -1141,7 +1199,7 @@ export const useStore = create<State>((set, get) => {
     save() {
       // a rename is moving this board's file - defer every save so nothing writes to the OLD
       // name mid-move (renameBoard reschedules once the move commits under the new name)
-      if (renameLock) return Promise.resolve(false)
+      if (saveHolds > 0) return Promise.resolve(false)
       // a resize gesture in flight = torn state (new sizes, pre-recipe positions):
       // even a PREVIOUSLY scheduled timer must defer to the gesture-end save
       if (get().gesture && resizedInGesture) { scheduleSave(); return Promise.resolve(false) }

package/src/client/shell/styles.css

@@ -505,9 +505,38 @@ body.sh-commenting .sh-lean { opacity: 0 }
 .sh-panel .it.board.drop-before::after { top: -1px }
 .sh-panel .it.board.drop-after::after { bottom: -1px }
 /* inline rename: the input wears the row's own type so the swap is seamless */
-.sh-panel .it.board.editing { cursor: default }
-.sh-panel .it.board.editing input { flex: 1; min-width: 0; padding: 0; border: 0; outline: 0; background: none;
+.sh-panel .it.board.editing, .sh-panel .it.folder.editing { cursor: default }
+.sh-panel .it.editing input { flex: 1; min-width: 0; padding: 0; border: 0; outline: 0; background: none;
   color: var(--glass-ink); font: inherit }
+.sh-panel .it.editing input::placeholder { color: var(--glass-ink-3) }
+/* folders: one level, same row grammar as boards (idle icon tertiary, count tertiary). A folder
+   holding the current board wears the ancestor wash so the active board's home survives a
+   collapse; its boards indent one step. Folder rows share the board seam rules; dropping INTO a
+   folder lights the whole row (wash + brand-blue ring) instead of a seam. */
+.sh-panel .it.folder svg { color: var(--glass-ink-3); flex: none; margin: 0 1px; transition: color .2s ease }
+.sh-panel .it.folder[data-reorderable]:active { cursor: grabbing }
+.sh-panel .it.folder.dragging { opacity: .4 }
+.sh-panel .it.folder.drop-before, .sh-panel .it.folder.drop-after { position: relative }
+.sh-panel .it.folder.drop-before::after, .sh-panel .it.folder.drop-after::after {
+  content: ''; position: absolute; left: 6px; right: 6px; height: 3px; border-radius: 3px;
+  background: #0088ff; pointer-events: none }
+.sh-panel .it.folder.drop-before::after { top: -1px }
+.sh-panel .it.folder.drop-after::after { bottom: -1px }
+.sh-panel .it.folder.drop-into { background: var(--accent-wash); box-shadow: inset 0 0 0 1.5px #0088ff }
+.sh-panel .it.folder.drop-into svg { color: #0088ff }
+.sh-panel .it.board.in-folder { padding-left: 28px }
+.sh-panel .it.board.draft { cursor: default; opacity: .6 }
+/* seams inside a folder are indented with its rows, so "inside" and "at the root" never draw alike */
+.sh-panel .it.board.in-folder.drop-before::after, .sh-panel .it.board.in-folder.drop-after::after { left: 28px }
+/* the Boards header carries a quiet folder-plus: tertiary, shows on hover of the header row */
+.sh-panel .sh-boards .hd { display: flex; align-items: center; margin-right: 6px }
+.sh-panel .sh-boards .hd span { flex: 1 }
+/* a bare glyph, no button chrome (padding would shrink it): tertiary, pointer, full ink on hover */
+.sh-panel .sh-hd-add { flex: none; color: var(--glass-ink-3); cursor: pointer; outline: none; border-radius: 4px;
+  opacity: 0; transition: opacity .15s ease, color .15s ease }
+.sh-panel .sh-boards .hd:hover .sh-hd-add, .sh-panel .sh-hd-add:focus-visible { opacity: 1 }
+.sh-panel .sh-hd-add:hover { color: var(--glass-ink) }
+.sh-panel .sh-hd-add:focus-visible { box-shadow: 0 0 0 2px var(--accent) }
 /* frame rows: one indent in (aligned to the label line), quieter ink */
 .sh-panel .sub { display: flex; align-items: center; height: 28px; padding: 0 8px 0 31px; margin-bottom: 1px;
   color: var(--glass-ink-2); font-size: 13px; font-weight: 400; border-radius: 8px; cursor: pointer }
@@ -562,8 +591,11 @@ body.sh-commenting .sh-lean { opacity: 0 }
   cursor: pointer; text-align: left }
 .sh-menu button:hover { background: var(--glass-hover) }
 .sh-menu button span { flex: 1; text-transform: capitalize }
-/* the sidebar right-click menu keeps its labels verbatim (they match the toolbar exactly) */
-.sh-ctxmenu button span { text-transform: none }
+/* the sidebar right-click menu keeps its labels verbatim (they match the toolbar exactly);
+   it scrolls rather than overflowing the window when the folder list grows long */
+.sh-ctxmenu { max-height: calc(100vh - 16px); max-width: 240px; overflow-y: auto; scrollbar-width: thin }
+.sh-ctxmenu button { flex: none; max-width: 100% }
+.sh-ctxmenu button span { text-transform: none; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; min-width: 0 }
 .sh-menu .chk { color: var(--glass-accent) }
 .sh-menu kbd { font: 500 10.5px -apple-system, system-ui, sans-serif; color: var(--glass-ink-3); background: none; border: 0 }
 .sh-menu .div { height: 1px; background: var(--glass-brd); margin: 4px 6px }

package/src/shared/board-tree.ts

@@ -0,0 +1,285 @@
+/**
+ * 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). */
+export const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/
+export const NAME_MAX = 64
+export const isBoardName = (n: unknown): n is string => typeof n === 'string' && n.length >= 1 && n.length <= NAME_MAX && BOARD_NAME.test(n)
+
+/** The folder registry beside the boards - underscore = infrastructure, never a board. */
+export 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. */
+export const isBoardFile = (f: string): boolean => f.endsWith('.json') && isBoardName(f.slice(0, -5))
+
+export type Folder = { kind: 'folder'; name: string; boards: string[]; description?: string }
+export type TreeItem = { kind: 'board'; name: string } | Folder
+
+export interface BoardRow { name: string; order?: number; folder?: string }
+export interface FolderRow { name: string; order?: number; description?: string }
+
+/** A description off a file: one sentence, trimmed, capped - absent when empty or not a string. */
+export const DESCRIPTION_MAX = 300
+export const readDescription = (v: unknown): string | undefined => {
+  if (typeof v !== 'string') return undefined
+  const s = v.trim().replace(/\s+/g, ' ').slice(0, DESCRIPTION_MAX)
+  return s || undefined
+}
+
+const rank = (o: number | undefined) => (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. */
+export function parseFolders(raw: unknown): FolderRow[] | string {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return 'expected an object'
+  const { version, folders } = raw as { version?: unknown; folders?: unknown }
+  if (version !== undefined && version !== 1) return `unsupported version ${String(version)}`
+  if (!Array.isArray(folders)) return 'expected a "folders" array'
+  const out: FolderRow[] = []
+  const seen = new Set<string>()
+  for (const f of folders) {
+    const name = (f as { name?: unknown })?.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 as { order?: unknown }).order
+    const d = readDescription((f as { description?: unknown }).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. */
+export function buildTree(boards: BoardRow[], folders: FolderRow[]): TreeItem[] {
+  const folderOrder = new Map<string, number | undefined>()
+  const folderDesc = new Map<string, string>()
+  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 = new Map<string, BoardRow[]>()
+  const rootBoards: BoardRow[] = []
+  for (const b of boards) {
+    if (!isBoardName(b.name) || b.name === 'all-scenes') continue
+    const folder = isBoardName(b.folder) ? b.folder : undefined
+    if (!folder) { rootBoards.push(b); continue }
+    if (!folderOrder.has(folder)) folderOrder.set(folder, undefined)   // implied by the board alone
+    const list = members.get(folder) ?? []
+    list.push(b)
+    members.set(folder, list)
+  }
+  const byRank = (a: BoardRow, b: BoardRow) => rank(a.order) - rank(b.order) || a.name.localeCompare(b.name)
+  type Root = { item: TreeItem; order: number | undefined }
+  const root: Root[] = [
+    ...rootBoards.map((b) => ({ item: { kind: 'board', name: b.name } as TreeItem, 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) } : {}) } as TreeItem,
+      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. */
+export function flatten(tree: TreeItem[]): string[] {
+  const out: string[] = []
+  for (const it of tree) { if (it.kind === 'board') out.push(it.name); else out.push(...it.boards) }
+  return out
+}
+
+/** The wire shape of a tree write (`POST boards/reorder`): plain strings for root boards,
+ *  `{ folder, boards }` for folders - what the sidebar posts and what the server validates. */
+export type WireItem = string | { folder: string; boards: string[]; description?: string }
+export const toWire = (tree: TreeItem[]): WireItem[] =>
+  tree.map((it) => (it.kind === 'board' ? it.name : { folder: it.name, boards: [...it.boards], ...(it.description ? { description: it.description } : {}) }))
+export const fromWire = (wire: WireItem[]): TreeItem[] =>
+  wire.map((w) => (typeof w === 'string' ? { kind: 'board', name: w } : { kind: 'folder', name: w.folder, boards: [...w.boards], ...(w.description ? { description: w.description } : {}) }))
+
+/** Validate a wire tree off the network. Returns the error, or null when it is sound:
+ *  every name on-grammar, `all-scenes` nowhere, no board twice, no folder twice, no
+ *  nesting (a folder's boards are strings), bounded. */
+export const TREE_MAX_BOARDS = 200
+export const TREE_MAX_FOLDERS = 50
+export function validateWire(wire: unknown): string | null {
+  if (!Array.isArray(wire)) return 'invalid tree'
+  const boards = new Set<string>(), folders = new Set<string>()
+  const board = (n: unknown): string | null => {
+    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 as { folder?: unknown; boards?: unknown; description?: unknown }
+    if (!isBoardName(folder)) return 'invalid folder name in tree'
+    if (description !== undefined && (typeof description !== 'string' || description.length > DESCRIPTION_MAX)) 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 > TREE_MAX_BOARDS || folders.size > TREE_MAX_FOLDERS) return 'tree too large'
+  return null
+}
+
+/** What the human types becomes a slug: "Old stuff" → "old-stuff". Empty when nothing
+ *  survives - the caller keeps the input open and says so. Always on-grammar or empty. */
+export function slugify(raw: string): string {
+  const s = raw.trim().toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-+|-+$/g, '').slice(0, NAME_MAX).replace(/-+$/g, '')
+  return isBoardName(s) ? s : ''
+}
+
+// ---- tree mutations (pure; the sidebar shows the result at once and persists it) ----
+
+export const cloneTree = (t: TreeItem[]): TreeItem[] => t.map((it) => (it.kind === 'board' ? { ...it } : { ...it, boards: [...it.boards] }))   // a folder's description rides along
+export const rootIndex = (t: TreeItem[], kind: TreeItem['kind'], name: string) => t.findIndex((it) => it.kind === kind && it.name === name)
+export const folderIn = (t: TreeItem[], name: string): Folder | undefined => t.find((it): it is Folder => it.kind === 'folder' && it.name === name)
+export const folderOf = (t: TreeItem[], board: string): string | null => t.find((it): it is Folder => it.kind === 'folder' && it.boards.includes(board))?.name ?? null
+export const boardsIn = (t: TreeItem[]): string[] => flatten(t)
+export const foldersIn = (t: TreeItem[]): string[] => t.filter((it) => it.kind === 'folder').map((it) => it.name)
+
+/** Remove a board wherever it sits; returns the list it left (root = null) and its index there. */
+export function takeBoard(t: TreeItem[], board: string): { list: string | null; index: number } | null {
+  const ri = rootIndex(t, 'board', board)
+  if (ri >= 0) { t.splice(ri, 1); return { list: null, index: ri } }
+  for (const it of t) {
+    if (it.kind !== 'folder') continue
+    const i = it.boards.indexOf(board)
+    if (i >= 0) { it.boards.splice(i, 1); return { list: it.name, index: i } }
+  }
+  return null
+}
+
+/** What is being dragged, and where it may land: a slot in a list (root = null) or the
+ *  inside of a folder (appended at its end). */
+export type Drag = { kind: TreeItem['kind']; name: string }
+export type Drop = { list: string | null; index: number } | { into: string }
+
+/** The row under the pointer, measured by the DOM and handed here as plain facts. */
+export interface Hit {
+  kind: TreeItem['kind']; name: string
+  parent: string | null      // the folder a board row lives in
+  below: boolean             // pointer in the lower half of the row
+  topEdge: boolean           // pointer in the top 30% of the row (folder rows: "before me")
+  gutter: boolean            // pointer left of a child row's indent (the root gutter = outdent)
+}
+
+/** The drop target for a drag over a row, or null. Boards land in any slot - root or inside
+ *  a folder - or INTO a folder; folders land in root slots only. Over a folder's child row the
+ *  root gutter means "after that folder" (the natural outdent). `all-scenes` = root end. */
+export function resolveDrop(t: TreeItem[], d: Drag, hit: Hit): Drop | null {
+  if (hit.kind === 'folder') {
+    const fi = rootIndex(t, 'folder', hit.name)
+    if (fi < 0) return null
+    if (d.kind === 'folder') return { list: null, index: hit.below ? fi + 1 : fi }
+    return hit.topEdge ? { list: null, index: fi } : { into: hit.name }   // top edge = before; the rest = inside
+  }
+  if (hit.name === 'all-scenes') return { list: null, index: t.length }   // over the pinned last row = root end slot
+  if (hit.parent) {
+    const pi = rootIndex(t, 'folder', hit.parent)
+    if (pi < 0) return null
+    if (d.kind === 'folder' || hit.gutter) return { list: null, index: pi + 1 }   // after that folder
+    const i = folderIn(t, hit.parent)?.boards.indexOf(hit.name) ?? -1
+    return i < 0 ? null : { list: hit.parent, index: hit.below ? i + 1 : i }
+  }
+  const i = rootIndex(t, 'board', hit.name)
+  return i < 0 ? null : { list: null, index: hit.below ? i + 1 : i }
+}
+
+/** A target that would leave the item where it is: nothing to show, nothing to drop. Into
+ *  the folder a board already sits in means "to its end" - a no-op only when it is last. */
+export function isOwnSlot(t: TreeItem[], d: Drag, target: Drop): boolean {
+  if ('into' in target) {
+    if (d.kind !== 'board') return true
+    const f = folderIn(t, target.into)
+    return !!f && f.boards[f.boards.length - 1] === d.name
+  }
+  let from = -1
+  if (d.kind === 'folder') from = target.list === null ? rootIndex(t, 'folder', d.name) : -1
+  else if (target.list === null) from = rootIndex(t, 'board', d.name)
+  else from = folderIn(t, target.list)?.boards.indexOf(d.name) ?? -1
+  return from >= 0 && (target.index === from || target.index === from + 1)
+}
+
+/** The tree after a drop, or null when the drop is impossible on this tree. */
+export function applyDrop(tree: TreeItem[], d: Drag, target: Drop): TreeItem[] | null {
+  const next = cloneTree(tree)
+  if (d.kind === 'folder') {
+    if ('into' in target || target.list !== null) return null
+    const from = rootIndex(next, 'folder', d.name)
+    if (from < 0) return null
+    const [it] = next.splice(from, 1)
+    next.splice(target.index > from ? target.index - 1 : target.index, 0, it!)   // removing `from` shifts later slots left
+    return next
+  }
+  const src = takeBoard(next, d.name)
+  if (!src) return null
+  if ('into' in target) {
+    const f = folderIn(next, target.into)
+    if (!f) return null
+    f.boards.push(d.name)
+    return next
+  }
+  const to = src.list === target.list && target.index > src.index ? target.index - 1 : target.index
+  if (target.list === null) { next.splice(Math.min(to, next.length), 0, { kind: 'board', name: d.name }); return next }
+  const f = folderIn(next, target.list)
+  if (!f) return null
+  f.boards.splice(Math.min(to, f.boards.length), 0, d.name)
+  return next
+}
+
+/** Move a board into a folder (at its end) or to the root at `atRoot` (default: the end). */
+export function moveBoard(tree: TreeItem[], board: string, folder: string | null, atRoot?: number): TreeItem[] | null {
+  const next = cloneTree(tree)
+  if (!takeBoard(next, board)) return null
+  if (folder === null) { next.splice(Math.min(atRoot ?? next.length, next.length), 0, { kind: 'board', name: board }); return next }
+  const f = folderIn(next, folder)
+  if (!f) return null
+  f.boards.push(board)
+  return next
+}
+
+/** A new folder at root `index`, holding `board` (pulled from wherever it sat) when given. */
+export function createFolder(tree: TreeItem[], name: string, index: number, board?: string): TreeItem[] | null {
+  if (foldersIn(tree).includes(name)) return null
+  const next = cloneTree(tree)
+  const boards: string[] = []
+  if (board) { if (!takeBoard(next, board)) return null; boards.push(board) }
+  next.splice(Math.min(index, next.length), 0, { kind: 'folder', name, boards })
+  return next
+}
+
+export function renameFolder(tree: TreeItem[], from: string, to: string): TreeItem[] | null {
+  if (from === to) return cloneTree(tree)
+  if (foldersIn(tree).includes(to)) return null
+  const next = cloneTree(tree)
+  const f = folderIn(next, from)
+  if (!f) return null
+  f.name = to
+  return next
+}
+
+/** Folders organise, never own: deleting one puts its boards back at the root, in its slot, in order. */
+export function deleteFolder(tree: TreeItem[], name: string): TreeItem[] | null {
+  const next = cloneTree(tree)
+  const i = rootIndex(next, 'folder', name)
+  if (i < 0) return null
+  const f = next[i] as Folder
+  next.splice(i, 1, ...f.boards.map((b): TreeItem => ({ kind: 'board', name: b })))
+  return next
+}
+
+/** Where "Move to new folder" puts the folder: the board's own root slot, or right after the
+ *  folder it sits in. */
+export const newFolderSlot = (tree: TreeItem[], board: string): number => {
+  const parent = folderOf(tree, board)
+  return parent ? rootIndex(tree, 'folder', parent) + 1 : Math.max(0, rootIndex(tree, 'board', board))
+}

package/templates/AGENTS-embedded.md

@@ -91,7 +91,7 @@ Report where the request came from: chat requests get chat replies; only comment
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
-  export const meta = { title: "...", viewport: "mobile" }   // literal values only
+  export const meta = { title: "...", viewport: "mobile", description: "..." }   // literal values only
   // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu; digit keys - 0 restores each
@@ -131,8 +131,17 @@ Report where the request came from: chat requests get chat replies; only comment
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before
-  exploring. `init` writes the first one; `marver dev` keeps it fresh.
+- design/manifest.json is the canvas with its purpose: the project (name, description),
+  every folder and board in sidebar order, every scene and frame - each with its
+  `description` when one was written. Read it before exploring; `marver dev` keeps it
+  fresh. `npx marver boards` prints the boards part as a tree.
+- **Descriptions.** Every object takes one optional `description`: one sentence, what it
+  is for and its state when that is not obvious (≤ ~160 chars). Project: `description`
+  in design/config.ts. Board: `"description"` in its JSON. Folder: on its `_folders.json`
+  entry. Scene: the FIRST line of its `_brief.md`. Frame: `meta.description`. Write it
+  when you create the thing; keep it true when the state changes (retired, winning
+  direction, superseded); before a session ends, re-read the manifest and fix any
+  description your session made false. That is how the next session orients in one read.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -159,8 +168,12 @@ edges; a variant-group name is one indivisible atom). **The default composition
 ONE horizontal band**: scenes side by side, frames flowing left to right; a second
 band only when you can say why the eye should move down, and then with generous
 vertical space. Without a recipe the shell stacks every scene as its own row - so
-every curated board carries one. BEFORE creating a board or publishing anything,
-read instructions/boards.md (the layout grammar, file format, publishing rules).
+every curated board carries one. Boards can sit in **folders** (one level): put
+`"folder": "<name>"` on a board file; `design/boards/_folders.json` names empty folders
+and ranks them - the human creates, renames, and drags folders in the sidebar too, so
+run `npx marver boards` (the tree as the files say it is) before you organise. BEFORE
+creating a board, organising boards, or publishing anything, read instructions/boards.md
+(the layout grammar, file format, folders and their moves, publishing rules).
 
 A round of feedback on a scene the human has already reviewed starts with a
 **version snapshot** (`design/scenes/<scene>-v<N>/` on the `archive` board) BEFORE

package/templates/AGENTS-studio.md

@@ -91,7 +91,7 @@ Report where the request came from: chat requests get chat replies; only comment
 ## Frames
 - A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
 - It default-exports a React component. No imports from the tool are needed. Optional:
-  export const meta = { title: "...", viewport: "mobile" }   // literal values only
+  export const meta = { title: "...", viewport: "mobile", description: "..." }   // literal values only
   // viewport names come from design/config.ts (default: mobile, tablet, laptop, monitor;
   // tv available commented-out). Pick the one the screen is designed for - the human can
   // flip the whole board to any device (Devices menu; digit keys - 0 restores each
@@ -130,8 +130,17 @@ Report where the request came from: chat requests get chat replies; only comment
   setTimeout(() => r(orders), 800)) and let the frame render its skeleton while awaiting.
 
 ## Orientation
-- design/manifest.json lists every frame (id, file, scene, title) - read it before
-  exploring. `init` writes the first one; `marver dev` keeps it fresh.
+- design/manifest.json is the canvas with its purpose: the project (name, description),
+  every folder and board in sidebar order, every scene and frame - each with its
+  `description` when one was written. Read it before exploring; `marver dev` keeps it
+  fresh. `npx marver boards` prints the boards part as a tree.
+- **Descriptions.** Every object takes one optional `description`: one sentence, what it
+  is for and its state when that is not obvious (≤ ~160 chars). Project: `description`
+  in design/config.ts. Board: `"description"` in its JSON. Folder: on its `_folders.json`
+  entry. Scene: the FIRST line of its `_brief.md`. Frame: `meta.description`. Write it
+  when you create the thing; keep it true when the state changes (retired, winning
+  direction, superseded); before a session ends, re-read the manifest and fix any
+  description your session made false. That is how the next session orients in one read.
 - Component galleries: create design/components/<name>/variants.tsx rendering each variant
   and each state (default / hover-styled / focus / disabled / loading) of one ui component.
 
@@ -159,8 +168,12 @@ edges; a variant-group name is one indivisible atom). **The default composition
 ONE horizontal band**: scenes side by side, frames flowing left to right; a second
 band only when you can say why the eye should move down, and then with generous
 vertical space. Without a recipe the shell stacks every scene as its own row - so
-every curated board carries one. BEFORE creating a board or publishing anything,
-read instructions/boards.md (the layout grammar, file format, publishing rules).
+every curated board carries one. Boards can sit in **folders** (one level): put
+`"folder": "<name>"` on a board file; `design/boards/_folders.json` names empty folders
+and ranks them - the human creates, renames, and drags folders in the sidebar too, so
+run `npx marver boards` (the tree as the files say it is) before you organise. BEFORE
+creating a board, organising boards, or publishing anything, read instructions/boards.md
+(the layout grammar, file format, folders and their moves, publishing rules).
 
 A round of feedback on a scene the human has already reviewed starts with a
 **version snapshot** (`design/scenes/<scene>-v<N>/` on the `archive` board) BEFORE