@zumer/snapdom-plugins 4.0.2 → 4.2.0

package/stream/src/overlays.js

@@ -0,0 +1,153 @@
+/**
+ * Broadcast overlay templates: a stage, a scoreboard with a clock, a lower third, a ticker and
+ * a live badge, as plain DOM with a small controller each. Framework-free: append `.el`
+ * wherever the overlay lives and stream the stage.
+ *
+ * Built to patch. Every box that changes is opaque, so a score or a clock tick repaints that
+ * box alone; the lower third slides with `left`, which moves an out-of-flow box the stream
+ * clears and redraws, where a `transform` slide would be a full frame on every step of it.
+ * Theme through CSS variables on the stage (--sdo-accent, --sdo-panel, --sdo-text, --sdo-font).
+ * Pinned by __tests__/plugin.stream.overlays.test.js.
+ * @module plugins/stream/overlays
+ */
+
+const CSS = `
+.sdo-stage{position:relative;overflow:hidden;--sdo-accent:#facc15;--sdo-panel:#0b0f17;--sdo-panel-2:#161d2b;--sdo-text:#fff;--sdo-ink:#111;--sdo-live:#ef4444;--sdo-font:Arial,Helvetica,sans-serif;font:16px/20px var(--sdo-font);color:var(--sdo-text)}
+.sdo-score{position:absolute;left:24px;top:24px;display:flex;background:var(--sdo-panel);border-radius:6px;overflow:hidden;box-shadow:0 4px 14px #0009}
+.sdo-team{display:flex;align-items:center;gap:10px;padding:8px 14px;background:var(--sdo-panel);font-weight:700;letter-spacing:.04em}
+.sdo-team i{width:10px;height:28px;border-radius:2px;display:block}
+.sdo-pts{min-width:44px;text-align:center;font:700 26px/32px var(--sdo-font);padding:4px 8px;background:var(--sdo-panel-2)}
+.sdo-clock{padding:0 14px;display:flex;align-items:center;background:var(--sdo-accent);color:var(--sdo-ink);font:700 20px/40px ui-monospace,Menlo,monospace}
+.sdo-live{position:absolute;right:24px;top:24px;background:var(--sdo-panel);border-radius:6px;padding:6px 12px 6px 28px;font-weight:700;letter-spacing:.1em}
+.sdo-live::before{content:'';position:absolute;left:11px;top:11px;width:10px;height:10px;border-radius:50%;background:var(--sdo-live);animation:sdo-pulse 1s ease-in-out infinite}
+@keyframes sdo-pulse{50%{opacity:.25}}
+.sdo-lower{position:absolute;left:24px;bottom:76px;display:flex;flex-direction:column;transition:left .45s cubic-bezier(.2,.8,.2,1)}
+.sdo-lower.sdo-hidden{left:-720px}
+.sdo-name{background:#f8fafc;color:#0b0f17;font:700 24px/30px var(--sdo-font);padding:6px 16px;border-radius:4px 4px 0 0}
+.sdo-role{background:#1d4ed8;color:#fff;padding:6px 16px;border-radius:0 0 4px 4px}
+.sdo-ticker{position:absolute;left:0;right:0;bottom:0;height:40px;background:var(--sdo-panel);overflow:hidden;display:flex;align-items:center}
+.sdo-tag{background:var(--sdo-live);height:40px;padding:0 14px;display:flex;align-items:center;font-weight:700;position:relative;z-index:1}
+.sdo-run{white-space:nowrap;padding-left:20px;animation:sdo-run var(--sdo-speed,18s) linear infinite}
+@keyframes sdo-run{from{transform:translateX(0)}to{transform:translateX(-50%)}}
+`
+
+function el(tag, className, text) {
+  const node = document.createElement(tag)
+  if (className) node.className = className
+  if (text != null) node.textContent = text
+  return node
+}
+
+function injectCss(doc = document) {
+  if (doc.getElementById('sdo-css')) return
+  const style = el('style')
+  style.id = 'sdo-css'
+  style.textContent = CSS
+  doc.head.append(style)
+}
+
+/**
+ * The transparent stage every overlay sits on; stream this element.
+ * @param {{width?: number, height?: number, theme?: Record<string, string>}} [options] -
+ *   size in CSS px (default 960x540); theme maps --sdo-* names without the prefix.
+ * @returns {HTMLDivElement}
+ */
+export function overlayStage({ width = 960, height = 540, theme = {} } = {}) {
+  injectCss()
+  const stage = el('div', 'sdo-stage')
+  stage.style.width = `${width}px`
+  stage.style.height = `${height}px`
+  for (const [k, v] of Object.entries(theme)) stage.style.setProperty(`--sdo-${k}`, v)
+  return stage
+}
+
+/**
+ * Two teams, their points and a running clock.
+ * @param {{home?: string, away?: string, homeColor?: string, awayColor?: string}} [options]
+ * @returns {{el: HTMLElement, score(home: number, away: number): void, add(side: 'home'|'away', n?: number): void,
+ *   clock: {start(): void, stop(): void, reset(seconds?: number): void, set(text: string): void}}}
+ */
+export function scoreboard({ home = 'HOME', away = 'AWAY', homeColor = '#22c55e', awayColor = '#3b82f6' } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-score')
+  const team = (name, color, first) => {
+    const t = el('div', 'sdo-team')
+    const swatch = el('i')
+    swatch.style.background = color
+    t.append(...(first ? [swatch, el('span', '', name)] : [el('span', '', name), swatch]))
+    return t
+  }
+  const pts = [el('div', 'sdo-pts', '0'), el('div', 'sdo-pts', '0')]
+  const clockEl = el('div', 'sdo-clock', '00:00.0')
+  root.append(team(home, homeColor, true), pts[0], pts[1], team(away, awayColor, false), clockEl)
+  const points = [0, 0]
+  let started = 0, offset = 0, timer = 0
+  const show = (s) => { clockEl.textContent = `${String(Math.floor(s / 60)).padStart(2, '0')}:${(s % 60).toFixed(1).padStart(4, '0')}` }
+  return {
+    el: root,
+    score(h, a) { points[0] = h; points[1] = a; pts[0].textContent = h; pts[1].textContent = a },
+    add(side, n = 1) { const i = side === 'away' ? 1 : 0; points[i] += n; pts[i].textContent = points[i] },
+    clock: {
+      start() {
+        if (timer) return
+        started = performance.now()
+        timer = setInterval(() => show(offset + (performance.now() - started) / 1000), 100)
+      },
+      stop() {
+        if (!timer) return
+        clearInterval(timer)
+        timer = 0
+        offset += (performance.now() - started) / 1000
+      },
+      reset(seconds = 0) { offset = seconds; started = performance.now(); show(seconds) },
+      set(text) { clockEl.textContent = text },
+    },
+  }
+}
+
+/**
+ * A name and a role that slide in and out.
+ * @param {{name?: string, role?: string, visible?: boolean}} [options]
+ * @returns {{el: HTMLElement, set(fields: {name?: string, role?: string}): void, show(): void, hide(): void}}
+ */
+export function lowerThird({ name = '', role = '', visible = true } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-lower' + (visible ? '' : ' sdo-hidden'))
+  const nameEl = el('div', 'sdo-name', name)
+  const roleEl = el('div', 'sdo-role', role)
+  root.append(nameEl, roleEl)
+  return {
+    el: root,
+    set({ name: n, role: r } = {}) { if (n != null) nameEl.textContent = n; if (r != null) roleEl.textContent = r },
+    show() { root.classList.remove('sdo-hidden') },
+    hide() { root.classList.add('sdo-hidden') },
+  }
+}
+
+/**
+ * A scrolling news line.
+ * @param {{label?: string, items?: string[], speed?: number}} [options] - speed: seconds per loop.
+ * @returns {{el: HTMLElement, set(items: string[]): void}}
+ */
+export function ticker({ label = 'NEWS', items = [], speed = 18 } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-ticker')
+  const run = el('div', 'sdo-run')
+  root.style.setProperty('--sdo-speed', `${speed}s`)
+  root.append(el('div', 'sdo-tag', label), run)
+  // Twice over, so the loop's -50% lands exactly where it started.
+  const set = (list) => { run.textContent = (list.join('   ·   ') + '   ·   ').repeat(2) }
+  set(items)
+  return { el: root, set }
+}
+
+/**
+ * A pulsing "LIVE" bug.
+ * @param {{text?: string}} [options]
+ * @returns {{el: HTMLElement, set(text: string): void}}
+ */
+export function liveBadge({ text = 'LIVE' } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-live', text)
+  return { el: root, set(t) { root.textContent = t } }
+}

