video-mode: calibrate the render window from the cover, not the recorder endpoint (fixes the black flash)

[mmkal]

Rendered videos flashed black near the end — the teardown calibration cover leaking into the render. This PR fixes the calibration and turns the reproify spec into a passing regression guard.

Before (0.36–0.40s black flash right before the finalHold, deterministic):

black-flash-rendered.webm

After (same spec, fixed):

black-flash-fixed.webm

Mechanism

At teardown, settleVideoRecorder paints a fullscreen rgb(1, 2, 3) cover (near-black) and holds it — deliberately outside the render range — so the recorder's endpoint can serve as the wall→raw clock marker. That assumed Playwright's ≥1s final-frame padding stops at the close instant; it actually lands ~1s past it, so sourceOffset = rawDuration − recordingEndedAt came out ~1s too large, every translated coordinate sat ~1s too deep in the raw, and the derived source-range end ran into the cover: content → black flash → finalHold. Every video-mode-start-behaviors rendering carried a ~0.76s version; iterate/iterate#2523's demo video flashed 0.32s.

Fix

The cover itself becomes the marker — it's the one thing in the recording whose wall-clock time videoMode knows exactly and whose pixels are unmistakable:

• settleVideoRecorder returns the moment it painted the cover (midpoint of DOM insert and the forcing screenshot).
• detectCalibrationCoverStartMs finds the cover's first raw frame by color — a backwards scan of the file's trailing cover run, so an app that legitimately paints near-black mid-test can never match. Tolerance covers webm quantization and true-black padding.
• sourceOffset = coverStartMs − coverPaintedAt (clamped ≥0); endpoint arithmetic stays as the fallback (no cover captured, decode failure, cover-only instant recordings).
• The derived source-range end is capped one frame short of the cover. Annotation minimums still win — now including each hold's sourceFrameAt — so near-instant recordings whose only captured frames ARE cover still render their synthetic reveals.
• Popup children get the same treatment: cover-calibrated childOffsetMs, and overlay windows (closeMs/enableToMs) capped at the cover's composite time.

Verification

• The former test.fail repro now passes as a plain regression test (frame-level: zero near-black frames in the render).
• Full suite: 152 passed, 0 failed.
• ffmpeg blackdetect over every rendered artifact in test-results: all tail flashes gone (start-behaviors ~0.76s each → clean; captions spec clean). Remaining single-frame (40ms) detections predate this change: dark leading frames on two reveal specs, and popup fade-boundary frames in the composites — candidates for a follow-up, an order of magnitude below the reported flash.

Baseline pacing video per AGENTS.md (spec/todo-app.spec.ts on this branch):

todo-baseline-fixed.webm

🤖 Generated with Claude Code

---

Coding agent session: cb910f09-4383-4d33-a11c-f02251cea10d

---

Note

Medium Risk
Changes core video timeline calibration and trim bounds for all rendered outputs; fallback paths remain, but mis-detection could shorten ranges or skew popup overlays.

Overview
Fixes a black flash right before finalHold in rendered demo videos: wall→raw timeline calibration used the recorder close endpoint, but Playwright keeps padding the last screencast frame ~1s past close, so annotations and the source trim ran ~1s into the teardown rgb(1,2,3) calibration cover.

Calibration now pairs settleVideoRecorder’s returned paint time with detectCalibrationCoverStartMs (backward ffmpeg scan for the trailing cover). sourceOffset uses coverStartMs − coverPaintedAt when both exist; recorder-end math remains the fallback. The derived source range end is capped one margin frame before the cover (highlight mins still win, including each hold’s sourceFrameAt). Popup children store calibrationCoverPaintedAt, use the same offset logic, and cap overlay closeMs / enableToMs at the cover’s composite time.

Adds spec/video-mode-black-flash.spec.ts: ffmpeg frame scan asserts zero near-black frames on a light-page render (regression guard for the former repro).

^{Reviewed by Cursor Bugbot for commit 6ead100. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pkg-pr-new]

Open in StackBlitz

pnpm add https://pkg.pr.new/middlewright@38

commit: 6ead100

[mmkal]

🤖 Note for the record: while verifying the review fixes I found a pre-existing load-flake family — the pixel-at-timestamp specs (uses a normal pointer tail after text cursor holds, reveals a stable single-line textarea fill, pans to an offscreen waitFor result…) each pass in isolation but a rotating member fails under full-suite parallel load, including on clean main (2/2 runs failed :2912 there under identical conditions). Not introduced by this branch; probably deserves its own task — under load the screencast captures fewer frames and these assertions sample within one frame of a boundary.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c4f2609. Configure here.}