@marver-design/marver 0.3.1 → 0.5.0

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

@@ -2,6 +2,7 @@ import { useEffect, useRef } from 'react'
 import { TransformWrapper, TransformComponent, type ReactZoomPanPinchContentRef } from 'react-zoom-pan-pinch'
 import { CONFIG, useStore } from '../store.ts'
 import { bootHash } from '../hash.ts'
+import { startPerf } from '../perf.ts'
 import { FrameNode, HEADER } from './FrameNode.tsx'
 
 /**
@@ -82,12 +83,20 @@ export function animateLayout(ms = 360) {
   presetTimer = window.setTimeout(() => w.classList.remove('sh-preset'), ms)
 }
 
+/** B0.2: one wheel event, whatever its origin - a shell-document wheel over the canvas, or
+ *  a wheel forwarded from a passive frame's iframe. clientX/Y are shell-viewport pixels. */
+export interface CanvasWheelInput {
+  deltaX: number; deltaY: number; deltaMode: number
+  ctrlKey: boolean; metaKey: boolean; clientX: number; clientY: number
+}
+
 export const canvasCtl = {
   fitNode(_key: string) {},
   fitNodes(_keys: string[]) {},
   fitAll() {},
   zoomTo(_scale: number) {},
   zoom100() { canvasCtl.zoomTo(1) },
+  wheel(_input: CanvasWheelInput) {},
 }
 
 /** Variant-group captions (SPEC-023 §4): "Landing · 3 variants" above each group with
@@ -131,6 +140,9 @@ export function Canvas() {
   const gesture = useStore((s) => s.gesture)
   const setScale = useStore((s) => s.setScale)
   const ref = useRef<ReactZoomPanPinchContentRef>(null)
+  const scaleTimer = useRef(0)
+
+  useEffect(() => { startPerf() }, [])   // B0.4: frame-time sampler (window.__mvPerf)
 
   useEffect(() => {
     const wrap = () => document.querySelector('.sh-canvas') as HTMLElement | null
@@ -231,41 +243,55 @@ export function Canvas() {
     return () => el.removeEventListener('pointerdown', down)
   }, [])
 
-  // Zoom curve: rzpp's wheel zoom is ADDITIVE in scale - a constant scale amount per
-  // pinch, which reads as sluggish when zoomed in and runaway when zoomed out (zoom is
-  // perceptually logarithmic). So ctrl/meta wheels (trackpad pinch arrives as ctrl-wheel
-  // in Chrome; cmd+scroll folds in too) are intercepted on an ANCESTOR of the wrapper -
-  // guaranteed to run before rzpp's own listener - and applied as an exponential step:
-  // constant ratio per finger distance, uniform feel at every zoom level.
+  // B0.2: the shell is the SINGLE wheel-camera owner. rzpp's wheel-pan is disabled (below);
+  // both entry paths - a shell-document wheel over the canvas, and a wheel forwarded from a
+  // passive frame's iframe (sh:wheel) - feed one applyCanvasWheel. Plain wheel pans (mirrors
+  // rzpp's old position-delta math); ctrl/meta wheel zooms about the cursor on an exponential
+  // curve (constant ratio per finger distance - uniform feel at every zoom, unlike rzpp's
+  // additive step). setTransform drives onTransformed, which repaints the grid.
   useEffect(() => {
     const app = document.querySelector('.sh-app') as HTMLElement | null
-    const el = document.querySelector('.sh-canvas') as HTMLElement | null
-    if (!app || !el) return
+    const canvas = document.querySelector('.sh-canvas') as HTMLElement | null
+    if (!app || !canvas) return
     let settle = 0
-    const onWheel = (e: WheelEvent) => {
-      if (!e.ctrlKey && !e.metaKey) return
-      if (!(e.target as HTMLElement | null)?.closest?.('.sh-canvas')) return
-      e.preventDefault()
-      e.stopImmediatePropagation()
+    const beginGesture = (panning: boolean) => {
+      // sh-camera = a CANVAS pan/zoom (drives the snapshot cover); sh-gesturing also drops iframe
+      // pointer-events. A frame click/drag sets only sh-gesturing, so it never flashes a snapshot.
+      document.getElementById('sh-world')?.classList.add('sh-gesturing', 'sh-camera')
+      document.body.classList.toggle('sh-panning', panning)
+      clearTimeout(settle)
+      settle = window.setTimeout(() => {
+        document.getElementById('sh-world')?.classList.remove('sh-gesturing', 'sh-camera')
+        document.body.classList.remove('sh-panning')
+      }, 160)
+    }
+    const applyCanvasWheel = (w: CanvasWheelInput) => {
       const inst = ref.current
-      if (!inst) return
+      if (!inst || useStore.getState().play) return
       const { positionX, positionY, scale } = inst.instance.transformState
-      // exponent scales with input; per-event ratio capped so a discrete mouse-wheel
-      // notch (|deltaY| ~100) stays controllable while trackpad streams pass through
-      const f = Math.min(1.4, Math.max(1 / 1.4, Math.exp(-e.deltaY * 0.0075 * (CONFIG.zoomSpeed ?? 1))))
+      const zooming = w.ctrlKey || w.metaKey
+      beginGesture(!zooming)
+      if (!zooming) { inst.setTransform(positionX - w.deltaX, positionY - w.deltaY, scale, 0, 'linear'); return }
+      const f = Math.min(1.4, Math.max(1 / 1.4, Math.exp(-w.deltaY * 0.0075 * (CONFIG.zoomSpeed ?? 1))))
       const next = Math.min(2, Math.max(0.05, scale * f))
       if (next === scale) return
+      const r = canvas.getBoundingClientRect()
+      const cx = w.clientX - r.left, cy = w.clientY - r.top
       const k = next / scale
-      const r = el.getBoundingClientRect()
-      const cx = e.clientX - r.left, cy = e.clientY - r.top
-      // rzpp's zoom callbacks never fire on setTransform - manage the gesture class here
-      document.getElementById('sh-world')?.classList.add('sh-gesturing')
-      clearTimeout(settle)
-      settle = window.setTimeout(() => document.getElementById('sh-world')?.classList.remove('sh-gesturing'), 160)
       inst.setTransform(cx - (cx - positionX) * k, cy - (cy - positionY) * k, next, 0, 'linear')
     }
+    canvasCtl.wheel = applyCanvasWheel
+    const onWheel = (e: WheelEvent) => {
+      const t = e.target as HTMLElement | null
+      if (!t?.closest?.('.sh-canvas')) return
+      if (t.closest('[data-sh-wheel-local]')) return   // escape hatch for scrollable shell UI in-canvas
+      e.preventDefault()
+      e.stopImmediatePropagation()
+      applyCanvasWheel({ deltaX: e.deltaX, deltaY: e.deltaY, deltaMode: e.deltaMode,
+        ctrlKey: e.ctrlKey, metaKey: e.metaKey, clientX: e.clientX, clientY: e.clientY })
+    }
     app.addEventListener('wheel', onWheel, { capture: true, passive: false })
-    return () => { app.removeEventListener('wheel', onWheel, { capture: true }); clearTimeout(settle) }
+    return () => { canvasCtl.wheel = () => {}; app.removeEventListener('wheel', onWheel, { capture: true }); clearTimeout(settle) }
   }, [])
 
   // space-pan: hold space, drag anywhere - nodes drop pointer-events so the canvas takes the drag
@@ -289,12 +315,14 @@ export function Canvas() {
     }
   }, [])
 
+  const camera = (on: boolean) => {
+    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing', 'sh-camera')
+  }
   const pan = (on: boolean) => () => {
-    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing')
+    camera(on)
     document.body.classList[on ? 'add' : 'remove']('sh-panning')
   }
-  const zoom = (on: boolean) => () =>
-    document.getElementById('sh-world')?.classList[on ? 'add' : 'remove']('sh-gesturing')
+  const zoom = (on: boolean) => () => camera(on)
 
   // no initialPosition props on the wrapper: rzpp applies them ASYNC after mount and
   // stomps the boot fit when data is inlined (published builds) - the boot fit owns
@@ -312,13 +340,22 @@ export function Canvas() {
       // ctrl/meta wheel zoom never reaches rzpp (exponential curve above); pinch.step
       // only serves real touch-screen pinch.
       wheel={{ wheelDisabled: true, step: 0.225 * (CONFIG.zoomSpeed ?? 1) }}
-      panning={{ wheelPanning: true, velocityDisabled: true, excluded: ['sh-no-pan'], disabled: gesture }}
+      // B0.2: rzpp no longer owns wheel-pan (the shell's applyCanvasWheel does, so it works
+      // over passive frames and forwarded from iframes too). excluded still governs pointer-drag.
+      panning={{ wheelPanning: false, velocityDisabled: true, excluded: ['sh-no-pan'], disabled: gesture }}
       pinch={{ step: 7.5 * (CONFIG.zoomSpeed ?? 1) }}
       onPanningStart={pan(true)}
       onPanningStop={pan(false)}
       onZoomStart={zoom(true)}
       onZoomStop={zoom(false)}
-      onTransformed={(r) => { setScale(r.state.scale); paintGrid(r.state.positionX, r.state.positionY, r.state.scale) }}
+      // B0.1: the grid repaints live via CSS vars (no React), but the store scale - which
+      // only the zoom-% badge reads - commits after the transform SETTLES, so no React
+      // re-render happens per tick during a pan/zoom.
+      onTransformed={(r) => {
+        paintGrid(r.state.positionX, r.state.positionY, r.state.scale)
+        clearTimeout(scaleTimer.current)
+        scaleTimer.current = window.setTimeout(() => setScale(r.state.scale), 120)
+      }}
       onInit={(r) => paintGrid(r.state.positionX, r.state.positionY, r.state.scale)}
     >
       <TransformComponent wrapperClass="sh-canvas" contentClass="sh-content">

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

@@ -1,6 +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
@@ -18,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)
@@ -28,13 +34,98 @@ 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
+  const laser = useStore((s) => s.laser)
+  const commentMode = useComments((s) => s.commentMode)
+  // a node hosting the OPEN thread card (or a draft composer) rises above its
+  // neighbors - each node is a stacking context, so an overflowing card would
+  // otherwise paint under the next frame
+  const hostsCard = useComments((s) =>
+    (!!s.active && s.threads.some((t) => t.id === s.active && t.nodeKey === node.key)) || s.draft?.nodeKey === node.key)
+  useEffect(() => {
+    if (node.status === 'ready' || !laser)
+      iframeRef.current?.contentWindow?.postMessage({ type: 'sh:laser', on: laser }, location.origin)
+  }, [laser, node.status])
+  // comment mode = pick mode in the frame (late loaders join like laser does)
+  useEffect(() => {
+    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(() => {
@@ -73,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()
@@ -84,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') {
@@ -157,7 +259,7 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     <div
       className={`sh-node${selected ? ' sel' : ''}${interact ? ' interact' : ''}`}
       data-theme={node.theme}
-      style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER }}
+      style={{ transform: `translate(${node.x}px, ${node.y}px)`, width: node.w, height: node.h + HEADER, zIndex: hostsCard ? 30 : undefined }}
       data-node={node.key}
     >
       {frame.variantGroup && (
@@ -192,12 +294,24 @@ 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' }}
         />
-        {!interact && (
+        {/* 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) */}
+        {!interact && !commentMode && !laser && (
           <div
             className="sh-overlay sh-no-pan"
             onPointerDown={(e) => drag(e, 'move')}
@@ -206,6 +320,12 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         )}
       </div>
 
+      {/* comments live OUTSIDE the clipped body: a card or pin near the frame edge
+          hangs over it (the vbadge precedent) instead of being cut off */}
+      <div className="cm-layer" style={{ top: HEADER, height: node.h }}>
+        <CommentLayer node={node} frameId={frame.id} iframe={iframeRef} />
+      </div>
+
       {selected && (
         <>
           <div className="sh-handle e sh-no-pan" onPointerDown={(e) => drag(e, 'e')} />

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)
+}