@marver-design/marver 0.16.0 → 0.16.1

package/src/client/shell/BoardList.tsx

@@ -1,12 +1,12 @@
 import { useEffect, useRef, useState, type MouseEvent as ReactMouseEvent, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react'
-import { useStore, HAS_ALL_SCENES, PUBLISHED, boardLabel, fetchBoardTree, type TreeBase } from './store.ts'
+import { useStore, HAS_ALL_SCENES, PUBLISHED, fetchBoardTree, rememberTitles, type TreeBase } from './store.ts'
 import { canvasCtl } from './canvas/Canvas.tsx'
 import { Tip } from './Tip.tsx'
 import { copyToClipboard, type MenuItem, type MenuOpener } from './ContextMenu.tsx'
 import { ArrowLineUpIcon, CardsIcon, CardsThreeIcon, FolderIcon, FolderMinusIcon, FolderOpenIcon, FolderPlusIcon, PencilSimpleIcon, SignpostIcon } from './icons.tsx'
 import {
-  applyDrop, boardsIn, createFolder, deleteFolder, folderOf, foldersIn, isBoardName, isOwnSlot, moveBoard, newFolderSlot, renameFolder, resolveDrop, rootIndex, slugify,
-  type Drag, type Drop, type TreeItem,
+  applyDrop, boardsIn, createFolder, deleteFolder, folderIn, folderOf, foldersIn, humanize, isOwnSlot, labelOf, moveBoard, newFolderSlot, readTitle, resolveDrop, retitleFolder, rootIndex, slugFor,
+  type Drag, type Drop, type Folder, type Row, type TreeItem,
 } from '../../shared/board-tree.ts'
 
 /**
@@ -21,7 +21,6 @@ import {
 
 const CLOSED_KEY = 'mv-folders-closed'   // collapsed folders are a viewer preference, never data
 const readClosed = (): Record<string, true> => { try { return JSON.parse(localStorage.getItem(CLOSED_KEY) ?? '{}') } catch { return {} } }
-const INDENT = 28                        // px a board row indents inside a folder; left of it is the root gutter
 
 /** The inline input: renaming a board or a folder, or naming a NEW folder that does not exist
  *  yet - drawn at root `index`, optionally with `board` already inside it. */
@@ -31,6 +30,8 @@ type Intent = (tree: TreeItem[]) => TreeItem[] | null
 
 export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
   const board = useStore((s) => s.board)
+  const titles = useStore((s) => s.boardTitles)                       // board slug → title, off the last tree read
+  const label = (n: string) => labelOf(n, titles[n])                  // a board's label; a folder's is labelOf(name, item.title)
   const [tree, setTree] = useState<TreeItem[]>([])
   const [naming, setNaming] = useState<Naming | null>(null)
   const [closed, setClosed] = useState<Record<string, true>>(readClosed)
@@ -50,7 +51,7 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
   // drag runs on pointer events, NOT native drag-and-drop: native DnD hands the cursor to
   // the OS (arrow/move), so a grabbing hand can't persist. Owning the gesture lets us hold
   // the grabbing cursor for the whole drag via a body class.
-  const gestureRef = useRef<{ pointerId: number; startX: number; startY: number; item: Drag; dragging: boolean; el: HTMLElement } | null>(null)
+  const gestureRef = useRef<{ pointerId: number; startX: number; startY: number; item: Drag; dragging: boolean; el: HTMLElement; x: number; y: number } | null>(null)
   const treeRef = useRef(tree)
   treeRef.current = tree
   const namingRef = useRef(naming)                                   // commit reads the LIVE naming state, never a stale closure (Escape, then a late blur)
@@ -70,6 +71,7 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
       if (seq !== loadSeq.current) return false                    // an older read landing late never overwrites a newer one
       confirmedRef.current = snap.tree
       baseRef.current = snap.base
+      rememberTitles(snap.titles)                                    // the labels follow the same latest-wins rule
       lastErr.current = ''
       show()
       return true
@@ -156,92 +158,117 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
     }
   }
 