package/stream/src/recorder.js

@@ -0,0 +1,41 @@
+/**
+ * Record any canvas a stream feeds (the stream's own, or one it is composited into over
+ * video) with the native MediaRecorder. The container follows the browser: Safari records
+ * MP4, Chromium and Firefox WebM unless they support MP4.
+ * @module plugins/stream/recorder
+ */
+
+const TYPES = ['video/mp4;codecs=avc1', 'video/mp4', 'video/webm;codecs=vp9', 'video/webm;codecs=vp8', 'video/webm']
+
+/**
+ * Start recording `canvas`.
+ * @param {HTMLCanvasElement} canvas
+ * @param {{fps?: number, duration?: number, bitrate?: number}} [options] - fps default 30;
+ *   with `duration` (ms) the recording stops by itself.
+ * @returns {{done: Promise<Blob>, stop: () => Promise<Blob>, type: string}}
+ */
+export function recordCanvas(canvas, options = {}) {
+  if (typeof MediaRecorder === 'undefined' || typeof canvas.captureStream !== 'function') {
+    throw new Error('[SnapDOM] stream: recording needs MediaRecorder and canvas.captureStream')
+  }
+  const type = TYPES.find((t) => MediaRecorder.isTypeSupported(t)) || ''
+  const recorder = new MediaRecorder(canvas.captureStream(options.fps ?? 30), {
+    mimeType: type, videoBitsPerSecond: options.bitrate,
+  })
+  const chunks = []
+  recorder.ondataavailable = (e) => { if (e.data.size) chunks.push(e.data) }
+  const done = new Promise((resolve, reject) => {
+    recorder.onstop = () => resolve(new Blob(chunks, { type: recorder.mimeType || type }))
+    recorder.onerror = (e) => reject(e.error || e)
+  })
+  recorder.start(1000)
+  if (options.duration) setTimeout(() => recorder.state !== 'inactive' && recorder.stop(), options.duration)
+  return {
+    done,
+    type: recorder.mimeType || type,
+    stop() {
+      if (recorder.state !== 'inactive') recorder.stop()
+      return done
+    },
+  }
+}

