@marver-design/marver 0.15.0 → 0.16.1

package/src/client/shell/store.ts

@@ -12,6 +12,10 @@ import shData from 'virtual:sh-data'
  *  is where `/` opens - never a synthesized aggregate of a filtered build. */
 const DATA: {
   manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string
+  /** the sidebar's folder tree over the published boards (0.16.0 bundles; older ones have none) */
+  tree?: TreeItem[]
+  /** 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
@@ -42,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. */
@@ -123,21 +127,56 @@ 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, labelOf, toWire, type TreeItem } from '../../shared/board-tree.ts'
 
-/** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
- *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
+/** The CAS tokens a tree write echoes: the sha256 of every board file as last seen, and of
+ *  the folder registry (null = there was no file). */
+export interface TreeBase { boards: Record<string, string>; folders: string | null }
+export interface TreeSnapshot { tree: TreeItem[]; base: TreeBase; 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 }, 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; title?: string }[]>,
+    fetch(`${ROUTE}/api/folders`).then(async (r) => {
+      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
+    }),
+  ])
+  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
-  const list: { name: string; order?: number }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
-  const curated = list
-    .filter((b) => b.name !== 'all-scenes')
-    .sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || a.name.localeCompare(b.name))
-    .map((b) => b.name)
-  return [...curated, 'all-scenes']
+  const snap = await fetchBoardTree()
+  rememberTitles(snap.titles)
+  return [...flatten(snap.tree), 'all-scenes']
 }