-  // ---- inline naming (rename a board, rename a folder, name a new folder) ----
+  // ---- inline naming (retitle a board, retitle a folder, name a new folder) ----
+  // What the human types is the TITLE - any casing, punctuation, emoji - what the row shows.
+  // The slug (the board's file name, the folder's key on its boards and in the registry) is
+  // the object's identity: agents, publish.json, URLs and comment threads hold it, so a rename
+  // never moves it. A new folder mints its slug from the title once. Typing exactly what the
+  // slug reads as anyway ("Research" for `research`) clears the title - the file stays clean.
+  // An empty entry, or the label unchanged, means never mind.
   const commit = async (raw: string) => {
     const n = namingRef.current
     if (!n || commitBusy.current) return                      // Enter already fired this (or Escape cancelled); ignore the follow-up blur
     commitBusy.current = true
     try {
+      const title = readTitle(raw)
+      if (!title) { setNaming(null); return }
+      // two rows reading alike would be a trap: a name another board (folder) already shows stays editing
+      const taken = (kind: 'board' | 'folder') => useStore.getState().toast(`a ${kind} called "${title}" already exists`)
+      const stored = (slug: string) => (title === humanize(slug) ? '' : title)
       if (n.kind === 'board') {
-        const next = raw.trim()
-        if (!next || next === n.name) { setNaming(null); return }
-        if (!isBoardName(next) || next === 'all-scenes' || boardsIn(tree).includes(next)) {
-          useStore.getState().toast('use a free name - lowercase letters, numbers and dashes'); return   // stay editing
-        }
-        const r = await useStore.getState().renameBoard(n.name, next)
-        if (r.ok) { setNaming(null); refresh() }
-        else useStore.getState().toast(r.error ?? 'rename failed')                                      // stay editing
+        if (title === label(n.name)) { setNaming(null); return }
+        if (boardsIn(tree).some((b) => b !== n.name && label(b) === title) || (HAS_ALL_SCENES && label('all-scenes') === title)) { taken('board'); return }
+        let r = await useStore.getState().renameBoard(n.name, stored(n.name), baseRef.current.boards[n.name])
+        if (!r.ok && r.stale && await load()) r = await useStore.getState().renameBoard(n.name, stored(n.name), baseRef.current.boards[n.name])   // the file moved on (a drag just before, an agent): re-read, once more
+        if (!r.ok) { useStore.getState().toast(r.error ?? 'rename failed'); return }   // stay editing
+        setNaming(null)
+        refresh()
         return
       }
-      // folders: what the human types becomes a slug ("Old stuff" -> old-stuff, shown "Old Stuff");
-      // an empty entry means never mind
-      if (!raw.trim() || (n.kind === 'folder' && slugify(raw) === n.name)) { setNaming(null); return }
-      const slug = slugify(raw)
-      if (!slug) { useStore.getState().toast('use letters, numbers and dashes'); return }
-      if (foldersIn(tree).includes(slug)) { useStore.getState().toast(`a folder named "${slug}" already exists`); return }
-      setNaming(null)
+      const folderLabels = tree.filter((it): it is Folder => it.kind === 'folder' && (n.kind !== 'folder' || it.name !== n.name)).map((it) => labelOf(it.name, it.title))
       if (n.kind === 'folder') {
-        const wasClosed = !!closed[n.name]
-        setOpen(n.name, true); setOpen(slug, !wasClosed)                          // the collapsed flag follows the name, and only that
-        mutate((t) => renameFolder(t, n.name, slug))
-      } else if (n.kind === 'new') {
-        setOpen(slug, true)                                                       // a new folder opens, whatever an old namesake left behind
-        if (!mutate((t) => createFolder(t, slug, n.index, n.board))) useStore.getState().toast('that board is gone - nothing changed')
+        const current = folderIn(tree, n.name)
+        if (!current || title === labelOf(n.name, current.title)) { setNaming(null); return }
+        if (folderLabels.includes(title)) { taken('folder'); return }
+        setNaming(null)
+        mutate((t) => retitleFolder(t, n.name, stored(n.name)))
+        return
       }
+      if (n.kind !== 'new') return
+      if (folderLabels.includes(title)) { taken('folder'); return }
+      const { index, board: withBoard } = n
+      const slug = slugFor(title, foldersIn(tree))                                // "Old stuff" → old-stuff (-2 past a namesake); "🚀" alone → folder
+      setNaming(null)
+      setOpen(slug, true)                                                       // a new folder opens, whatever an old namesake left behind
+      if (!mutate((t) => createFolder(t, slug, index, withBoard, stored(slug) || undefined))) useStore.getState().toast('that board is gone - nothing changed')
     } finally { commitBusy.current = false }
   }
 
   // ---- drag and drop: one pointer gesture for board rows and folder rows ----
