@marver-design/marver 0.16.0 → 0.17.0

package/src/client/shell/store.ts

@@ -14,6 +14,8 @@ 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[]
+  /** slug → title of the published boards (0.16.1 bundles); folder titles ride on `tree` */
+  titles?: Record<string, string>
   /** 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
@@ -44,7 +46,7 @@ export function hydrateBoardPolicy(boards: Record<string, { type?: string; open?
 }
 
 export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number; slide?: boolean }
-export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
+export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number; title?: string; description?: string }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
   /** RESOLVED theme (what renders): themeUser ?? frame meta.theme ?? viewTheme. */
@@ -125,23 +127,23 @@ 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'
+import { buildTree, flatten, labelOf, toWire, type TreeItem } from '../../shared/board-tree.ts'
 
 /** 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 }
+export interface TreeSnapshot { tree: TreeItem[]; base: TreeBase; titles: Record<string, string> }
 
 /** 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 } }
+  if (DATA) return { tree: DATA.tree ?? DATA.names.filter((n) => n !== 'all-scenes').map((n) => ({ kind: 'board', name: n })), base: { boards: {}, folders: null }, titles: DATA.titles ?? {} }
   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/boards`).then((r) => r.json()) as Promise<{ name: string; sha256: string; order?: number; folder?: string; title?: string }[]>,
     fetch(`${ROUTE}/api/folders`).then(async (r) => {
-      const j = await r.json() as { folders?: { name: string; order?: number }[]; sha256?: string | null; error?: string }
+      const j = await r.json() as { folders?: { name: string; order?: number; title?: string }[]; sha256?: string | null; error?: string }
       if (!r.ok) throw new Error(j?.error ?? `folders ${r.status}`)
       return j
     }),
@@ -149,20 +151,32 @@ export async function fetchBoardTree(): Promise<TreeSnapshot> {
   return {
     tree: buildTree(boards, reg.folders ?? []),
     base: { boards: Object.fromEntries(boards.map((b) => [b.name, b.sha256])), folders: reg.sha256 ?? null },
+    titles: Object.fromEntries(boards.flatMap((b) => (b.title ? [[b.name, b.title]] : []))),
   }
 }
+/** A tree read's board titles become the labels' - called by the reader once it knows the
+ *  read is its latest (an older response must not overwrite a newer one's labels). Folder
+ *  titles ride on the tree's folder items: a board and a folder may share a slug, never one map. */
+export function rememberTitles(titles: Record<string, string>) {
+  if (JSON.stringify(useStore.getState().boardTitles) !== JSON.stringify(titles)) useStore.setState({ boardTitles: titles })
+}
 
 /** 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
-  return [...flatten((await fetchBoardTree()).tree), 'all-scenes']
+  const snap = await fetchBoardTree()
+  rememberTitles(snap.titles)
+  return [...flatten(snap.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)
+/** Display name for a board: its title when one is set (subscribe to `boardTitles` to
+ *  re-render on change), else the Title-Cased slug ('all-scenes' reads "All Scenes"). */
+export const boardLabel = (n: string) => labelOf(n, useStore.getState().boardTitles[n])
+/** Display name for a scene: the title in its brief's front matter, else the Title-Cased directory. */
+export const sceneLabel = (n: string) => labelOf(n, useStore.getState().manifest?.scenes.find((s) => s.name === n)?.title)
 
 /** The double-submit CSRF token the owner gate wants echoed (same read as comments-store). */
 const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
@@ -208,6 +222,8 @@ const initialViewTheme = () => {
   return CONFIG.themes[0] ?? 'light'
 }
 const manifestKey = (m: Manifest) => JSON.stringify(m.frames)   // any change counts, not just added/removed ids
+let scenesRev = 0                                                // bumps per sh:scenes, so a load that straddled one keeps the live labels
+let liveScenes: Manifest['scenes'] | null = null                 // the last sh:scenes payload - applied late when it beat the first manifest
 
 /** Latest measured content heights, keyed frameId@width. TRANSIENT by design:
  * auto sizes are never serialized - a reload remeasures. */
