@marver-design/marver 0.19.2 → 0.21.0

package/src/shared/board-tree.ts

@@ -1,9 +1,11 @@
 /**
  * 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.
+ * board file - one slug, the folder it sits in directly), ranked among its siblings by
+ * `order`, and `design/boards/_folders.json` says which folders exist, where they rank, and
+ * which folder holds which (`parent`). Two levels: a folder holds boards and folders, a
+ * folder inside a folder (a sub-folder) holds boards only. `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). */
@@ -17,11 +19,12 @@ export const FOLDERS_FILE = '_folders.json'
  *  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[]; title?: string; description?: string }
+/** A folder and what it holds, in order: boards, and - in a top-level folder only - sub-folders. */
+export type Folder = { kind: 'folder'; name: string; items: TreeItem[]; title?: string; description?: string }
 export type TreeItem = { kind: 'board'; name: string } | Folder
 
 export interface BoardRow { name: string; order?: number; folder?: string; title?: string }
-export interface FolderRow { name: string; order?: number; title?: string; description?: string }
+export interface FolderRow { name: string; order?: number; parent?: string; title?: string; description?: string }
 
 /** A description off a file: one sentence, trimmed, capped - absent when empty or not a string. */
 export const DESCRIPTION_MAX = 300
@@ -50,13 +53,25 @@ const rank = (o: number | undefined) => (typeof o === 'number' && Number.isFinit
 /** A folder's title and description, present only when set. */
 const folderExtras = (it: { title?: string; description?: string }) => ({ ...(it.title ? { title: it.title } : {}), ...(it.description ? { description: it.description } : {}) })
 
+/** The registry versions this code reads. Version 2 is written only when a folder has a
+ *  `parent`, so a flat registry stays readable by every Marver; an older Marver refuses a
+ *  version-2 file as malformed instead of rewriting it without its nesting. */
+export const REGISTRY_VERSION_FLAT = 1
+export const REGISTRY_VERSION_NESTED = 2
+/** The tree-write protocol a shell speaks. A shell that predates nesting reads a nested
+ *  registry flat (it ignores `parent`) and would post that flat tree back with a perfectly
+ *  current hash - the hash proves freshness, not understanding - so the server refuses a write
+ *  without this marker whenever the registry on disk nests. */
+export const TREE_PROTOCOL = 2
+
 /** 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. */
+ *  malformed registry is an ERROR the human must fix (silently reading it as empty, or
+ *  flattening a broken nesting, 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 (version !== undefined && version !== REGISTRY_VERSION_FLAT && version !== REGISTRY_VERSION_NESTED) return `unsupported version ${String(version)}`
   if (!Array.isArray(folders)) return 'expected a "folders" array'
   const out: FolderRow[] = []
   const seen = new Set<string>()
@@ -66,66 +81,92 @@ export function parseFolders(raw: unknown): FolderRow[] | string {
     if (seen.has(name)) return `folder "${name}" is listed twice`
     seen.add(name)
     const o = (f as { order?: unknown }).order
+    const p = (f as { parent?: unknown }).parent
+    if (p !== undefined && !isBoardName(p)) return `folder "${name}" has an invalid parent - a folder name`
     const t = readTitle((f as { title?: unknown }).title)
     const d = readDescription((f as { description?: unknown }).description)
-    out.push({ name, ...(typeof o === 'number' && Number.isFinite(o) ? { order: o } : {}), ...(t ? { title: t } : {}), ...(d ? { description: d } : {}) })
+    out.push({ name, ...(typeof o === 'number' && Number.isFinite(o) ? { order: o } : {}), ...(p !== undefined ? { parent: p } : {}), ...(t ? { title: t } : {}), ...(d ? { description: d } : {}) })
+  }
+  const byName = new Map(out.map((f) => [f.name, f]))
+  for (const f of out) {
+    if (f.parent === undefined) continue
+    if (version !== REGISTRY_VERSION_NESTED) return `folder "${f.name}" names a parent - nested folders need "version": 2`
+    if (f.parent === f.name) return `folder "${f.name}" cannot be its own parent`
+    const p = byName.get(f.parent)
+    if (!p) return `folder "${f.name}" names an unknown parent "${f.parent}"`
+    if (p.parent !== undefined) return `folder "${f.name}" would sit three levels deep - folders nest one level only`
   }
   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. A folder's
- *  title and description ride on its item (they live in the registry a tree write rewrites);
- *  a board's title stays with its row - it lives in the board's own file. */
+/** Sidebar order from the files. At every level the boards and folders there share one
+ *  sequence, ranked by `order`, then kind (board before folder), then name; unranked sorts
+ *  after ranked. The root holds root boards and top-level folders (registered without a
+ *  parent, or implied by a board that names an unregistered folder); a top-level folder holds
+ *  its boards and its sub-folders; a sub-folder holds its boards. A folder's title and
+ *  description ride on its item (they live in the registry a tree write rewrites); a board's
+ *  title stays with its row - it lives in the board's own file. */
 export function buildTree(boards: BoardRow[], folders: FolderRow[]): TreeItem[] {
-  const folderOrder = new Map<string, number | undefined>()
-  const folderMeta = new Map<string, { title?: string; description?: string }>()
-  for (const f of folders) if (isBoardName(f.name) && !folderOrder.has(f.name)) { folderOrder.set(f.name, f.order); folderMeta.set(f.name, folderExtras(f)) }
+  const reg = new Map<string, FolderRow>()
+  for (const f of folders) if (isBoardName(f.name) && !reg.has(f.name)) reg.set(f.name, f)
+  // a parent the registry does not hold as a top-level folder leaves the child top-level -
+  // parseFolders refuses such files; this keeps buildTree total for any rows it is handed
+  const parentOf = (n: string): string | undefined => {
+    const p = reg.get(n)?.parent
+    return p !== undefined && p !== n && reg.has(p) && reg.get(p)!.parent === undefined ? p : undefined
+  }
   const members = new Map<string, BoardRow[]>()
+  const implied: string[] = []
   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
+    if (!reg.has(folder) && !implied.includes(folder)) implied.push(folder)   // implied by the board alone: always top-level
     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), ...(folderMeta.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)
+  type Ranked = { item: TreeItem; order: number | undefined }
+  const sorted = (xs: Ranked[]): TreeItem[] =>
+    xs.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)).map((r) => r.item)
+  const boardsHere = (name: string | null): Ranked[] =>
+    (name === null ? rootBoards : members.get(name) ?? []).map((b) => ({ item: { kind: 'board', name: b.name }, order: b.order }))
+  const folder = (name: string, kids: Ranked[]): Ranked =>
+    ({ item: { kind: 'folder', name, items: sorted(kids), ...folderExtras(reg.get(name) ?? {}) }, order: reg.get(name)?.order })
+  const subsOf = (top: string) => [...reg.keys()].filter((n) => parentOf(n) === top)
+  const tops = [...[...reg.keys()].filter((n) => !parentOf(n)), ...implied]
+  return sorted([
+    ...boardsHere(null),
+    ...tops.map((t) => folder(t, [...boardsHere(t), ...subsOf(t).map((s) => folder(s, boardsHere(s)))])),
+  ])
 }
 