-/** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
-export const boardLabel = (n: string) => humanize(n)
+/** 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: 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] ?? ''
@@ -183,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. */
@@ -279,8 +320,17 @@ 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 }>
-  reorderBoards(order: string[]): Promise<boolean>
+  /** 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
   setScale(s: number): void
@@ -317,8 +367,18 @@ export const useStore = create<State>((set, get) => {
   let editRev = 0                                    // bumps per edit; a stale save response may never clear dirty over a newer edit
   let loadSeq = 0                                    // stale boot() responses never overwrite a newer board
   let switchSeq = 0                                  // last click wins when board switches race
-  let renameLock = false                             // while a board file is being renamed, autosave must not fire against the OLD name (a mustExist PUT would 409-gone and clear dirty, losing the in-flight edit)
-  const scheduleSave = () => { editRev++; if (renameLock) return; clearTimeout(saveTimer); saveTimer = setTimeout(() => get().save(), 500) }
+  // While a board file is being renamed or rewritten by a structural write (rename, the
+  // sidebar's tree arrange), autosave must not fire against it (a mustExist PUT would
+  // 409-gone and clear dirty, losing the in-flight edit; a stale baseHash would 409 and
+  // reload). A COUNT, not a flag: two holders never release each other. Structural writes
+  // also run one at a time through `structChain`, so a rename can never interleave a
+  // tree write on the same file.
+  let saveHolds = 0
+  const holdSaves = () => { saveHolds++; clearTimeout(saveTimer) }
+  const releaseSaves = () => { if (--saveHolds === 0 && get().dirty) scheduleSave() }
+  let structChain: Promise<unknown> = Promise.resolve()
+  const structural = <T,>(fn: () => Promise<T>): Promise<T> => { const p = structChain.then(fn, fn); structChain = p.catch(() => {}); return p }
+  const scheduleSave = () => { editRev++; if (saveHolds > 0) return; clearTimeout(saveTimer); saveTimer = setTimeout(() => get().save(), 500) }
 
   // One cancelable, BOARD-SCOPED reflow after content measurements settle.
   // The captured board name is the generation guard - a debounce surviving a board
@@ -566,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 }
@@ -582,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
@@ -614,45 +676,88 @@ 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 } })
     },
 
-    async renameBoard(from, to) {
-      const active = from === get().board
-      // Renaming the ACTIVE board renames its file out from under the autosave. Flush any
-      // pending write FIRST (switchBoard's pattern), so a mustExist PUT never races the move.
-      if (active) {
-        let ok = true
-        for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
-        if (get().dirty) return { ok: false, error: 'unsaved changes - try again' }
-        // hold autosave across the round-trip: an edit landing mid-rename must NOT save to the
-        // old name (a mustExist PUT would 409-gone and clear dirty, losing the edit)
-        renameLock = true
-        clearTimeout(saveTimer)
-      }
-      // Release the lock and resume autosave. Re-read the LIVE board, not the captured `active`:
-      // a board switch may have completed while we awaited, so only the board that is STILL
-      // `from` gets renamed to `to` in state (a switched-away board keeps its own name/nodes).
-      const release = () => { if (active) { renameLock = false; if (get().dirty) scheduleSave() } }
+    renameBoard(name, title, baseHash) {
+      return structural(async () => {
+        const from = name
+        const active = from === get().board
+        // 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-write would PUT against a
+          // hash the rewrite is about to move
+          holdSaves()
+        }
+        try {
+          // the active board's hash is freshest in the store (an autosave may have landed since
+          // the sidebar looked); every other board's is the sidebar's
+          const base = active && get().boardHash ? get().boardHash : baseHash
+          let res: Response
+          try { res = await postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) }) }
+          catch { return { ok: false, error: 'could not reach the dev server' } }
+          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('boards/rename', { from, to }) }
-      catch { release(); return { ok: false, error: 'could not reach the dev server' } }
-      if (!res.ok) {
-        release()
-        const e = await res.json().catch(() => ({} as { error?: string }))
-        return { ok: false, error: e?.error ?? `rename failed (${res.status})` }
-      }
-      // Content is byte-identical after a file move, so boardHash still matches for the next
-      // autosave; only the name (and the URL, via the board-change subscription) changes. Set
-      // the new name BEFORE releasing the lock so a resumed save targets `to`.
-      if (active && get().board === from) set({ board: to })
-      release()
+      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
+    },
 
-    async reorderBoards(order) {
-      let res: Response
-      try { res = await postOwner('boards/reorder', { order }) } catch { return false }
-      return res.ok
+    // The whole sidebar tree in one write: order, membership, the folders themselves. The
+    // write rewrites the ACTIVE board's file too (its `order`/`folder`), so it runs like a
+    // rename: flush the pending autosave first, hold autosave across the round-trip, then
+    // advance boardHash to the hash the server answered - the autosave's CAS token stays
+    // true and the watcher's echo is filtered as our own. `base` carries the hashes the
+    // sidebar last saw; a 409 (`stale`) means someone else wrote first - refetch and replay.
+    arrangeBoards(tree, base) {
+      return structural(async () => {
+        let ok = true
+        for (let i = 0; i < 5 && get().dirty && ok; i++) { clearTimeout(saveTimer); ok = await get().save() }
+        if (get().dirty) return { ok: false as const, stale: false, error: 'unsaved changes - try again' }
+        holdSaves()
+        try {
+          // the active board's hash is freshest in the store (an autosave may have landed since
+          // the sidebar looked); every other board's is the sidebar's
+          const active = get().board
+          const boards = { ...base.boards, ...(get().boardHash && base.boards[active] !== undefined ? { [active]: get().boardHash } : {}) }
+          let res: Response
+          try { res = await postOwner('boards/reorder', { tree: toWire(tree), base: { boards, folders: base.folders } }) }
+          catch { return { ok: false as const, stale: false, error: 'could not reach the dev server' } }
+          const body = await res.json().catch(() => ({} as { error?: string; sha256?: { boards?: Record<string, string> } }))
+          if (!res.ok) return { ok: false as const, stale: res.status === 409, error: body?.error }
+          const sha = body?.sha256?.boards?.[get().board]
+          if (sha) set({ boardHash: sha })
+          return { ok: true as const }
+        } finally { releaseSaves() }   // whatever happened, autosave resumes
+      })
     },
 
     applyManifest(m) {
@@ -1141,7 +1246,7 @@ export const useStore = create<State>((set, get) => {
     save() {
       // a rename is moving this board's file - defer every save so nothing writes to the OLD
       // name mid-move (renameBoard reschedules once the move commits under the new name)
-      if (renameLock) return Promise.resolve(false)
+      if (saveHolds > 0) return Promise.resolve(false)
       // a resize gesture in flight = torn state (new sizes, pre-recipe positions):
       // even a PREVIOUSLY scheduled timer must defer to the gesture-end save
       if (get().gesture && resizedInGesture) { scheduleSave(); return Promise.resolve(false) }

package/src/client/shell/styles.css

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