docs(engine): root-cause the video fast-capture gate + R&D escape hatch

Probing established the real failure mode: drawElementImage drops
layer-promoted subtrees while their transforms animate (sub-composition
entrance/zoom scenes capture black until settled). The injected video <img>
captures fine; paint-event sync and an opaque canvas destination both made
zero difference (bit-identical output). Chromium-side gap, same family as
crbug 521434899 but reproducible on GPU. HF_FAST_CAPTURE_VIDEO=true bypasses
the gate for future probing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-06-14 15:43:35 -07:00
co-authored by Claude Opus 4.8
parent 8ce3871d72
commit 10ffe77f4a
+15 -4
View File
@@ -347,10 +347,21 @@ async function initDrawElementOrTransparentBackground(
if (useDrawElement) {
session.isSwiftShader = await detectSwiftShader(page);
const transparent = session.options.format === "png";
// drawElementImage does not capture the per-frame video <img> (the snapshot
// predates it) — verified black on both macOS and native Linux/BeginFrame —
// so any composition containing <video> falls back to screenshot capture.
const hasVideo = await page.evaluate(() => document.querySelector("video") !== null);
// Video compositions fall back to screenshot capture. Root cause (probed on
// macOS GPU, matches the Linux CI failure): drawElementImage drops
// layer-promoted subtrees while their transforms ANIMATE — sub-composition
// entrance/zoom scenes capture black until the animation settles. The
// injected per-frame video <img> itself captures fine; paint-event sync and
// an opaque destination were both verified to make zero difference
// (bit-identical output), so this is a Chromium-side capture gap, same
// family as crbug 521434899 but reproducible on GPU. Video comps are where
// animated promoted layers are guaranteed, hence the gate; DOM/CSS/GSAP
// comps with non-promoted transforms capture correctly.
// HF_FAST_CAPTURE_VIDEO=true bypasses the gate for future R&D probing.
const hasVideo =
process.env.HF_FAST_CAPTURE_VIDEO === "true"
? false
: await page.evaluate(() => document.querySelector("video") !== null);
const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent, hasVideo);
if (mode === "screenshot") {
const reason =