@marver-design/marver 0.3.1 → 0.5.0

package/src/client/shell/comments-store.ts

@@ -0,0 +1,180 @@
+/**
+ * Comment state for the shell (SPEC-M3 §6) - its own small store beside the canvas
+ * store. One API client for both worlds: `marver dev` (api.ts mirror, local profile,
+ * poll) and the published serve (collab.ts, sessions, SSE). The shell never branches
+ * on which one it is beyond capability flags the endpoints themselves report.
+ */
+import { create } from 'zustand'
+import { replay, type CommentEvent, type Thread } from '../../shared/events.ts'
+import { ROUTE } from '../const.ts'
+
+export interface Me { email: string; name: string; avatar?: string }
+
+interface CommentsState {
+  events: CommentEvent[]              // the active board's log
+  threads: Thread[]                   // derived on every change
+  board: string | null
+  me: Me | null                       // null on published until signed in
+  local: boolean                      // dev mirror (identity is the local profile)
+  commentMode: boolean                // C - picking + composing
+  show: boolean                       // Shift+C - pins visible at all
+  active: string | null               // open thread id
+  draft: { nodeKey: string; frame: string; anchor: unknown } | null   // picked, composing
+  needsIdentity: boolean              // published viewer tried to comment while signed out
+  inviteToken: string | null          // arrived via an invite link - claim flow, token known
+
+  load(board: string): Promise<void>
+  live(board: string): () => void
+  send(events: CommentEvent[]): Promise<boolean>
+  create(body: string): Promise<void>
+  reply(threadId: string, body: string): Promise<void>
+  replyOk(threadId: string, body: string): Promise<boolean>
+  resolve(threadId: string, reopen?: boolean): Promise<void>
+  setMode(on: boolean): void
+  setShow(show: boolean): void
+  setActive(id: string | null): void
+  setDraft(d: CommentsState['draft']): void
+  signIn(email: string, password: string): Promise<string | null>
+  claim(token: string, password: string, name: string, avatar?: string): Promise<string | null>
+  saveProfile(patch: Partial<Me>): Promise<void>
+  dismissIdentity(): void
+}
+
+const uuid = () => crypto.randomUUID()
+const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
+const api = async (path: string, body?: unknown) => {
+  const res = await fetch(`${ROUTE}/api/${path}`, body === undefined ? undefined : {
+    method: 'POST', headers: { 'content-type': 'application/json', 'x-mv-c': csrf() },
+    body: JSON.stringify(body),
+  })
+  return { ok: res.ok, status: res.status, data: await res.json().catch(() => ({})) }
+}
+
+export const useComments = create<CommentsState>((set, get) => {
+  const derive = (events: CommentEvent[]) => ({ events, threads: replay(events) })
+  const union = (events: CommentEvent[]) => {
+    const have = new Set(get().events.map((e) => e.id))
+    const fresh = events.filter((e) => !have.has(e.id))
+    if (fresh.length) set(derive([...get().events, ...fresh]))
+  }
+
+  return {
+    events: [], threads: [], board: null, me: null, local: false,
+    commentMode: false, show: true, active: null, draft: null, needsIdentity: false, inviteToken: null,
+
+    async load(board) {
+      set({ board })
+      const me = await api('me')
+      if (me.ok) set({ me: me.data.user ?? null, local: !!me.data.local })
+      const res = await api(`comments/${board}`)
+      if (res.ok && get().board === board) set(derive(res.data.events ?? []))
+    },
+
+    /** Liveness: SSE on the published serve; dev has no event rail (its sync loop
+     *  writes files) so it polls only - an EventSource there would 404-retry forever. */
+    live(board) {
+      const stops: (() => void)[] = []
+      let es: EventSource | null = null
+      const wantSSE = () => {
+        if (es || get().local) return
+        es = new EventSource(`${ROUTE}/api/events`)
+        es.addEventListener('comment', (e) => {
+          try {
+            const { board: b, ev } = JSON.parse((e as MessageEvent).data)
+            if (b === get().board) union([ev])
+          } catch { /* ignore */ }
+        })
+        es.addEventListener('resync', () => { void get().load(board) })
+        es.onerror = () => { /* EventSource retries itself; the poll covers the gap */ }
+      }
+      // `local` is only known once load() has answered - defer the SSE decision past it
+      const t = setTimeout(wantSSE, 1500)
+      stops.push(() => { clearTimeout(t); es?.close() })
+      const poll = () => { if (get().board === board) void api(`comments/${board}`).then((r) => r.ok && union(r.data.events ?? [])) }
+      const iv = setInterval(poll, 30_000)
+      const onFocus = () => poll()
+      window.addEventListener('focus', onFocus)
+      stops.push(() => { clearInterval(iv); window.removeEventListener('focus', onFocus) })
+      return () => stops.forEach((f) => f())
+    },
+
+    async send(events) {
+      const { board } = get()
+      if (!board) return false
+      const res = await api(`comments/${board}`, { events })
+      if (res.status === 401) { set({ needsIdentity: true }); return false }
+      // any other refusal gets said out loud - a silent dead Enter key reads as a bug
+      // (the canonical case: a signed-in viewer on a read-only board)
+      if (!res.ok) {
+        const { useStore } = await import('./store.ts')
+        useStore.getState().toast(String((res.data as any)?.error ?? 'comment rejected'))
+      }
+      // union only what the server took - a rejected send must not leave phantoms -
+      // and only if the user is still LOOKING at that board (a slow response after a
+      // board switch must not leak events into the wrong client state); client ids
+      // keep the eventual SSE/poll echo idempotent either way
+      if (res.ok && get().board === board) union(events)
+      return res.ok
+    },
+
+    async create(body) {
+      const { draft, me } = get()
+      if (!draft || !body.trim()) return
+      const id = uuid()
+      const ok = await get().send([{
+        id: uuid(), ts: Date.now(), type: 'create', commentId: id,
+        nodeKey: draft.nodeKey, frame: draft.frame, anchor: draft.anchor,
+        author: me ?? undefined, body: body.trim(),
+      }])
+      if (ok) set({ draft: null, active: id, commentMode: false })
+    },
+
+    async reply(threadId, body) { await get().replyOk(threadId, body) },
+    async replyOk(threadId, body) {
+      if (!body.trim()) return false
+      return get().send([{
+        id: uuid(), ts: Date.now(), type: 'reply', commentId: uuid(), parentId: threadId,
+        author: get().me ?? undefined, body: body.trim(),
+      }])
+    },
+
+    async resolve(threadId, reopen = false) {
+      await get().send([{ id: uuid(), ts: Date.now(), type: reopen ? 'reopen' : 'resolve', commentId: threadId }])
+    },
+
+    setMode(on) { set({ commentMode: on, ...(on ? { show: true } : { draft: null }) }) },
+    setShow(show) { set({ show }) },
+    setActive(active) { set({ active }) },
+    setDraft(draft) { set({ draft }) },
+    dismissIdentity() { set({ needsIdentity: false }) },   // inviteToken survives dismissal - commenting later reopens the claim
+
+    async signIn(email, password) {
+      const res = await api('auth/signin', { email, password })
+      if (!res.ok) return res.data?.error ?? 'sign-in failed'
+      set({ me: res.data.user, needsIdentity: false })
+      return null
+    },
+    async claim(token, password, name, avatar) {
+      const res = await api('auth/claim', { token, password, name, avatar })
+      if (!res.ok) return res.data?.error ?? 'claim failed'
+      set({ me: res.data.user, needsIdentity: false, inviteToken: null })
+      return null
+    },
+    async saveProfile(patch) {
+      const res = await api('profile', patch)
+      if (res.ok) set({ me: res.data.user })
+    },
+  }
+})
+
+// dev-only debug handle - the canvas store exposes the same
+if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) (window as any).__mvComments = useComments
+
+/** Initials + deterministic hue for avatarless authors - the whole fallback ladder. */
+export const avatarFallback = (author?: { email?: string; name?: string }) => {
+  const name = author?.name || author?.email || '?'
+  const initials = name.split(/\s+/).map((w) => w[0]).slice(0, 2).join('').toUpperCase()
+  let h = 0
+  for (const c of (author?.email || name)) h = (h * 31 + c.charCodeAt(0)) % 360
+  return { initials, hue: h }
+}

package/src/client/shell/cursor-arrow-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 26 26"><defs><filter id="s" x="-40%" y="-40%" width="180%" height="180%"><feDropShadow dx="0.4" dy="0.9" stdDeviation="0.7" flood-color="#000000" flood-opacity="0.4"/></filter></defs><g filter="url(#s)"><g transform="rotate(-20 6 3)"><path fill="#FFFFFF" stroke="#18181b" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round" d="M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a1 1 0 0 1 .7-.3h6.87a1 1 0 0 0 .7-1.7L6.35 2.85a.5.5 0 0 0-.85.35Z"/></g></g></svg>

package/src/client/shell/cursor-arrow.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="22" height="22" viewBox="0 0 26 26"><defs><filter id="s" x="-40%" y="-40%" width="180%" height="180%"><feDropShadow dx="0.4" dy="0.9" stdDeviation="0.7" flood-color="#000000" flood-opacity="0.4"/></filter></defs><g filter="url(#s)"><g transform="rotate(-20 6 3)"><path fill="#000000" stroke="#FFFFFF" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round" d="M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a1 1 0 0 1 .7-.3h6.87a1 1 0 0 0 .7-1.7L6.35 2.85a.5.5 0 0 0-.85.35Z"/></g></g></svg>

package/src/client/shell/hash.ts

