Skip to content

fix(cli): warn preflight when color grading meets no hardware GPU - #3882

Open
miga-heygen wants to merge 1 commit into
mainfrom
fix/color-grading-gpu-preflight-warning
Open

fix(cli): warn preflight when color grading meets no hardware GPU#3882
miga-heygen wants to merge 1 commit into
mainfrom
fix/color-grading-gpu-preflight-warning

Conversation

@miga-heygen

Copy link
Copy Markdown
Contributor

Summary

  • check --browser-gpu (or default auto) on a composition using data-color-grading can blow past the navigation-ready timeout when the browser silently falls back to SwiftShader/software WebGL — the grading canvas's per-frame GPU readback has no fast path under software WebGL and has been measured at ~40x slower than an ungraded composition (vault finding color-grading-canvas-readpixels-gpu-stall-under-swiftshader.md, root-caused and live-reproduced by cli-repro). This is an inherent SwiftShader limitation (see graveyard swiftshader-de-speedup.md), not something to "fix" directly.
  • Adds compositionUsesColorGrading() and detectColorGradingGpuStallRisk() (packages/cli/src/browser/gpuPolicy.ts): a cheap static HTML scan for data-color-grading, combined with the existing GPU-mode probe (forcing "auto" to get the ground-truth hardware/software answer even for an explicit --browser-gpu request, since that mode always reports back "hardware" verbatim otherwise).
  • Wired into check's runBrowserCheck (packages/cli/src/utils/checkBrowser.ts): prints the warning before opening the browser (so it's visible even if navigation subsequently times out and the whole report gets replaced with a generic runtime failure — runCheckPipeline's catch discards runBrowserCheck's in-progress findings on that path), and also records it as a "warning"-severity runtime finding so a run that succeeds anyway still surfaces it in check --strict / check --json.
  • Warning text suggests concrete next steps: a much larger --timeout, running on a host with a real GPU, or the documented monochrome-preprocessing workaround (grading intensity: 0) to skip the expensive per-frame pass entirely. Does not attempt to auto-scale the timeout or otherwise change render behavior — the underlying slowness is a genuine SwiftShader constraint, not a bug to paper over.
  • requestedMode: "software" (deliberate --no-browser-gpu) is not warned about — the user already opted into the slow path knowingly.

PRINFRA-685

Test plan

  • bunx vitest run packages/cli/src/browser/gpuPolicy.test.ts packages/cli/src/browser/gpuPolicy.colorGradingStall.test.ts — 10/10 pass, including: detection on/off the color-grading attribute, warns only when composition+software-GPU combo holds, stays silent (and never probes) for ungraded compositions or explicit --no-browser-gpu, forces the "auto" ground-truth probe even for explicit --browser-gpu, and treats a probe failure as "nothing to warn about."
  • bunx tsc --noEmit -p packages/cli clean
  • bunx oxlint + bunx oxfmt --write clean (no unwanted reformatting)
  • bunx fallow audit --base origin/main --fail-on-issues clean (0 issues, 4 changed files)
  • Pre-commit hooks (lefthook: largefiles/tracked-artifacts/lint/format/fallow/typecheck/commitlint) all passed
  • packages/cli/src/utils/checkBrowser.test.ts fails with Error: No such built-in module: node: both with and without this change — confirmed pre-existing/environmental via a clean origin/main re-run, unrelated to this fix

🤖 Generated with Claude Code

check --browser-gpu on a composition using data-color-grading can blow
past the navigation timeout when the browser silently falls back to
SwiftShader: the grading canvas's per-frame GPU readback has no fast
path under software WebGL (~40x slower, measured), a known SwiftShader
limitation rather than a hyperframes bug (see vault finding
color-grading-canvas-readpixels-gpu-stall-under-swiftshader.md).

Detect the composition/GPU combination before opening the browser and
print an actionable warning (larger --timeout, a real-GPU host, or the
monochrome-preprocessing workaround) so a stalled or timed-out check
isn't a silent mystery. Also recorded as a "warning" runtime finding
when the run succeeds anyway, so check --strict and --json surface it
structurally too.

PRINFRA-685

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant