fix(cli): keep the color grading GPU warning out of --strict results

Whether a host has a GPU says nothing about the composition, so the warning stays on stderr and no longer fails check --strict on GPU-less CI. Also trims the warning text and doc comment.

Author: miguel-heygen

packages/cli/src/browser/gpuPolicy.colorGradingStall.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mocks = vi.hoisted(() => ({
   ensureBrowser: vi.fn(),
@@ -13,22 +13,25 @@ vi.mock("@hyperframes/engine", () => ({
   resolveBrowserGpuMode: mocks.resolveBrowserGpuMode,
 }));
 
-import { detectColorGradingGpuStallRisk } from "./gpuPolicy.js";
+import { compositionUsesColorGrading, detectColorGradingGpuStallRisk } from "./gpuPolicy.js";
 
 const GRADED_HTML =
   '<div data-composition-id="main"><img data-color-grading=\'{"adjust":{"saturation":-1}}\' src="a.jpg" /></div>';
 const UNGRADED_HTML = '<div data-composition-id="main"><img src="a.jpg" /></div>';
 
+describe("compositionUsesColorGrading", () => {
+  it("detects data-color-grading on any element, not just the composition root", () => {
+    expect(compositionUsesColorGrading(GRADED_HTML)).toBe(true);
+    expect(compositionUsesColorGrading(UNGRADED_HTML)).toBe(false);
+  });
+});
+
 describe("detectColorGradingGpuStallRisk", () => {
   beforeEach(() => {
     vi.resetAllMocks();
     mocks.ensureBrowser.mockResolvedValue({ executablePath: "/chrome", source: "cache" });
   });
 
-  afterEach(() => {
-    vi.resetAllMocks();
-  });
-
   it("warns when the composition uses color grading and no hardware GPU is found", async () => {
     mocks.resolveBrowserGpuMode.mockResolvedValue("software");
     const warning = await detectColorGradingGpuStallRisk(GRADED_HTML, "auto");

packages/cli/src/browser/gpuPolicy.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { compositionUsesColorGrading, resolveLocalBrowserGpuMode } from "./gpuPolicy.js";
+import { resolveLocalBrowserGpuMode } from "./gpuPolicy.js";
 
 // compositionRequiresWebGpu and assertWebGpuAdapterAvailable are implemented
 // in @hyperframes/engine (browserManager.ts) and only re-exported here — see
@@ -12,15 +12,4 @@ describe("local browser GPU policy", () => {
     expect(resolveLocalBrowserGpuMode(true, "software")).toBe("hardware");
     expect(resolveLocalBrowserGpuMode(false, "hardware")).toBe("software");
   });
-
-  it("detects data-color-grading on any element, not just the composition root", () => {
-    expect(
-      compositionUsesColorGrading(
-        '<div data-composition-id="main"><img data-color-grading=\'{"adjust":{"saturation":-1}}\' src="a.jpg" /></div>',
-      ),
-    ).toBe(true);
-    expect(
-      compositionUsesColorGrading('<div data-composition-id="main"><img src="a.jpg" /></div>'),
-    ).toBe(false);
-  });
 });

packages/cli/src/browser/gpuPolicy.ts

@@ -27,37 +27,22 @@ export async function resolveCaptureBrowserGpuMode(
 // existing CLI imports don't need to change their module path.
 export { compositionRequiresWebGpu, assertWebGpuAdapterAvailable } from "@hyperframes/engine";
 
+const COLOR_GRADING_ATTR_RE = new RegExp(`\\s${HF_COLOR_GRADING_ATTR}[\\s=>]`, "i");
+
 export function compositionUsesColorGrading(html: string): boolean {
-  const escapedAttr = HF_COLOR_GRADING_ATTR.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
-  return new RegExp(`\\s${escapedAttr}(?:\\s|=|>)`, "i").test(html);
+  return COLOR_GRADING_ATTR_RE.test(html);
 }
 
 const COLOR_GRADING_GPU_STALL_WARNING =
-  `This composition uses ${HF_COLOR_GRADING_ATTR}, but no hardware GPU was detected — ` +
-  "the browser will render on the SwiftShader/software WebGL fallback. Color grading's " +
-  "per-element canvas readback has no fast path under software WebGL: it has been measured " +
-  "at roughly 40x slower than an ungraded composition, which is easily enough to exceed the " +
-  "navigation/render-ready timeout, or to make check/render painfully slow even once past it. " +
-  "If this run is unexpectedly slow or times out, try a much larger --timeout, run on a host " +
-  "with a real GPU, or preprocess to monochrome derivatives with grading intensity 0 before " +
-  "capturing with --browser-gpu to skip the expensive per-frame grading pass entirely.";
+  `This composition uses ${HF_COLOR_GRADING_ATTR}, but no hardware GPU was detected, so the ` +
+  "browser renders with software WebGL (SwiftShader). Color grading's per-frame canvas readback " +
+  "is far slower there and can exceed the navigation timeout. If this run is slow or " +
+  "times out, raise --timeout or run on a host with a real GPU.";
 
 /**
- * Preflight for a known SwiftShader limitation (not a hyperframes bug): a
- * per-element color-grading canvas pays a synchronous GPU-stall readback cost
- * that software WebGL has no fast path for, ~40x slower than an ungraded
- * composition in measured practice. `requestedMode: "software"` is a
- * deliberate, already-informed choice and is not warned about; `"auto"` /
- * `"hardware"` both expect speed, so a silent fallback to software there is
- * exactly the surprise this call is meant to catch before capture starts.
- * Reuses `resolveCaptureBrowserGpuMode`'s cached probe (forcing `"auto"` to
- * get the ground-truth answer even when the caller requested `"hardware"`,
- * which always reports back `"hardware"` verbatim) — resolved against the
- * same `ensureBrowser()` executable path a subsequent real launch will use,
- * so this doesn't seed the shared cache with a different browser's probe.
- * Best-effort: any probe failure here is treated as "nothing to warn about"
- * rather than failing the caller — the real launch will surface a genuine
- * browser problem on its own.
+ * Warns before capture when a graded composition will run on software WebGL. An explicit
+ * "software" request is a deliberate choice and stays silent; "hardware" is reported verbatim
+ * by the engine, so probe "auto" for the real answer. Shares the engine's cached probe.
  */
 export async function detectColorGradingGpuStallRisk(
   html: string,
@@ -70,6 +55,7 @@ export async function detectColorGradingGpuStallRisk(
     const actualMode = await resolveCaptureBrowserGpuMode("auto", browser.executablePath);
     return actualMode === "software" ? COLOR_GRADING_GPU_STALL_WARNING : null;
   } catch {
+    // Best-effort: the real launch surfaces a genuine browser failure.
     return null;
   }
 }

packages/cli/src/utils/checkBrowser.ts

@@ -158,11 +158,7 @@ export async function runBrowserCheck(
   const html = await bundleWithLocalizedFonts(project.dir);
   await preResolveHostileMediaProxies(project.dir, html, options.autoProxy);
   const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
-  // Printed eagerly (not just recorded as a finding) because the risk this
-  // flags is a navigation timeout — if it fires, `runBrowserCheck` throws
-  // before ever returning a report, so a finding pushed to `drafts` would be
-  // discarded along with the whole in-flight result (see runCheckPipeline's
-  // catch, which replaces browser with emptyBrowserResult() on that path).
+  // stderr, not a report finding: a timeout discards the report, and a host fact must not fail --strict.
   const colorGradingGpuWarning = await detectColorGradingGpuStallRisk(html, requestedGpuMode);
   if (colorGradingGpuWarning) console.warn(`\n[hyperframes] ${colorGradingGpuWarning}`);
   const server = await serveStaticProjectHtml(
@@ -173,14 +169,6 @@ export async function runBrowserCheck(
     options.autoProxy,
   );
   const drafts: RuntimeDraft[] = [];
-  if (colorGradingGpuWarning) {
-    drafts.push({
-      code: "color_grading_gpu_stall_risk",
-      severity: "warning",
-      message: colorGradingGpuWarning,
-      time: 0,
-    });
-  }
   let currentTime = 0;
   let chromeBrowser: import("puppeteer-core").Browser | undefined;