@@ -304,7 +320,16 @@ interface State {
   setDeviceView(name: string | null): void
   resizeSelected(name: string | null): void
   switchBoard(name: string): Promise<void>
-  renameBoard(from: string, to: string): Promise<{ ok: boolean; error?: string }>
+  /** what the sidebar labels boards by: slug → title, off the last tree read */
+  boardTitles: Record<string, string>
+  /** retitle a board - what humans see ('' = back to the Title-Cased slug). The file never
+   *  moves: its name is the board's identity (agents, publish.json, URLs, comment threads).
+   *  `baseHash` = the file as last seen; a 409 (`stale`) means someone wrote it since. */
+  renameBoard(name: string, title: string, baseHash?: string): Promise<{ ok: true } | { ok: false; stale?: boolean; error?: string }>
+  /** a scene's title, into its brief's front matter (the directory never moves) */
+  renameScene(scene: string, title: string): Promise<{ ok: boolean; error?: string }>
+  /** `sh:scenes`: the scenes changed (a brief's title or description) with the frames intact */
+  setScenes(scenes: Manifest['scenes']): void
   arrangeBoards(tree: TreeItem[], base: TreeBase): Promise<{ ok: true } | { ok: false; stale: boolean; error?: string }>
   pulsePath(): void
   copyFrameImage(scale: 2 | 4): void
@@ -601,13 +626,13 @@ export const useStore = create<State>((set, get) => {
   return {
     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,
+    panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {},
     pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
 
     async boot() {
       const seq = ++loadSeq
       const boardName = get().board
-      const revAtStart = editRev
+      const revAtStart = editRev, scenesAtStart = scenesRev
       const next = await loadBoardState(boardName)
       if (seq !== loadSeq) return false        // a newer load superseded this one
       if (!next) { get().toast(`board "${boardName}" failed to load`); return false }
@@ -617,11 +642,13 @@ export const useStore = create<State>((set, get) => {
       set(next)
       if (next.dirty) scheduleSave()          // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
+      else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } })   // an sh:scenes that landed mid-fetch outranks the file we read
       return true
     },
 
     async switchBoard(name) {
       const mySwitch = ++switchSeq             // also cancels any pending switch (incl. re-clicking the current board)
+      const scenesAtStart = scenesRev
       if (name === get().board) return
       // a resize held across a switch: settle THIS board (retidy if it has a recipe)
       // before the flush, so the torn mid-gesture state is never what reaches disk
@@ -649,41 +676,61 @@ export const useStore = create<State>((set, get) => {
       set({ board: name, interact: null, ...next })
       if (next.dirty) scheduleSave()           // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
+      else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } })
     },
 
-    renameBoard(from, to) {
+    renameBoard(name, title, baseHash) {
       return structural(async () => {
+        const from = name
         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.
+        // Retitling the ACTIVE board rewrites its file under the autosave. Flush any pending
+        // write FIRST (switchBoard's pattern), so a PUT never races the rewrite.
         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)
+          // hold autosave across the round-trip: an edit landing mid-write would PUT against a
+          // hash the rewrite is about to move
           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 {
+          // 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 base = active && get().boardHash ? get().boardHash : baseHash
           let res: Response
-          try { res = await postOwner('boards/rename', { from, to }) }
+          try { res = await postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) }) }
           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 })
+          const body = await res.json().catch(() => ({} as { error?: string; sha256?: string }))
+          if (!res.ok) return { ok: false, stale: res.status === 409, error: body?.error ?? `rename failed (${res.status})` }
+          // the write rewrote the file: the active board's CAS token moves to the hash the server
+          // answered (else the next autosave 409s against our own write) - before releasing the hold
+          if (active && get().board === from && body?.sha256) set({ boardHash: body.sha256 })
+          const titles = { ...get().boardTitles }   // the label changes now; the next tree read confirms it from the file
+          if (title) titles[from] = title; else delete titles[from]
+          set({ boardTitles: titles })
           return { ok: true }
         } finally { if (active) releaseSaves() }   // whatever happened, autosave resumes
       })
     },
 
