fix(engine): stop compositing phantom duplicates on captureBeyondViewport (#2607)

* fix(core): stop the async media-metadata rebind once render capture starts seeking

scheduleMetadataDurationHydration re-resolves and can swap the captured
GSAP timeline off a debounced loadedmetadata/durationchange event, fully
uncoordinated with the producer's own per-frame renderSeek calls. When a
full-length <video>'s metadata resolves after capture has already begun
(slow I/O, Docker), this races the deterministic BeginFrame capture loop
and can reflow sub-composition state mid-render, producing phase-offset
duplicate content in captured frames (#2550).

Render-mode duration correction already happens deterministically during
the probe stage before capture starts, so once renderSeek has been called
once there is nothing left for this self-correction to do — gate it off
for the rest of the session.

* fix(core): scope the metadata-rebind guard to actual render/export pages

renderSeek isn't capture-exclusive — Studio's own preview iframe falls
back to it for compositions whose timeline overhangs every native
adapter's duration. Gating the HF#2550 fix on renderCaptureSeekStarted
alone silently disabled the metadata-driven duration self-correction for
that live-scrub case too, where it's still needed. Require the render/
export page signal (window.__HF_EXPORT_RENDER_SEEK_CONFIG, set only by
the producer's fileServer.ts) alongside it, and add a regression test
covering the Studio-preview case.

* fix(engine): stop requesting beyond-viewport capture for video comps that don't need it

Root-caused HF#2550 by reproducing the reporter's public repro end-to-end
(not just the timeline-rebind mechanism from the earlier commits in this
branch) on native Linux: instrumented the actual DOM state during a real
capture session and confirmed the sub-composition never double-mounts —
getBoundingClientRect and the timeline's own local time both match the
single, correct DOM tree throughout. The phantom second copy only exists
in the captured screenshot pixels.

Bisected it to captureBeyondViewport: resolveVideoCaptureBeyondViewport
(#1094's tall-portrait fix) forces `Page.captureScreenshot`'s beyond-viewport
path on for any render with a native <video>, regardless of whether the
page's content actually overflows the declared capture height. On
SwiftShader that beyond-viewport path can composite a stale, vertically
offset paint of the page alongside the fresh one for content that fits
entirely within the viewport — producing exactly the reported phase-offset
duplicate. Disabling captureBeyondViewport (repro's video still present)
eliminates the duplicate outright; re-enabling it reproduces the duplicate
byte-for-byte, isolating it as the actual cause.

Adds pageContentExceedsCaptureHeight, a ground-truth measurement of the
page's actual scrollHeight against the requested capture height, and wires
it into initializeSession to downgrade captureBeyondViewport back to false
once the page is settled and it's confirmed unnecessary — the "reliable
clip predictor" the original #1094 fix's ponytail comment flagged as
missing. This keeps #1094's fix intact for content that genuinely
overflows while closing the SwiftShader ghosting hazard for the (common)
case of video that fits inside its own viewport.

* test(producer): add HF#2550 video+sub-composition regression fixture

Checks in the reporter's confirmed real-world reproduction (media
regenerated via ffmpeg testsrc2, matching their public repro repo) as a
regression fixture, with a golden baseline rendered against the fix.

Verified end-to-end via the project's own Docker regression harness:
- Rendering this fixture with the fix produces the golden baseline
  (clean, single flowchart instance, captureBeyondViewport correctly
  downgraded).
- Direct CLI renders (not through this harness) against unpatched code
  reproduce the reported phantom-duplicate artifact reliably (10/10).

Caveat documented in meta.json: the underlying bug is timing-dependent.
Two harness runs against unpatched code, using this same fixture, did
not reproduce the artifact (0/2) — the harness's in-process render path
apparently doesn't hit the same race window a direct CLI process does on
this host. This fixture is a best-effort regression guard and a
preserved real-world repro, not the sole protection — the deterministic
guard is packages/engine/src/services/screenshotService.test.ts's
pageContentExceedsCaptureHeight unit tests, which exercise the actual
fix logic directly.

Also adds an .gitattributes LFS rule for this fixture's source
index.html (744 KB — carries the real project's embedded base64
assets, over the largefiles hook's 500 KB non-LFS limit).

* fix: route HF#2550 fixture binaries through LFS (were committed raw)

filter.lfs.clean/smudge were locally configured as a no-op "cat" in
this repo's shared .git/config, silently disabling LFS filtering for
every worktree. The previous commit's large binaries (output.mp4,
compiled.html, source index.html, source video) landed as raw blobs
instead of LFS pointers as a result. Ran `git lfs install --local
--force` to restore the correct filter commands, then re-staged the
affected files so they commit as proper LFS pointers.

* fix(engine): address capture viewport review feedback

packages/engine/src/services/frameCapture.ts

@@ -28,6 +28,7 @@ import {
   beginFrameCapture,
   ensureRenderFrameSiblings,
   getCdpSession,
+  pageContentExceedsCaptureHeight,
   pageScreenshotCapture,
   initTransparentBackground,
   shouldDefaultCaptureBeyondViewport,
@@ -2004,6 +2005,23 @@ export async function initializeSession(session: CaptureSession): Promise<void>
 
     await recordSessionInitTelemetry(session, initStart);
 
+    // Ground-truth-check the upstream captureBeyondViewport request (see
+    // pageContentExceedsCaptureHeight) now that the page is fully settled —
+    // downgrade it when the page doesn't actually overflow the requested
+    // capture height, since the beyond-viewport CDP path is otherwise pure
+    // downside (HF#2550: phantom duplicate content on SwiftShader) for
+    // content it was never needed for.
+    if (session.options.captureBeyondViewport) {
+      const needsBeyondViewport = await pageContentExceedsCaptureHeight(
+        page,
+        session.options.height,
+      );
+      if (!needsBeyondViewport) {
+        session.options.captureBeyondViewport = false;
+        logInitPhase("captureBeyondViewport downgraded: page content fits the capture viewport");
+      }
+    }
+
     // drawElement or transparent-background init — runs after page is fully ready.
     await initDrawElementOrTransparentBackground(session, page, logInitPhase);
 

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

@@ -5,6 +5,7 @@ import { parseHTML } from "linkedom";
 import { type Page } from "puppeteer-core";
 import {
   pageScreenshotCapture,
+  pageContentExceedsCaptureHeight,
   cdpSessionCache,
   ensureRenderFrameSiblings,
   applyDomLayerMask,
@@ -143,6 +144,37 @@ describe("shouldDefaultCaptureBeyondViewport", () => {
   });
 });
 
+describe("pageContentExceedsCaptureHeight", () => {
+  function makeFakePageWithScrollHeight(scrollHeight: number): Page {
+    return { evaluate: vi.fn().mockResolvedValue(scrollHeight) } as unknown as Page;
+  }
+
+  it("is false when the page fits exactly within the requested height", async () => {
+    const page = makeFakePageWithScrollHeight(1920);
+    await expect(pageContentExceedsCaptureHeight(page, 1920)).resolves.toBe(false);
+  });
+
+  it("tolerates subpixel rounding just past the requested height", async () => {
+    const page = makeFakePageWithScrollHeight(1920.5);
+    await expect(pageContentExceedsCaptureHeight(page, 1920)).resolves.toBe(false);
+  });
+
+  it("tolerates exactly one CSS pixel past the requested height", async () => {
+    const page = makeFakePageWithScrollHeight(1921);
+    await expect(pageContentExceedsCaptureHeight(page, 1920)).resolves.toBe(false);
+  });
+
+  it("detects content just beyond the rounding tolerance", async () => {
+    const page = makeFakePageWithScrollHeight(1922);
+    await expect(pageContentExceedsCaptureHeight(page, 1920)).resolves.toBe(true);
+  });
+
+  it("is true when the page genuinely overflows the requested height", async () => {
+    const page = makeFakePageWithScrollHeight(2007);
+    await expect(pageContentExceedsCaptureHeight(page, 1920)).resolves.toBe(true);
+  });
+});
+
 describe("injectVideoFramesBatch replacement layout", () => {
   it("does not copy opposing inset constraints onto the injected frame image", async () => {
     const { window, document } = parseHTML(

packages/engine/src/services/screenshotService.ts

@@ -182,6 +182,30 @@ export async function beginFrameCapture(
   };
 }
 
+/**
+ * True if the page's actual rendered content is taller than the requested
+ * capture height. `captureBeyondViewport` exists for exactly one reason
+ * (#1094): a native `<video>` surface whose content genuinely overflows the
+ * viewport-bound capture path clips its bottom edge to black. A video that
+ * fits entirely inside its composition's declared viewport doesn't have that
+ * problem — ground-truth measurement beats the coarser "has a video, so
+ * always request beyond-viewport" heuristic, which also unnecessarily routes
+ * every video render through a CDP capture path prone to producing phantom
+ * duplicate content on SwiftShader (#2550).
+ *
+ * Callers measure once after page settle. Hyperframes compositions have a
+ * fixed-height, overflow-clipped render surface; timeline animation may move
+ * pixels within that surface but must not grow document flow during capture.
+ */
+export async function pageContentExceedsCaptureHeight(
+  page: Page,
+  requestedHeight: number,
+): Promise<boolean> {
+  const scrollHeight = await page.evaluate(() => document.documentElement.scrollHeight);
+  // Small tolerance for subpixel layout rounding, not a real overflow signal.
+  return scrollHeight > requestedHeight + 1;
+}
+
 /**
  * Capture a screenshot using standard Page.captureScreenshot CDP call.
  * Fallback for environments where BeginFrame is unavailable (macOS, Windows).