@marver-design/marver 0.4.0 → 0.5.0

package/src/client/shell/canvas/FrameNode.tsx

@@ -1,8 +1,10 @@
-import { memo, useEffect, useRef } from 'react'
+import { memo, useCallback, useEffect, useRef } from 'react'
 import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
 import { CopyIcon, IntentGlyph, ReloadIcon, XIcon } from '../icons.tsx'
 import { CommentLayer } from '../Comments.tsx'
 import { useComments } from '../comments-store.ts'
+import { registerFrame, unregisterFrame } from './frame-registry.ts'
+import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
 
 export const HEADER = 28
 const SNAP = 12
@@ -20,7 +22,9 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   const frame = useStore((s) => s.frameFor(node))
   const selected = useStore((s) => s.selection.includes(node.key))
   const interact = useStore((s) => s.interact === node.key)
-  const scale = useStore((s) => s.scale)
+  // B0.1: no reactive scale subscription - it re-rendered every FrameNode on every
+  // pan/zoom tick. gestureScale below measures the world rect (the canonical source,
+  // Law G-5); the stored scale is only a never-hit fallback, read lazily at drag time.
   const { select, setInteract, moveNode, moveSelectedBy, resizeNode, setStatus, setGesture, toast } = useStore.getState()
   const iframeRef = useRef<HTMLIFrameElement>(null)
   const themeRef = useRef(node.theme)
@@ -30,13 +34,73 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
   if (frame && initialSrc.current === null) initialSrc.current = frameUrl(frame, node.theme)
   const fileRef = useRef(frame ? `${frame.kind}:${frame.file}` : null)
 
-  // theme switch without remount
+  // theme switch without remount: the live iframe flips via message (no navigation). The lean is
+  // INVALIDATED (not mutated) - a baked mermaid SVG can't be re-themed in place, so we drop it, show
+  // live while it re-renders in the new theme, and the capture effect (theme is a dep) rebuilds a
+  // fresh lean that is only shown once ready. No light-on-dark flash.
   useEffect(() => {
     if (themeRef.current !== node.theme) {
       themeRef.current = node.theme
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:set-theme', theme: node.theme }, '*')
+      invalidateLean(node.key)
     }
-  }, [node.theme])
+  }, [node.theme, node.key])
+
+  // B0.3: register this frame's WindowProxy so the shell routes its messages in O(1)
+  // (source window -> node), instead of rescanning every iframe + walking the DOM per
+  // message. Registration runs SYNCHRONOUSLY through the ref callback (P1): a fast static
+  // HTML frame or an immediate boot failure can post sh:ready/sh:error before a passive
+  // effect would run, and the registry is the security gate that would otherwise drop it
+  // as an unknown source (misleading 10s timeout). The WindowProxy is stable across
+  // navigations; onLoad re-asserts it (idempotent) after each navigation.
+  const regWin = useRef<WindowProxy | null>(null)
+  const registerWin = () => {
+    const iframe = iframeRef.current
+    const win = iframe?.contentWindow
+    if (!iframe || !win || regWin.current === win) return
+    regWin.current = win
+    registerFrame(win, { key: node.key, iframe })
+  }
+  const bindIframe = useCallback((el: HTMLIFrameElement | null) => {
+    if (regWin.current && (!el || el.contentWindow !== regWin.current)) { unregisterFrame(regWin.current); regWin.current = null }
+    iframeRef.current = el
+    registerWin()
+  }, [node.key])
+
+  // SPEC-M5: register the facade <iframe> so the lean coordinator can drive its srcdoc imperatively.
+  const bindLean = useCallback((el: HTMLIFrameElement | null) => { registerLeanFrame(node.key, el) }, [node.key])
+  // capture a fresh lean snapshot once the frame is ready and quiet, and whenever its CONTENT changes
+  // (nav). Resize needs no re-capture (the lean doc reflows) and theme needs none (attribute flip),
+  // so neither is a dep - keeping captures rare. Never during a gesture; the coordinator serialises.
+  useEffect(() => {
+    // capture reads the live iframe's same-origin document - true in dev AND publish (published frames
+    // are bundled same-origin and served by `marver serve`), so the lean tier works in both via this
+    // client-side capture. Fail-soft: a frame that can't serialise stays live (publish == today's
+    // behaviour in the worst case). No headless build step / heavy dependency needed.
+    if (node.status !== 'ready' || node.missing) return
+    const iframe = iframeRef.current
+    if (!iframe) return
+    const t = setTimeout(() => scheduleCapture(node.key, iframe, { sourceRevision: String(node.nav ?? 0), theme: node.theme }), 450)
+    return () => clearTimeout(t)
+    // node.theme IS a dep: baked content (mermaid SVG) can't be re-themed by the cover's attribute
+    // flip, so a theme change re-captures after the live frame re-renders (key includes theme).
+  }, [node.status, node.nav, node.key, node.missing, node.theme])
+  useEffect(() => () => dropSnapshot(node.key), [node.key])   // drop the snapshot on unmount
+  // a reload / file-swap / error takes the frame out of 'ready': drop its cover so a stale picture
+  // never lingers (nav may not bump on a same-file reload). The next 'ready' re-captures.
+  useEffect(() => { if (node.status !== 'ready') dropSnapshot(node.key) }, [node.status, node.key])
+  // LEAN-PRIMARY focus handoff: entering interact shows the live app (drop the now-stale lean at
+  // once); leaving it recaptures the live frame's CURRENT state (the user may have typed/toggled)
+  // and only swaps back to lean once that fresh capture is admitted. force=true: same nav/theme.
+  const prevInteract = useRef(interact)
+  useEffect(() => {
+    if (prevInteract.current === interact) return
+    const wasInteract = prevInteract.current
+    prevInteract.current = interact
+    if (interact) invalidateLean(node.key)
+    else if (wasInteract && node.status === 'ready' && iframeRef.current)
+      scheduleCapture(node.key, iframeRef.current, { sourceRevision: String(node.nav ?? 0), theme: node.theme }, true)
+  }, [interact, node.key, node.nav, node.theme, node.status])
 
   // laser mode (SPEC-M3 §7) rides the same rail; re-sent when a frame becomes ready
   // so late loaders join an already-lasered board