-/** Every board in reading order - the order the switchers and the landing pick use. */
+/** Every board in reading order, depth-first - 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) }
+  const walk = (items: TreeItem[]) => { for (const it of items) { if (it.kind === 'board') out.push(it.name); else walk(it.items) } }
+  walk(tree)
   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.
- *  A folder's title and description ride with it (they live in the registry the write
- *  rewrites); a board's title lives in its own file and never rides the tree. */
-export type WireItem = string | { folder: string; boards: string[]; title?: string; description?: string }
+/** The wire shape of a tree write (`POST boards/reorder`): plain strings for boards,
+ *  `{ folder, items }` for folders, `items` holding boards and - one level down - folders.
+ *  What the sidebar posts and the server validates. A folder's title and description ride
+ *  with it (they live in the registry the write rewrites); a board's title lives in its own
+ *  file and never rides the tree. A one-level `{ folder, boards }` item (an older shell) is
+ *  still read. */
+export type WireItem = string | { folder: string; items: WireItem[]; title?: string; description?: string }
+type WireIn = string | { folder: string; items?: WireIn[]; boards?: string[]; title?: string; description?: string }
 export const toWire = (tree: TreeItem[]): WireItem[] =>
-  tree.map((it) => (it.kind === 'board' ? it.name : { folder: it.name, boards: [...it.boards], ...folderExtras(it) }))
-export const fromWire = (wire: WireItem[]): TreeItem[] =>
-  wire.map((w) => (typeof w === 'string' ? { kind: 'board', name: w } : { kind: 'folder', name: w.folder, boards: [...w.boards], ...folderExtras(w) }))
+  tree.map((it) => (it.kind === 'board' ? it.name : { folder: it.name, items: toWire(it.items), ...folderExtras(it) }))
+export const wireKids = (w: Exclude<WireIn, string>): WireIn[] => w.items ?? w.boards ?? []
+export const fromWire = (wire: WireIn[]): TreeItem[] =>
+  wire.map((w) => (typeof w === 'string' ? { kind: 'board', name: w } : { kind: 'folder', name: w.folder, items: fromWire(wireKids(w)), ...folderExtras(w) }))
 
 /** 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. */
