@marver-design/marver 0.14.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)
 
@@ -251,6 +276,8 @@ interface State {
   playUpdateRevision: string | null                        // a revision arrived while play is open
   playNav: number                                          // bumps to reload the play stage on demand
   pathPulse: number                                        // bumps on each successful path copy - flashes the toolbar icon into a check
+  imagePulse: number                                       // bumps on each successful image copy - same flash, the images-square icon
+  imageBusy: boolean                                       // a copy-as-image render is in flight (one at a time)
 
   boot(): Promise<boolean>
   applyManifest(m: Manifest): void
@@ -278,8 +305,9 @@ 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
   togglePanel(): void
   setTheme(theme: string): void
@@ -314,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
@@ -564,7 +602,7 @@ export const useStore = create<State>((set, get) => {
     manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false, laser: false,
     board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null,
     panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, boardHash: null, dirty: false,
-    pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0,
+    pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
 
     async boot() {
       const seq = ++loadSeq
@@ -613,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) {
@@ -1017,6 +1078,53 @@ export const useStore = create<State>((set, get) => {
     },
     setScale(scale) { set({ scale }) },
     pulsePath() { set((s) => ({ pathPulse: s.pathPulse + 1 })) },
+    // Copy the ONE selected frame to the clipboard as a PNG - the dev server's headless
+    // renderer (/api/shot, the same picture `marver shot` gives an agent) sized to what the
+    // node shows, at 2x (or 4x). The ClipboardItem takes a PROMISE: clipboard.write runs
+    // inside the click/keydown gesture and the browser waits for the bytes - a plain
+    // await-then-write would have lost the transient activation during the 1-4s render.
+    copyFrameImage(scale) {
+      const s = get()
+      if (PUBLISHED || s.imageBusy || s.selection.length !== 1) return
+      const node = s.nodes.find((n) => n.key === s.selection[0])
+      if (!node || node.missing) return
+      const frame = s.frameFor(node)
+      if (!frame) { s.toast('frame is still indexing - try again in a second'); return }
+      const CI = (globalThis as { ClipboardItem?: typeof ClipboardItem }).ClipboardItem
+      if (!CI || !navigator.clipboard?.write || (CI.supports && !CI.supports('image/png'))) { s.toast("this browser can't put images on the clipboard - use Chrome, Edge or Safari"); return }
+      set({ imageBusy: true })
+      const done = () => set({ imageBusy: false })
+      const qs = new URLSearchParams({ frame: frame.id, theme: node.theme, scale: String(scale), w: String(Math.round(node.w)), h: String(Math.round(node.h)), format: 'png' })
+      // the render is serialized server-side behind any CLI/jam shots; a minute is the ceiling
+      // before the UI gives up on this copy (the server's own watchdog is 45s per shot)
+      const ctl = new AbortController()
+      const timer = setTimeout(() => ctl.abort(), 60_000)
+      let meta: { scale?: number; note?: string } = {}
+      const png = fetch(`${ROUTE}/api/shot?${qs}`, { headers: { 'x-mv-c': csrf() }, signal: ctl.signal }).then(async (r) => {
+        if (!r.ok) throw new Error((await r.json().catch(() => ({}))).error ?? `shot failed (${r.status})`)
+        try { meta = JSON.parse(atob((r.headers.get('x-mv-shot') ?? '').replace(/-/g, '+').replace(/_/g, '/'))) } catch { /* summary is advisory */ }
+        return r.blob()
+      }).finally(() => clearTimeout(timer))
+      let renderErr = ''
+      png.catch((e: Error) => { renderErr = e.name === 'AbortError' ? 'timed out - the renderer is busy' : e.message })
+      const fail = (err: unknown) => {
+        done()
+        // a prompt clipboard refusal (no gesture, focus lost) must not wait a minute on the
+        // render: abandon the fetch, toast now. A render failure surfaces its own cause.
+        if (!renderErr) ctl.abort()
+        s.toast(renderErr ? `render failed - ${renderErr}` : (err as Error)?.name === 'NotAllowedError' ? 'copy blocked - click the canvas first' : `copy failed - ${(err as Error)?.message ?? err}`)
+      }
+      try {
+        navigator.clipboard.write([new CI({ 'image/png': png })]).then(
+          () => {
+            done()
+            const used = meta.scale ?? scale
+            s.toast(used < scale ? `image copied at ${used}x - frame too tall for ${scale}x` : scale === 4 ? 'image copied (4x)' : 'image copied')
+            set((st) => ({ imagePulse: st.imagePulse + 1 }))
+          },
+          fail)
+      } catch (err) { fail(err) }   // a synchronous constructor/type error must not wedge busy
+    },
     togglePanel() { set((s) => ({ panelOpen: !s.panelOpen })) },
     // global theme = the VIEW preference: persists across boards + reloads, clears
     // per-frame pins. Frames declaring meta.theme keep their mode (they only work there).
@@ -1091,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

@@ -413,6 +413,12 @@ body.sh-commenting .sh-lean { opacity: 0 }
   justify-content: center; padding: 0 6px; margin: 0 2px 0 3px }
 .sh-ctx button.on { background: var(--glass-accent-bg); color: var(--glass-accent) }
 .sh-ctx button:hover:not(.on) { background: var(--glass-hover); color: var(--glass-ink) }
+/* multi-select / no-op states read as quiet, not broken */
+.sh-ctx button:disabled { cursor: default; opacity: .45 }
+.sh-ctx button:disabled:hover { background: none; color: var(--glass-ink-2) }
+/* copy-as-image while the headless render runs (1-4s): a slow breathe on the icon */
+.sh-ctx button.busy { opacity: 1; color: var(--glass-accent); animation: sh-ctx-breathe 1.1s ease-in-out infinite }
+@keyframes sh-ctx-breathe { 0%, 100% { opacity: .35 } 50% { opacity: 1 } }
 .sh-ctx .sep { width: 1px; height: 14px; background: var(--glass-brd); margin: 0 3px }
 
 /* error / missing cards (inside the frame body) */
@@ -499,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 }
@@ -556,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))
+}