package/stream/src/stream.js

@@ -0,0 +1,484 @@
+/**
+ * `snapdom.stream(el)`: a live element as a canvas that repaints only what changed.
+ *
+ * A browser compositor does not repaint the page when one button changes; it repaints that
+ * layer. This does the same over captures. The first frame is a full capture. After that,
+ * every change (mutation records, typing, focus, hover, running animations) is attributed to
+ * the nearest ancestor that can be painted standalone over the previous pixels: an opaque
+ * box, with no ancestor effect (opacity, filter, transform, blend, mask) between it and the
+ * root, inside every clipping ancestor and under no positioned element. A box that moved or
+ * was restyled hands the change to the enclosing box that did not; an absolutely positioned
+ * box over a solid or clear backdrop may move and resize itself, since it pushes nothing.
+ * Only that subtree is captured, laid out at its subpixel phase, and drawn over its backdrop
+ * or where it is fully opaque. Anything this cannot prove is a full frame, with the reason
+ * on the frame.
+ *
+ * Measured 2026-10-23, 1000px grid, one card's text changed per frame, median ms per frame
+ * (full / patch): 400 cards Chromium 11.7 / 4.2, Firefox 28 / 4, WebKit 20 / 4; 2000 cards
+ * 52.9 / 4.9, 119 / 5, 90 / 4. The patch cost tracks the changed box, not the page.
+ *
+ * Output: `stream.canvas` is updated in place; `onFrame` receives the dirty rects in canvas
+ * pixels, so a WebGL consumer can `texSubImage2D` just those and a video consumer can use
+ * `canvas.captureStream()`. Pinned by __tests__/plugin.stream.test.js, which compares every
+ * patched frame against a full capture of the same DOM state.
+ *
+ * Built on the public capture API plus one engine contract, the internal `__subpixel` option
+ * (src/engines/svg.js), which lays a patch out at the page's subpixel offset.
+ * @module plugins/stream
+ */
+import { snapdom as capture } from '@zumer/snapdom'
+
+// WebKit keeps toCanvas, whose draw workarounds a raw decode would skip. Every iOS browser is
+// WebKit; elsewhere WebKit is AppleWebKit without a Chromium token.
+const WEBKIT = typeof navigator !== 'undefined' && (/ipad|iphone|ipod/i.test(navigator.userAgent) ||
+  (/applewebkit/i.test(navigator.userAgent) && !/chrome|chromium|crios|edg|opr|android/i.test(navigator.userAgent)))
+
+const EVENTS = ['input', 'change', 'focusin', 'focusout', 'pointerover', 'pointerout', 'scroll', 'toggle']
+/** A patch larger than this share of the frame costs about what a full frame does. */
+const MAX_PATCH_AREA = 0.5
+/** Self-healing keyframe: anything the heuristics missed lasts at most this long, or 50
+ *  full frames' worth of time, so the safety net costs under 2% of the main thread (a
+ *  3000-card lab frame took 235 ms: every 2 s it froze the page 7 times in 8 s). */
+const KEYFRAME_MS = 2000
+const KEYFRAME_COST = 50
+
+function opaqueColor(value) {
+  if (!value || value === 'transparent') return false
+  const m = value.match(/rgba?\(([^)]+)\)/)
+  if (!m) return false
+  const parts = m[1].split(/[\s,/]+/).filter(Boolean)
+  return parts.length < 4 || parseFloat(parts[3]) >= 1
+}
+
+/** An ancestor effect the standalone subtree capture would not reproduce. */
+function hasEffect(cs) {
+  return parseFloat(cs.opacity) < 1 || cs.filter !== 'none' || cs.transform !== 'none' ||
+    cs.mixBlendMode !== 'normal' || (cs.maskImage && cs.maskImage !== 'none') ||
+    cs.clipPath !== 'none' || (cs.backdropFilter && cs.backdropFilter !== 'none')
+}
+
+function clips(cs) {
+  return cs.overflowX !== 'visible' || cs.overflowY !== 'visible'
+}
+
+function inside(a, b) {
+  return a.left >= b.left - 0.5 && a.top >= b.top - 0.5 && a.right <= b.right + 0.5 && a.bottom <= b.bottom + 0.5
+}
+
+/** Whether a clipping ancestor cuts into `r`: past its edges, or into a rounded corner. A
+ *  clock flush with the end of a rounded scoreboard drew square corners where the page
+ *  clipped them round. */
+function escapesClip(r, clip, cs) {
+  if (!inside(r, clip)) return true
+  const radius = Math.max(...['borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomRightRadius', 'borderBottomLeftRadius']
+    .map((p) => parseFloat(cs[p]) || 0))
+  if (!radius) return false
+  return [[clip.left, clip.top], [clip.right - radius, clip.top], [clip.left, clip.bottom - radius], [clip.right - radius, clip.bottom - radius]]
+    .some(([x, y]) => intersects(r, { left: x, top: y, right: x + radius, bottom: y + radius }))
+}
+
+function intersects(a, b) {
+  return a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom
+}
+
+function sameRect(a, b) {
+  return Math.abs(a.left - b.left) < 0.5 && Math.abs(a.top - b.top) < 0.5 &&
+    Math.abs(a.width - b.width) < 0.5 && Math.abs(a.height - b.height) < 0.5
+}
+
+/** Targets whose records have a net effect. The capture pipeline writes to live nodes and
+ *  undoes the write (text-overflow, line-clamp, content-visibility); those records cancel. */
+function netTargets(records, out, restyled) {
+  const attrs = new Map(), chars = new Map()
+  for (const rec of records) {
+    if (rec.type === 'attributes') {
+      const key = rec.target
+      let byName = attrs.get(key)
+      if (!byName) attrs.set(key, byName = new Map())
+      if (!byName.has(rec.attributeName)) byName.set(rec.attributeName, rec.oldValue)
+    } else if (rec.type === 'characterData') {
+      if (!chars.has(rec.target)) chars.set(rec.target, rec.oldValue)
+    } else {
+      let added = 0
+      for (const n of rec.addedNodes) added += n.nodeType === 3 ? n.data.length : 1e6
+      for (const n of rec.removedNodes) added -= n.nodeType === 3 ? n.data.length : 1e6
+      if (added || rec.addedNodes.length !== rec.removedNodes.length) out.add(rec.target)
+      else {
+        const before = [...rec.removedNodes].map(n => n.data).join('')
+        const after = [...rec.addedNodes].map(n => n.data).join('')
+        if (before !== after) out.add(rec.target)
+      }
+    }
+  }
+  for (const [el, byName] of attrs) {
+    for (const [name, old] of byName) if (el.getAttribute(name) !== old) { out.add(el); restyled?.add(el); break }
+  }
+  for (const [node, old] of chars) if (node.data !== old) out.add(node.parentElement)
+}
+
+function describe(node) {
+  const el = node?.nodeType === 1 ? node : node?.parentElement
+  if (!el) return 'a detached node'
+  return `<${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}${el.classList?.length ? '.' + [...el.classList].join('.') : ''}>`
+}
+
+async function decode(url) {
+  const img = new Image()
+  img.decoding = 'sync'
+  img.src = url
+  await img.decode()
+  return img
+}
+
+/**
+ * Stream an element into a canvas, repainting only the boxes that changed.
+ * @param {Element} element
+ * @param {object} [options] - capture options (scale, dpr, embedFonts, ...), plus:
+ * @param {(frame: {full: boolean, reason: string|null, rects: {x:number,y:number,width:number,height:number}[], ms: number, canvas: HTMLCanvasElement}) => void} [options.onFrame]
+ * @param {number} [options.fps] - cap on frames per second; default every animation frame.
+ * @param {boolean} [options.patches=true] - false repaints full frames only (the baseline).
+ * @returns {{canvas: HTMLCanvasElement, stop: () => void, ready: Promise<void>, stats: object}}
+ */
+export function stream(element, options = {}) {
+  const { onFrame, fps, patches = true, ...rest } = options
+  const opts = { ...rest, outerShadows: false, dpr: rest.dpr ?? (globalThis.devicePixelRatio || 1) }
+  const k = (opts.scale ?? 1) * opts.dpr
+  const canvas = document.createElement('canvas')
+  const ctx = canvas.getContext('2d')
+  const dirty = new Set()
+  const restyled = new Set() // elements whose own attributes changed: their box may have too
+  const rects = new WeakMap() // element -> rect at the last paint that covered it
+  const backdrops = new Map() // this frame's hosts that draw over a solid colour
+  const movedFrom = new Map() // this frame's out-of-flow hosts that moved -> their old rect
+  const stats = { full: 0, patch: 0, skipped: 0, lastMs: 0 }
+  let floaters = []
+  let forceFull = true
+  let lastKeyframe = 0
+  let keyframeDue = false // set from idle time once the keyframe interval has passed
+  let fullMs = 0
+  let idleAsked = false
+  let stopped = false
+  let busy = false
+  let lastTick = 0
+  let rootRect = null
+  let animating = new Set() // targets of the animations running at the last tick
+  let ox = 0, oy = 0 // canvas pixels from the canvas origin to the root's border box
+
+  const observer = new MutationObserver(records => netTargets(records, dirty, restyled))
+  observer.observe(element, { subtree: true, childList: true, attributes: true, characterData: true, attributeOldValue: true, characterDataOldValue: true })
+  const onEvent = (e) => {
+    dirty.add(e.target)
+    if (e.relatedTarget && element.contains(e.relatedTarget)) dirty.add(e.relatedTarget)
+  }
+  for (const type of EVENTS) element.addEventListener(type, onEvent, true)
+  const onResize = () => { forceFull = true }
+  addEventListener('resize', onResize)
+
+  function rectOf(el) {
+    const r = el.getBoundingClientRect()
+    return { left: r.left - rootRect.left, top: r.top - rootRect.top, right: r.right - rootRect.left, bottom: r.bottom - rootRect.top, width: r.width, height: r.height }
+  }
+
+  /** `r` grown to whole canvas pixels, in the same root-relative CSS px. */
+  function pixelRect(r) {
+    return { left: (Math.floor(ox + r.left * k) - ox) / k, top: (Math.floor(oy + r.top * k) - oy) / k, right: (Math.ceil(ox + r.right * k) - ox) / k, bottom: (Math.ceil(oy + r.bottom * k) - oy) / k }
+  }
+
+  /** The nearest absolutely or fixed positioned ancestor: it leaves the flow, so its own
+   *  changes of size or place move nothing else. Drawn only over a backdrop. */
+  function positionedHost(node) {
+    for (let el = node?.nodeType === 1 ? node : node?.parentElement; el && el !== element; el = el.parentElement) {
+      const cs = getComputedStyle(el)
+      if (cs.position !== 'absolute' && cs.position !== 'fixed') continue
+      for (let a = el; a !== element; a = a.parentElement) {
+        const as = getComputedStyle(a)
+        if (hasEffect(as) || (a !== el && clips(as))) return null
+      }
+      return el
+    }
+    return null
+  }
+
+  /** Remember every box's rect and the positioned elements that can paint over others. */
+  function snapshotLayout() {
+    rootRect = element.getBoundingClientRect()
+    floaters = []
+    for (const el of element.querySelectorAll('*')) {
+      rects.set(el, rectOf(el))
+      const cs = getComputedStyle(el)
+      if (cs.position === 'absolute' || cs.position === 'fixed' || cs.position === 'sticky' ||
+        (cs.position === 'relative' && cs.zIndex !== 'auto') || cs.transform !== 'none') floaters.push(el)
+    }
+  }
+
+  /** The box a change to `node` can be repainted through, or null for a full frame. */
+  function hostFor(node) {
+    let el = node?.nodeType === 1 ? node : node?.parentElement
+    if (!el || el === element || !element.contains(el)) return null
+    const chain = []
+    for (let a = el; a && a !== element; a = a.parentElement) chain.push(a)
+    // Search above the highest ancestor with an effect or a clip the box would escape.
+    let start = 0
+    for (let i = 0; i < chain.length; i++) {
+      const cs = getComputedStyle(chain[i])
+      if (hasEffect(cs)) start = i + 1
+      else if (i > 0 && clips(cs) && escapesClip(rectOf(chain[0]), rectOf(chain[i]), cs)) start = i
+    }
+    for (let i = start; i < chain.length; i++) {
+      const cs = getComputedStyle(chain[i])
+      if (!opaqueColor(cs.backgroundColor)) continue
+      // Visible overflow paints outside the box, over pixels the patch does not repaint.
+      if (!clips(cs) && (chain[i].scrollWidth > chain[i].clientWidth + 1 || chain[i].scrollHeight > chain[i].clientHeight + 1)) continue
+      return chain[i]
+    }
+    return null
+  }
+
+  async function full() {
+    // A full frame is the one long task of a stream; 'auto' lets a long clone yield (#503).
+    const t0 = performance.now()
+    // A full frame is the one long task of a stream; 'auto' lets a long clone yield (#503).
+    // Lab, 1000 cards under constant edits: worst frame gap 67 -> 33 ms. Under edits on
+    // every frame a big tree tears and redoes in one task, which only the interval helps.
+    const res = await capture(element, { fast: 'auto', ...opts })
+    const { vbW, vbH, contentX = 0, contentY = 0 } = res.meta
+    const src = WEBKIT ? await res.toCanvas() : await decode(res.url)
+    const w = Math.round(vbW * k), h = Math.round(vbH * k)
+    if (canvas.width !== w || canvas.height !== h) { canvas.width = w; canvas.height = h }
+    ctx.clearRect(0, 0, w, h)
+    ctx.drawImage(src, 0, 0, w, h)
+    ox = contentX * k
+    oy = contentY * k
+    snapshotLayout()
+    lastKeyframe = performance.now()
+    keyframeDue = false
+    fullMs = lastKeyframe - t0
+    stats.full++
+    return [{ x: 0, y: 0, width: w, height: h }]
+  }
+
+  /** The solid colour behind `host` ('transparent' over a clear root) when the patch can be
+   *  drawn over it and come out exact, edges and corners included; null otherwise. Needs no
+   *  shadow or outline of its own (they paint outside the box, where the fill would erase
+   *  them), only opaque or clear ancestor backgrounds up to the first opaque one, and no
+   *  other box on the whole-pixel rect around the host, or around `old`, where a moved host
+   *  was. */
+  function backdropOf(host, old) {
+    const cs = getComputedStyle(host)
+    if (cs.boxShadow !== 'none' || (cs.outlineStyle !== 'none' && parseFloat(cs.outlineWidth) > 0)) return null
+    let color = null
+    for (let a = host.parentElement; a && !color; a = a === element ? null : a.parentElement) {
+      const s = getComputedStyle(a)
+      if (s.backgroundImage !== 'none') return null
+      if (opaqueColor(s.backgroundColor)) color = s.backgroundColor
+      else if (s.backgroundColor !== 'rgba(0, 0, 0, 0)' && s.backgroundColor !== 'transparent') return null
+    }
+    const areas = [pixelRect(rectOf(host)), ...(old ? [pixelRect(old)] : [])]
+    const others = [...host.parentElement.children, ...floaters]
+    for (const other of others) {
+      if (other === host || host.contains(other) || other.contains(host)) continue
+      const or = rects.get(other)
+      if (or && areas.some((a) => intersects(or, a))) return null
+    }
+    return color || 'transparent'
+  }
+
+  function paintBackdrop(backdrop, x, y, w, h) {
+    ctx.clearRect(x, y, w, h)
+    if (backdrop !== 'transparent') {
+      ctx.fillStyle = backdrop
+      ctx.fillRect(x, y, w, h)
+    }
+  }
+
+  /** Capture one host at its subpixel phase and return its pixels, placed. */
+  async function renderPatch(host) {
+    const r = rectOf(host)
+    // Lay the patch out at the page's subpixel phase (svg engine, options.__subpixel), so
+    // its glyphs and snapped box edges land on the same pixels as in the full frame:
+    // white cards on black at 1fr offsets differed on 596 pixels at phase zero.
+    const left = ox + r.left * k, top = oy + r.top * k
+    const x0 = Math.floor(left + 0.001), y0 = Math.floor(top + 0.001)
+    const phase = { x: (left - x0) / k, y: (top - y0) / k }
+    // Always passed, even at phase zero: it also lays the root out at its exact width.
+    const res = await capture(host, { ...opts, __subpixel: phase })
+    const { vbW, vbH, contentX = 0, contentY = 0 } = res.meta
+    const x = Math.round(x0 - contentX * k), y = Math.round(y0 - contentY * k)
+    const w = Math.round(vbW * k), h = Math.round(vbH * k)
+    const src = WEBKIT ? await res.toCanvas() : await decode(res.url)
+    const layer = document.createElement('canvas')
+    layer.width = w
+    layer.height = h
+    const backdrop = backdrops.get(host)
+    if (backdrop) {
+      // Over its solid backdrop the patch is the full frame's pixels, edges included.
+      const lctx = layer.getContext('2d')
+      if (backdrop !== 'transparent') {
+        lctx.fillStyle = backdrop
+        lctx.fillRect(0, 0, w, h)
+      }
+      lctx.drawImage(src, 0, 0, w, h)
+      return { layer, x, y, w, h, backdrop, host, drawnAt: r }
+    }
+    // Otherwise keep only the pixels the box covers fully. Inside an opaque box that is
+    // everything; what is left are its antialiased edges and rounded corners, which did not
+    // change (restyled hosts without a backdrop climb in plan) and which drawing again would
+    // blend over themselves. Same scene: 36 pixels off without this, 0 with it.
+    const lctx = layer.getContext('2d', { willReadFrequently: true })
+    lctx.drawImage(src, 0, 0, w, h)
+    const img = lctx.getImageData(0, 0, w, h)
+    const px = img.data
+    for (let i = 3; i < px.length; i += 4) if (px[i] < 255) px[i] = 0
+    lctx.putImageData(img, 0, 0)
+    return { layer, x, y, w, h, host, drawnAt: r }
+  }
+
+  async function patch(hosts) {
+    // Captures and decodes overlap; the draws then land in one synchronous pass, so the
+    // canvas never shows half a frame. Three hosts a frame (clock, KPI, list row) in
+    // demos/stream-webgl.html: 11.9 ms one after another.
+    const layers = await Promise.all(hosts.map(renderPatch))
+    const out = []
+    for (const [host, old] of movedFrom) {
+      const r = pixelRect(old)
+      const x = Math.round(ox + r.left * k), y = Math.round(oy + r.top * k)
+      const w = Math.round(ox + r.right * k) - x, h = Math.round(oy + r.bottom * k) - y
+      paintBackdrop(backdrops.get(host), x, y, w, h)
+      out.push({ x, y, width: w, height: h })
+    }
+    for (const { layer, x, y, w, h, backdrop } of layers) {
+      // A backdrop layer is the full frame's pixels for its whole rect: replace, not blend.
+      if (backdrop) ctx.clearRect(x, y, w, h)
+      ctx.drawImage(layer, x, y)
+      out.push({ x, y, width: w, height: h })
+    }
+    movedFrom.clear()
+    // Remember where each host was drawn, not where it is now: a sliding box kept moving
+    // while it was captured, and clearing its current rect next frame left a trail behind.
+    for (const { host, drawnAt } of layers) {
+      rects.set(host, drawnAt)
+      for (const el of host.querySelectorAll('*')) rects.set(el, rectOf(el))
+    }
+    stats.patch++
+    return out
+  }
+
+  /** Hosts for this frame, or the reason only a full frame is safe. */
+  function plan() {
+    if (!patches) return 'patches off'
+    if (forceFull) return 'resize'
+    if (keyframeDue) return 'keyframe'
+    const now = element.getBoundingClientRect()
+    if (!sameRect({ left: 0, top: 0, width: now.width, height: now.height }, { left: 0, top: 0, width: rootRect.width, height: rootRect.height })) return 'root resized'
+    rootRect = now
+    const hosts = new Set()
+    for (const node of dirty) {
+      if (!node?.isConnected) return 'node removed'
+      let host = hostFor(node)
+      // A box that moved or resized may have moved its siblings, and a restyled box may have
+      // changed its own edges, which only a solid backdrop lets the patch redraw. If an
+      // enclosing host kept its rect, the change stayed inside it: repaint that box instead.
+      while (host && (!sameRect(rects.get(host) || {}, rectOf(host)) || (restyled.has(host) && !backdropOf(host)))) host = hostFor(host.parentElement)
+      if (!host) {
+        // Out of the flow, a box can move or resize freely: clear where it was, draw it
+        // where it is. A lower third whose name got longer.
+        const p = positionedHost(node)
+        const old = p && rects.get(p)
+        if (old && backdropOf(p, old)) {
+          host = p
+          // Always clear where it was last drawn: a slide's last step can be under the
+          // half-pixel sameRect allows, and the column it left kept the old edge.
+          movedFrom.set(p, old)
+        }
+      }
+      if (!host) return `no host for ${describe(node)}`
+      hosts.add(host)
+    }
+    // Outermost hosts only: a box inside another dirty box is repainted by it.
+    for (const h of [...hosts]) {
+      for (let a = h.parentElement; a && a !== element; a = a.parentElement) if (hosts.has(a)) { hosts.delete(h); break }
+    }
+    let area = 0
+    backdrops.clear()
+    for (const h of movedFrom.keys()) if (!hosts.has(h)) movedFrom.delete(h)
+    for (const h of hosts) {
+      const backdrop = backdropOf(h)
+      if (backdrop) backdrops.set(h, backdrop)
+      const after = rectOf(h)
+      area += after.width * after.height
+      for (const f of floaters) {
+        if (f === h || h.contains(f) || f.contains(h)) continue
+        if (intersects(rectOf(f), after)) return `${describe(f)} overlaps ${describe(h)}`
+      }
+    }
+    if (area > MAX_PATCH_AREA * rootRect.width * rootRect.height) return 'patch area too large'
+    return [...hosts]
+  }
+
+  async function tick() {
+    if (stopped) return
+    requestAnimationFrame(tick)
+    const now = performance.now()
+    if (busy || (fps && now - lastTick < 1000 / fps)) return
+    // A running animation repaints its target every frame, and once more when it stops: the
+    // frame before a pause or the end of a transition is not where it came to rest.
+    const running = new Set()
+    for (const a of element.getAnimations?.({ subtree: true }) || []) {
+      if (a.playState === 'running') running.add(a.effect?.target || element)
+    }
+    for (const target of running) dirty.add(target)
+    for (const target of animating) if (!running.has(target)) dirty.add(target)
+    animating = running
+    netTargets(observer.takeRecords(), dirty, restyled)
+    // The keyframe waits for idle time, so it never lands on top of a burst of edits.
+    if (!keyframeDue && !idleAsked && now - lastKeyframe > Math.max(KEYFRAME_MS, fullMs * KEYFRAME_COST)) {
+      idleAsked = true
+      const due = () => { keyframeDue = true; idleAsked = false }
+      if (typeof requestIdleCallback === 'function') requestIdleCallback(due, { timeout: KEYFRAME_MS })
+      else due()
+    }
+    if (!dirty.size && !forceFull && !keyframeDue) { stats.skipped++; return }
+    busy = true
+    lastTick = now
+    try {
+      const hosts = plan()
+      dirty.clear()
+      restyled.clear()
+      const reason = typeof hosts === 'string' ? hosts : null
+      forceFull = false
+      const out = reason ? await full() : hosts.length ? await patch(hosts) : []
+      // Records produced by our own capture are net-zero; anything else lands next frame.
+      netTargets(observer.takeRecords(), dirty, restyled)
+      stats.lastMs = performance.now() - now
+      if (out.length) onFrame?.({ full: !!reason, reason, rects: out, ms: stats.lastMs, canvas })
+    } finally {
+      busy = false
+    }
+  }
+
+  const ready = (async () => {
+    busy = true
+    try {
+      forceFull = false
+      // Edits from before the capture are in it. Edits landing while it runs may come after
+      // it read the DOM: they stay dirty for the first tick. Dropping them here lost them
+      // until a keyframe (a 1000-card lab under edits kept stale cards for seconds).
+      await full()
+      netTargets(observer.takeRecords(), dirty, restyled)
+      onFrame?.({ full: true, reason: 'start', rects: [{ x: 0, y: 0, width: canvas.width, height: canvas.height }], ms: 0, canvas })
+    } finally { busy = false }
+    requestAnimationFrame(tick)
+  })()
+
+  return {
+    canvas,
+    ready,
+    stats,
+    stop() {
+      stopped = true
+      observer.disconnect()
+      for (const type of EVENTS) element.removeEventListener(type, onEvent, true)
+      removeEventListener('resize', onResize)
+    },
+  }
+}