+ *  every name on-grammar, `all-scenes` nowhere, no board twice, no folder twice, folders
+ *  two levels deep at most, bounded. */
 export const TREE_MAX_BOARDS = 200
 export const TREE_MAX_FOLDERS = 50
 export function validateWire(wire: unknown): string | null {
@@ -137,18 +178,27 @@ export function validateWire(wire: unknown): string | null {
     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, title, description } = w as { folder?: unknown; boards?: unknown; title?: unknown; description?: unknown }
-    if (!isBoardName(folder)) return 'invalid folder name in tree'
-    if (title !== undefined && (typeof title !== 'string' || Array.from(title).length > TITLE_MAX)) return 'invalid folder title'
-    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 }
+  const walk = (list: unknown[], depth: number): string | null => {
+    for (const w of list) {
+      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'
+      if (depth >= 2) return 'folders nest one level only'
+      const { folder, items, boards: legacy, title, description } = w as { folder?: unknown; items?: unknown; boards?: unknown; title?: unknown; description?: unknown }
+      if (!isBoardName(folder)) return 'invalid folder name in tree'
+      if (title !== undefined && (typeof title !== 'string' || Array.from(title).length > TITLE_MAX)) return 'invalid folder title'
+      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)
+      const kids = items ?? legacy
+      if (!Array.isArray(kids)) return 'invalid folder in tree'
+      if (items === undefined && kids.some((k) => typeof k !== 'string')) return 'invalid folder in tree'   // a one-level item holds boards only
+      const e = walk(kids, depth + 1)
+      if (e) return e
+    }
+    return null
   }
+  const e = walk(wire, 0)
+  if (e) return e
   if (boards.size > TREE_MAX_BOARDS || folders.size > TREE_MAX_FOLDERS) return 'tree too large'
   return null
 }
@@ -160,26 +210,62 @@ export function slugify(raw: string): string {
   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)
+// ---- reading the tree ----
 
-/** 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 } }
+/** A deep copy: mutations work on it and the caller's tree stays as it was (a folder's
+ *  title and description ride along). */
+export const cloneTree = (t: TreeItem[]): TreeItem[] => t.map((it) => (it.kind === 'board' ? { ...it } : { ...it, items: cloneTree(it.items) }))
+/** Every folder with the folder it sits in (null = the root), top-level folders first in
+ *  reading order, each followed by its sub-folders. */
+export function folderEntries(t: TreeItem[]): { folder: Folder; parent: string | null }[] {
+  const out: { folder: Folder; parent: string | null }[] = []
   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 } }
