@marver-design/marver 0.16.1 → 0.18.0

package/src/client/frame-host/serialize.ts

@@ -1,195 +0,0 @@
-// The DOM-snapshot serializer. Turns a live, same-origin frame Document into a
-// self-contained STATIC html string: post-render DOM + full inlined CSS (styleSheets +
-// adoptedStyleSheets), JS stripped. Rendered in a `sandbox="allow-same-origin"` (NO allow-scripts)
-// iframe srcdoc, it reflows / theme-flips / device-sweeps with the browser's own layout engine and
-// the app's own stylesheet - so color is identical (same tokens, no raster) and layout is real CSS.
-//
-// Runs in the SHELL (same origin as every frame), reading the live iframe's contentDocument directly
-// - no bridge round-trip. Fail soft: any throw returns a `degraded` result the coordinator refuses to
-// show. Correctness beats the flash-guard: a frame we cannot serialise faithfully stays live.
-
-export interface ScrollEntry { sel: string; top: number; left: number }
-export interface SerializeResult {
-  html: string
-  scrollMap: ScrollEntry[]          // native scrollers to restore shell-side after load
-  degraded: string[]                // 'canvas' | 'video' | 'shadow-dom' | 'cross-origin-css' | 'js-layout'
-  notes: string[]
-  cssBytes: number
-}
-
-const STRIP_TAGS = new Set(['SCRIPT', 'NOSCRIPT'])
-
-/** Absolutize relative url() in a sheet's cssText against that sheet's href (consolidating
- *  rules into one <style> moves the url() base from each sheet to the srcdoc base). */
-function absolutizeUrls(css: string, sheetHref: string | null): string {
-  if (!sheetHref) return css
-  return css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (m, q, ref: string) => {
-    if (/^(data:|https?:|blob:|#|\/)/i.test(ref) || !ref.trim()) return m
-    try { return `url(${q}${new URL(ref, sheetHref).href}${q})` } catch { return m }
-  })
-}
-
-/** Serialise one sheet's rules, recursing into same-origin @import (so imported CSS is inlined, not
- *  left as an invalid mid-list @import pointing at an un-inlined sheet). Bumps `xo` on any unreadable
- *  (cross-origin) sheet or import so the caller can degrade. */
-function rulesText(rules: CSSRuleList, href: string | null, xo: { n: number }): string {
-  let text = ''
-  for (const r of Array.from(rules)) {
-    if (r.type === 3 /* CSSRule.IMPORT_RULE */) {
-      const imp = r as CSSImportRule & { supportsText?: string; layerName?: string | null }
-      const sheet = imp.styleSheet
-      if (!sheet) { xo.n++; continue }
-      let inner: string
-      try { inner = rulesText(sheet.cssRules, sheet.href ?? href, xo) } catch { xo.n++; continue }
-      // preserve the import's conditions - flattening them makes a conditional (e.g. desktop-only,
-      // layered, feature-gated) sheet globally active and mis-render the lean.
-      if (imp.layerName != null) inner = `@layer${imp.layerName ? ' ' + imp.layerName : ''}{\n${inner}\n}`
-      if (imp.supportsText) inner = `@supports (${imp.supportsText}){\n${inner}\n}`
-      const m = imp.media?.mediaText
-      if (m && m !== 'all') inner = `@media ${m}{\n${inner}\n}`
-      text += inner
-      continue
-    }
-    text += r.cssText + '\n'
-  }
-  return absolutizeUrls(text, href)
-}
-
-/** Collect every CSS rule the document renders with: <style>/<link> sheets (recursing @import) AND
- *  constructable adoptedStyleSheets. Cross-origin sheets throw on .cssRules - record + degrade (never
- *  claim fidelity). Honours per-sheet media (`<link media=print>`) and skips disabled sheets. */
-function collectCss(doc: Document, degraded: string[], notes: string[]): string {
-  const chunks: string[] = []
-  const xo = { n: 0 }
-  const dump = (sheet: CSSStyleSheet, href: string | null, label: string) => {
-    if (sheet.disabled) return
-    let rules: CSSRuleList | null = null
-    try { rules = sheet.cssRules } catch { xo.n++; return }
-    if (!rules) return
-    const text = rulesText(rules, href, xo)
-    if (!text) return
-    const media = sheet.media?.mediaText
-    chunks.push(`/* ${label} */\n${media && media !== 'all' ? `@media ${media}{\n${text}\n}` : text}`)
-  }
-  for (const s of Array.from(doc.styleSheets)) dump(s as CSSStyleSheet, s.href, s.href ?? 'inline')
-  const adopted = (doc as Document & { adoptedStyleSheets?: CSSStyleSheet[] }).adoptedStyleSheets ?? []
-  adopted.forEach((s, i) => dump(s, null, `adopted[${i}]`))
-  if (xo.n) { degraded.push('cross-origin-css'); notes.push(`${xo.n} cross-origin stylesheet(s)/import(s) unreadable`) }
-  if (adopted.length) notes.push(`${adopted.length} adoptedStyleSheet(s) inlined`)
-  return chunks.join('\n')
-}
-
-/** A stable-ish selector for restoring scroll in the identical-structure lean doc. */
-function selectorFor(el: Element): string {
-  const seg: string[] = []
-  for (let cur: Element | null = el; cur && cur !== el.ownerDocument.documentElement; cur = cur.parentElement) {
-    if (cur.id) { seg.unshift(`#${CSS.escape(cur.id)}`); break }
-    const tag = cur.tagName.toLowerCase()
-    let n = 1
-    for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling) if (sib.tagName === cur.tagName) n++
-    seg.unshift(`${tag}:nth-of-type(${n})`)
-  }
-  return seg.join('>')
-}
-
-/** Strip execution + inline handlers from the clone; flag content that cannot reflow as DOM. */
-function scrub(root: Element, doc: Document, degraded: string[]): void {
-  root.querySelectorAll('script, noscript, link[rel~="modulepreload"], link[rel~="preload"], link[rel~="stylesheet"]').forEach((n) => n.remove())
-  const walk = doc.createTreeWalker(root, NodeFilter.SHOW_ELEMENT)
-  const flag = { canvas: false, video: false, nested: false }
-  for (let el = walk.currentNode as Element | null; el; el = walk.nextNode() as Element | null) {
-    for (const attr of Array.from(el.attributes)) {
-      if (/^on/i.test(attr.name)) el.removeAttribute(attr.name)
-      else if (/^\s*javascript:/i.test(attr.value)) el.removeAttribute(attr.name)
-    }
-    const tag = el.tagName
-    if (tag === 'CANVAS') flag.canvas = true
-    if (tag === 'VIDEO') flag.video = true
-    // a nested iframe/object/embed can't reflow in a scriptless clone (blank/stale, and would
-    // re-fetch third-party content) - degrade to live rather than ship a broken lean.
-    if (tag === 'IFRAME' || tag === 'OBJECT' || tag === 'EMBED') flag.nested = true
-    if (STRIP_TAGS.has(tag)) el.remove()
-  }
-  if (flag.canvas) degraded.push('canvas')
-  if (flag.video) degraded.push('video')
-  if (flag.nested) degraded.push('nested-frame')
-}
-
-/** Open shadow roots must be detected on the ORIGINAL tree - cloneNode(true) drops them, so the clone
- *  can never reveal them. A frame with any shadow DOM (open here, or closed via the boot-time flag)
- *  degrades to live rather than shipping a lean copy missing its shadow content. */
-function hasOpenShadow(doc: Document): boolean {
-  const walk = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_ELEMENT)
-  for (let el = walk.currentNode as Element | null; el; el = walk.nextNode() as Element | null)
-    if ((el as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot) return true
-  return false
-}
-
-/** Copy live form PROPERTIES (value/checked/selected) into the clone. They are runtime state, not
- *  attributes, so cloneNode never carries them - without this a re-captured frame shows empty inputs
- *  and unchecked boxes. Original and clone share structure, so we pair them in document order.
- *  tagName/type checks (not instanceof) because the clone nodes are owned by the frame's realm. */
-function syncFormState(doc: Document, clone: HTMLElement): void {
-  const live = doc.querySelectorAll('input, textarea, option')
-  const dst = clone.querySelectorAll('input, textarea, option')
-  live.forEach((src, i) => {
-    const d = dst[i]
-    if (!d || d.tagName !== src.tagName) return
-    if (src.tagName === 'INPUT') {
-      const s = src as HTMLInputElement
-      // never bake a password into the retained snapshot html; a file input can't be reconstructed
-      if (s.type === 'password' || s.type === 'file') { d.removeAttribute('value'); return }
-      if (s.type === 'checkbox' || s.type === 'radio') s.checked ? d.setAttribute('checked', '') : d.removeAttribute('checked')
-      else d.setAttribute('value', s.value)
-    } else if (src.tagName === 'TEXTAREA') { d.textContent = (src as HTMLTextAreaElement).value }
-    else if (src.tagName === 'OPTION') { (src as HTMLOptionElement).selected ? d.setAttribute('selected', '') : d.removeAttribute('selected') }
-  })
-}
-
-/**
- * Serialize a live same-origin Document into a static, self-contained html string.
- * @param doc       the live frame document (same origin - we read its cssRules directly)
- * @param baseHref  the frame's real URL, injected as <base> so relative url()/img/font resolve
- */
-export function serializeDoc(doc: Document, baseHref: string): SerializeResult {
-  const notes: string[] = []
-  const degraded: string[] = []
-
-  // shadow DOM (open detected on the original tree, closed via the boot-time attachShadow flag):
-  // either kind degrades the frame to live - cloneNode cannot carry a shadow root.
-  const win = doc.defaultView as (Window & { __mvClosedShadow?: boolean }) | null
-  if (win?.__mvClosedShadow || hasOpenShadow(doc)) { degraded.push('shadow-dom'); notes.push('shadow root(s) present') }
-
-  const css = collectCss(doc, degraded, notes)
-  const cssBytes = new Blob([css]).size
-
-  // scroll offsets to restore shell-side (native scrollers; a virtualised one that fails to resolve
-  // OR whose offset does not stick re-degrades the frame in the coordinator). != 0 catches RTL/negative.
-  const scrollMap: ScrollEntry[] = []
-  for (const el of Array.from(doc.querySelectorAll<HTMLElement>('*'))) {
-    if (el.scrollTop !== 0 || el.scrollLeft !== 0) scrollMap.push({ sel: selectorFor(el), top: el.scrollTop, left: el.scrollLeft })
-  }
-  const de = doc.documentElement
-  if (de.scrollTop !== 0 || de.scrollLeft !== 0) scrollMap.push({ sel: ':root', top: de.scrollTop, left: de.scrollLeft })
-
-  // clone the RENDERED dom (React's committed output = authored markup that reflows under CSS)
-  const html = doc.documentElement.cloneNode(true) as HTMLElement
-  scrub(html, doc, degraded)
-  syncFormState(doc, html)
-
-  // head: <meta charset> + <base> (relative url()/img/font resolve against the real frame URL) +
-  // ONE inlined stylesheet (both themes, all media queries). Drop the clone's own style nodes.
-  const head = html.querySelector('head') ?? html.insertBefore(doc.createElement('head'), html.firstChild)
-  head.querySelectorAll('style').forEach((n) => n.remove())
-  // sentinel first rule: the coordinator checks --mv-lean-ok resolves before showing the lean. If a
-  // hardened host's CSP (style-src 'self') blocked this inline <style>, the sentinel is absent and the
-  // frame stays live rather than showing an unstyled cover.
-  const style = doc.createElement('style'); style.textContent = ':root{--mv-lean-ok:1}\n' + css
-  const base = doc.createElement('base'); base.setAttribute('href', baseHref)
-  const meta = doc.createElement('meta'); meta.setAttribute('charset', 'utf-8')
-  head.insertBefore(style, head.firstChild)
-  head.insertBefore(base, head.firstChild)
-  head.insertBefore(meta, head.firstChild)
-
-  return { html: '<!doctype html>\n' + html.outerHTML, scrollMap, degraded: Array.from(new Set(degraded)), notes, cssBytes }
-}

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

@@ -1,233 +0,0 @@
-/**
- * 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: 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: 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)
-}