+    async renameScene(scene, title) {
+      let res: Response
+      try { res = await postOwner('scenes/rename', { scene, title }) }
+      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})` } }
+      // the label changes now; the watcher's sh:scenes confirms it from the file
+      const m = get().manifest
+      if (m) set({ manifest: { ...m, scenes: m.scenes.map((s) => (s.name === scene ? { ...s, ...(title ? { title } : {}), ...(title ? {} : { title: undefined }) } : s)) } })
+      return { ok: true }
+    },
+    setScenes(scenes) {
+      if (!Array.isArray(scenes)) return
+      scenesRev++
+      liveScenes = scenes
+      const m = get().manifest
+      if (m) set({ manifest: { ...m, scenes } })   // before the first manifest: kept for the boot's commit
+    },
+
     // 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

package/src/client/shell/styles.css

@@ -526,8 +526,12 @@ body.sh-commenting .sh-lean { opacity: 0 }
 .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 */
+/* seams inside a folder are indented with its rows, so "inside" and "at the root" never draw alike;
+   an open EMPTY folder draws that indented seam under its own header (drop-in) */
 .sh-panel .it.board.in-folder.drop-before::after, .sh-panel .it.board.in-folder.drop-after::after { left: 28px }
+.sh-panel .it.folder.drop-in { position: relative }
+.sh-panel .it.folder.drop-in::after { content: ''; position: absolute; left: 28px; right: 6px; bottom: -1px; height: 3px; border-radius: 3px;
+  background: #0088ff; pointer-events: none }
 /* 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 }

package/src/shared/board-tree.ts

@@ -17,11 +17,11 @@ 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[]; description?: string }
+export type Folder = { kind: 'folder'; name: string; boards: string[]; title?: 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 }
+export interface BoardRow { name: string; order?: number; folder?: string; title?: string }
+export interface FolderRow { name: string; order?: number; 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
@@ -31,7 +31,24 @@ export const readDescription = (v: unknown): string | undefined => {
   return s || undefined
 }
 
+/** A title off a file - what humans see, free text: any casing, punctuation, emoji. Control
+ *  characters dropped, whitespace collapsed, capped in code points (never half a surrogate
+ *  pair). Absent when empty or not a string; the display then falls back to the slug. */
+export const TITLE_MAX = 120
+export const readTitle = (v: unknown): string | undefined => {
+  if (typeof v !== 'string') return undefined
+  // eslint-disable-next-line no-control-regex
+  const s = Array.from(v.replace(/[\u0000-\u001f\u007f]/g, ' ').trim().replace(/\s+/g, ' ')).slice(0, TITLE_MAX).join('').trim()
+  return s || undefined
+}
+/** Title Case off a slug - the display when no title is set ("old-stuff" → "Old Stuff"). */
+export const humanize = (s: string): string => s.replace(/-/g, ' ').replace(/(^|\s)\S/g, (c) => c.toUpperCase())
+/** What a board, folder or scene is called on screen: its title, else its humanized slug. */
+export const labelOf = (name: string, title?: string): string => title ?? humanize(name)
+
 const rank = (o: number | undefined) => (typeof o === 'number' && Number.isFinite(o) ? o : Infinity)
+/** 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 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
@@ -49,19 +66,22 @@ 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 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 } : {}), ...(d ? { description: d } : {}) })
+    out.push({ name, ...(typeof o === 'number' && Number.isFinite(o) ? { order: o } : {}), ...(t ? { title: t } : {}), ...(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. */
+ *  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. */
 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 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 members = new Map<string, BoardRow[]>()
   const rootBoards: BoardRow[] = []
   for (const b of boards) {
@@ -78,7 +98,7 @@ export function buildTree(boards: BoardRow[], folders: FolderRow[]): TreeItem[]
   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,
+      item: { kind: 'folder', name, boards: (members.get(name) ?? []).sort(byRank).map((b) => b.name), ...(folderMeta.get(name) ?? {}) } as TreeItem,
       order,
     })),
   ]
@@ -94,12 +114,14 @@ export function flatten(tree: TreeItem[]): string[] {
 }
 
 /** 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 }
+ *  `{ 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 }
 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 } : {}) }))
+  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], ...(w.description ? { description: w.description } : {}) }))
+  wire.map((w) => (typeof w === 'string' ? { kind: 'board', name: w } : { kind: 'folder', name: w.folder, boards: [...w.boards], ...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
@@ -118,8 +140,9 @@ export function validateWire(wire: unknown): string | 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 }
+    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)
@@ -163,35 +186,59 @@ export function takeBoard(t: TreeItem[], board: string): { list: string | null;
 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)
-}
+/** 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. */
+export const INDENT = 28
 
-/** 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
+/** 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. */
+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 blocks: { top: number; bottom: number }[] = []
+    for (const r of rows) {
+      if (r.parent && 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
+    const f = (y - r.top) / (r.bottom - r.top)
+    if (f >= 0.25 && (f < 0.75 || !r.open)) return { into: r.name }
   }
-  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 }
+  let g = 0
+  for (const r of rows) if (y >= mid(r)) g++
+  const above = rows[g - 1], below = rows[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 })
   }