+    out.push({ folder: it, parent: null })
+    for (const k of it.items) if (k.kind === 'folder') out.push({ folder: k, parent: it.name })
+  }
+  return out
+}
+/** A folder anywhere in the tree. */
+export const folderIn = (t: TreeItem[], name: string): Folder | undefined => folderEntries(t).find((e) => e.folder.name === name)?.folder
+/** The folder a folder sits in - null for a top-level folder (or one that is not there). */
+export const parentOf = (t: TreeItem[], name: string): string | null => folderEntries(t).find((e) => e.folder.name === name)?.parent ?? null
+/** The folder a board sits in directly, at either level - null at the root. */
+export function folderOf(t: TreeItem[], board: string): string | null {
+  for (const { folder } of folderEntries(t)) if (folder.items.some((k) => k.kind === 'board' && k.name === board)) return folder.name
+  return null
+}
+export const boardsIn = (t: TreeItem[]): string[] => flatten(t)
+export const foldersIn = (t: TreeItem[]): string[] => folderEntries(t).map((e) => e.folder.name)
+/** Does this folder hold folders? Such a folder can only ever sit at the root. */
+export const hasSubfolders = (f: Folder): boolean => f.items.some((k) => k.kind === 'folder')
+/** The list a slot lives in: the root (null) or a folder's items. */
+export const listIn = (t: TreeItem[], list: string | null): TreeItem[] | undefined => (list === null ? t : folderIn(t, list)?.items)
+/** Where an item sits in a list, or -1. */
+export const indexIn = (t: TreeItem[], list: string | null, kind: TreeItem['kind'], name: string): number =>
+  listIn(t, list)?.findIndex((it) => it.kind === kind && it.name === name) ?? -1
+export const rootIndex = (t: TreeItem[], kind: TreeItem['kind'], name: string) => indexIn(t, null, kind, name)
+/** How deep a list sits: the root 0, a top-level folder's items 1, a sub-folder's items 2. */
+export const depthOf = (t: TreeItem[], list: string | null): number => (list === null ? 0 : parentOf(t, list) === null ? 1 : 2)
+
+/** Remove an item wherever it sits; returns the list it left (root = null), its index there
+ *  and the item itself. */
+export function takeItem(t: TreeItem[], kind: TreeItem['kind'], name: string): { list: string | null; index: number; item: TreeItem } | null {
+  const lists: (string | null)[] = [null, ...foldersIn(t)]
+  for (const list of lists) {
+    const items = listIn(t, list)!
+    const i = items.findIndex((it) => it.kind === kind && it.name === name)
+    if (i >= 0) { const [item] = items.splice(i, 1); return { list, index: i, item: item! } }
   }
   return null
 }
+/** 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 r = takeItem(t, 'board', board)
+  return r ? { list: r.list, index: r.index } : null
+}
+
+// ---- drag and drop ----
 
 /** 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). */
@@ -187,120 +273,160 @@ export type Drag = { kind: TreeItem['kind']; name: string }
 export type Drop = { list: string | null; index: number } | { into: string }
 
 /** A row the sidebar rendered, measured - the list as the human sees it, top to bottom,
- *  the pinned `all-scenes` row included (it is the root's end). `open` is the folder's
- *  disclosure; `left` is the row's left edge, from which the child indent is measured. */
-export interface Row { kind: TreeItem['kind']; name: string; parent: string | null; open?: boolean; top: number; bottom: number; left: number }
-/** Px a board row indents inside a folder; the seams inside draw from there too. */
+ *  the pinned `all-scenes` row included (it is the root's end). `parent` is the folder the
+ *  row sits in (null = the root) and `depth` that list's depth (0 root, 1 a top-level
+ *  folder's items, 2 a sub-folder's). `open` is a folder's disclosure; `left` is the row's
+ *  left edge, from which the indent of each level is measured. */
+export interface Row { kind: TreeItem['kind']; name: string; parent: string | null; depth: number; open?: boolean; top: number; bottom: number; left: number }
+/** Px each level of nesting indents its rows; the seams inside draw from there too. */
 export const INDENT = 28
 
