fix(cli): warn preflight when color grading meets no hardware GPU - #3882
Open
miga-heygen wants to merge 1 commit into
Open
fix(cli): warn preflight when color grading meets no hardware GPU#3882miga-heygen wants to merge 1 commit into
miga-heygen wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
check --browser-gpu(or defaultauto) on a composition usingdata-color-gradingcan 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 findingcolor-grading-canvas-readpixels-gpu-stall-under-swiftshader.md, root-caused and live-reproduced by cli-repro). This is an inherent SwiftShader limitation (see graveyardswiftshader-de-speedup.md), not something to "fix" directly.compositionUsesColorGrading()anddetectColorGradingGpuStallRisk()(packages/cli/src/browser/gpuPolicy.ts): a cheap static HTML scan fordata-color-grading, combined with the existing GPU-mode probe (forcing"auto"to get the ground-truth hardware/software answer even for an explicit--browser-gpurequest, since that mode always reports back"hardware"verbatim otherwise).check'srunBrowserCheck(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 discardsrunBrowserCheck'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 incheck --strict/check --json.--timeout, running on a host with a real GPU, or the documented monochrome-preprocessing workaround (gradingintensity: 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/clicleanbunx oxlint+bunx oxfmt --writeclean (no unwanted reformatting)bunx fallow audit --base origin/main --fail-on-issuesclean (0 issues, 4 changed files)packages/cli/src/utils/checkBrowser.test.tsfails withError: No such built-in module: node:both with and without this change — confirmed pre-existing/environmental via a cleanorigin/mainre-run, unrelated to this fix🤖 Generated with Claude Code