fix(engine): route ALL video to screenshot fallback — fast video unsupported

Validated on a native amd64 Linux runner that per-frame BeginFrame does NOT make
drawElementImage capture video (fast-vs-baseline ~12 dB, region black) — same as
macOS. So video falls back to screenshot on every platform, not just macOS.
Make the validation workflow manual-only (it fails by design until fast video
is implemented).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vanceingalls

.github/workflows/fast-video-validation.yml

@@ -9,15 +9,9 @@
 name: Fast-capture video validation
 
 on:
-  # Temporary: lets the workflow run on this branch before it lands on the
-  # default branch (workflow_dispatch is only triggerable from default). Remove
-  # before merge — workflow_dispatch is the intended trigger.
-  push:
-    branches: ["drawelement-fast-capture"]
-    paths:
-      - ".github/workflows/fast-video-validation.yml"
-      - "packages/producer/scripts/validate-fast-video.ts"
-      - "packages/engine/src/services/**"
+  # Manual only. NOTE: currently fails by design — fast capture cannot capture
+  # video on any platform yet (see docs/fast-capture-limitations.md, Limitation 2).
+  # This is the regression gate for if/when fast video is implemented.
   workflow_dispatch:
     inputs:
       composition:

packages/engine/src/services/drawElementService.test.ts

@@ -53,24 +53,16 @@ describe("resolveDrawElementCaptureMode", () => {
     expect(resolveDrawElementCaptureMode(false, false)).toBe("drawelement");
   });
 
-  // ── video routing: needs a per-frame BeginFrame paint for a fresh snapshot ──
-  it("video without BeginFrame paint → screenshot (stale snapshot otherwise)", () => {
-    expect(resolveDrawElementCaptureMode(false, false, /* hasVideo */ true, /* bf */ false)).toBe(
-      "screenshot",
-    );
+  // ── video routing: drawElementImage can't capture video on any platform ──
+  it("video → screenshot (drawElementImage does not capture video frames)", () => {
+    expect(resolveDrawElementCaptureMode(false, false, /* hasVideo */ true)).toBe("screenshot");
   });
 
-  it("video WITH BeginFrame paint → drawelement (Linux headless-shell paints each frame)", () => {
-    expect(resolveDrawElementCaptureMode(false, false, /* hasVideo */ true, /* bf */ true)).toBe(
-      "drawelement",
-    );
+  it("video + GPU still screenshot (verified broken on macOS and Linux/BeginFrame)", () => {
+    expect(resolveDrawElementCaptureMode(false, false, true)).toBe("screenshot");
   });
 
-  it("no video → drawelement regardless of BeginFrame", () => {
-    expect(resolveDrawElementCaptureMode(false, false, false, false)).toBe("drawelement");
-  });
-
-  it("transparent + SwiftShader still screenshot even with BeginFrame", () => {
-    expect(resolveDrawElementCaptureMode(true, true, false, true)).toBe("screenshot");
+  it("no video → drawelement", () => {
+    expect(resolveDrawElementCaptureMode(false, false, false)).toBe("drawelement");
   });
 });

packages/engine/src/services/drawElementService.ts

@@ -21,23 +21,20 @@ import type { Page } from "puppeteer-core";
  * Two cases fall back to screenshot (see docs/fast-capture-limitations.md):
  *  - transparent + SwiftShader: software-GL drops promoted sub-layers on a
  *    transparent canvas destination (Chromium bug 521434899).
- *  - hasVideo + !beginFramePaints: drawElementImage draws a snapshot taken at
- *    the paint event; without a per-frame BeginFrame paint (e.g. macOS, which
- *    has no --enable-begin-frame-control) the snapshot is stale → black/frozen
- *    video. Where BeginFrame drives a paint each frame (Linux headless-shell)
- *    the snapshot is current and video captures correctly.
- *
- * @param beginFramePaints true when a per-frame HeadlessExperimental.beginFrame
- *   advances + paints the compositor before each capture (Linux headless-shell).
+ *  - hasVideo: drawElementImage draws a snapshot taken at the paint event and
+ *    does not capture the freshly-injected per-frame video <img> — the video
+ *    region comes out black/stale. This was verified on BOTH macOS and a native
+ *    amd64 Linux runner (where per-frame BeginFrame *does* paint) — fast-vs-
+ *    baseline PSNR ~12 dB either way — so video is unconditionally routed to
+ *    screenshot capture regardless of platform. Fast video is future R&D.
  */
 export function resolveDrawElementCaptureMode(
   isSwiftShader: boolean,
   transparent: boolean,
   hasVideo = false,
-  beginFramePaints = false,
 ): "drawelement" | "screenshot" {
   if (transparent && isSwiftShader) return "screenshot";
-  if (hasVideo && !beginFramePaints) return "screenshot";
+  if (hasVideo) return "screenshot";
   return "drawelement";
 }
 

packages/engine/src/services/frameCapture.ts

@@ -347,22 +347,16 @@ 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);
-    // BeginFrame drives a per-frame paint (Linux headless-shell) → drawElementImage
-    // reads a fresh snapshot, so video captures correctly. Without it (macOS) the
-    // snapshot is stale → video would be black; route those renders to screenshot.
-    const beginFramePaints = session.beginFrameTimeTicks > 0;
-    const mode = resolveDrawElementCaptureMode(
-      session.isSwiftShader,
-      transparent,
-      hasVideo,
-      beginFramePaints,
-    );
+    const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent, hasVideo);
     if (mode === "screenshot") {
       const reason =
         transparent && session.isSwiftShader
           ? "transparent output on SwiftShader (Chromium bug 521434899)"
-          : "video without per-frame BeginFrame paint (drawElementImage snapshot would be stale)";
+          : "composition contains <video> (drawElementImage does not capture video frames)";
       console.log(`[engine] fast capture: falling back to screenshot — ${reason}`);
       session.captureMode = "screenshot";
       if (transparent) {