+/** How deep the dragged item may land: a board anywhere (2), a folder without sub-folders
+ *  inside a top-level folder (1), a folder holding sub-folders at the root only (0). */
+function landingDepth(t: TreeItem[], d: Drag): number {
+  if (d.kind === 'board') return 2
+  const f = folderIn(t, d.name)
+  return f && !hasSubfolders(f) ? 1 : 0
+}
+
 /** The drop target for a pointer at (x, y) over the rendered rows - never null inside the
  *  list (the ends clamp), so a release anywhere over the sidebar lands somewhere the seam
- *  showed. Boards: the middle band of a folder header (a closed one: its lower band too) is
- *  INTO it; otherwise the nearest gap by row midlines, read from the row above it: after a
- *  root board or a closed folder = root; after an open folder's header, or between two of
- *  its boards = inside; after a folder's LAST board (or under an open empty folder) the gap
- *  is shared between the folder and the root, and the row under the pointer decides: still
- *  over that last board (that header), at or right of the indent the seams draw at = inside;
- *  over the root row below it, or in the gutter = root, after the folder. Folders: root gaps
- *  only, each root item one block. */
+ *  showed. INTO: the middle band of a folder header (a closed one: its lower band too), when
+ *  what is dragged may sit inside it. Otherwise the nearest gap by row midlines. A gap inside
+ *  a list belongs to it. A gap where lists END - after the last row of a folder, or under an
+ *  open empty folder - is shared by every level that ends there, down to the level of the row
+ *  below; the row under the pointer decides: still over the row above, the deepest level whose
+ *  indent the pointer reaches; over the row below (or past it), that row's own level. A folder
+ *  never lands inside itself; one that holds sub-folders moves between root items only, each
+ *  root item one block. */
 export function resolveDrop(t: TreeItem[], d: Drag, rows: Row[], x: number, y: number): Drop | null {
   const mid = (r: { top: number; bottom: number }) => (r.top + r.bottom) / 2
-  if (d.kind === 'folder') {
+  const deepest = landingDepth(t, d)
+  if (deepest === 0) {
     const blocks: { top: number; bottom: number }[] = []
     for (const r of rows) {
-      if (r.parent && blocks.length) { blocks[blocks.length - 1]!.bottom = r.bottom; continue }
+      if (r.depth > 0 && blocks.length) { blocks[blocks.length - 1]!.bottom = r.bottom; continue }
       blocks.push({ top: r.top, bottom: r.bottom })
     }
     let g = 0
     for (const b of blocks) if (y >= mid(b)) g++
     return { list: null, index: Math.min(g, t.length) }
   }
-  for (const r of rows) {
-    if (r.kind !== 'folder' || y < r.top || y >= r.bottom) continue
+  // what a dragged folder holds is never a place to land; its own header stays in the
+  // geometry, so a wobble over it resolves to its own slot - a no-op, never an eviction
+  const rs = d.kind === 'folder' ? rows.filter((r) => r.parent !== d.name && !(r.parent && parentOf(t, r.parent) === d.name)) : rows
+  for (const r of rs) {
+    if (r.kind !== 'folder' || (d.kind === 'folder' && r.name === d.name) || y < r.top || y >= r.bottom || r.depth + 1 > deepest) continue
     const f = (y - r.top) / (r.bottom - r.top)
     if (f >= 0.25 && (f < 0.75 || !r.open)) return { into: r.name }
   }
   let g = 0
-  for (const r of rows) if (y >= mid(r)) g++
-  const above = rows[g - 1], below = rows[g]
+  for (const r of rs) if (y >= mid(r)) g++
+  const above = rs[g - 1], below = rs[g]
   if (!above) return { list: null, index: 0 }
   if (above.name === 'all-scenes') return { list: null, index: t.length }
-  const inside = (folder: string, index: number, alt: Drop): Drop => (y < above.bottom && x >= above.left + INDENT ? { list: folder, index } : alt)
-  if (above.kind === 'board') {
-    if (!above.parent) { const i = rootIndex(t, 'board', above.name); return i < 0 ? null : { list: null, index: i + 1 } }
-    const fi = rootIndex(t, 'folder', above.parent)
-    const i = folderIn(t, above.parent)?.boards.indexOf(above.name) ?? -1
-    if (fi < 0 || i < 0) return null
-    if (below?.kind === 'board' && below.parent === above.parent) return { list: above.parent, index: i + 1 }
-    return inside(above.parent, i + 1, { list: null, index: fi + 1 })
+  type Slot = { list: string | null; index: number; depth: number }
+  // the deepest slot the gap can mean: inside an open folder, under its header - or right after the row above, in its own list
+  let first: Slot
+  if (above.kind === 'folder' && above.open && !(d.kind === 'folder' && above.name === d.name)) first = { list: above.name, index: 0, depth: above.depth + 1 }
+  else {
+    const i = indexIn(t, above.parent, above.kind, above.name)
+    if (i < 0) return null
+    first = { list: above.parent, index: i + 1, depth: above.depth }
+  }
+  // then, level by level up to the root: right after the folder that holds the slot before
+  const chain: Slot[] = [first]
+  for (let s = first; s.list !== null;) {
+    const up = parentOf(t, s.list)
+    const i = indexIn(t, up, 'folder', s.list)
+    if (i < 0) return null
+    s = { list: up, index: i + 1, depth: s.depth - 1 }
+    chain.push(s)
   }
-  const fi = rootIndex(t, 'folder', above.name)
-  if (fi < 0) return null
-  if (!above.open) return { list: null, index: fi + 1 }
-  if (below?.kind === 'board' && below.parent === above.name) return { list: above.name, index: 0 }
-  return inside(above.name, 0, { list: null, index: fi + 1 })
+  const floor = below ? below.depth : 0
+  const slots = chain.filter((s) => s.depth >= floor && s.depth <= deepest)
+  const strip = (s: Slot): Drop => ({ list: s.list, index: s.index })
+  if (!slots.length) { const s = chain.find((c) => c.depth <= deepest); return s ? strip(s) : null }
+  if (slots.length === 1) return strip(slots[0]!)
+  if (y < above.bottom) for (const s of slots) if (x >= above.left + s.depth * INDENT) return strip(s)
+  return strip(slots[slots.length - 1]!)
 }
 
 /** 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. */
+ *  the folder an item 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
+    const last = f?.items[f.items.length - 1]
+    return !!last && last.kind === d.kind && last.name === 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
+  const from = indexIn(t, target.list, d.kind, d.name)
   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. */
+/** The tree after a drop, or null when the drop is impossible on this tree: a folder into
+ *  itself, into a sub-folder, or - when it holds sub-folders - into any folder. */
 export function applyDrop(tree: TreeItem[], d: Drag, target: Drop): TreeItem[] | null {
   const next = cloneTree(tree)
+  const dest = 'into' in target ? target.into : target.list
   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)
+    const f = folderIn(next, d.name)
     if (!f) return null
-    f.boards.push(d.name)
-    return next
+    if (dest !== null && (dest === d.name || hasSubfolders(f) || !folderIn(next, dest) || parentOf(next, dest) !== null)) return null
   }
-  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)
+  const src = takeItem(next, d.kind, d.name)
+  if (!src) return null
+  const list = listIn(next, dest)
+  if (!list) return null
+  const to = 'into' in target ? list.length : src.list === dest && target.index > src.index ? target.index - 1 : target.index   // removing the item shifts later slots left
+  list.splice(Math.min(to, list.length), 0, src.item)
   return next
 }
 