@@ -7,12 +7,16 @@
  *   #/                     default board, fit all
  *   #/b/<board>            board, fit all
  *   #/b/<board>?n=k1,k2    board with nodes selected, camera fit to selection
+ *   #/b/<board>?c=<id>     board with a comment thread open (SPEC-M3 §6)
+ *   #/i/<token>            invite link - opens the claim dialog with the token
  *   #/p/<board>?at=<frame-id>&device=<viewport>&theme=<theme>   play mode
  */
 
 export interface HashState {
   board?: string
   n?: string[]
+  c?: string
+  invite?: string
   play?: { at?: string; device?: string; theme?: string }
 }
 
@@ -25,13 +29,16 @@ export function parseHash(hash: string = location.hash): HashState {
     const q = raw.indexOf('?')
     const path = q === -1 ? raw : raw.slice(0, q)
     const params = new URLSearchParams(q === -1 ? '' : raw.slice(q + 1))
+    const mi = path.match(/^\/i\/([\w-]{8,128})$/)
+    if (mi) return { invite: mi[1] }
     const m = path.match(/^\/(b|p)\/([^/?]+)$/)
     if (!m) return {}
     const board = decodeURIComponent(m[2])
     if (!BOARD_RE.test(board)) return {}
     if (m[1] === 'b') {
       const n = (params.get('n') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
-      return { board, ...(n.length ? { n } : {}) }
+      const c = params.get('c') ?? undefined
+      return { board, ...(n.length ? { n } : {}), ...(c && /^[\w-]+$/.test(c) ? { c } : {}) }
     }
     return {
       board,
@@ -51,8 +58,12 @@ export function buildHash(s: HashState): string {
     if (s.play.theme) p.set('theme', s.play.theme)
     return `#/p/${s.board}?${p}`
   }
-  if (!s.board || (s.board === 'all-scenes' && !s.n?.length)) return '#/'
-  return `#/b/${s.board}${s.n?.length ? `?n=${s.n.join(',')}` : ''}`
+  if (!s.board || (s.board === 'all-scenes' && !s.n?.length && !s.c)) return '#/'
+  const p = new URLSearchParams()
+  if (s.n?.length) p.set('n', s.n.join(','))
+  if (s.c) p.set('c', s.c)
+  const q = p.toString()
+  return `#/b/${s.board}${q ? `?${decodeURIComponent(q)}` : ''}`
 }
 
 /** Write the hash; identical URLs are skipped so restore paths never loop. */

package/src/client/shell/icons.tsx

@@ -27,6 +27,10 @@ export const PlusIcon = icon(<path d="M224,128a8,8,0,0,1-8,8H136v80a8,8,0,0,1-16
 export const XIcon = icon(<path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z" />)
 export const ReloadIcon = icon(<path d="M240,56v48a8,8,0,0,1-8,8H184a8,8,0,0,1,0-16H211.4L184.81,71.64l-.25-.24a80,80,0,1,0-1.67,114.78,8,8,0,0,1,11,11.63A95.44,95.44,0,0,1,128,224h-1.32A96,96,0,1,1,195.75,60L224,85.8V56a8,8,0,1,1,16,0Z" />)
 export const CheckIcon = icon(<path d="M229.66,77.66l-128,128a8,8,0,0,1-11.32,0l-56-56a8,8,0,0,1,11.32-11.32L96,188.69,218.34,66.34a8,8,0,0,1,11.32,11.32Z" />)
+export const ColumnsIcon = icon(<path d="M104,32H64A16,16,0,0,0,48,48V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,104,32Zm0,176H64V48h40ZM192,32H152a16,16,0,0,0-16,16V208a16,16,0,0,0,16,16h40a16,16,0,0,0,16-16V48A16,16,0,0,0,192,32Zm0,176H152V48h40Z" />)
+export const ArrowUpIcon = icon(<path d="M205.66,117.66a8,8,0,0,1-11.32,0L136,59.31V216a8,8,0,0,1-16,0V59.31L61.66,117.66a8,8,0,0,1-11.32-11.32l72-72a8,8,0,0,1,11.32,0l72,72A8,8,0,0,1,205.66,117.66Z" />)
+export const CommentIcon = icon(<path d="M132,24A100.11,100.11,0,0,0,32,124v84a16,16,0,0,0,16,16h84a100,100,0,0,0,0-200Zm0,184H48V124a84,84,0,1,1,84,84Z" />)
+export const CheckSquareOffsetIcon = icon(<path d="M224,48V208a16,16,0,0,1-16,16H136a8,8,0,0,1,0-16h72V48H48v96a8,8,0,0,1-16,0V48A16,16,0,0,1,48,32H208A16,16,0,0,1,224,48ZM125.66,154.34a8,8,0,0,0-11.32,0L64,204.69,45.66,186.34a8,8,0,0,0-11.32,11.32l24,24a8,8,0,0,0,11.32,0l56-56A8,8,0,0,0,125.66,154.34Z" />)
 export const DevicesIcon = icon(<path d="M224,72H208V64a24,24,0,0,0-24-24H40A24,24,0,0,0,16,64v96a24,24,0,0,0,24,24H152v8a24,24,0,0,0,24,24h48a24,24,0,0,0,24-24V96A24,24,0,0,0,224,72ZM40,168a8,8,0,0,1-8-8V64a8,8,0,0,1,8-8H184a8,8,0,0,1,8,8v8H176a24,24,0,0,0-24,24v72Zm192,24a8,8,0,0,1-8,8H176a8,8,0,0,1-8-8V96a8,8,0,0,1,8-8h48a8,8,0,0,1,8,8Zm-96,16a8,8,0,0,1-8,8H88a8,8,0,0,1,0-16h40A8,8,0,0,1,136,208Zm80-96a8,8,0,0,1-8,8H192a8,8,0,0,1,0-16h16A8,8,0,0,1,216,112Z" />)
 export const DeviceMobileIcon = icon(<path d="M176,16H80A24,24,0,0,0,56,40V216a24,24,0,0,0,24,24h96a24,24,0,0,0,24-24V40A24,24,0,0,0,176,16ZM72,64H184V192H72Zm8-32h96a8,8,0,0,1,8,8v8H72V40A8,8,0,0,1,80,32Zm96,192H80a8,8,0,0,1-8-8v-8H184v8A8,8,0,0,1,176,224Z" />)
 export const DeviceTabletIcon = icon(<path d="M192,24H64A24,24,0,0,0,40,48V208a24,24,0,0,0,24,24H192a24,24,0,0,0,24-24V48A24,24,0,0,0,192,24ZM56,72H200V184H56Zm8-32H192a8,8,0,0,1,8,8v8H56V48A8,8,0,0,1,64,40ZM192,216H64a8,8,0,0,1-8-8v-8H200v8A8,8,0,0,1,192,216Z" />)
@@ -41,6 +45,8 @@ export const PanelFilledIcon = icon(<><rect x="32" y="48" width="192" height="16
 
 /** Plain UI frame - the rectangle every non-content sidebar row leads with. */
 export const FrameRectIcon = icon(<rect x="40" y="52" width="176" height="152" rx="20" fill="none" stroke="currentColor" strokeWidth="16" />)
+export const LinkIcon = icon(<path d="M137.54,186.36a8,8,0,0,1,0,11.31l-9.94,10A56,56,0,0,1,48.38,128.4L72.5,104.28A56,56,0,0,1,149.31,102a8,8,0,1,1-10.64,12,40,40,0,0,0-54.85,1.63L59.7,139.72a40,40,0,0,0,56.58,56.58l9.94-9.94A8,8,0,0,1,137.54,186.36Zm70.08-138a56.08,56.08,0,0,0-79.22,0l-9.94,9.95a8,8,0,0,0,11.32,11.31l9.94-9.94a40,40,0,0,1,56.58,56.58L172.18,140.4a40,40,0,0,1-54.85,1.6,8,8,0,1,0-10.64,12,56,56,0,0,0,76.81-2.26l24.12-24.12A56.08,56.08,0,0,0,207.62,48.38Z" />)
+export const LaserIcon = icon(<><circle cx="128" cy="128" r="56" fill="none" stroke="currentColor" strokeWidth="16" /><path d="M128 24 V56 M128 200 V232 M24 128 H56 M200 128 H232" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" /><circle cx="128" cy="128" r="12" /></>)
 
 /* Content-frame intent glyphs (SPEC-026), custom in the same 256-space. */
 export const DiagramShapeIcon = icon(<><rect x="28" y="36" width="88" height="64" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="140" y="156" width="88" height="64" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><path d="M116 68 H184 V156" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" strokeLinejoin="round" /></>)

package/src/client/shell/labels.ts

@@ -0,0 +1,10 @@
+/** Pure display-label helpers. Standalone (no virtual-module imports) so they are unit-testable
+ *  and cheap to import anywhere. Re-exported from store.ts for existing call sites. */
+
+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())

package/src/client/shell/perf.ts

@@ -0,0 +1,92 @@
+/**
+ * B0.4: canvas performance instrumentation. Zero cost unless explicitly enabled.
+ *
+ * Enabled in dev, or in ANY build (incl. packed/published - the SPEC-M4 gate is dev AND
+ * publish) via `?mvperf` in the URL or `localStorage.mvPerf==='1'`. So publish-side gate
+ * measurement is possible without shipping an always-on probe.
+ *
+ * Two honest signals, sampled ONLY while a gesture is active (the `#sh-world.sh-gesturing`
+ * class every gesture path already sets):
+ *  - frame INTERVALS (rAF deltas). A healthy 60Hz frame is ~16.7ms, so the interval is NOT
+ *    "main-thread work" - we report its p50/p95/max and, as the jank signal, `dropped` =
+ *    intervals over 32ms (a missed refresh).
+ *  - long-task durations (PerformanceObserver 'longtask', >50ms by spec) landing during a
+ *    gesture: actual main-thread work that blew the budget. 0 long-tasks = smooth.
+ *
+ * Read it live:  __mvPerf.report()  /  __mvPerf.reset()
+ * perfMark(name) + counters are the plug points Stages 2-3 use (blank-frame / warm-latency).
+ */
+
+// "in motion" = a pan/zoom/drag gesture OR a device-sweep/tidy preset animation - both are the
+// windows where jank matters and the perf gate is measured.
+const GESTURING = () => {
+  const w = document.getElementById('sh-world')
+  return !!w && (w.classList.contains('sh-camera') || w.classList.contains('sh-preset'))
+}
+
+const frames: number[] = []   // inter-frame intervals (ms) during gestures
+const tasks: number[] = []    // long-task durations (ms) during gestures
+const MAX = 1200
+let last = 0
+let raf = 0
+
+const counters: Record<string, number> = { blankFrames: 0 }
+const marks: { name: string; t: number }[] = []
+
+const enabled = (): boolean => {
+  if (import.meta.env.DEV) return true
+  try {
+    if (typeof location !== 'undefined' && /[?&]mvperf\b/.test(location.search)) return true
+    return localStorage.getItem('mvPerf') === '1'
+  } catch { return false }
+}
+
+const tick = (t: number) => {
+  if (last && GESTURING()) { const dt = t - last; frames.push(dt); if (frames.length > MAX) frames.shift() }
+  last = t
+  raf = requestAnimationFrame(tick)
+}
+
+const pct = (sorted: number[], p: number): number => {
+  if (!sorted.length) return 0
+  const i = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))
+  return Math.round(sorted[i] * 100) / 100
+}
+const top = (sorted: number[]): number => (sorted.length ? Math.round(sorted[sorted.length - 1] * 100) / 100 : 0)
+const frac = (n: number, d: number): number => (d ? Math.round((n / d) * 1000) / 1000 : 0)
+
+/** One-shot event later stages record (e.g. a blank frame, or warm-promotion latency). */
+export const perfMark = (name: string): void => {
+  counters[name] = (counters[name] ?? 0) + 1
+  marks.push({ name, t: last })
+  if (marks.length > 400) marks.shift()
+}
+
+/** Start the sampler. Idempotent; a no-op unless enabled() (dev, ?mvperf, or localStorage). */
+export function startPerf(): void {
+  if (raf || !enabled()) return
+  raf = requestAnimationFrame(tick)
+  try {
+    const obs = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) if (GESTURING()) { tasks.push(e.duration); if (tasks.length > MAX) tasks.shift() }
+    })
+    obs.observe({ type: 'longtask', buffered: false })
+  } catch { /* longtask entry type unsupported (e.g. Safari) - frame intervals still sample */ }
+  ;(window as unknown as { __mvPerf: unknown }).__mvPerf = {
+    report() {
+      const fi = [...frames].sort((a, b) => a - b)
+      const tw = [...tasks].sort((a, b) => a - b)
+      const dropped = fi.filter((d) => d > 32).length
+      return {
+        gestureFrames: fi.length,
+        frameP50: pct(fi, 50), frameP95: pct(fi, 95), frameMax: top(fi),
+        dropped, droppedFrac: frac(dropped, fi.length),
+        // actual main-thread work during gestures (long tasks >50ms). 0 = smooth.
+        longTasks: tw.length, longTaskP95: pct(tw, 95), longTaskMax: top(tw),
+        counters: { ...counters },
+      }
+    },
+    reset() { frames.length = 0; tasks.length = 0; marks.length = 0; for (const k in counters) counters[k] = 0 },
+    marks: () => [...marks],
+  }
+}

package/src/client/shell/store.ts

@@ -35,9 +35,10 @@ export interface Node {
 }
 export interface Toast { id: number; text: string }
 
-export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean } = shConfig
+export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean; projectName?: string } = shConfig
 
