@marver-design/marver 0.4.0 → 0.6.0

package/src/client/content/img-lod.ts

@@ -0,0 +1,107 @@
+// Client-side image Level-Of-Detail, running INSIDE a content frame's iframe.
+//
+// THE PROBLEM: a 2708x1610 screenshot is ~1.5MB as a PNG but ~17MB once decoded to RGBA. A board with
+// 150 of them holds ~2.6GB of decoded bitmaps, and the browser resamples every one each zoom frame =
+// jank + memory pressure. File size is a red herring; DECODED size is the killer.
+//
+// THE FIX: decode each image STRAIGHT to its on-screen size with createImageBitmap(blob,{resizeWidth}) -
+// the full-size decode is never retained - and paint it on a <canvas> via a zero-copy bitmaprenderer
+// transfer. The bitmap is FROZEN while the canvas is being pan/zoomed (the shell posts sh:camera
+// {moving:true}) and only re-picked when the gesture SETTLES (sh:camera {moving:false, scale}), so zoom
+// never triggers a decode/resample storm. Crisp at rest, cheap in motion. This mirrors how tldraw does
+// LOD (resolution by on-screen size, debounced so it never thrashes mid-zoom).
+
+/** Feature probe: createImageBitmap with resize + a canvas bitmaprenderer that can receive it. */
+export const lodSupported = (() => {
+  try {
+    if (typeof createImageBitmap !== 'function' || typeof document === 'undefined') return false
+    const ctx = document.createElement('canvas').getContext('bitmaprenderer')
+    return !!ctx && typeof ctx.transferFromImageBitmap === 'function'
+  } catch { return false }
+})()
+
+// Quantized resize widths (device px). A `want` above the top bucket decodes at NATIVE (bucket 0 = no
+// resize), reached only when a frame is zoomed in past ~2048 on-screen device px.
+const BUCKETS = [256, 640, 1280, 2048]
+const DPR = (): number => Math.min(window.devicePixelRatio || 1, 2)   // cap at 2; 3x buys nothing here
+
+// Bounded decode pool: never run more than N createImageBitmap jobs at once (peak decode memory + CPU).
+const MAX = 3
+let active = 0
+const q: Array<() => void> = []
+const pump = (): void => { while (active < MAX && q.length) q.shift()!() }
+const schedule = (job: () => Promise<void>): void => {
+  q.push(() => { active++; void job().finally(() => { active--; pump() }) })
+  pump()
+}
+
+interface Item { canvas: HTMLCanvasElement; src: string; bucket: number; token: number }
+const items = new Set<Item>()
+let scale = 0.2      // overview default until the shell primes the settled scale on frame-ready
+let moving = false
+
+function pick(devicePx: number): number {
+  for (const b of BUCKETS) if (b >= devicePx) return b
+  return 0           // native decode - only past the top bucket
+}
+
+async function decode(it: Item, bucket: number): Promise<void> {
+  const token = ++it.token
+  let bmp: ImageBitmap
+  try {
+    const blob = await (await fetch(it.src)).blob()
+    bmp = bucket
+      ? await createImageBitmap(blob, { resizeWidth: bucket, resizeQuality: 'high' })
+      : await createImageBitmap(blob)
+  } catch { return }                                       // network / decode failure: keep the last frame
+  if (it.token !== token || !it.canvas.isConnected) { bmp.close(); return }   // superseded or unmounted
+  const ctx = it.canvas.getContext('bitmaprenderer')
+  if (!ctx) { bmp.close(); return }
+  // PIN the display aspect-ratio on the first decode and never change it. Different buckets round to
+  // slightly different integer dims (256x153 = 1.673 vs 1280x761 = 1.682), so if each drove height:auto
+  // the layout box would shift a hair on every resolution switch - the doc reflows, the content frame
+  // auto-resizes, and the frame "jiggles" as you zoom (and the reflow storm helped starve frames to a
+  // ready-timeout). A fixed aspect-ratio makes the box identical across buckets: only pixels sharpen.
+  if (!it.canvas.style.aspectRatio) it.canvas.style.aspectRatio = `${bmp.width} / ${bmp.height}`
+  it.canvas.width = bmp.width; it.canvas.height = bmp.height
+  ctx.transferFromImageBitmap(bmp)                         // zero-copy; consumes + closes the bitmap
+  it.bucket = bucket
+}
+
+function refresh(it: Item): void {
+  const layoutW = it.canvas.getBoundingClientRect().width
+  if (!layoutW) return                                     // not laid out yet (or display:none)
+  const want = pick(Math.ceil(layoutW * scale * DPR()))
+  if (want === it.bucket) return
+  // hysteresis: only DOWNgrade once we're comfortably below the current level, so a jittery zoom that
+  // hovers a threshold doesn't swap back and forth (upgrades are always taken - sharper is worth it).
+  if (it.bucket > 0 && want > 0 && want < it.bucket && Math.ceil(layoutW * scale * DPR()) > it.bucket * 0.6) return
+  schedule(() => decode(it, want))
+}
+
+/** A content <canvas> registers here; returns an unregister fn. Paints a cheap first frame immediately,
+ *  then sharpens to the real zoom on the next prime/settle. */
+export function registerLodImage(canvas: HTMLCanvasElement, src: string): () => void {
+  const it: Item = { canvas, src, bucket: -1, token: 0 }
+  items.add(it)
+  schedule(() => decode(it, BUCKETS[0]))                   // low-res first paint (fast, ~1MB); prime sharpens
+  return () => { items.delete(it); it.token++ }            // token bump drops any in-flight decode
+}
+
+// The shell posts camera transitions ONCE per gesture. Freeze during motion; re-pick every image's
+// resolution to the SETTLED zoom - but debounced, and cancelling any queued work from a prior settle, so
+// a fast zoom in-out-in doesn't stack decode waves across all frames (which starved the main thread and
+// timed frames out). The re-decode only fires once the camera has truly rested.
+let settleTimer = 0
+if (typeof window !== 'undefined' && lodSupported) {
+  window.addEventListener('message', (e) => {
+    if (e.origin !== location.origin) return
+    const m = (e as MessageEvent).data as { type?: string; moving?: boolean; scale?: number } | null
+    if (!m || m.type !== 'sh:camera') return
+    if (m.moving) { moving = true; clearTimeout(settleTimer); q.length = 0; return }   // new gesture: drop pending decodes
+    moving = false
+    if (typeof m.scale === 'number' && m.scale > 0) scale = m.scale
+    clearTimeout(settleTimer)
+    settleTimer = window.setTimeout(() => { if (!moving) for (const it of items) refresh(it) }, 220)
+  })
+}

