@marver-design/marver 0.16.0 → 0.16.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

@@ -133,8 +133,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

@@ -132,8 +132,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

package/templates/instructions/discover.md

@@ -45,7 +45,19 @@ e.g. `# Checkout - the buyer's path from cart to receipt (v2, after the pricing
 That line lands in `design/manifest.json` as the scene's `description`, so a later
 session reads it without opening the brief; keep it true as the scene moves on (a
 scene that only needs a gist - a version snapshot, an archive - gets a one-line brief).
-Show it. Get the nod.
+A scene's directory is its identity (every frame id starts with it); what humans SEE
+for it is `title` in the brief's YAML front matter - optional, free text - the sidebar
+Title-Cases the directory otherwise (`checkout` → "Checkout", but `mvp` → "Mvp"):
+
+```md
+---
+title: "Checkout (v2)"
+---
+# Checkout - the buyer's path from cart to receipt (v2, after the pricing pivot)
+```
+
+The human's Rename on a scene writes exactly that line; leave the block alone and
+never rename the directory for a title. Show the brief. Get the nod.
 
 **Unattended?** When the human is away or has said "don't ask", the interview and
 the nod convert to obligations, not blockers: answer the five questions yourself