-export const cap = (s: string) => (s ? s[0].toUpperCase() + s.slice(1) : s)
+export { cap, humanize } from './labels.ts'
+import { cap, humanize } from './labels.ts'
 
 /** Board names for switchers: all-scenes first, the rest sorted. Throws on transport
  *  failure - callers keep their last known list. */
@@ -47,7 +48,7 @@ export async function fetchBoardNames(): Promise<string[]> {
   return ['all-scenes', ...list.map((b) => b.name).filter((n) => n !== 'all-scenes').sort()]
 }
 /** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
-export const boardLabel = (n: string) => (n === 'all-scenes' ? 'All scenes' : cap(n))
+export const boardLabel = (n: string) => humanize(n)
 
 const HEADER = 28
 let toastSeq = 0
@@ -112,6 +113,7 @@ interface State {
   viewTheme: string                   // the global theme preference; sticky across boards and reloads
   play: { at: string; device: string; theme: string } | null   // play mode (SPEC-M2 §1); at = current frame id
   gesture: boolean                    // a frame drag/resize is in progress - canvas panning is disabled
+  laser: boolean                      // laser/inspect mode (SPEC-M3 §7): frames outline their structure
   board: string                       // active board name; 'all-scenes' is the auto board
   boardAuto: boolean                  // auto boards gain new frames on arrival; curated boards never do
   deviceView: string | null           // board-wide device preview (viewport name), null = free-form layout
@@ -124,6 +126,14 @@ interface State {
   toasts: Toast[]
   boardHash: string | null            // sha256 of the board file on disk, when materialized
   dirty: boolean
+  // A6/A7 controlled HMR (transient, never persisted): a frame the user is actively using
+  // (interact/play target, mid-gesture, laser/comment engaged) is "leased" - a hot update to
+  // it is DEFERRED (coalesced to the latest revision) until a safe point, so an agent edit
+  // never yanks the user out of their flow.
+  pendingFrameRevisions: Record<string, string>            // frameId -> latest deferred revision
+  externalLeases: Record<string, { laser?: true; comment?: true }>   // nodeKey -> transient engagement
+  playUpdateRevision: string | null                        // a revision arrived while play is open
+  playNav: number                                          // bumps to reload the play stage on demand
 
   boot(): Promise<boolean>
   applyManifest(m: Manifest): void
@@ -139,6 +149,11 @@ interface State {
   setInteract(key: string | null): void
   setPlay(p: State['play']): void
   setGesture(g: boolean): void
+  setLaser(on: boolean): void
+  invalidateFrames(frameIds: string[], revision: string): void
+  setExternalLease(nodeKey: string, reason: 'laser' | 'comment', on: boolean): void
+  flushFrameUpdates(frameIds?: string[]): void
+  applyPlayUpdate(): void
   moveSelectedBy(dx: number, dy: number, starts: Record<string, { x: number; y: number }>): void
   setSelectedTheme(theme: string): void
   setDeviceView(name: string | null): void
@@ -153,6 +168,16 @@ interface State {
   save(): Promise<boolean>
 }
 
+/** A6: is any node of this frame in active use, so a hot update must DEFER? Frame-scoped -
+ *  if the same frame is placed twice and one copy is active, both stay on the same revision. */
+function frameIsLeased(frameId: string, s: State): boolean {
+  return s.nodes.some((n) =>
+    n.frame === frameId && n.status !== 'error' && (
+      s.interact === n.key ||
+      (s.gesture && s.selection.includes(n.key)) ||
+      !!s.externalLeases[n.key]))
+}
+
 export const useStore = create<State>((set, get) => {
   let saveTimer: ReturnType<typeof setTimeout> | undefined
   let saveChain: Promise<boolean> = Promise.resolve(true)   // saves are serialized; responses only commit if the board is still active
@@ -388,9 +413,10 @@ export const useStore = create<State>((set, get) => {
   }
 
   return {
-    manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false,
+    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: [], boardHash: null, dirty: false,
+    pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0,
 
     async boot() {
       const seq = ++loadSeq
@@ -685,8 +711,22 @@ export const useStore = create<State>((set, get) => {
     // interact is a ONE-frame mode: entering it collapses any multi-selection to the
     // interacted frame (a 4-frame selection double-clicked otherwise leaves all four
     // painted as "interactive"). Exiting keeps the frame selected for continuity.
-    setInteract(key) { set((s) => ({ interact: key, selection: key ? [key] : s.selection })) },
+    setInteract(key) {
+      set((s) => ({ interact: key, selection: key ? [key] : s.selection }))
+      get().flushFrameUpdates()   // A6: the frame just left interact is no longer leased
+    },
     setPlay(play) { set({ play }) },
+    setLaser(laser) {
+      if (laser) { set({ laser }); return }
+      // leaving laser mode drops every laser engagement lease (the bridge stops reporting), but
+      // keeps comment engagement; the freed frames may now flush a deferred update
+      set((s) => ({
+        laser,
+        externalLeases: Object.fromEntries(
+          Object.entries(s.externalLeases).filter(([, v]) => v.comment).map(([k]) => [k, { comment: true as const }])),
+      }))
+      get().flushFrameUpdates()
+    },
     setGesture(gesture) {
       set({ gesture })
       // SPEC-024 §4: a board WITH a layout recipe re-applies it when a resize
@@ -696,6 +736,49 @@ export const useStore = create<State>((set, get) => {
         if (get().layout || get().sceneRows?.length) get().runTidy()   // schedules the save
         else scheduleSave()
       }
+      if (!gesture) get().flushFrameUpdates()   // A6: gesture end is a safe point for deferred updates
+    },
+    // A6/A7: apply a controlled hot update. A leased frame's revision is deferred (coalesced to
+    // the latest) and applied at the next safe point; an idle frame reloads now via its nav nonce.
+    invalidateFrames(frameIds, revision) {
+      const ids = new Set(frameIds.filter((x) => typeof x === 'string'))
+      if (!ids.size) return
+      bumpManifestRev()
+      const s = get()
+      const pending = { ...s.pendingFrameRevisions }
+      const nodes = s.nodes.map((n) => {
+        if (!ids.has(n.frame)) return n
+        if (frameIsLeased(n.frame, s)) { pending[n.frame] = revision; return n }
+        return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 }
+      })
+      set({ nodes, pendingFrameRevisions: pending, ...(s.play ? { playUpdateRevision: revision } : {}) })
+    },
+    flushFrameUpdates(frameIds) {
+      const s = get()
+      const ids = (frameIds ?? Object.keys(s.pendingFrameRevisions)).filter((id) => s.pendingFrameRevisions[id] && !frameIsLeased(id, s))
+      if (!ids.length) return
+      bumpManifestRev()
+      const apply = new Set(ids)
+      const pending = { ...s.pendingFrameRevisions }
+      for (const id of ids) delete pending[id]
+      const nodes = s.nodes.map((n) => apply.has(n.frame)
+        ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 } : n)
+      set({ nodes, pendingFrameRevisions: pending })
+    },
+    setExternalLease(nodeKey, reason, on) {
+      set((s) => {
+        const cur = { ...(s.externalLeases[nodeKey] ?? {}) }
+        if (on) cur[reason] = true; else delete cur[reason]
+        const leases = { ...s.externalLeases }
+        if (Object.keys(cur).length) leases[nodeKey] = cur; else delete leases[nodeKey]
+        return { externalLeases: leases }
+      })
+      if (!on) get().flushFrameUpdates()
+    },
+    applyPlayUpdate() {
+      if (!get().playUpdateRevision) return
+      bumpManifestRev()
+      set((s) => ({ playUpdateRevision: null, playNav: s.playNav + 1 }))
     },
     setScale(scale) { set({ scale }) },
     togglePanel() { set((s) => ({ panelOpen: !s.panelOpen })) },
@@ -800,10 +883,19 @@ export const useStore = create<State>((set, get) => {
         try {
           const res = await fetch(`${ROUTE}/api/boards/${boardName}`, {
             method: 'PUT', headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ board, baseHash: boardHash }),
+            // A9: a board loaded from disk (boardHash set) autosaves with mustExist so a
+            // rename/delete out from under us returns 409 instead of resurrecting a ghost.
+            body: JSON.stringify({ board, baseHash: boardHash, mustExist: !!boardHash }),
           })
           if (get().board !== boardName) return true   // switched boards mid-flight; stale response must not touch state
           if (res.status === 409) {
+            const info = await res.json().catch(() => ({} as { gone?: boolean }))
+            if (info?.gone) {
+              // renamed/deleted externally - drop the write, don't recreate it or loop
+              set({ dirty: false })
+              get().toast('this board was renamed or removed - not recreating it')
+              return true
+            }
             const reloaded = await get().boot()   // hash advances only when the authoritative reload commits
             if (reloaded) get().toast('board changed on disk - canvas layout reloaded')
             return reloaded   // false keeps dirty set; the next debounce retries once edits settle
@@ -822,3 +914,6 @@ export const useStore = create<State>((set, get) => {
     },
   }
 })
+
+// dev-only inspection hook for tests/debugging (never installed in published builds)
+if (import.meta.env.DEV) (window as unknown as { __mvStore: unknown }).__mvStore = useStore