@marver-design/marver 0.21.0 → 0.22.0

package/src/client/shell/store.ts

@@ -17,6 +17,10 @@ const DATA: {
   tree?: TreeItem[]
   /** slug → title of the published boards (0.16.1 bundles); folder titles ride on `tree` */
   titles?: Record<string, string>
+  /** slug → resolved type, and the status a publish row opted into (0.22 bundles; spec 20) */
+  meta?: Record<string, BoardMeta>
+  /** when the build read the statuses it ships - a published status is a snapshot */
+  statusAsOf?: 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 }
   /** the generation of the glass textures this build shipped (publish-bakes.ts); absent = none */
@@ -25,6 +29,8 @@ const DATA: {
 
 /** The published textures' generation, or 0: the static index this build shipped is at /__mv/bakes/<gen>/index.json. */
 export const BAKES = DATA?.bakes ?? 0
+/** When a published bundle's statuses were read (spec 20) - absent in dev, where they are live. */
+export const STATUS_AS_OF = DATA?.statusAsOf ?? null
 
 /** Every published board is locked to a stage mode - the canvas shell is never
  *  offered on this bundle (01-sharing §5.1's all-boards rule). */
@@ -139,20 +145,32 @@ export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
 import { canAutoReload } from './canvas/ready-watch.ts'
 import { buildTree, flatten, labelOf, toWire, TREE_PROTOCOL, type TreeItem } from '../../shared/board-tree.ts'
+import type { BoardType, StatusWord } from '../../shared/board-types.ts'
+import type { Phase, Status } from '../../shared/status.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; titles: Record<string, string> }
+export interface TreeSnapshot { tree: TreeItem[]; base: TreeBase; titles: Record<string, string>; meta: Record<string, BoardMeta> }
+/** What spec 20 adds to a board's row: its resolved type, and - for feature and project boards -
+ *  its status read from context/. Dev carries the evidence for the tooltip; a published bundle
+ *  carries only what its publish row opted into. */
+export interface BoardMeta {
+  type?: BoardType
+  /** `row` is the table row that decided it (1-3: a decision on the board) */
+  status?: { status: Status; row?: number; fill?: Phase; reason?: string; evidence?: string[] }
+  /** what a person may set it to from the sidebar (dev only) - shared/board-types settableStatuses */
+  settable?: StatusWord[]
+}
 
 /** The sidebar tree: root boards and folders in rank order, each folder's boards and
  *  sub-folders 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 ?? {} }
+  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 ?? {}, meta: DATA.meta ?? {} }
   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/boards`).then((r) => r.json()) as Promise<{ name: string; sha256: string; order?: number; folder?: string; title?: string; type?: BoardType; status?: BoardMeta['status'] | null; settable?: StatusWord[] }[]>,
     fetch(`${ROUTE}/api/folders`).then(async (r) => {
       const j = await r.json() as { folders?: { name: string; order?: number; parent?: string; title?: string }[]; sha256?: string | null; error?: string }
       if (!r.ok) throw new Error(j?.error ?? `folders ${r.status}`)
@@ -163,8 +181,13 @@ export async function fetchBoardTree(): Promise<TreeSnapshot> {
     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]] : []))),
+    meta: Object.fromEntries(boards.map((b) => [b.name, { ...(b.type && b.type !== 'plain' ? { type: b.type } : {}), ...(b.status ? { status: b.status } : {}), ...(b.settable?.length ? { settable: b.settable } : {}) }])),
   }
 }
+/** A tree read's types and statuses, kept under the same latest-wins rule as its titles. */
+export function rememberMeta(meta: Record<string, BoardMeta>) {
+  if (JSON.stringify(useStore.getState().boardMeta) !== JSON.stringify(meta)) useStore.setState({ boardMeta: meta })
+}
 /** 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. */
@@ -179,6 +202,7 @@ export async function fetchBoardNames(): Promise<string[]> {
   if (DATA) return DATA.names
   const snap = await fetchBoardTree()
   rememberTitles(snap.titles)
+  rememberMeta(snap.meta)
   return [...flatten(snap.tree), 'all-scenes']
 }
 /** Does the switcher carry the auto `all-scenes` board? Always in dev; published only when it shipped. */
@@ -322,7 +346,9 @@ interface State {
   imagePulse: number                                       // bumps on each successful image copy - same flash, the images-square icon
   imageBusy: boolean                                       // a copy-as-image render is in flight (one at a time)
 
-  boot(): Promise<boolean>
+  /** (re)load the open board from disk. `mayCommit`, when given, is asked again at the moment the
+   *  reload would land - a caller's own conditions (a status write's: nothing moved since its flush) */
+  boot(mayCommit?: () => boolean): Promise<boolean>
   applyManifest(m: Manifest): void
   frameFor(node: Node): FrameEntry | undefined
   moveNode(key: string, x: number, y: number): void
@@ -353,10 +379,16 @@ interface State {
   switchBoard(name: string): Promise<void>
   /** what the sidebar labels boards by: slug → title, off the last tree read */
   boardTitles: Record<string, string>
+  /** what the sidebar draws beside a board: its type and status (spec 20), off the last tree read */
+  boardMeta: Record<string, BoardMeta>
   /** 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 board's status, decided by a person (the sidebar's picker): one of its `settable` statuses,
+   *  or null to clear the decision (back to the evidence); blocked carries its reason. Only
+   *  `status` and `reason` change in the file; a 409 (`stale`) means someone wrote it since. */
+  setBoardStatus(name: string, status: StatusWord | null, reason?: 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 */
@@ -669,10 +701,10 @@ 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, boardTitles: DATA?.titles ?? {},
+    panelOpen: true, scale: 1, toasts: [], working: [], workingSince: {}, boardHash: null, dirty: false, boardTitles: DATA?.titles ?? {}, boardMeta: DATA?.meta ?? {},
     pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0, pathPulse: 0, imagePulse: 0, imageBusy: false,
 
-    async boot() {
+    async boot(mayCommit) {
       const seq = ++loadSeq
       const boardName = get().board
       const revAtStart = editRev, scenesAtStart = scenesRev
@@ -680,7 +712,7 @@ export const useStore = create<State>((set, get) => {
       if (seq !== loadSeq) return false        // a newer load superseded this one
       if (!next) { get().toast(`board "${boardName}" failed to load`); return false }
       // the user kept editing while we fetched - their newer state wins over the reload
-      if (get().board !== boardName || editRev !== revAtStart) return false
+      if (get().board !== boardName || editRev !== revAtStart || (mayCommit && !mayCommit())) return false
       const live = get().manifest             // a WS manifest update may have landed mid-fetch
       set(next)
       if (next.dirty) scheduleSave()          // load-time prune must reach the disk
@@ -738,12 +770,18 @@ export const useStore = create<State>((set, get) => {
           // hash the rewrite is about to move
           holdSaves()
         }
+        const rev = editRev                                          // setBoardStatus's guard on the reload
+        const mayReload = () => active && get().board === from && editRev === rev && !get().gesture
         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
+          const send = (base: string | null | undefined) => postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) })
           let res: Response
-          try { res = await postOwner('boards/rename', { from, title, ...(base ? { baseHash: base } : {}) }) }
+          try {
+            res = await send(active && get().boardHash ? get().boardHash : baseHash)
+            // the open board changed on disk: reload it, then once more (setBoardStatus's reasoning)
+            if (res.status === 409 && mayReload() && await get().boot(mayReload)) res = await send(get().boardHash)
+          }
           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})` }
@@ -758,6 +796,47 @@ export const useStore = create<State>((set, get) => {
       })
     },
 
+    setBoardStatus(name, status, reason, baseHash) {
+      return structural(async () => {
+        const active = name === get().board
+        // the active board's file is rewritten under the autosave: flush first, hold across (renameBoard's pattern)
+        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' }
+          holdSaves()
+        }
+        // what a reload may replace: this board as flushed - holdSaves pauses saving, not editing, so an
+        // edit, a drag or a board switch while the request is out means the reload is not ours to do
+        const rev = editRev
+        const mayReload = () => active && get().board === name && editRev === rev && !get().gesture
+        try {
+          const send = (base: string | null | undefined) => postOwner('boards/status', { name, status, ...(reason ? { reason } : {}), ...(base ? { baseHash: base } : {}) })
+          let res: Response
+          try {
+            res = await send(active && get().boardHash ? get().boardHash : baseHash)
+            // the open board changed on disk (an agent wrote it): its hash in the store is behind, and a
+            // retry with it would 409 again - reload the board (layout and hash together) when nothing
+            // has changed here since the flush, then try once more against what is on disk now
+            if (res.status === 409 && mayReload() && await get().boot(mayReload)) res = await send(get().boardHash)
+          }
+          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 ?? `status failed (${res.status})` }
+          if (active && get().board === name && body?.sha256) set({ boardHash: body.sha256 })
+          // a decision shows at once; what the evidence says after a clear comes with the next tree read
+          if (status) {
+            const meta = { ...get().boardMeta }
+            const cur = meta[name] ?? {}
+            const row = ({ archived: 1, paused: 2, blocked: 3, 'in-progress': 5, done: 6, todo: 8, backlog: 9 } as const)[status]
+            meta[name] = { ...cur, status: { status, row, ...(status === 'blocked' && reason ? { reason } : {}), evidence: [`design/boards/${name}.json: "status": "${status}"`] } }
+            set({ boardMeta: meta })
+          }
+          return { ok: true }
+        } finally { if (active) releaseSaves() }
+      })
+    },
+
     async renameScene(scene, title) {
       let res: Response
       try { res = await postOwner('scenes/rename', { scene, title }) }

package/src/client/shell/styles.css

@@ -469,6 +469,15 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-panel .it.board svg { color: var(--glass-ink-3); flex: none; margin: 0 1px; transition: color .2s ease }
 .sh-panel .it.board.cur { background: var(--accent-wash); color: var(--glass-accent); font-weight: 600 }
 .sh-panel .it.board.cur svg { color: var(--glass-accent) }
+/* spec 20: a feature or project board's status ring sits at the row's end, in its own colours -
+   never the accent of the current row - with its evidence in the tooltip */
+.sh-panel .it.board .st { flex: none; display: inline-flex; margin-left: auto; font-style: normal }
+/* the settled statuses' fills, one value per theme: done is the content palette's green (Apple's
+   systemGreen); archived is Apple's brown - its increased-contrast value on light, its default on
+   dark, where the increased-contrast one turns peach - so it reads as the same brown box in both */
+.sh-app { --status-done: #34c759; --status-archived: #956d51 }
+.sh-app.dark { --status-done: #30d158; --status-archived: #b78a66 }
+.sh-panel .it.board .st svg, .sh-panel .it.board.cur .st svg { color: inherit; margin: 0 }
 /* drag-to-reorder: a grab cursor, the lifted row dims, and a 2px accent rule marks the
    drop seam above or below the hovered row */
 /* a board row is click-to-switch first (pointer on hover); the grabbing hand appears the
@@ -508,14 +517,16 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .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, .sh-panel .it.folder.in-folder { padding-left: 28px }
-.sh-panel .it.board.in-sub { padding-left: 56px }
+/* 8px row padding + INDENT (22px, board-tree.ts) per level: a nested row's icon starts exactly
+   where its folder's name starts, at every level */
+.sh-panel .it.board.in-folder, .sh-panel .it.folder.in-folder { padding-left: 30px }
+.sh-panel .it.board.in-sub { padding-left: 52px }
 .sh-panel .it.board.draft { cursor: default; opacity: .6 }
 /* seams are indented with the list they land in (--seam-left, set on the row that draws them),
    so "inside", "inside the sub-folder" and "at the root" never draw alike; an open EMPTY folder
    draws that indented seam under its own header (drop-in) */
 .sh-panel .it.folder.drop-in { position: relative }
-.sh-panel .it.folder.drop-in::after { content: ''; position: absolute; left: var(--seam-left, 28px); right: 6px; bottom: -1px; height: 3px; border-radius: 3px;
+.sh-panel .it.folder.drop-in::after { content: ''; position: absolute; left: var(--seam-left, 30px); 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 }
@@ -588,6 +599,26 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .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 }
+/* the board status picker (StatusPicker.tsx): opens in place of the right-click menu - a filter,
+   what the evidence says now, the statuses a person may set, numbered, and a line on the rest */
+.sh-ctxpanel { width: 248px; max-width: 248px }
+.sh-status-picker { display: flex; flex-direction: column }
+.sh-status-picker .sp-input { height: 32px; margin: 0 0 4px; padding: 0 10px; border: 0; border-bottom: 1px solid var(--glass-brd);
+  border-radius: 0; background: none; color: var(--glass-ink); font: 500 12.5px -apple-system, system-ui, sans-serif; outline: 0 }
+.sh-status-picker .sp-input::placeholder { color: var(--glass-ink-3) }
+.sh-status-picker .sp-now { display: flex; align-items: center; gap: 8px; height: 30px; padding: 0 10px; margin-bottom: 2px;
+  font: 500 12px -apple-system, system-ui, sans-serif; color: var(--glass-ink) }
+.sh-status-picker .sp-now small { margin-left: auto; color: var(--glass-ink-3); font-size: 11px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 120px }
+.sh-status-picker .sp-list { display: flex; flex-direction: column }
+.sh-status-picker .sp-list button { width: 100% }
+.sh-status-picker .sp-list button.hi { background: var(--glass-hover) }
+.sh-status-picker .sp-list button span { text-transform: none }
+.sh-status-picker .sp-chk { color: var(--glass-ink); flex: none }
+.sh-status-picker .sp-head { display: flex; align-items: center; gap: 8px; height: 30px; padding: 0 10px; font: 600 12px -apple-system, system-ui, sans-serif; color: var(--glass-ink) }
+.sh-status-picker .sp-empty { padding: 8px 10px; color: var(--glass-ink-3); font: 500 12px -apple-system, system-ui, sans-serif }
+.sh-status-picker .sp-foot { border-top: 1px solid var(--glass-brd); margin-top: 4px; padding: 7px 10px 3px; color: var(--glass-ink-3);
+  font: 500 11px/1.35 -apple-system, system-ui, sans-serif }
+.sh-status-picker[data-status-picker="reason"] .sp-input { border: 1px solid var(--glass-brd); border-radius: 9px; margin: 2px 6px 0; height: 30px }
 
 /* shadcn-style tooltip: contrast-flipped solid, zoom-fade in */
 .sh-tip { position: absolute; z-index: 400; pointer-events: none; padding: 5px 10px; border-radius: 8px;   /* topmost ephemeral chrome - above modals (300) or in-dialog tips vanish */

package/src/shared/board-tree.ts

@@ -8,6 +8,8 @@
  * tree - callers pin it last.
  */
 
+import { readType } from './board-types.ts'
+
 /** The on-disk name grammar shared by boards and folders (a board name is a filename). */
 export const BOARD_NAME = /^[a-z0-9][a-z0-9-]*$/
 export const NAME_MAX = 64
@@ -20,11 +22,11 @@ export const FOLDERS_FILE = '_folders.json'
 export const isBoardFile = (f: string): boolean => f.endsWith('.json') && isBoardName(f.slice(0, -5))
 
 /** A folder and what it holds, in order: boards, and - in a top-level folder only - sub-folders. */
-export type Folder = { kind: 'folder'; name: string; items: TreeItem[]; title?: string; description?: string }
+export type Folder = { kind: 'folder'; name: string; items: TreeItem[]; title?: string; description?: string; type?: string }
 export type TreeItem = { kind: 'board'; name: string } | Folder
 
 export interface BoardRow { name: string; order?: number; folder?: string; title?: string }
-export interface FolderRow { name: string; order?: number; parent?: string; title?: string; description?: string }
+export interface FolderRow { name: string; order?: number; parent?: string; title?: string; description?: string; type?: string }
 
 /** A description off a file: one sentence, trimmed, capped - absent when empty or not a string. */
 export const DESCRIPTION_MAX = 300
@@ -50,8 +52,12 @@ export const humanize = (s: string): string => s.replace(/-/g, ' ').replace(/(^|
 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 } : {}) })
+/** A folder's title, description and type, present only when set. */
+const folderExtras = (it: { title?: string; description?: string; type?: string }) => ({
+  ...(it.title ? { title: it.title } : {}),
+  ...(it.description ? { description: it.description } : {}),
+  ...(readType(it.type) ? { type: it.type } : {}),
+})
 
 /** The registry versions this code reads. Version 2 is written only when a folder has a
  *  `parent`, so a flat registry stays readable by every Marver; an older Marver refuses a
@@ -85,7 +91,8 @@ export function parseFolders(raw: unknown): FolderRow[] | string {
     if (p !== undefined && !isBoardName(p)) return `folder "${name}" has an invalid parent - a folder name`
     const t = readTitle((f as { title?: unknown }).title)
     const d = readDescription((f as { description?: unknown }).description)
-    out.push({ name, ...(typeof o === 'number' && Number.isFinite(o) ? { order: o } : {}), ...(p !== undefined ? { parent: p } : {}), ...(t ? { title: t } : {}), ...(d ? { description: d } : {}) })
+    const ty = readType((f as { type?: unknown }).type)
+    out.push({ name, ...(typeof o === 'number' && Number.isFinite(o) ? { order: o } : {}), ...(p !== undefined ? { parent: p } : {}), ...(t ? { title: t } : {}), ...(d ? { description: d } : {}), ...(ty ? { type: ty } : {}) })
   }
   const byName = new Map(out.map((f) => [f.name, f]))
   for (const f of out) {
@@ -104,7 +111,7 @@ export function parseFolders(raw: unknown): FolderRow[] | string {
  *  after ranked. The root holds root boards and top-level folders (registered without a
  *  parent, or implied by a board that names an unregistered folder); a top-level folder holds
  *  its boards and its sub-folders; a sub-folder holds its boards. A folder's title and
- *  description ride on its item (they live in the registry a tree write rewrites); a board's
+ *  description and type 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 reg = new Map<string, FolderRow>()
@@ -152,12 +159,12 @@ export function flatten(tree: TreeItem[]): string[] {
 
 /** The wire shape of a tree write (`POST boards/reorder`): plain strings for boards,
  *  `{ folder, items }` for folders, `items` holding boards and - one level down - folders.
- *  What the sidebar posts and the server validates. A folder's title and description ride
+ *  What the sidebar posts and the server validates. A folder's title, description and type ride
  *  with it (they live in the registry the write rewrites); a board's title lives in its own
  *  file and never rides the tree. A one-level `{ folder, boards }` item (an older shell) is
  *  still read. */
-export type WireItem = string | { folder: string; items: WireItem[]; title?: string; description?: string }
-type WireIn = string | { folder: string; items?: WireIn[]; boards?: string[]; title?: string; description?: string }
+export type WireItem = string | { folder: string; items: WireItem[]; title?: string; description?: string; type?: string }
+type WireIn = string | { folder: string; items?: WireIn[]; boards?: string[]; title?: string; description?: string; type?: string }
 export const toWire = (tree: TreeItem[]): WireItem[] =>
   tree.map((it) => (it.kind === 'board' ? it.name : { folder: it.name, items: toWire(it.items), ...folderExtras(it) }))
 export const wireKids = (w: Exclude<WireIn, string>): WireIn[] => w.items ?? w.boards ?? []
@@ -183,10 +190,11 @@ export function validateWire(wire: unknown): string | null {
       if (typeof w === 'string') { const e = board(w); if (e) return e; continue }
       if (!w || typeof w !== 'object' || Array.isArray(w)) return 'invalid tree item'
       if (depth >= 2) return 'folders nest one level only'
-      const { folder, items, boards: legacy, title, description } = w as { folder?: unknown; items?: unknown; boards?: unknown; title?: unknown; description?: unknown }
+      const { folder, items, boards: legacy, title, description, type } = w as { folder?: unknown; items?: unknown; boards?: unknown; title?: unknown; description?: unknown; type?: 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 (type !== undefined && !readType(type)) return 'invalid folder type'
       if (folders.has(folder)) return `folder "${folder}" appears twice`
       folders.add(folder)
       const kids = items ?? legacy
@@ -213,7 +221,7 @@ export function slugify(raw: string): string {
 // ---- reading the tree ----
 
 /** A deep copy: mutations work on it and the caller's tree stays as it was (a folder's
- *  title and description ride along). */
+ *  title, description and type ride along). */
 export const cloneTree = (t: TreeItem[]): TreeItem[] => t.map((it) => (it.kind === 'board' ? { ...it } : { ...it, items: cloneTree(it.items) }))
 /** Every folder with the folder it sits in (null = the root), top-level folders first in
  *  reading order, each followed by its sub-folders. */
@@ -230,6 +238,12 @@ export function folderEntries(t: TreeItem[]): { folder: Folder; parent: string |
 export const folderIn = (t: TreeItem[], name: string): Folder | undefined => folderEntries(t).find((e) => e.folder.name === name)?.folder
 /** The folder a folder sits in - null for a top-level folder (or one that is not there). */
 export const parentOf = (t: TreeItem[], name: string): string | null => folderEntries(t).find((e) => e.folder.name === name)?.parent ?? null
+/** Every board's folder, in one pass - for callers that ask for many boards (folderOf walks the tree). */
+export function folderMap(t: TreeItem[]): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const { folder } of folderEntries(t)) for (const k of folder.items) if (k.kind === 'board') out.set(k.name, folder.name)
+  return out
+}
 /** The folder a board sits in directly, at either level - null at the root. */
 export function folderOf(t: TreeItem[], board: string): string | null {
   for (const { folder } of folderEntries(t)) if (folder.items.some((k) => k.kind === 'board' && k.name === board)) return folder.name
@@ -278,8 +292,11 @@ export type Drop = { list: string | null; index: number } | { into: string }
  *  folder's items, 2 a sub-folder's). `open` is a folder's disclosure; `left` is the row's
  *  left edge, from which the indent of each level is measured. */
 export interface Row { kind: TreeItem['kind']; name: string; parent: string | null; depth: number; open?: boolean; top: number; bottom: number; left: number }
-/** Px each level of nesting indents its rows; the seams inside draw from there too. */
-export const INDENT = 28
+/** Px each level of nesting indents its rows; the seams inside draw from there too. One step is
+ *  a row's lead (1px icon margin + 14px icon + 1px margin + 7px gap) less the icon's own left
+ *  margin, so a nested row's icon starts exactly where its folder's name does (styles.css,
+ *  `.in-folder` / `.in-sub`). */
+export const INDENT = 22
 
 /** How deep the dragged item may land: a board anywhere (2), a folder without sub-folders
  *  inside a top-level folder (1), a folder holding sub-folders at the root only (0). */

package/src/shared/board-types.ts

@@ -0,0 +1,103 @@
+/**
+ * Board types (spec 20) - what a board is FOR in the workspace, one vocabulary every canvas
+ * shares so any sidebar reads at a glance. A board states its own `"type"`, or wears the type of
+ * the nearest typed folder above it (its folder, then that folder's parent), else it is plain.
+ * Moving a board changes an inherited type, never one the board states itself.
+ *
+ * Pure and shared: the dev API, the manifest, the build, the shell and the CLI all read types
+ * through here, so a type means one thing everywhere.
+ */
+
+export const BOARD_TYPES = ['start', 'feature', 'surface', 'project', 'feedback', 'context', 'deck', 'archive'] as const
+export type KnownType = (typeof BOARD_TYPES)[number]
+export type BoardType = KnownType | 'plain'
+
+/** What each type is for - the sidebar's tooltip, the CLI's help, the docs. */
+export const TYPE_ROLES: Record<BoardType, string> = {
+  start: 'the way in: the index, the shipped record, the timeline',
+  feature: 'one capability: its spec, lo-fi and hi-fi',
+  surface: 'the whole product to walk, from frames on feature boards',
+  project: 'a deliverable or a question',
+  feedback: 'one frame per theme',
+  context: 'what came in from outside: meetings, threads, competitors',
+  deck: 'slides',
+  archive: 'snapshots and retired work',
+  plain: 'a board',
+}
+
+/** The grammar a stored type keeps to. Any on-grammar word survives a write - a newer Marver's
+ *  type is never dropped by an older shell - while only the known ones are drawn. */
+export const TYPE_GRAMMAR = /^[a-z][a-z-]{0,31}$/
+/** A type off a file: the word when it is on-grammar, else absent. */
+export const readType = (v: unknown): string | undefined => (typeof v === 'string' && TYPE_GRAMMAR.test(v) ? v : undefined)
+/** A type this Marver draws. */
+export const knownType = (v: unknown): KnownType | undefined =>
+  (BOARD_TYPES as readonly string[]).includes(v as string) ? (v as KnownType) : undefined
+
+/** A board's type: its own when it states one (an unknown word reads as plain - the board spoke
+ *  for itself), else its folder's, else that folder's parent's, else plain. */
+export function resolveType(own: unknown, folder?: unknown, parent?: unknown): BoardType {
+  if (readType(own)) return knownType(own) ?? 'plain'
+  return knownType(folder) ?? knownType(parent) ?? 'plain'
+}
+
+/** The publish type a board's type proposes when its publish row names none - how a board
+ *  PRESENTS when published, a separate question from what it is for. */
+export const PROPOSED_PUBLISH: Partial<Record<BoardType, 'slides' | 'refs' | 'doc' | 'mix'>> = {
+  deck: 'slides',
+  context: 'refs',
+  project: 'doc',
+  feature: 'mix',
+  surface: 'mix',
+}
+
+/** The types that carry a status (spec 20, open question 2: features and projects - the others
+ *  have no lifecycle of their own). */
+export const HAS_STATUS: readonly BoardType[] = ['feature', 'project']
+
+/** The decisions a board may state by hand. `done` is never one: Done comes only from the shipped
+ *  record. `todo`, `backlog` and `in-progress` count only where there is no `context/`. */
+export const DECISIONS = ['archived', 'paused', 'blocked'] as const
+export const BY_HAND = ['in-progress', 'todo', 'backlog'] as const
+export const STATUS_WORDS = [...DECISIONS, ...BY_HAND, 'done'] as const
+export type StatusWord = (typeof STATUS_WORDS)[number]
+export const readStatusWord = (v: unknown): StatusWord | undefined =>
+  (STATUS_WORDS as readonly string[]).includes(v as string) ? (v as StatusWord) : undefined
+/** The statuses a person may set on a feature or project board, in the order a picker lists them:
+ *  the three decisions always; Backlog, To do and In progress only where there is no `context/`
+ *  (with it they are read from the evidence). Never Done - that is the shipped record's alone. */
+export const settableStatuses = (contextPresent: boolean): StatusWord[] =>
+  contextPresent ? ['blocked', 'paused', 'archived'] : ['backlog', 'todo', 'in-progress', 'blocked', 'paused', 'archived']
+
+/** A capability slug - the same grammar as a board name, so a feature board and its contract
+ *  share it. */
+export const readCapability = (v: unknown): string | undefined =>
+  typeof v === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v) ? v : undefined
+/** A blocked board's reason: one sentence, trimmed and capped. */
+export const REASON_MAX = 300
+export const readReason = (v: unknown): string | undefined => {
+  if (typeof v !== 'string') return undefined
+  const s = v.trim().replace(/\s+/g, ' ').slice(0, REASON_MAX)
+  return s || undefined
+}
+
+/** The sidebar every canvas shares (spec 19, The canvas): folder modules, each typed, so a board
+ *  made inside one wears its type. `marver init --kind` creates a kind's set on a fresh canvas;
+ *  `marver folders add <module>` adds one later. Names are slugs; only Start here needs a title. */
+export const FOLDER_MODULES: Record<string, { name: string; title?: string; type: KnownType }> = {
+  start: { name: 'start-here', title: 'Start here', type: 'start' },
+  features: { name: 'features', type: 'feature' },
+  surfaces: { name: 'surfaces', type: 'surface' },
+  projects: { name: 'projects', type: 'project' },
+  feedback: { name: 'feedback', type: 'feedback' },
+  context: { name: 'context', type: 'context' },
+  decks: { name: 'decks', type: 'deck' },
+  archive: { name: 'archive', type: 'archive' },
+}
+/** A kind of work's folders, in sidebar order: the core (Start here, Feedback, Context, Archive)
+ *  around the kind's own modules. Decks are an add-on for either. */
+export const KIND_FOLDERS = {
+  product: ['start', 'features', 'surfaces', 'feedback', 'context', 'archive'],
+  knowledge: ['start', 'projects', 'feedback', 'context', 'archive'],
+} as const
+export type Kind = keyof typeof KIND_FOLDERS