@@ -56,6 +120,12 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (node.status === 'ready' || !commentMode)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:pick', on: commentMode }, location.origin)
   }, [commentMode, node.status])
+  // B0.2: the interact target owns its own wheel (app scrolls); passive frames forward
+  // wheel to the canvas. Replayed on ready like laser/pick so a reload restores truth.
+  useEffect(() => {
+    if (node.status === 'ready' || !interact)
+      iframeRef.current?.contentWindow?.postMessage({ type: 'sh:interactive', on: interact }, location.origin)
+  }, [interact, node.status])
 
   // a frame whose FILE actually changed (e.g. tsx -> html swap, same id) must renavigate
   useEffect(() => {
@@ -94,7 +164,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     const world = document.getElementById('sh-world')!
     // Law G-5: measured scale, never stored zoom state. #sh-world is 1px wide by design,
     // so its rendered rect width IS the scale (survives browser page-zoom too).
-    const gestureScale = world.getBoundingClientRect().width || scale || 1
+    const gestureScale = world.getBoundingClientRect().width || useStore.getState().scale || 1
     const start = { x: e.clientX, y: e.clientY, nx: node.x, ny: node.y, nw: node.w, nh: node.h }
     // group drag: moving any member moves the whole selection by the same delta
     const st = useStore.getState()
@@ -105,10 +175,21 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         if (n) groupStarts[k] = { x: n.x, y: n.y }
       }
     }
-    world.classList.add('sh-gesturing')
-    setGesture(true)
+    // Defer sh-gesturing (and its `will-change: transform` on .sh-content) until an ACTUAL drag
+    // begins - a bare click otherwise promotes then demotes the compositor layer, re-rasterising
+    // the frame's text at a fractional zoom = the "jiggle". A pure click now never toggles it.
+    let gesturing = false
+    const begin = () => {
+      if (gesturing) return
+      gesturing = true
+      world.classList.add('sh-gesturing')   // drops iframe pointer-events (sh-camera is NOT set, so no cover)
+      setGesture(true)
+    }
+    const MOVE_THRESHOLD = 3   // px in screen space before a press counts as a drag
 
     const onMove = (ev: PointerEvent) => {
+      if (!gesturing && Math.hypot(ev.clientX - start.x, ev.clientY - start.y) < MOVE_THRESHOLD) return
+      begin()
       const dx = (ev.clientX - start.x) / gestureScale
       const dy = (ev.clientY - start.y) / gestureScale
       if (mode === 'move') {
@@ -213,11 +294,20 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
           </div>
         ) : null}
         <iframe
-          ref={iframeRef}
+          ref={bindIframe}
+          className="sh-live"
           src={initialSrc.current ?? frameUrl(frame, node.theme)}
           title={frame.id}
+          onLoad={registerWin}
           style={{ width: node.w, height: node.h, display: node.missing || node.status === 'error' ? 'none' : 'block' }}
         />
+        {/* SPEC-M5 lean facade: a DOM-snapshot (static html, 0 JS) covering the live iframe only while
+            the canvas is gesturing (CSS), so a heavy frame never flashes white mid-transform and the
+            device sweep reflows correctly. sandbox WITHOUT allow-scripts = no JS runs; allow-same-origin
+            so fonts/assets resolve and the shell can flip its theme + restore scroll. Never registered,
+            never messaged, pointer-events:none - it is NOT the live iframe (role: .sh-lean).
+            Rendered in dev AND publish (runtime client-side capture; frames are same-origin in both). */}
+        <iframe ref={bindLean} className="sh-lean" sandbox="allow-same-origin" title="" aria-hidden tabIndex={-1} />
         {/* the overlay eats mouse events for drag-by-body; laser and comment mode both
             need the mouse INSIDE the frame for hover highlights, so it steps aside
             (drag still works via the header) */}

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],
+  }
+}