-  const i = rootIndex(t, 'board', hit.name)
-  return i < 0 ? null : { list: null, index: hit.below ? i + 1 : i }
+  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 })
 }
 
 /** A target that would leave the item where it is: nothing to show, nothing to drop. Into
@@ -248,25 +295,36 @@ export function moveBoard(tree: TreeItem[], board: string, folder: string | null
 }
 
 /** 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 {
+export function createFolder(tree: TreeItem[], name: string, index: number, board?: string, title?: 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 })
+  next.splice(Math.min(index, next.length), 0, { kind: 'folder', name, boards, ...(title ? { title } : {}) })
   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
+/** Retitle a folder: what humans see (''= clear, back to the Title-Cased slug). The slug is
+ *  its identity - `folder:` on every member board, the registry key - and never changes here. */
+export function retitleFolder(tree: TreeItem[], name: string, title: string): TreeItem[] | null {
   const next = cloneTree(tree)
-  const f = folderIn(next, from)
+  const f = folderIn(next, name)
   if (!f) return null
-  f.name = to
+  if (title) f.title = title; else delete f.title
   return next
 }
 
+/** The slug a NEW folder gets from the title the human typed: `slugify(title)`, then `-2`,
+ *  `-3`, ... past a taken one; `fallback` (and `fallback-2`, ...) when nothing survives
+ *  slugifying ("🚀"). Slugs are minted once - a rename changes the title, never the slug. */
+export function slugFor(title: string, taken: string[], fallback = 'folder'): string {
+  const s = slugify(title)
+  if (s && !taken.includes(s)) return s
+  const base = s || fallback
+  if (!s && !taken.includes(base)) return base
+  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. */
 export function deleteFolder(tree: TreeItem[], name: string): TreeItem[] | null {
   const next = cloneTree(tree)

package/templates/AGENTS-embedded.md

@@ -81,7 +81,10 @@ planning. The human should see the request land on the canvas within the first m
    lit frame, never before one.
 3. Build. Independent frames can go in parallel - one subagent per frame, each marking
    its own; frames that depend on one another go in order.
-4. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
+4. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
+   `--all`) renders the frames headless in one go - one PNG path per line - and you READ
+   the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
+5. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
    self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
    and never lean on expiry instead of `done`.
 
@@ -133,8 +136,15 @@ Report where the request came from: chat requests get chat replies; only comment
 ## Orientation
 - 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.
+  `description` when one was written, and its `title` when the human (or you) named it.
+  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
+  boards part as a tree.
+- **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
+  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
+  that never move on a rename. `title` is what humans see - free text (casing,
+  punctuation, emoji) on the board JSON, the `_folders.json` entry, the brief's front
+  matter; frames have `meta.title`. When the human says "the Checkout A/B board", the
+  manifest maps that title to its slug. Rename a slug only when asked, as one refactor.
 - **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`

package/templates/AGENTS-studio.md

@@ -81,7 +81,10 @@ planning. The human should see the request land on the canvas within the first m
    lit frame, never before one.
 3. Build. Independent frames can go in parallel - one subagent per frame, each marking
    its own; frames that depend on one another go in order.
-4. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
+4. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
+   `--all`) renders the frames headless in one go - one PNG path per line - and you READ
+   the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
+5. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
    self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
    and never lean on expiry instead of `done`.
 
@@ -132,8 +135,15 @@ Report where the request came from: chat requests get chat replies; only comment
 ## Orientation
 - 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.
+  `description` when one was written, and its `title` when the human (or you) named it.
+  Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
+  boards part as a tree.
+- **Names vs titles.** A board's file name, a folder's `name`, a scene's directory are
+  IDENTITIES: slugs you address, that publish.json, URLs and comment threads hold, and
+  that never move on a rename. `title` is what humans see - free text (casing,
+  punctuation, emoji) on the board JSON, the `_folders.json` entry, the brief's front
+  matter; frames have `meta.title`. When the human says "the Checkout A/B board", the
+  manifest maps that title to its slug. Rename a slug only when asked, as one refactor.
 - **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`

package/templates/instructions/boards.md

@@ -10,10 +10,20 @@ viewport and lays it out:
 
 ```json
 { "version": 1, "name": "checkout-compare", "order": 1, "auto": false,
+  "title": "Checkout A/B",
   "description": "Cart step, direction A vs B side by side - B is the current favourite",
   "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
 ```
 
+- **The file name is the board's identity** - what you, `publish.json`, URLs and
+  comment threads address (`board: checkout-compare`). It is a slug
+  (`^[a-z0-9][a-z0-9-]*$`) and never moves on a rename.
+- `title` - what humans SEE: free text, any casing, punctuation, emoji ("MVP", "UI",
+  "Checkout (v2) 🛒"). Optional: without one the sidebar Title-Cases the slug
+  (`checkout-compare` → "Checkout Compare"), which is fine for most boards. Write a
+  title when the slug would read wrong (`mvp` → "Mvp") or when the human names it.
+  The human's Rename in the sidebar edits the title only; the manifest carries both, so
+  "the Checkout A/B board" resolves to `checkout-compare`.
 - `description` - one sentence on what the board is for and where it stands. It is
   how a later session (or the human's next agent) knows this board without opening
   it; it lands in design/manifest.json. Write it at creation, keep it true.
@@ -28,8 +38,9 @@ viewport and lays it out:
   orienting board (an overview or the primary flow) - never a giant one. Boards
   without an `order` sort after the ranked ones, by name. Set `order` deliberately on
   every curated board; it is the first impression. The human can also drag-reorder boards
-  in the sidebar (which rewrites `order`), rename one from its right-click menu, and file
-  boards into folders (below) - so your ranking is a starting point they may adjust.
+  in the sidebar (which rewrites `order`), retitle one from its right-click menu (which
+  writes `title`), and file boards into folders (below) - so your ranking is a starting
+  point they may adjust.
 - `auto: false` boards show exactly their list. `all-scenes` is auto-managed (it holds
   EVERY frame, so it is the heavy one) and always sinks to the BOTTOM of the switcher -
   never the landing board, and never write its file.
@@ -64,12 +75,14 @@ Files are the truth, and two files carry it:
 
   ```json
   { "version": 1, "folders": [
-    { "name": "research", "order": 1, "description": "The thinking behind the live boards - specs, flows, references" },
+    { "name": "research", "order": 1, "title": "R&D", "description": "The thinking behind the live boards - specs, flows, references" },
     { "name": "archive", "order": 3, "description": "Retired directions and scene versions, oldest first" } ] }
   ```
 
-  A folder's `description` says what belongs in it - the next session files boards
-  right without asking.
+  A folder's `name` is its slug - the identity its boards point at with `folder`; its
+  `title` (optional, free text) is what humans see, exactly as on a board; its
+  `description` says what belongs in it - the next session files boards right without
+  asking.
 
   It exists so an EMPTY folder can exist and so a folder has a rank at the root.
   A folder a board names but the registry lacks is still real (it sorts after the
@@ -91,8 +104,12 @@ The moves, each a file edit, so the files always agree:
   an `order` among the top-level items.
 - **Rank** folders and boards: `order` on the board (among its siblings) and on the
   registry entry (among the top-level items). Renumber the siblings you touch.
-- **Rename** a folder: rewrite `folder` on every member AND the registry entry - a
-  registry rename alone leaves the members in the old (implied) folder.
+- **Retitle** a folder (or a board): set `title` on the registry entry (on the board
+  file). **Rename a slug** - a folder's `name`, a board's file name - only when asked,
+  and as one refactor: a folder slug is on every member's `folder` field (rewrite them
+  all, AND the registry entry - a registry rename alone leaves the members in the old,
+  implied folder); a board file name is in `publish.json`, in its comment threads and in
+  every path anyone copied. A title does what a rename usually wanted.
 - **Delete** a folder: remove `folder` from every member, then its registry entry.
   Folders organise, never own: deleting one never deletes a board.
 - The **landing board** is the first board in sidebar order, folders included -
@@ -105,8 +122,9 @@ last. Propose the grouping in one sentence and do it; keep folder names short an
 plain.
 
 The human does all of this too - from the sidebar: New folder (right-click the Boards
-header, or its `+`), Rename, Delete folder, "Move to …" on a board, and DRAG: boards
-into and out of folders, folders among boards. Each drag rewrites `order` (and
+header, or its `+`), Rename (the title - slugs never move from the sidebar), Delete
+folder, "Move to …" on a board, and DRAG: boards into and out of folders, folders among
+boards. Each drag rewrites `order` (and
 `folder`) on the boards it touches and the registry - the shell owns those fields
 while the canvas is open, exactly as it owns `order`; write membership and new
 folders freely, and never rewrite an arrangement the human just made. The shell