package/src/client/content/index.tsx

@@ -9,7 +9,12 @@
  */
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { CONTENT_WIDTH } from '../const.ts'
-import { assetUrl, renderMarkdown } from './md.ts'
+import { assetUrl, renderMarkdown, FAMILIES } from './md.ts'
+import { lodSupported, registerLodImage } from './img-lod.ts'
+
+// D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
+const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
+  `.mv-md .mv-c-${f}{color:${c.light}}.dark .mv-md .mv-c-${f},[data-theme="dark"] .mv-md .mv-c-${f}{color:${c.dark}}`).join('\n')
 
 export { Diagram } from './diagram.tsx'
 
@@ -75,6 +80,14 @@ export function Md({ children }: { children?: ReactNode }) {
 export function Img({ src, caption, alt, h }: { src: string; caption?: string; alt?: string; h?: number }) {
   const url = assetUrl(src)
   const [err, setErr] = useState(false)
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  // LOD: paint the image on a <canvas> decoded to its on-screen size (never the full 17MB bitmap), and
+  // re-pick resolution only when the canvas settles after a zoom. See img-lod.ts. Falls back to a plain
+  // <img> where createImageBitmap/bitmaprenderer isn't available (correctness over the optimization).
+  useEffect(() => {
+    if (!url || err || !lodSupported || !canvasRef.current) return
+    return registerLodImage(canvasRef.current, url)
+  }, [url, err])
   if (!url || err) {
     return (
       <div className="mv-block mv-imgerr">
@@ -84,13 +97,18 @@ export function Img({ src, caption, alt, h }: { src: string; caption?: string; a
       </div>
     )
   }
+  // A reference image ALWAYS shows in full: it fills its column at its natural aspect ratio, never
+  // cropped and never letterboxed. Equal-aspect images (e.g. a row of screenshots) line up on their own,
+  // and the frame auto-heights to fit. `h` is accepted for back-compat but no longer constrains size -
+  // capping height below natural would force the image narrower than its column (whitespace) or slice it
+  // (the old object-fit:cover). Width:100% + height:auto come from the .mv-img-el rule.
+  void h
+  const style = undefined
   return (
     <figure className="mv-block mv-img">
-      {/* h: shared rendered height for a row of mixed-aspect images - equal widths
-          alone never make unequal images READ equal; cover-crop to one height does */}
-      <img src={url} alt={alt ?? caption ?? ''} loading="lazy"
-        style={h ? { height: h, width: '100%', objectFit: 'cover' } : undefined}
-        onError={() => setErr(true)} />
+      {lodSupported
+        ? <canvas ref={canvasRef} className="mv-img-el" role="img" aria-label={alt ?? caption ?? ''} style={style} />
+        : <img className="mv-img-el" src={url} alt={alt ?? caption ?? ''} loading="lazy" style={style} onError={() => setErr(true)} />}
       {caption && <figcaption>{caption}</figcaption>}
     </figure>
   )
@@ -106,7 +124,7 @@ function ensureStyles() {
   stylesIn = true
   const el = document.createElement('style')
   el.id = 'mv-content-css'
-  el.textContent = CSS
+  el.textContent = CSS + '\n' + FAMILY_CSS
   document.head.appendChild(el)
 }
 
@@ -140,14 +158,24 @@ body { margin: 0; }
    a whisper, not a card - the content pops, the block only frames it */
 .mv-block { margin: 0; padding: ${UNIT}px; border: 1px solid var(--mv-block-line);
   border-radius: 10px; background: var(--mv-block-bg); }
-.mv-block figcaption, .mv-img figcaption { font-size: 12.5px; color: var(--mv-faint); padding-top: 8px; }
+/* an image block is NOT a card: the screenshot IS the content. Drop the surface + border so we don't
+   frame a frame; give the image itself a hairline edge and a whisper of shadow so it reads as a clean,
+   distinct object on the page (no heavy double-border around browser mockups). */
+.mv-block.mv-img { padding: 0; border: none; background: none; }
+/* INSET hairline: the line sits ON the image's own rounded edge (outline-offset:-1px), overriding a
+   screenshot's ragged or baked-in dark border instead of drawing a second frame outside it. It shares
+   the image's exact border-radius (same element), so the two never mismatch. Grayscale token = clean in
+   both light and dark. A whisper of drop shadow lifts it off the page. */
+.mv-img .mv-img-el { outline: 1px solid var(--mv-line); outline-offset: -1px;
+  box-shadow: 0 1px 4px rgba(20, 22, 28, 0.07); }
+.mv-block figcaption, .mv-img figcaption { font-size: 12.5px; color: var(--mv-faint); padding-top: 10px; }
 .mv-diagram-svg { display: flex; justify-content: center; }
 .mv-diagram-svg svg { max-width: 100%; height: auto; }
 .mv-diagram-err { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--mv-muted);
   font-family: ui-monospace, "SF Mono", Menlo, monospace; }
 .mv-diagram-err b { color: #E0402F; font-family: inherit; }
 .mv-diagram-err .dim, .mv-imgerr .dim { color: var(--mv-faint); font-size: 12px; }
-.mv-img img { display: block; max-width: 100%; border-radius: 6px; }
+.mv-img .mv-img-el { display: block; width: 100%; height: auto; max-width: 100%; border-radius: 6px; }
 .mv-imgerr { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--mv-muted); }
 .mv-imgerr b { color: #E0402F; }
 

package/src/client/content/md.ts

@@ -8,6 +8,19 @@ import { Marked } from 'marked'
 
 const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
 
+/** D3: named color families for inline Md - the SAME families the diagrams use, so prose and
+ *  the diagram beside it speak one color language. Theme pairs (light/dark). Bound to classes,
+ *  never raw HTML (raw HTML stays inert). Used by the `:family[text]` extension + the frame CSS. */
+export const FAMILIES: Record<string, { light: string; dark: string }> = {
+  blue:   { light: '#0088FF', dark: '#3B9DFF' },
+  orange: { light: '#F5820A', dark: '#FF9F33' },
+  purple: { light: '#B32BC8', dark: '#D34FE8' },
+  green:  { light: '#1FA34A', dark: '#34C759' },
+  red:    { light: '#E5342B', dark: '#FF453A' },
+  gray:   { light: '#8B95A3', dark: '#7D8794' },
+}
+const FAMILY_RE = new RegExp(`^:(${Object.keys(FAMILIES).join('|')})\\[([^\\]\\n]+)\\]`)
+
 /** Relative design/assets/ path -> served URL; null for anything else (fail closed).
  *  Decodes BEFORE validating (a %2e%2e must not sneak past the ".." check) and
  *  re-encodes per segment, so the validated path is the path the browser requests. */
@@ -45,6 +58,22 @@ const marked = new Marked({
   },
 })
 
+// D3: `:blue[shipper's world]` -> a family-colored span (inline markdown inside still parses).
+marked.use({
+  extensions: [{
+    name: 'mvcolor',
+    level: 'inline',
+    start(src: string) { return src.match(/:(?:blue|orange|purple|green|red|gray)\[/)?.index },
+    tokenizer(this: any, src: string) {
+      const m = FAMILY_RE.exec(src)
+      if (m) return { type: 'mvcolor', raw: m[0], family: m[1], tokens: this.lexer.inlineTokens(m[2]) }
+    },
+    renderer(this: any, token: any) {
+      return `<span class="mv-c-${token.family}">${this.parser.parseInline(token.tokens)}</span>`
+    },
+  }],
+})
+
 export function renderMarkdown(src: string): string {
   return marked.parse(src, { async: false }) as string
 }

package/src/client/content/palette.ts

@@ -25,6 +25,12 @@ export const THEME_CSS = `
   .nodeLabel, .cluster-label { font-weight: 600; line-height: 1.4; }
   .nodeLabel p, .edgeLabel p, .label p { margin: 0; }
   .edgeLabel, .edgeLabel .label { font-weight: 500; }
+  /* D1 head/gloss hierarchy: a "Head :: gloss" label renders as two paragraphs -
+     bold head (the strong from the markdown), lighter/smaller gloss below. */
+  .nodeLabel p + p, .cluster-label p + p {
+    font-weight: 400; font-size: 0.84em; opacity: 0.68;
+    letter-spacing: 0; margin-top: 3px;
+  }
 `
 
 /** Mermaid themeVariables for one mode. Base theme + these = the marver look. */

package/src/client/frame-host/bridge.js

@@ -4,6 +4,15 @@ const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
 const post = (msg) => { if (window.parent !== window) window.parent.postMessage(msg, '*') }
 const id = new URLSearchParams(location.search).get('id') ?? location.pathname
 
+// SPEC-M5: the shell serialises this frame's DOM (same origin) for the lean facade. Open shadow roots
+// are walkable, but a CLOSED root is invisible after the fact - flag it at creation so the serialiser
+// degrades the frame (keeps it live) instead of shipping a lean copy missing its shadow content.
+const _attachShadow = Element.prototype.attachShadow
+if (_attachShadow) Element.prototype.attachShadow = function (init) {
+  if (init && init.mode === 'closed') window.__mvClosedShadow = true
+  return _attachShadow.call(this, init)
+}
+
 // theme lands as BOTH signals: [data-theme] plus the `dark` class Tailwind/shadcn key on
 const setTheme = (theme) => {
   document.documentElement.dataset.theme = theme
@@ -32,6 +41,8 @@ window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: St
 window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:error', id, message: `unhandled rejection: ${e.reason}` }))
 
 window.addEventListener('message', (e) => {
+  // commands come from the SHELL (parent) only - embedded app content must not flip the theme
+  if (e.source !== window.parent || window.parent === window) return
   if (e?.data?.type === 'sh:set-theme') setTheme(e.data.theme)
 })
 
@@ -40,10 +51,23 @@ if (isHtmlFrame) {
   document.readyState === 'loading' ? addEventListener('DOMContentLoaded', ready) : ready()
 }
 
-// pinch inside a frame must not zoom the parent PAGE (wheel events here belong to the
-// iframe's document, so the shell's blocker cannot see them). Keyboard cmd +/- untouched.
-window.addEventListener('wheel', (e) => { if (e.ctrlKey || e.metaKey) e.preventDefault() }, { passive: false })
+// B0.2 wheel ownership. A frame is either the interact/play target (the APP owns wheel -
+// its own scroll) or passive (laser/comment/plain view - the CANVAS owns wheel). Wheel
+// events land in the iframe's document, so the shell can't see them: when passive we
+// forward them to the shell, when interactive we leave them for the app (only blocking
+// the browser's own ctrl/meta page pinch-zoom). preventing here is mandatory - the parent
+// gets the forwarded message too late to cancel the iframe's own scroll.
+let interactiveOn = false
+window.addEventListener('wheel', (e) => {
+  if (interactiveOn) { if (e.ctrlKey || e.metaKey) e.preventDefault(); return }
+  e.preventDefault()
+  e.stopImmediatePropagation()
+  post({ type: 'sh:wheel', id, deltaX: e.deltaX, deltaY: e.deltaY, deltaMode: e.deltaMode,
+    ctrlKey: e.ctrlKey, metaKey: e.metaKey, clientX: e.clientX, clientY: e.clientY })
+}, { capture: true, passive: false })
 document.addEventListener('gesturestart', (e) => e.preventDefault())
+// a nested scroll container hitting its boundary must not chain into the shell page
+document.documentElement.style.overscrollBehavior = 'contain'
 
 // ---- laser mode + element picking (SPEC-M3 §5, §7) ----------------------------------
 // Laser: one injected stylesheet, outline only (zero layout shift), depth-based hue -
@@ -91,6 +115,15 @@ const COPIED_HTML = `<svg width="12" height="12" viewBox="0 0 256 256" fill="cur
 let laserOn = false, pickOn = false, hoverEl = null, labelEl = null
 const modeActive = () => laserOn || pickOn
 
+// A6: report transient laser/comment engagement (pointer inside this frame AND a mode on) so the
+// shell leases the frame - a hot update to it then defers until the pointer leaves or the mode
+// ends, instead of yanking the user mid-inspect/mid-comment.
+let pointerInside = false
+const reportInteraction = () => post({ type: 'sh:interaction', id, laser: pointerInside && laserOn, comment: pointerInside && pickOn })
+document.addEventListener('mouseover', () => { if (!pointerInside) { pointerInside = true; reportInteraction() } })
+document.addEventListener('mouseout', (e) => { if (!e.relatedTarget) { pointerInside = false; reportInteraction() } })
+window.addEventListener('blur', () => { if (pointerInside) { pointerInside = false; reportInteraction() } })
+
 // laser and pick are independent looks over shared hover machinery: the stylesheet
 // is regenerated on every flip so each mode contributes exactly its own rules
 const applyModes = () => {
@@ -258,8 +291,10 @@ window.addEventListener('message', (e) => {
   const m = e?.data
   if (!m || typeof m !== 'object') return
   // independent toggles - each mode contributes its own rules, applyModes composes
-  if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes() }
-  if (m.type === 'sh:pick') { pickOn = !!m.on; applyModes() }
+  if (m.type === 'sh:laser') { laserOn = !!m.on; applyModes(); reportInteraction() }
+  if (m.type === 'sh:pick') { pickOn = !!m.on; applyModes(); reportInteraction() }
+  // B0.2: interact/play target owns its own wheel; passive frames forward it to the canvas
+  if (m.type === 'sh:interactive') { interactiveOn = !!m.on }
   if (m.type === 'sh:copy-ok') showCopied(m.seq)
   if (m.type === 'sh:resolve-anchors' && Array.isArray(m.anchors)) {
     const rects = m.anchors.slice(0, 200).map((a) => {

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

@@ -0,0 +1,195 @@
+// SPEC-M5 slice 1: 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 (codex P1: 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 }
+}