-/** Move a board into a folder (at its end) or to the root at `atRoot` (default: the end). */
+// ---- tree mutations (pure; the sidebar shows the result at once and persists it) ----
+
+/** Move a board into a folder at either level (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)
+  f.items.push({ kind: 'board', name: board })
+  return next
+}
+
+/** Move a folder to the root at `atRoot` (default: the end) - "Move to top level" for a sub-folder. */
+export function moveFolderToRoot(tree: TreeItem[], name: string, atRoot?: number): TreeItem[] | null {
+  const next = cloneTree(tree)
+  const src = takeItem(next, 'folder', name)
+  if (!src) return null
+  // an explicit slot was measured before the folder left the root; the default end was not
+  const at = atRoot === undefined ? next.length : src.list === null && atRoot > src.index ? atRoot - 1 : atRoot
+  next.splice(Math.min(at, next.length), 0, src.item)
   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, title?: string): TreeItem[] | null {
+/** Can this list hold a folder? The root and a top-level folder can; a sub-folder, or a
+ *  folder that is not there, cannot. */
+export const holdsFolders = (t: TreeItem[], parent: string | null): boolean => parent === null || (!!folderIn(t, parent) && parentOf(t, parent) === null)
+
+/** A new folder at `index` in `parent`'s items (null = the root), holding `board` (pulled
+ *  from wherever it sat) when given. Only the root and top-level folders hold folders. */
+export function createFolder(tree: TreeItem[], name: string, index: number, board?: string, title?: string, parent: string | null = null): 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, ...(title ? { title } : {}) })
+  if (!holdsFolders(next, parent)) return null
+  const items: TreeItem[] = []
+  if (board) {
+    const src = takeItem(next, 'board', board)
+    if (!src) return null
+    items.push(src.item)
+    if (src.list === parent && src.index < index) index--                       // the board left a slot before the new one
+  }
+  const list = listIn(next, parent)!
+  list.splice(Math.min(index, list.length), 0, { kind: 'folder', name, items, ...(title ? { title } : {}) })
   return next
 }
 
@@ -325,19 +451,24 @@ export function slugFor(title: string, taken: string[], fallback = 'folder'): st
   for (let i = 2; ; i++) { const c = `${base.slice(0, NAME_MAX - 1 - String(i).length)}-${i}`; if (!taken.includes(c)) return c }
 }
 
-/** Folders organise, never own: deleting one puts its boards back at the root, in its slot, in order. */
+/** Folders organise, never own: deleting one moves what it holds up one level, into its
+ *  place, in order - a top-level folder's boards and sub-folders to the root, a
+ *  sub-folder's boards into its parent. */
 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 })))
+  const src = takeItem(next, 'folder', name)
+  if (!src) return null
+  listIn(next, src.list)!.splice(src.index, 0, ...(src.item as Folder).items)
   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))
+/** Where "Move to new folder" puts the folder: in the board's own slot, at its own level - the
+ *  root, or a sub-folder inside the top-level folder the board sits in; a board in a
+ *  sub-folder gets the new folder right after that sub-folder (that level holds no folders). */
+export function newFolderSlot(tree: TreeItem[], board: string): { parent: string | null; index: number } {
+  const home = folderOf(tree, board)
+  if (home === null) return { parent: null, index: Math.max(0, rootIndex(tree, 'board', board)) }
+  const up = parentOf(tree, home)
+  if (up === null) return { parent: home, index: Math.max(0, indexIn(tree, home, 'board', board)) }
+  return { parent: up, index: indexIn(tree, up, 'folder', home) + 1 }
 }

package/templates/AGENTS-embedded.md

@@ -197,9 +197,9 @@ 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. 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
+every curated board carries one. Boards can sit in **folders**, two levels deep: put
+`"folder": "<name>"` on a board file (the folder it sits in directly); `design/boards/_folders.json`
+names empty folders, ranks them, and nests a sub-folder with `"parent"` - 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).

package/templates/AGENTS-studio.md

@@ -197,9 +197,9 @@ 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. 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
+every curated board carries one. Boards can sit in **folders**, two levels deep: put
+`"folder": "<name>"` on a board file (the folder it sits in directly); `design/boards/_folders.json`
+names empty folders, ranks them, and nests a sub-folder with `"parent"` - 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).