-  /** The drop target under the pointer for the item being dragged, or null. The DOM hit becomes
-   *  plain facts (which row, which half, the top edge, the root gutter) for the pure resolver. */
-  const dropAt = (x: number, y: number, d: Drag): Drop | null => {
-    const el = (document.elementFromPoint(x, y) as HTMLElement | null)?.closest('[data-board-row],[data-folder-row]') as HTMLElement | null
-    if (!el) return null
+  /** The rows as rendered, measured - what the pure resolver reads the pointer against. */
+  const rootRef = useRef<HTMLDivElement>(null)
+  const measure = (): Row[] => Array.from(rootRef.current?.querySelectorAll<HTMLElement>('[data-board-row],[data-folder-row]') ?? []).map((el) => {
     const r = el.getBoundingClientRect()
-    const hit = {
-      kind: (el.hasAttribute('data-folder-row') ? 'folder' : 'board') as Drag['kind'],
-      name: el.dataset.folderRow ?? el.dataset.board ?? '',
-      parent: el.hasAttribute('data-folder-row') ? null : (el.dataset.folder ?? null),
-      below: y > r.top + r.height / 2,
-      topEdge: y < r.top + r.height * 0.3,
-      gutter: x < r.left + INDENT,
-    }
-    const target = resolveDrop(treeRef.current, d, hit)
+    const folder = el.hasAttribute('data-folder-row')
+    return { kind: folder ? 'folder' : 'board', name: el.dataset.folderRow ?? el.dataset.board ?? '', parent: folder ? null : (el.dataset.folder ?? null), open: el.dataset.open === '1', top: r.top, bottom: r.bottom, left: r.left }
+  })
+  /** The drop target for the pointer at (x, y), or null: outside the panel (a release there
+   *  cancels), or a slot that would change nothing. Inside the panel there is always one - the
+   *  ends clamp - so the seam on screen is exactly where a release lands. */
+  const dropAt = (x: number, y: number, d: Drag): Drop | null => {
+    const panel = rootRef.current?.closest('.sh-panel')?.getBoundingClientRect()
+    if (!panel || x < panel.left || x >= panel.right || y < panel.top || y >= panel.bottom) return null
+    const target = resolveDrop(treeRef.current, d, measure(), x, y)
     return target && !isOwnSlot(treeRef.current, d, target) ? target : null
   }
+  const dropRef = useRef<Drop | null>(null)                          // the target on screen; the release applies THIS, never a recomputation
+  const showDrop = (t: Drop | null) => { dropRef.current = t; setDrop(t) }
   const resetPointer = () => {
     const g = gestureRef.current
     gestureRef.current = null
     if (g) { try { g.el.releasePointerCapture(g.pointerId) } catch { /* already released */ } }
     document.body.classList.remove('sh-board-dragging')
     setDrag(null)
-    setDrop(null)
+    showDrop(null)
   }
   const onPointerDown = (e: ReactPointerEvent<HTMLButtonElement>, item: Drag) => {
     if (e.button !== 0) return                                    // left button only; right-click opens the menu
     const el = e.currentTarget
     try { el.setPointerCapture(e.pointerId) } catch { /* capture can fail on rapid input */ }
-    gestureRef.current = { pointerId: e.pointerId, startX: e.clientX, startY: e.clientY, item, dragging: false, el }
+    gestureRef.current = { pointerId: e.pointerId, startX: e.clientX, startY: e.clientY, item, dragging: false, el, x: e.clientX, y: e.clientY }
   }
   const onPointerMove = (e: ReactPointerEvent<HTMLButtonElement>) => {
     const g = gestureRef.current
     if (!g || g.pointerId !== e.pointerId) return
+    g.x = e.clientX; g.y = e.clientY
     if (!g.dragging) {
       if (Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < 5) return   // click vs drag threshold
       g.dragging = true
       setDrag(g.item)
       document.body.classList.add('sh-board-dragging')            // holds the grabbing cursor for the whole drag
     }
-    setDrop(dropAt(e.clientX, e.clientY, g.item))
+    showDrop(dropAt(e.clientX, e.clientY, g.item))
   }
+  // the tree changed under a drag in progress (a poll, an agent's write): the seam is re-read
+  // against the rows as they are NOW, from where the pointer is - never a slot that no longer means it
+  useEffect(() => {
+    const g = gestureRef.current
+    if (g?.dragging) showDrop(dropAt(g.x, g.y, g.item))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tree])
   const onPointerUp = (e: ReactPointerEvent<HTMLButtonElement>) => {
     const g = gestureRef.current
     if (!g || g.pointerId !== e.pointerId) return
     // the item is the one the gesture STARTED on - never the row that happens to receive the
-    // up (capture can be lost, a refresh can re-key the dragged row)
+    // up (capture can be lost, a refresh can re-key the dragged row); the target is the seam
+    // the human saw
     const item = g.item
     const dragged = g.dragging
-    const target = dragged ? dropAt(e.clientX, e.clientY, item) : null
+    // a release outside the panel cancels, even after a seam showed (the pointer can leave
+    // between the last move and the up); inside, the seam is the contract
+    const panel = rootRef.current?.closest('.sh-panel')?.getBoundingClientRect()
+    const inside = !!panel && e.clientX >= panel.left && e.clientX < panel.right && e.clientY >= panel.top && e.clientY < panel.bottom
+    const target = dragged && inside ? dropRef.current : null
     resetPointer()
     if (dragged) {
       if (!target) return
@@ -290,7 +317,6 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
   }
   const onMenuRef = useRef(onMenu)
   onMenuRef.current = onMenu
-  const rootRef = useRef<HTMLDivElement>(null)
   useEffect(() => {
     const panel = rootRef.current?.closest('.sh-panel')
     const scroll = rootRef.current?.closest('.sh-panel-scroll')
@@ -320,13 +346,14 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
     return drop.index === index ? ' drop-before' : last && drop.index === index + 1 ? ' drop-after' : ''
   }
   const boardRow = (n: string, parent: string | null, index: number, last: boolean) => {
+    const dragging = drag?.kind === 'board' && drag.name === n
+    const dropCls = dragging ? '' : n === 'all-scenes' ? (drop && !('into' in drop) && drop.list === null && drop.index === tree.length ? ' drop-before' : '') : seam(parent, index, last)
+    // the row being renamed is still a row: measured by a drag (its slot exists) and it draws its seam
     if (naming?.kind === 'board' && naming.name === n) return (
-      <div key={n} className={`it board editing${parent ? ' in-folder' : ''}`}><CardsIcon size={14} />{input(n)}</div>
+      <div key={n} data-board-row data-board={n} data-folder={parent ?? undefined} className={`it board editing${parent ? ' in-folder' : ''}${dropCls}`}><CardsIcon size={14} />{input(label(n))}</div>
     )
     const canDrag = !PUBLISHED && n !== 'all-scenes'
     const item: Drag = { kind: 'board', name: n }
-    const dragging = drag?.kind === 'board' && drag.name === n
-    const dropCls = dragging ? '' : n === 'all-scenes' ? (drop && !('into' in drop) && drop.list === null && drop.index === tree.length ? ' drop-before' : '') : seam(parent, index, last)
     return (
       <button key={`${parent ?? ''}/${n}`} data-board-row data-board={n} data-folder={parent ?? undefined} data-reorderable={canDrag || undefined}
         className={`it board${parent ? ' in-folder' : ''}${n === board ? ' cur' : ''}${dragging ? ' dragging' : ''}${dropCls}`}
@@ -341,22 +368,25 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
         onPointerCancel={canDrag ? () => resetPointer() : undefined}
         onLostPointerCapture={canDrag ? (e) => { if (gestureRef.current?.pointerId === e.pointerId) resetPointer() } : undefined}>
         {n === 'all-scenes' ? <CardsThreeIcon size={14} /> : <CardsIcon size={14} />}
-        <span>{boardLabel(n)}</span>
+        <span>{label(n)}</span>
       </button>
     )
   }
-  const folderRow = (f: string, boards: string[], index: number): ReactNode[] => {
+  const folderRow = (it: Folder, boards: string[], index: number): ReactNode[] => {
+    const f = it.name
     const open = !closed[f]
     const rows: ReactNode[] = []
     if (naming?.kind === 'folder' && naming.name === f) {
-      rows.push(<div key={`f:${f}`} className="it folder editing">{open ? <FolderOpenIcon size={14} /> : <FolderIcon size={14} />}{input(f)}</div>)
+      rows.push(<div key={`f:${f}`} data-folder-row={f} data-open={open ? '1' : '0'} className={`it folder editing${seam(null, index, false)}`}>{open ? <FolderOpenIcon size={14} /> : <FolderIcon size={14} />}{input(labelOf(f, it.title))}</div>)
     } else {
       const item: Drag = { kind: 'folder', name: f }
       const dragging = drag?.kind === 'folder' && drag.name === f
       const into = !!drag && !!drop && 'into' in drop && drop.into === f
+      // a slot inside an open EMPTY folder has no board row to draw on: the indented seam sits under the header
+      const inSeam = !!drag && !!drop && !('into' in drop) && drop.list === f && open && boards.length === 0
       rows.push(
-        <button key={`f:${f}`} data-folder-row={f} data-reorderable={!PUBLISHED || undefined}
-          className={`it folder${boards.includes(board) ? ' held' : ''}${dragging ? ' dragging' : ''}${into ? ' drop-into' : ''}${dragging ? '' : seam(null, index, false)}`}
+        <button key={`f:${f}`} data-folder-row={f} data-open={open ? '1' : '0'} data-reorderable={!PUBLISHED || undefined}
+          className={`it folder${boards.includes(board) ? ' held' : ''}${dragging ? ' dragging' : ''}${into ? ' drop-into' : ''}${inSeam ? ' drop-in' : ''}${dragging ? '' : seam(null, index, false)}`}
           onClick={(e) => { if (PUBLISHED || e.detail === 0) setOpen(f, !open) }}
           onContextMenu={(e) => onMenu(e, folderMenu(f, boards))}
           onPointerDown={!PUBLISHED ? (e) => onPointerDown(e, item) : undefined}
@@ -365,7 +395,7 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
           onPointerCancel={!PUBLISHED ? () => resetPointer() : undefined}
           onLostPointerCapture={!PUBLISHED ? (e) => { if (gestureRef.current?.pointerId === e.pointerId) resetPointer() } : undefined}>
           {open ? <FolderOpenIcon size={14} /> : <FolderIcon size={14} />}
-          <span>{boardLabel(f)}</span>
+          <span>{labelOf(f, it.title)}</span>
           <small>{boards.length}</small>
         </button>,
       )
@@ -380,12 +410,12 @@ export function BoardList({ onMenu }: { onMenu: MenuOpener }) {
   const rows: ReactNode[] = []
   const draftRows = draft ? [
     <div key="f:new" className="it folder editing"><FolderOpenIcon size={14} />{input('', 'Folder name')}</div>,
-    ...(draft.board ? [<div key="new/board" className={`it board in-folder draft${draft.board === board ? ' cur' : ''}`}><CardsIcon size={14} /><span>{boardLabel(draft.board)}</span></div>] : []),
+    ...(draft.board ? [<div key="new/board" className={`it board in-folder draft${draft.board === board ? ' cur' : ''}`}><CardsIcon size={14} /><span>{label(draft.board)}</span></div>] : []),
   ] : []
   tree.forEach((it, i) => {
     if (draft && draft.index === i) rows.push(...draftRows)
     if (it.kind === 'board') { if (draft?.board !== it.name) rows.push(boardRow(it.name, null, i, false)) }
-    else rows.push(...folderRow(it.name, draft?.board ? it.boards.filter((b) => b !== draft.board) : it.boards, i))
+    else rows.push(...folderRow(it, draft?.board ? it.boards.filter((b) => b !== draft.board) : it.boards, i))
   })
   if (draft && draft.index >= tree.length) rows.push(...draftRows)
   if (HAS_ALL_SCENES) rows.push(boardRow('all-scenes', null, -1, false))   // a published bundle without it shows none

package/src/client/shell/LockedApp.tsx

@@ -107,7 +107,8 @@ export function App() {
     return c.live(board)
   }, [board])
 
-  useEffect(() => { document.title = board ? `${boardLabel(board)} - Marver` : 'Marver' }, [board])
+  const titles = useStore((s) => s.boardTitles)
+  useEffect(() => { document.title = board ? `${boardLabel(board)} - Marver` : 'Marver' }, [board, titles])
 
   return (
     <div tabIndex={-1} className="sh-app dark">

package/src/client/shell/Play.tsx

@@ -168,6 +168,7 @@ export function PlayOverlay() {
 function BoardMenu({ current }: { current: string }) {
   const pop = usePopover()
   const [names, setNames] = useState<string[]>([current])
+  useStore((s) => s.boardTitles)   // labels follow titles (the fetch below refreshes them)
   // refreshed on every open - agents create boards while you present
   useEffect(() => { if (pop.open) fetchBoardNames().then(setNames).catch(() => {}) }, [pop.open])
   return (

package/src/client/shell/labels.ts

@@ -4,7 +4,7 @@
 export const cap = (s: string): string => (s ? s[0].toUpperCase() + s.slice(1) : s)
 
 /** D5: derive a display label from a kebab slug - drop the dashes, Title Case each word.
- *  For board/scene NAMES only (device/theme names are single words, cap is right there).
- *  Acronyms ("tms" -> "Tms") await the board `title` override (C3); an explicit title,
- *  once present, is shown verbatim and never passes through here. */
-export const humanize = (s: string): string => s.replace(/-/g, ' ').replace(/(^|\s)\S/g, (c) => c.toUpperCase())
+ *  For board/folder/scene NAMES only (device/theme names are single words, cap is right
+ *  there). An explicit `title` (boards, folders, scenes - v1.6.1) is shown verbatim and never
+ *  passes through here; `labelOf` in shared/board-tree.ts picks. */
+export { humanize } from '../../shared/board-tree.ts'

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 }