fix(cli): surface video frame-injection failures in snapshot output

[vanceingalls]

What

Surfaces three previously-silent degradation paths in snapshot's video frame-injection: (1) warns when @hyperframes/engine is unavailable (injection wholly unavailable), (2) warns when some-but-not-all active <video> frames could be extracted at a given seek time, (3) warns instead of silently swallowing injection failures.

Why

Two wild Windows reports: system-Chrome snapshots omitted direct <video> media while overlay HTML rendered correctly; seven non-overlapping <video> clips on one track rendered black in both snapshot and check with only one clip ever painting. snapshot DOES have an FFmpeg-based frame-injection path, but it degraded silently in all three of these spots — users had no signal that what they were looking at was black/stale.

Validation

Existing snapshot.test.ts suite (12 tests) green — these are new warning paths with no prior coverage, consistent with the rest of the command's console-output surface (not unit-tested). CLI build clean.

🤖 Generated with Claude Code

[vanceingalls]

• fix(cli): surface video frame-injection failures in snapshot output #2255 👈 (View in Graphite)
• fix(shader-transitions): pin cloned scene roots to composition dimensions #2254
• fix(cli): fold canvas pixel hashes into the frozen-sweep fingerprint #2253
• chore(producer): resync stale committed puppeteer-core symlinks to lockfile version #2259
• fix(producer): disk-headroom gate before hdr raw frame pre-extraction #2256
• feat(cli): preview --browser-no-gpu for gpu-unstable hosts #2252
• fix(cli): settle post-seek font subset loads before audit screenshots #2251
• fix(engine): densify drawelement self-verify with parallel worker count #2250
• fix(producer): withhold de parallel router below a machine ram floor #2249
• fix(producer,engine): gate drawelement on ancestor background-image + tail verify sample #2247
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miga-heygen]

#2255 — surface video frame-injection failures in snapshot output

Verdict: LGTM 🟢

Three previously-silent failures now surface warnings:

1. Engine unavailable at import → warns that <video> elements will appear black (was silent, two wild Windows reports)
2. Partial frame extraction (some active videos couldn't be extracted at seek time) → warns with count
3. syncVideoFrameVisibility injection failure → warns instead of silently falling through

All use console.warn with actionable context ("verify media via a draft render's extracted frames instead"). No behavior change for the happy path — these only fire when something goes wrong that previously produced black frames silently.

Review by Miga

[miguel-heygen]

Reviewed current head 7afc1c4. Engine-unavailable, partial extraction, and injection exceptions now produce specific warnings while preserving snapshot continuation; no sensitive path data is added. Required checks are green. APPROVE.

[james-russo-rames-d-jusso]

Reviewed at 7afc1c4.

All three silent-degradation paths in snapshot's video frame-injection get surfaced. The observability shape matches the rest of the command (console warn, not a structured event) so it's consistent with the existing surface — dashboards that scrape stderr will see it.

• Path 1 (@hyperframes/engine unavailable): warns once. Users know their <video data-start> will be black; comment now says why (chrome-headless ignores programmatic currentTime writes).
• Path 2 (partial extraction, updates.length < active.length): warns per seek time with N/M. Also correctly fires when 0/N extracted, which is the worst-visibility subcase.
• Path 3 (syncVideoFrameVisibility throws): warns instead of silent fall-through. Covers both the updates.length > 0 inject branch and the [] clear-stale-overlays branch — the message says "video frame injection failed" for both, which is a slight semantic drift for the clear-overlays branch, but the aggregate user-visible outcome ("videos will appear black/stale") is the same in both branches so I don't think it's worth splitting the message.

LGTM from my side.

— Review by Rames D Jusso

[jrusso1020]

Approving per the channel stamp-flow: Rames-D and Magi both cleared, CI clean at 7afc1c4.

The base branch was changed.