@marver-design/marver 0.4.0 → 0.6.0

package/src/client/shell/canvas/frame-registry.ts

@@ -0,0 +1,18 @@
+/**
+ * B0.3: O(1) source-window -> node lookup for the frame->shell message protocol.
+ *
+ * Every postMessage from a frame previously triggered a full `document.querySelectorAll
+ * ('iframe')` scan plus a `closest('[data-node]')` DOM walk to find the sender's node.
+ * A frame's WindowProxy is a stable object for the life of its iframe element (it survives
+ * same-element navigations - the iframe law keeps one element per node key), so one
+ * registration holds for the frame's whole life. The registry doubles as the security
+ * gate: an event whose source is not registered is not a known frame and is dropped.
+ */
+export interface FrameReg { key: string; iframe: HTMLIFrameElement }
+
+const byWindow = new WeakMap<WindowProxy, FrameReg>()
+
+export const registerFrame = (win: WindowProxy, reg: FrameReg): void => { byWindow.set(win, reg) }
+export const unregisterFrame = (win: WindowProxy): void => { byWindow.delete(win) }
+export const frameByWindow = (win: unknown): FrameReg | undefined =>
+  win ? byWindow.get(win as WindowProxy) : undefined

package/src/client/shell/canvas/snapshots.ts

@@ -0,0 +1,233 @@
+/**
+ * SPEC-M5 slice 1: the lean-frame facade coordinator. Imperative on purpose - the facade is a
+ * `<iframe class="sh-lean" sandbox="allow-same-origin">` driven by setting .srcdoc directly, so no
+ * FrameNode subscribes to snapshot state and a pan/zoom tick triggers zero React renders.
+ *
+ * The lean tier is a DOM SNAPSHOT, not a bitmap: the shell serialises the live frame's document
+ * (same origin) into self-contained static html (post-render DOM + full inlined CSS, JS stripped).
+ * LEAN-PRIMARY: this snapshot is what you SEE for a passive frame - at rest AND during pan/zoom - so
+ * there is NO per-gesture swap between the lean and the live iframe (two documents never render
+ * pixel-identically; the swap shifted text ~1-2px = jiggle, and flashed mermaid/theme). The live app
+ * shows underneath only when the frame is interacted, in laser/comment mode, or while the lean is
+ * being (re)built. Real DOM + real CSS: exact color, native reflow on resize. Theme change / focus
+ * INVALIDATE the lean (never mutate a displayed one - baked mermaid can't re-theme in place) and a
+ * fresh capture is admitted before it is shown again. Captures run bounded-parallel, viewport-first, at idle, never while busy.
+ *
+ * Correctness beats the flash-guard (codex): a frame the serialiser cannot render faithfully
+ * (canvas/video/shadow-dom/cross-origin-css, or an unrestorable scroller) is left DEGRADED - no
+ * `data-ready`, no cover, live pixels stay. Every install is guarded by a per-node GENERATION token
+ * so an in-flight capture can never paint a stale/wrong-node cover after a reload or unmount.
+ */
+import { serializeDoc, type SerializeResult } from '../../frame-host/serialize.ts'
+
+export interface SnapMeta { sourceRevision: string; theme: string }
+
+interface Entry { key: string; html: string; scrollMap: SerializeResult['scrollMap']; degraded: string[]; theme: string; gen: number; live: HTMLIFrameElement; meta: SnapMeta }
+const byNode = new Map<string, Entry>()                    // nodeKey -> current lean snapshot
+const frames = new Map<string, HTMLIFrameElement>()        // nodeKey -> the facade <iframe> element
+const gen = new Map<string, number>()                      // nodeKey -> generation (bumped on drop/reload)
+const recheck = new Map<string, number>()                  // nodeKey -> a one-shot re-capture timer (slow async)
+const rechecked = new Set<string>()                        // nodes whose one-shot recheck already fired (no re-arm loop)
+const MAX_LEAN_BYTES = 4 * 1024 * 1024                     // over this a frame is too heavy to inline - stay live
+
+// content identity INCLUDES theme: content whose colors are baked into the DOM at render time
+// (mermaid SVG) cannot be re-themed by the cover's attribute mutation, so a theme change must
+// re-capture after the live frame re-renders. Size still needs no re-capture (the lean doc reflows).
+const keyOf = (m: SnapMeta) => `${m.sourceRevision}|${m.theme}`
+const genOf = (k: string) => gen.get(k) ?? 0
+const bumpGen = (k: string) => gen.set(k, genOf(k) + 1)    // invalidate any in-flight capture/onload for k
+
+const inMotion = (): boolean => {
+  const w = document.getElementById('sh-world')
+  return !!w && (w.classList.contains('sh-gesturing') || w.classList.contains('sh-preset'))
+}
+// never serialise while laser/comment mode is on: those inject outline styles + hover chrome into the
+// live doc, which the shell-side clone would bake into the lean (visible after the mode ends).
+const modeActive = (): boolean => document.body.classList.contains('sh-laser') || document.body.classList.contains('sh-commenting')
+const busy = (): boolean => inMotion() || modeActive()
+
+/** Apply a node's current theme to its lean doc via attribute mutation (allow-same-origin lets the
+ *  shell touch the doc; the full CSS is inlined so only which rules match changes - no re-capture). */
+function applyTheme(doc: Document, theme: string): void {
+  doc.documentElement.dataset.theme = theme
+  doc.documentElement.classList.toggle('dark', theme === 'dark')
+  // pin the cover's color-scheme to the FRAME theme, not the viewer's OS. A srcdoc doc otherwise
+  // follows the OS: on a dark-mode Mac the UA canvas + any prefers-color-scheme rules go dark and
+  // bleed into the cover (dark mermaid boxes) while data-theme says light. This holds it to light.
+  doc.documentElement.style.colorScheme = theme
+}
+
+/** Restore captured scroll offsets shell-side (the lean doc runs no JS). Returns false if any mapped
+ *  scroller cannot be resolved OR the offset did not stick (clamped by a differently-reflowed lean
+ *  doc) - the frame then degrades to live rather than showing a mis-scrolled cover. */
+function restoreScroll(doc: Document, scrollMap: Entry['scrollMap']): boolean {
+  for (const s of scrollMap) {
+    const el = s.sel === ':root' ? doc.documentElement : doc.querySelector<HTMLElement>(s.sel)
+    if (!el) return false
+    el.scrollTop = s.top; el.scrollLeft = s.left
+    if (Math.abs(el.scrollTop - s.top) > 2 || Math.abs(el.scrollLeft - s.left) > 2) return false
+  }
+  return true
+}
+
+/** Install the stored snapshot into a node's lean iframe: parse srcdoc, then on load restore scroll,
+ *  apply theme, and (only if nothing degraded AND fonts+paint have settled) mark ready. Every step is
+ *  generation-guarded so a superseded capture or an about:blank reset never re-admits a cover. */
+function install(nodeKey: string): void {
+  const iframe = frames.get(nodeKey)
+  if (!iframe) return
+  iframe.onload = null                                     // detach any prior handler (about:blank reset can't re-admit)
+  delete iframe.dataset.ready
+  const e = byNode.get(nodeKey)
+  if (!e || e.degraded.length) { iframe.removeAttribute('srcdoc'); return }   // degraded = no cover, keep live
+  const myGen = e.gen
+  iframe.onload = () => {
+    if (genOf(nodeKey) !== myGen || frames.get(nodeKey) !== iframe) return    // superseded / remounted
+    const cur = byNode.get(nodeKey)
+    const doc = iframe.contentDocument
+    if (!cur || !doc) return
+    if (!restoreScroll(doc, cur.scrollMap)) { cur.degraded = [...cur.degraded, 'scroll']; iframe.removeAttribute('srcdoc'); return }
+    // CSP guard (codex): if a hardened host blocked the inline <style> (style-src 'self'), the lean is
+    // unstyled - the sentinel custom prop won't resolve. Stay live rather than show an unstyled cover.
+    if (getComputedStyle(doc.documentElement).getPropertyValue('--mv-lean-ok').trim() !== '1') { iframe.removeAttribute('srcdoc'); return }
+    applyTheme(doc, cur.theme)
+    // font+paint readiness gate (F3): the srcdoc doc reloads fonts independently, so mark ready only
+    // after its fonts settle + two paints, else a fallback-font seam shows on the swap.
+    const markReady = () => {
+      if (genOf(nodeKey) !== myGen || frames.get(nodeKey) !== iframe) return
+      iframe.dataset.ready = '1'
+      // slow-async guard: a data fetch / route change that lands AFTER the capture window would leave
+      // the lean frozen on a loading state. ONE bounded re-capture ~3s after admit catches it; later
+      // changes self-heal on focus. `rechecked` makes it truly one-shot - the recheck's own recapture
+      // must not re-arm the timer (that was an endless ~3s loop), so a long-poll can't thrash.
+      clearTimeout(recheck.get(nodeKey))
+      if (cur.live && !rechecked.has(nodeKey)) recheck.set(nodeKey, window.setTimeout(() => {
+        recheck.delete(nodeKey); rechecked.add(nodeKey)
+        if (genOf(nodeKey) === myGen) scheduleCapture(nodeKey, cur.live, cur.meta, true)
+      }, 3000))
+    }
+    void (doc.fonts?.ready ?? Promise.resolve()).then(() => requestAnimationFrame(() => requestAnimationFrame(markReady)))
+  }
+  iframe.srcdoc = e.html
+}
+
+/** FrameNode registers its facade <iframe> on mount so the coordinator can drive it imperatively. */
+export function registerLeanFrame(nodeKey: string, iframe: HTMLIFrameElement | null): void {
+  if (!iframe) { frames.delete(nodeKey); return }
+  frames.set(nodeKey, iframe)
+  if (byNode.has(nodeKey)) install(nodeKey)
+}
+
+/** Hide the lean at once (show the live app underneath) and cancel in-flight work. Used when a frame
+ *  is focused/interacted, or its theme changes: a baked mermaid SVG cannot be re-themed in place, so
+ *  we never mutate a DISPLAYED snapshot across themes - we drop it and rebuild a fresh one, which is
+ *  only shown once it passes admission. Live stays visible in the meantime (live-fallback). */
+export function invalidateLean(nodeKey: string): void {
+  bumpGen(nodeKey)
+  pending.delete(nodeKey)
+  clearTimeout(recheck.get(nodeKey)); recheck.delete(nodeKey); rechecked.delete(nodeKey)
+  const iframe = frames.get(nodeKey)
+  if (iframe) delete iframe.dataset.ready
+}
+
+/** Drop a node's snapshot (unmount, or content changed / frame reloaded). Cancels queued + in-flight
+ *  work via the generation bump and clears the cover. */
+export function dropSnapshot(nodeKey: string): void {
+  bumpGen(nodeKey)
+  byNode.delete(nodeKey)
+  pending.delete(nodeKey)
+  clearTimeout(recheck.get(nodeKey)); recheck.delete(nodeKey); rechecked.delete(nodeKey)
+  const iframe = frames.get(nodeKey)
+  if (iframe) { iframe.onload = null; delete iframe.dataset.ready; iframe.removeAttribute('srcdoc') }
+}
+
+// ---- capture coordinator: bounded-parallel, viewport-first, idle-scheduled, never while busy --------
+const pending = new Map<string, { live: HTMLIFrameElement; meta: SnapMeta }>()   // nodeKey -> latest request
+const inflightNodes = new Set<string>()   // nodes currently being captured - never capture one twice at once
+const MAX_CONCURRENT = 3   // overlap the per-frame settle waits (mostly timers) so a big board's leans
+let inflight = 0           // land in ~1/3 the wall-clock of strictly-serial, without janking the loop
+const idle = (fn: () => void) =>
+  (window as unknown as { requestIdleCallback?: (f: () => void, o?: object) => void }).requestIdleCallback?.(fn, { timeout: 600 }) ?? setTimeout(fn, 80)
+const rafSettle = () => new Promise<void>((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())))
+const withDeadline = <T,>(p: Promise<T>, ms: number) => Promise.race([p, new Promise<void>((r) => setTimeout(r, ms))])
+
+/** Wait until the frame's DOM stops mutating for `quietMs` (bounded by `maxMs`). Async content -
+ *  lazily-imported mermaid renders its SVG well after the frame reports 'ready', late images/webfont
+ *  swaps, entrance animations - all land here. Capturing before this quiet window yields a cover
+ *  missing the diagram (the mermaid pop-in/out bug). Same-origin, so the shell can observe the doc. */
+function domQuiet(doc: Document, quietMs: number, maxMs: number): Promise<void> {
+  return new Promise((resolve) => {
+    let timer = 0, done = false
+    const finish = () => { if (done) return; done = true; clearTimeout(timer); clearTimeout(hard); mo.disconnect(); resolve() }
+    const mo = new MutationObserver(() => { clearTimeout(timer); timer = window.setTimeout(finish, quietMs) })
+    try { mo.observe(doc.documentElement, { subtree: true, childList: true, attributes: true, characterData: true }) }
+    catch { return resolve() }
+    timer = window.setTimeout(finish, quietMs)
+    const hard = window.setTimeout(finish, maxMs)
+  })
+}
+
+/** Request a fresh lean snapshot for a ready/quiet frame. Coalesces to the latest per node. `force`
+ *  recaptures even when the key is unchanged - used on blur, where the live state changed under the
+ *  same revision/theme (typed input, toggled UI) and the old lean is now wrong. */
+export function scheduleCapture(nodeKey: string, live: HTMLIFrameElement, meta: SnapMeta, force = false): void {
+  if (!force && byNode.get(nodeKey)?.key === keyOf(meta)) return   // already have this content revision
+  pending.set(nodeKey, { live, meta })
+  pump()
+}
+
+/** The next node to capture: the pending frame nearest the viewport centre, on-screen before off. So
+ *  the frames the user is actually looking at get their lean first (perceived-instant), and the rest
+ *  fill in behind - instead of registration order, which pops in arbitrary corners of a big board. */
+function pickNext(): string | null {
+  let best: string | null = null, bestScore = Infinity
+  const vw = window.innerWidth, vh = window.innerHeight
+  for (const [k, req] of pending) {
+    if (inflightNodes.has(k)) continue                   // that node is mid-capture; its re-request waits
+    const r = req.live.getBoundingClientRect()
+    const off = r.bottom < 0 || r.top > vh || r.right < 0 || r.left > vw
+    const dx = r.left + r.width / 2 - vw / 2, dy = r.top + r.height / 2 - vh / 2
+    const score = (off ? 1e7 : 0) + Math.hypot(dx, dy)   // on-screen first, then by distance to centre
+    if (score < bestScore) { bestScore = score; best = k }
+  }
+  return best
+}
+
+function pump(): void {
+  if (busy()) { if (pending.size) idle(pump); return }   // never serialise mid-gesture or during laser/comment
+  while (inflight < MAX_CONCURRENT) {
+    const nodeKey = pickNext()
+    if (!nodeKey) break
+    const req = pending.get(nodeKey)!
+    pending.delete(nodeKey)
+    inflightNodes.add(nodeKey); inflight++
+    const done = () => { inflightNodes.delete(nodeKey); inflight--; idle(pump) }
+    void capture(nodeKey, req.live, req.meta).then(done, done)
+  }
+}
+
+async function capture(nodeKey: string, live: HTMLIFrameElement, meta: SnapMeta): Promise<void> {
+  const myGen = genOf(nodeKey)
+  const doc = live.contentDocument
+  if (!doc) return
+  // settle: fonts, two stable paints, THEN a DOM-quiet window so async content (mermaid renders its
+  // SVG after 'ready', late images) is captured - not a diagram-less frame. All bounded.
+  await withDeadline(doc.fonts?.ready ?? Promise.resolve(), 400).catch(() => {})
+  await rafSettle()
+  await domQuiet(doc, 180, 2500)   // still-loading frames wait longer so async data lands in-capture
+  // bail if the world changed under us during settle: superseded (drop/reload), a newer request
+  // landed, the frame renavigated, or a gesture/preset started (serialising+parsing now would jank).
+  if (genOf(nodeKey) !== myGen || pending.has(nodeKey) || live.contentDocument !== doc) return
+  if (busy()) { pending.set(nodeKey, { live, meta }); return }       // requeue for the next idle tick
+  let result: SerializeResult
+  try { result = serializeDoc(doc, doc.URL) }   // <base> = the frame's own URL, so relative url()/img/font resolve
+  catch { return }                              // fail soft: keep live pixels
+  // budget: a pathologically heavy frame (huge inlined CSS/DOM) would multiply memory across the board
+  // and jank the main thread parsing it - over the cap, degrade (stay live) AND drop the html so the
+  // giant string is not retained in byNode (keeping it would defeat the memory bound).
+  const oversized = result.html.length > MAX_LEAN_BYTES
+  const degraded = oversized ? [...result.degraded, 'oversized'] : result.degraded
+  const theme = doc.documentElement.dataset.theme || meta.theme   // theme AT capture, not a stale closure
+  byNode.set(nodeKey, { key: keyOf(meta), html: oversized ? '' : result.html, scrollMap: oversized ? [] : result.scrollMap, degraded, theme, gen: myGen, live, meta })
+  install(nodeKey)
+}

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/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,19 +35,25 @@ 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. */
+/** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
+ *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
+ *  Throws on transport failure - callers keep their last known list. */
 export async function fetchBoardNames(): Promise<string[]> {
   if (DATA) return DATA.names
-  const list: { name: string }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
-  return ['all-scenes', ...list.map((b) => b.name).filter((n) => n !== 'all-scenes').sort()]
+  const list: { name: string; order?: number }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
+  const curated = list
+    .filter((b) => b.name !== 'all-scenes')
+    .sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || a.name.localeCompare(b.name))
+    .map((b) => b.name)
+  return [...curated, 'all-scenes']
 }
 /** 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
@@ -125,6 +131,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
@@ -141,6 +155,10 @@ interface State {
   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
@@ -155,6 +173,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
@@ -393,6 +421,7 @@ export const useStore = create<State>((set, get) => {
     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
@@ -576,27 +605,38 @@ export const useStore = create<State>((set, get) => {
     measureNode(key, frameId, ownWidth, measuredWidth, height) {
       const s = get()
       const node = s.nodes.find((n) => n.key === key)
-      if (!node || node.sizeMode !== 'auto') return       // manual/device always win
+      // Only an explicit DEVICE viewport locks a content frame's height. 'auto' and 'manual' both
+      // auto-fit height: a content frame must always grow/shrink to show ALL its content, even after
+      // the human drags its WIDTH (SPEC-026 r4). 'manual' just means the human owns the WIDTH; the
+      // HEIGHT is still measured, so resizing width reflows and refits height (no clipped/empty frame).
+      if (!node || node.sizeMode === 'device') return
       if (node.frame !== frameId) return                  // generation guard: a reused node key
                                                           // across a board switch never mis-attributes
       const f = s.manifest?.frames.find((x) => x.id === node.frame)
       if (!f?.contentWidth) return                        // not a content frame - spoof-proofing
       if (![ownWidth, measuredWidth, height].every((v) => Number.isFinite(v) && v > 0)) return
-      const maxH = Math.round(2.5 * Math.max(844, ...Object.values(CONFIG.viewports).map((v) => v.height)))
-      // declared meta.viewport WINS over the Doc layout width - the existing precedence
-      const vpw = CONFIG.viewports[f.viewport ?? '']?.width
-      const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+      // Generous cap: a reference doc with many screenshots is legitimately very tall and must fit in
+      // FULL (this was 2.5x a viewport ~= 2700px, which clipped image-heavy docs). Still bounded so a
+      // broken measurement can't mint an infinite frame.
+      const maxH = 40000
       const H = Math.min(maxH, Math.max(80, Math.round(height)))
       const curW = Math.round(node.w)
       measuredHeights.set(`${node.frame}@${Math.round(measuredWidth)}`, H)
-      if (Math.round(measuredWidth) !== curW) return      // height not true at the applied width
-      if (W !== curW) {
-        // Doc layout changed (document<->wide): adopt the new own width first; the
-        // iframe resizes, remeasures, and the height commits on the next message
-        set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
-        scheduleReflow()
-        return
+      // AUTO owns the width too - adopt the Doc's declared/own width. MANUAL keeps the human's width
+      // and only fits the height.
+      if (node.sizeMode !== 'manual') {
+        // declared meta.viewport WINS over the Doc layout width - the existing precedence
+        const vpw = CONFIG.viewports[f.viewport ?? '']?.width
+        const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+        if (W !== curW) {
+          // Doc layout changed (document<->wide): adopt the new own width first; the
+          // iframe resizes, remeasures, and the height commits on the next message
+          set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
+          scheduleReflow()
+          return
+        }
       }
+      if (Math.round(measuredWidth) !== curW) return      // height only true at the width it was measured at
       if (Math.round(node.h) === H) return
       set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
       scheduleReflow()
@@ -687,9 +727,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) { set({ laser }) },
+    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
@@ -699,6 +752,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 })) },
@@ -803,10 +899,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
@@ -825,3 +930,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