Skip to content

Write HTML. Render video. Built for agents.

perf(cli): check skips contrast screenshots it can compute from styles (#5871)

Miguel Ángel7917f7fe058b
diff --git a/packages/cli/bin/hyperframes.mjs b/packages/cli/bin/hyperframes.mjs
index 7c312f1c94..95d72345dc 100644
--- a/packages/cli/bin/hyperframes.mjs
+++ b/packages/cli/bin/hyperframes.mjs
@@ -1,5 +1,6 @@
#!/usr/bin/env node
+import module from "node:module";
import { runtimeVersionError } from "../dist/runtimeVersion.js";
const error = runtimeVersionError(process.versions.node);
@@ -7,5 +8,7 @@ if (error) {
console.error(error);
process.exitCode = 1;
} else {
+ // Reuses V8 bytecode across runs (os.tmpdir()/node-compile-cache); Node 22.0 has no such API.
+ module.enableCompileCache?.();
await import("../dist/cli.js");
}
diff --git a/packages/cli/src/browser/launch.process.test.ts b/packages/cli/src/browser/launch.process.test.ts
index 1475445b77..239343c900 100644
--- a/packages/cli/src/browser/launch.process.test.ts
+++ b/packages/cli/src/browser/launch.process.test.ts
@@ -1,5 +1,5 @@
import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
@@ -8,6 +8,7 @@ import { waitForTestCondition } from "../utils/processTestUtils.js";
const fixturePath = join(dirname(fileURLToPath(import.meta.url)), "launch.fixture.ts");
const children = new Set<ChildProcess>();
+const profiles = new Set<string>();
/** Pids of every process whose command line carries this profile dir (Chromium and its helpers). */
function browserPids(profileDir: string): number[] {
@@ -30,6 +31,7 @@ function startFixture(profileDir: string, readyPath: string, mode = "launch"): C
{ stdio: "ignore" },
);
children.add(child);
+ profiles.add(profileDir);
return child;
}
@@ -38,9 +40,17 @@ const exited = (child: ChildProcess) =>
child.once("exit", (code, signal) => resolve({ code, signal })),
);
+// Chrome outlives a SIGKILLed parent, so a failed case also kills its browser directly.
afterEach(() => {
for (const child of children) child.kill("SIGKILL");
+ for (const pid of [...profiles].flatMap(browserPids)) {
+ try {
+ process.kill(pid, "SIGKILL");
+ } catch {}
+ }
+ for (const profile of profiles) rmSync(dirname(profile), { recursive: true, force: true });
children.clear();
+ profiles.clear();
});
describe.skipIf(process.platform !== "linux")("managed browser shutdown", () => {
diff --git a/packages/cli/src/capture/captureCompositionFrame.prelaunch.browser.test.ts b/packages/cli/src/capture/captureCompositionFrame.prelaunch.browser.test.ts
new file mode 100644
index 0000000000..6f7c3b93c8
--- /dev/null
+++ b/packages/cli/src/capture/captureCompositionFrame.prelaunch.browser.test.ts
@@ -0,0 +1,54 @@
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { afterAll, beforeAll, expect, it } from "vitest";
+import {
+ openSettledCompositionPage,
+ prelaunchCompositionBrowser,
+} from "./captureCompositionFrame.js";
+
+const html = (width: number) =>
+ `<!doctype html><html><body><div data-composition-id="main" data-width="${width}" data-height="360" data-duration="1"></div><script>window.__renderReady = true;</script></body></html>`;
+
+let server: Server;
+let url: string;
+
+beforeAll(async () => {
+ server = createServer((_req, res) =>
+ res.writeHead(200, { "Content-Type": "text/html" }).end(html(640)),
+ );
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/`;
+});
+
+afterAll(() => {
+ server.closeAllConnections();
+ server.close();
+});
+
+it.each([
+ { guess: 640, reused: true },
+ { guess: 800, reused: false },
+])(
+ "uses a browser started early only if it got the same launch ($guess px guess)",
+ async ({ guess, reused }) => {
+ const prelaunched = prelaunchCompositionBrowser(html(guess), "software");
+ const early = (await prelaunched.launched)?.browser;
+ expect(early?.connected).toBe(true);
+ const { browser } = await openSettledCompositionPage(html(640), url, {
+ renderReadyTimeoutMs: 5_000,
+ renderReadyWarningSuffix: "test",
+ browserGpuMode: "software",
+ prelaunched,
+ });
+ try {
+ await prelaunched.discard();
+ expect(browser === early).toBe(reused);
+ expect(early?.connected).toBe(reused);
+ expect(browser.connected).toBe(true);
+ } finally {
+ await browser.close();
+ await early?.close().catch(() => undefined);
+ }
+ },
+ 90_000,
+);
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index d068007fd6..32772afa0f 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -114,6 +114,59 @@ export interface OpenSettledCompositionPageOptions {
// Runs after the page exists but before page.goto, so console/pageerror/
// request listeners can attach without missing load-time events.
beforeNavigate?: (page: Page) => void | Promise<void>;
+ // Started before the project was bundled; used only if it was launched with the same arguments.
+ prelaunched?: PrelaunchedBrowser;
+}
+
+interface LaunchedBrowser {
+ browser: Browser;
+ softwareWebGpu: boolean;
+}
+
+export interface PrelaunchedBrowser {
+ launched: Promise<LaunchedBrowser | undefined>;
+ take(key: string): Promise<LaunchedBrowser | undefined>;
+ discard(): Promise<void>;
+}
+
+type LaunchOptions = Pick<
+ OpenSettledCompositionPageOptions,
+ "browserGpuMode" | "signal" | "onBrowser"
+>;
+
+function launchKey(html: string, noListen: boolean, options: LaunchOptions): string {
+ const viewport = resolveCompositionViewportFromHtml(html);
+ const gpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
+ return JSON.stringify([viewport, compositionRequiresWebGpu(html), noListen, gpuMode]);
+}
+
+export function prelaunchCompositionBrowser(
+ html: string,
+ browserGpuMode?: BrowserGpuMode,
+): PrelaunchedBrowser {
+ const abort = new AbortController();
+ const options = { browserGpuMode, signal: abort.signal };
+ const key = launchKey(html, false, options);
+ const launched = launchCompositionBrowser(html, false, options).catch(() => undefined);
+ let taken = false;
+ const discard = async () => {
+ if (taken) return;
+ taken = true;
+ abort.abort();
+ await (await launched)?.browser.close().catch(() => undefined);
+ };
+ return {
+ launched,
+ take: async (wanted) => {
+ if (wanted !== key) return discard().then(() => undefined);
+ taken = true;
+ const result = await launched;
+ if (result?.browser.connected) return result;
+ await result?.browser.close().catch(() => undefined);
+ return undefined;
+ },
+ discard,
+ };
}
export interface FfmpegRunResult {
@@ -249,14 +302,45 @@ export async function openSettledCompositionPage(
url: string,
options: OpenSettledCompositionPageOptions,
): Promise<SettledCompositionPage> {
+ const viewport = resolveCompositionViewportFromHtml(html);
+ const requiresWebGpu = compositionRequiresWebGpu(html);
+ // Nothing may listen (a sandbox refused it): DevTools over a pipe, one process, pages answered in-process.
+ const answer = (await import("../utils/staticProjectServer.js")).inProcessAnswer(url);
+ const noListen = answer !== undefined;
+ let chromeBrowser: Browser | undefined;
+ try {
+ const launched =
+ (await options.prelaunched?.take(launchKey(html, noListen, options))) ??
+ (await launchCompositionBrowser(html, noListen, options));
+ chromeBrowser = launched.browser;
+ const softwareWebGpu = launched.softwareWebGpu;
+ options.onBrowser?.(chromeBrowser);
+ options.onBrowserReady?.();
+ const page = await chromeBrowser.newPage();
+ await installPageFunctionGuard(page);
+ await page.setViewport(viewport);
+ if (answer) await answerPageInProcess(page, url, answer);
+ await options.beforeNavigate?.(page);
+ await gotoWhenSent(page, url, pageNavigationTimeoutMs(options.navigationTimeoutMs));
+ await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
+ const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
+ return { browser: chromeBrowser, page, renderReadyTimedOut };
+ } catch (err) {
+ return rethrowAfterBrowserCleanup(chromeBrowser, err);
+ }
+}
+
+async function launchCompositionBrowser(
+ html: string,
+ noListen: boolean,
+ options: LaunchOptions,
+): Promise<LaunchedBrowser> {
const viewport = resolveCompositionViewportFromHtml(html);
const { ensureBrowser, findSystemBrowser } = await import("../browser/manager.js");
const browser = await ensureBrowser({ signal: options.signal });
const puppeteer = await import("puppeteer-core");
const { buildChromeArgs } = await import("@hyperframes/engine");
const requestedGpuMode = options.browserGpuMode ?? resolveCliChromeGpuMode();
- // Nothing may listen (a sandbox refused it): DevTools over a pipe, one process, pages answered in-process.
- const answer = (await import("../utils/staticProjectServer.js")).inProcessAnswer(url);
const requiresWebGpu = compositionRequiresWebGpu(html);
let softwareWebGpu = false;
const launch = async (executablePath: string): Promise<Browser> => {
@@ -264,7 +348,7 @@ export async function openSettledCompositionPage(
const resolvedGpuMode = await resolveManagedGpuMode(requestedGpuMode, executablePath, {
signal: options.signal,
onBrowser: options.onBrowser,
- noListen: answer !== undefined,
+ noListen,
});
options.signal?.throwIfAborted();
const webGpu = resolveLocalWebGpu(resolvedGpuMode, requiresWebGpu);
@@ -277,54 +361,37 @@ export async function openSettledCompositionPage(
headless: true,
signal: options.signal,
executablePath,
- ...(answer ? oneProcessOverPipe({ args }) : { args }),
+ ...(noListen ? oneProcessOverPipe({ args }) : { args }),
});
};
- let chromeBrowser: Browser | undefined;
+ let chromeBrowser: Browser;
try {
- try {
- chromeBrowser = await launch(browser.executablePath);
- } catch (launchError) {
- const message = normalizeErrorMessage(launchError);
- const remediation = windowsChromeCrashRemediation(message);
- if (!remediation) throw launchError;
-
- const systemBrowser =
- browser.source === "cache" || browser.source === "download"
- ? findSystemBrowser()
- : undefined;
- if (!systemBrowser || systemBrowser.executablePath === browser.executablePath) {
- throw new Error(`${message}\n\n${remediation}`, { cause: launchError });
- }
+ chromeBrowser = await launch(browser.executablePath);
+ } catch (launchError) {
+ const message = normalizeErrorMessage(launchError);
+ const remediation = windowsChromeCrashRemediation(message);
+ if (!remediation) throw launchError;
+
+ const systemBrowser =
+ browser.source === "cache" || browser.source === "download" ? findSystemBrowser() : undefined;
+ if (!systemBrowser || systemBrowser.executablePath === browser.executablePath) {
+ throw new Error(`${message}\n\n${remediation}`, { cause: launchError });
+ }
- console.warn(
- `[hyperframes] Managed chrome-headless-shell crashed at launch; retrying once with system Chrome at ${systemBrowser.executablePath}.`,
+ console.warn(
+ `[hyperframes] Managed chrome-headless-shell crashed at launch; retrying once with system Chrome at ${systemBrowser.executablePath}.`,
+ );
+ try {
+ chromeBrowser = await launch(systemBrowser.executablePath);
+ } catch (fallbackError) {
+ throw new Error(
+ `System Chrome fallback also failed: ${normalizeErrorMessage(fallbackError)}\n\n${remediation}`,
+ { cause: fallbackError },
);
- try {
- chromeBrowser = await launch(systemBrowser.executablePath);
- } catch (fallbackError) {
- throw new Error(
- `System Chrome fallback also failed: ${normalizeErrorMessage(fallbackError)}\n\n${remediation}`,
- { cause: fallbackError },
- );
- }
}
-
- options.onBrowser?.(chromeBrowser);
- options.onBrowserReady?.();
- const page = await chromeBrowser.newPage();
- await installPageFunctionGuard(page);
- await page.setViewport(viewport);
- if (answer) await answerPageInProcess(page, url, answer);
- await options.beforeNavigate?.(page);
- await gotoWhenSent(page, url, pageNavigationTimeoutMs(options.navigationTimeoutMs));
- await assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu);
- const renderReadyTimedOut = !(await waitForCompositionSettle(page, options));
- return { browser: chromeBrowser, page, renderReadyTimedOut };
- } catch (err) {
- return rethrowAfterBrowserCleanup(chromeBrowser, err);
}
+ return { browser: chromeBrowser, softwareWebGpu };
}
// Serialized into the page; the seek-target cascade must stay one function.
diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts
index 93690b13ad..30348fbc09 100644
--- a/packages/cli/src/commands/check.test.ts
+++ b/packages/cli/src/commands/check.test.ts
@@ -1208,6 +1208,28 @@ describe("check pipeline", () => {
expect(report.runtime.findings[0]?.code).toBe("check_lint_failure");
});
+ it.each([
+ { lint: cleanLint(), handed: true },
+ { lint: lintWith("error", "lint_error", "Lint error."), handed: false },
+ ])(
+ "closes the browser started during lint unless the browser pass took it",
+ async ({ lint, handed }) => {
+ const prelaunched = {
+ launched: Promise.resolve(undefined),
+ take: vi.fn(async () => undefined),
+ discard: vi.fn(async () => undefined),
+ };
+ const { deps, runBrowserCheck } = dependencies(fakeDriver(), { lint });
+ deps.prelaunchBrowser = vi.fn(async () => prelaunched);
+ await runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps);
+
+ expect(runBrowserCheck.mock.calls.map((call) => call[4])).toEqual(
+ handed ? [prelaunched] : [],
+ );
+ expect(prelaunched.discard).toHaveBeenCalledTimes(1);
+ },
+ );
+
it("marks browserSkipped false once a browser session actually runs", async () => {
const { report } = await runScenario(fakeDriver());
expect(report.browserSkipped).toBe(false);
diff --git a/packages/cli/src/commands/contrast-audit.browser.js b/packages/cli/src/commands/contrast-audit.browser.js
index fbed24163d..fb657aae4e 100644
--- a/packages/cli/src/commands/contrast-audit.browser.js
+++ b/packages/cli/src/commands/contrast-audit.browser.js
@@ -22,6 +22,143 @@ window.__contrastAuditPrepare = function () {
return !!el.ownerSVGElement;
}
+ // Raster-free contrast: a leaf text box whose backdrop is provably one opaque CSS colour needs no
+ // screenshot. Anything this cannot prove (overlays, images, blending, rotation, round corners) returns null.
+ var REPLACED = /^(IMG|VIDEO|CANVAS|IFRAME|OBJECT|EMBED|INPUT|TEXTAREA|SELECT|svg|PICTURE)$/;
+ var paintCache = new Map();
+ function blends(cs) {
+ return (
+ cs.opacity !== "1" ||
+ cs.filter !== "none" ||
+ (cs.backdropFilter || cs.webkitBackdropFilter || "none") !== "none" ||
+ cs.mixBlendMode !== "normal" ||
+ (cs.maskImage || cs.webkitMaskImage || "none") !== "none" ||
+ cs.clipPath !== "none"
+ );
+ }
+ function axisAligned(cs) {
+ var t = cs.transform;
+ if (t === "none") return true;
+ var m = t.match(/^matrix\(([^)]+)\)$/);
+ if (!m) return false;
+ var v = m[1].split(",").map(parseFloat);
+ return v[1] === 0 && v[2] === 0;
+ }
+ function pseudoPaints(el) {
+ return ["::before", "::after"].some(function (pseudo) {
+ var content = getComputedStyle(el, pseudo).content;
+ return content !== "none" && content !== "normal";
+ });
+ }
+ function hasOwnText(el) {
+ for (var n = el.firstChild; n; n = n.nextSibling) {
+ if (n.nodeType === 3 && /\S/.test(n.nodeValue || "")) return true;
+ }
+ return false;
+ }
+ function boxPaints(el, cs) {
+ var bg = parseColor(cs.backgroundColor || "");
+ return (
+ (cs.backgroundImage || "none") !== "none" ||
+ !bg ||
+ bg[3] !== 0 ||
+ ["Top", "Right", "Bottom", "Left"].some(function (side) {
+ return (
+ cs["border" + side + "Style"] !== "none" && parseFloat(cs["border" + side + "Width"]) > 0
+ );
+ }) ||
+ cs.boxShadow !== "none" ||
+ (cs.outlineStyle !== "none" && parseFloat(cs.outlineWidth) > 0) ||
+ pseudoPaints(el)
+ );
+ }
+ // True unless the element provably adds no pixels of its own.
+ function paints(el) {
+ if (paintCache.has(el)) return paintCache.get(el);
+ var cs = getComputedStyle(el);
+ var result =
+ cs.visibility === "hidden" && cs.filter === "none"
+ ? false
+ : REPLACED.test(el.tagName) ||
+ !!el.ownerSVGElement ||
+ hasOwnText(el) ||
+ boxPaints(el, cs) ||
+ blends(cs);
+ paintCache.set(el, result);
+ return result;
+ }
+ function intersects(a, b) {
+ return a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+ }
+ function solidBackdrop(el, rect, cs) {
+ if (el.children.length > 0 || el.ownerSVGElement || cs.textShadow !== "none") return null;
+ if (cs.textDecorationLine !== "none" || boxPaints(el, cs) || !axisAligned(cs)) return null;
+ if ((cs.backdropFilter || cs.webkitBackdropFilter || "none") !== "none") return null;
+ var region = {
+ left: Math.max(0, rect.left),
+ top: Math.max(0, rect.top),
+ right: Math.min(window.innerWidth, rect.right),
+ bottom: Math.min(window.innerHeight, rect.bottom),
+ };
+ if (region.right <= region.left || region.bottom <= region.top) return null;
+ var chain = new Set([el]);
+ var solid = null;
+ for (var a = el.parentElement; a; a = a.parentElement) {
+ chain.add(a);
+ var acs = getComputedStyle(a);
+ if (blends(acs) || !axisAligned(acs) || pseudoPaints(a)) return null;
+ if (a === document.body || a === document.documentElement) {
+ if (!solid) solid = canvasColor(a, acs, region);
+ if (!solid && (a === document.documentElement || boxPaints(a, acs))) return null;
+ continue;
+ }
+ if (solid) {
+ if (acs.overflow !== "visible" && !contains(a.getBoundingClientRect(), acs, region))
+ return null;
+ continue;
+ }
+ var bg =
+ (acs.backgroundImage || "none") === "none" ? parseColor(acs.backgroundColor || "") : null;
+ if (bg && bg[3] === 1) {
+ var radius = ["TopLeft", "TopRight", "BottomRight", "BottomLeft"].some(function (corner) {
+ return parseFloat(acs["border" + corner + "Radius"]) > 0;
+ });
+ if (radius || !contains(a.getBoundingClientRect(), acs, region)) return null;
+ solid = bg;
+ continue;
+ }
+ if (hasOwnText(a) || boxPaints(a, acs)) return null;
+ }
+ if (!solid) return null;
+ var all = document.querySelectorAll("*");
+ for (var i = 0; i < all.length; i++) {
+ var other = all[i];
+ if (chain.has(other) || !intersects(other.getBoundingClientRect(), region)) continue;
+ if (paints(other)) return null;
+ }
+ return [solid[0], solid[1], solid[2]];
+ }
+ // body's background paints the whole canvas unless html has its own (CSS background propagation).
+ function canvasColor(el, cs, region) {
+ var bg =
+ (cs.backgroundImage || "none") === "none" ? parseColor(cs.backgroundColor || "") : null;
+ var html = document.documentElement;
+ var htmlCs = getComputedStyle(html);
+ var htmlBg = parseColor(htmlCs.backgroundColor || "");
+ var htmlPaints = (htmlCs.backgroundImage || "none") !== "none" || !htmlBg || htmlBg[3] !== 0;
+ if (el === html) return bg && bg[3] === 1 ? bg : null;
+ if (!bg || bg[3] !== 1) return null;
+ return htmlPaints && !contains(el.getBoundingClientRect(), cs, region) ? null : bg;
+ }
+ function contains(box, cs, region) {
+ return (
+ box.left + parseFloat(cs.borderLeftWidth) <= region.left &&
+ box.top + parseFloat(cs.borderTopWidth) <= region.top &&
+ box.right - parseFloat(cs.borderRightWidth) >= region.right &&
+ box.bottom - parseFloat(cs.borderBottomWidth) >= region.bottom
+ );
+ }
+
function parseColor(c) {
var m = (c || "").match(/^rgba?\(([^)]+)\)$/i);
if (!m) {
@@ -317,6 +454,7 @@ window.__contrastAuditPrepare = function () {
fontWeight: fontWeight,
large: large,
ownBg: ownBg,
+ solidBg: ownBg ? null : solidBackdrop(el, rect, cs),
bbox: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
});
}
@@ -387,22 +525,27 @@ window.__contrastAuditFinish = async function (imgBase64, time, candidates, regi
// never want a decode failure below to leave the page's text invisible.
__contrastAuditRestoreAll();
- var img = new Image();
- await new Promise(function (resolve) {
- img.onload = resolve;
- img.onerror = function () {
- resolve();
- };
- img.src = "data:image/png;base64," + imgBase64;
- });
- if (!img.naturalWidth) return [];
- var canvas = document.createElement("canvas");
- canvas.width = img.naturalWidth || 1920;
- canvas.height = img.naturalHeight || 1080;
- var ctx = canvas.getContext("2d");
- if (!ctx) return [];
- ctx.drawImage(img, 0, 0);
- var px = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+ // No image when every candidate's background is known from styles.
+ var canvas = { width: region ? region.frameWidth : 0, height: region ? region.frameHeight : 0 };
+ var px = null;
+ if (imgBase64) {
+ var img = new Image();
+ await new Promise(function (resolve) {
+ img.onload = resolve;
+ img.onerror = function () {
+ resolve();
+ };
+ img.src = "data:image/png;base64," + imgBase64;
+ });
+ if (!img.naturalWidth) return [];
+ canvas = document.createElement("canvas");
+ canvas.width = img.naturalWidth || 1920;
+ canvas.height = img.naturalHeight || 1080;
+ var ctx = canvas.getContext("2d");
+ if (!ctx) return [];
+ ctx.drawImage(img, 0, 0);
+ px = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+ }
// A clipped shot holds `region.clip` of the frame: clamp to the frame, read at the offset.
var w = region ? region.frameWidth : canvas.width;
var h = region ? region.frameHeight : canvas.height;
@@ -429,11 +572,12 @@ window.__contrastAuditFinish = async function (imgBase64, time, candidates, regi
// sampleGridPoints.
var stepX = Math.max(1, Math.floor((x1 - x0) / 12));
var stepY = Math.max(1, Math.floor((y1 - y0) / 6));
+ var known = c.ownBg && c.ownBg.length >= 4 && c.ownBg[3] >= 0.99 ? c.ownBg : c.solidBg;
var rr = [],
gg = [],
bb = [],
aa = [];
- for (var y = y0; y <= y1; y += stepY) {
+ for (var y = y0; !known && y <= y1; y += stepY) {
for (var x = x0; x <= x1; x += stepX) {
var idx = ((y - oy) * canvas.width + (x - ox)) * 4;
rr.push(px[idx]);
@@ -442,13 +586,13 @@ window.__contrastAuditFinish = async function (imgBase64, time, candidates, regi
aa.push(px[idx + 3]);
}
}
- if (rr.length === 0) continue;
+ if (!known && rr.length === 0) continue;
var bgR, bgG, bgB;
- if (c.ownBg && c.ownBg.length >= 4 && c.ownBg[3] >= 0.99) {
- bgR = c.ownBg[0];
- bgG = c.ownBg[1];
- bgB = c.ownBg[2];
+ if (known) {
+ bgR = known[0];
+ bgG = known[1];
+ bgB = known[2];
} else {
// A transparent sampled backdrop is supplied by the downstream editor,
// not this composition. WCAG contrast cannot be inferred until that live
diff --git a/packages/cli/src/commands/contrast-solid.browser.test.ts b/packages/cli/src/commands/contrast-solid.browser.test.ts
new file mode 100644
index 0000000000..04ae5b215b
--- /dev/null
+++ b/packages/cli/src/commands/contrast-solid.browser.test.ts
@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { join } from "node:path";
+import { afterAll, beforeAll, expect, it } from "vitest";
+import { openSettledCompositionPage } from "../capture/captureCompositionFrame.js";
+
+const P = "position:absolute;margin:0;font:28px sans-serif;color:#9ab";
+const HTML = `<!doctype html><html><body style="margin:0;background:#0d1117">
+<div data-composition-id="main" data-width="800" data-height="600" data-duration="1" style="position:relative;width:800px;height:600px">
+ <p id="on-canvas" style="${P};left:20px;top:20px">On canvas</p>
+ <div style="position:absolute;left:20px;top:80px;width:300px;height:60px;background:#204060"><p id="on-panel" style="${P};left:10px;top:10px">On panel</p></div>
+ <p id="under-overlay" style="${P};left:20px;top:160px">Under overlay</p>
+ <div style="position:absolute;left:10px;top:150px;width:300px;height:60px;background:rgba(255,0,0,.4);pointer-events:none"></div>
+ <img src="data:image/gif;base64,R0lGODlhAQABAIAAAP8AAP///yH5BAAAAAAALAAAAAABAAEAAAICRAEAOw==" style="position:absolute;left:20px;top:230px;width:200px;height:40px">
+ <p id="over-image" style="${P};left:20px;top:230px">Over image</p>
+ <div style="position:absolute;left:400px;top:20px;width:300px;height:60px;background:linear-gradient(#123,#456)"><p id="on-gradient" style="${P};left:10px;top:10px">Gradient</p></div>
+ <div style="position:absolute;left:400px;top:100px;width:300px;height:60px;background:#204060;border-radius:30px"><p id="rounded" style="${P};left:10px;top:10px">Rounded</p></div>
+ <div style="position:absolute;left:400px;top:180px;width:300px;height:60px;background:#204060;opacity:.5"><p id="faded" style="${P};left:10px;top:10px">Faded</p></div>
+ <p id="shadowed" style="${P};left:400px;top:260px;text-shadow:0 0 6px #fff">Shadowed</p>
+ <div style="position:absolute;left:400px;top:340px;width:300px;height:60px;background:#204060;transform:rotate(5deg)"><p id="rotated" style="${P};left:10px;top:10px">Rotated</p></div>
+</div><script>window.__renderReady = true;</script></body></html>`;
+const SCRIPT = readFileSync(join(import.meta.dirname, "contrast-audit.browser.js"), "utf8");
+
+let server: Server;
+let url: string;
+
+beforeAll(async () => {
+ server = createServer((_req, res) =>
+ res.writeHead(200, { "Content-Type": "text/html" }).end(HTML),
+ );
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/`;
+});
+
+afterAll(() => {
+ server.closeAllConnections();
+ server.close();
+});
+
+type Candidate = { selector: string; solidBg: number[] | null };
+
+it("reads a backdrop from styles only where pixels would give the same contrast", async () => {
+ const { browser, page } = await openSettledCompositionPage(HTML, url, {
+ renderReadyTimeoutMs: 5_000,
+ renderReadyWarningSuffix: "test",
+ browserGpuMode: "software",
+ });
+ try {
+ await page.addScriptTag({ content: SCRIPT });
+ const finish = async (dropSolid: boolean) => {
+ const prepared = (await page.evaluate("window.__contrastAuditPrepare()")) as Candidate[];
+ const shot = await page.screenshot({ encoding: "base64", omitBackground: true });
+ const candidates = dropSolid ? prepared.map((c) => ({ ...c, solidBg: null })) : prepared;
+ const entries = await page.evaluate(
+ (png: string, items: unknown[]) =>
+ Reflect.apply(Reflect.get(window, "__contrastAuditFinish"), window, [
+ png,
+ 0,
+ items,
+ null,
+ ]),
+ shot,
+ candidates,
+ );
+ return { prepared, entries };
+ };
+
+ const styled = await finish(false);
+ const solid = Object.fromEntries(styled.prepared.map((c) => [c.selector, c.solidBg]));
+ expect(solid).toEqual({
+ "#on-canvas": [13, 17, 23],
+ "#on-panel": [32, 64, 96],
+ "#under-overlay": null,
+ "#over-image": null,
+ "#on-gradient": null,
+ "#rounded": null,
+ "#faded": null,
+ "#shadowed": null,
+ "#rotated": null,
+ });
+ expect(styled.entries).toEqual((await finish(true)).entries);
+ } finally {
+ await browser.close();
+ }
+}, 90_000);
diff --git a/packages/cli/src/utils/checkBrowser.test.ts b/packages/cli/src/utils/checkBrowser.test.ts
index 4bdc755fa9..2ac2369211 100644
--- a/packages/cli/src/utils/checkBrowser.test.ts
+++ b/packages/cli/src/utils/checkBrowser.test.ts
@@ -271,6 +271,42 @@ it("takes no contrast screenshot at a sample with no text to measure", async ()
expect(page.screenshot).not.toHaveBeenCalled();
});
+it("measures text on its own opaque fill without a contrast screenshot", async () => {
+ vi.spyOn(Date, "now").mockReturnValue(100);
+ mountCanvasFixture(`<div id="headline">Readable copy</div>`);
+ const headline = document.querySelector("#headline");
+ if (!headline) throw new Error("Contrast fixture failed to mount");
+ vi.spyOn(headline, "getBoundingClientRect").mockReturnValue(new DOMRect(50, 50, 300, 40));
+ vi.spyOn(window, "getComputedStyle").mockImplementation(
+ () =>
+ ({
+ display: "block",
+ visibility: "visible",
+ opacity: "1",
+ color: "rgb(255,255,255)",
+ fill: "",
+ backgroundColor: "rgb(0,0,0)",
+ backgroundImage: "none",
+ fontSize: "32px",
+ fontWeight: "700",
+ }) as unknown as CSSStyleDeclaration,
+ );
+ const page = fakePage();
+ page.screenshot = vi.fn(async () => "c3R1Yg==");
+ installSessionMock(page);
+
+ const result = await runBrowserCheck(
+ PROJECT,
+ { ...DEFAULT_CHECK_OPTIONS, samples: 1, contrast: true },
+ { kind: "none" },
+ runAuditGrid,
+ );
+
+ expect(result.contrastChecked).toBeGreaterThan(0);
+ expect(result.contrastFindings).toEqual([]);
+ expect(page.screenshot).not.toHaveBeenCalled();
+});
+
it("uses check --timeout for both navigation and render-ready settling", async () => {
mountCanvasFixture();
const page = fakePage();
diff --git a/packages/cli/src/utils/checkBrowser.ts b/packages/cli/src/utils/checkBrowser.ts
index 173c72734c..afd25868eb 100644
--- a/packages/cli/src/utils/checkBrowser.ts
+++ b/packages/cli/src/utils/checkBrowser.ts
@@ -17,6 +17,7 @@ import {
seekCompositionTimeline,
waitForPreferredSeekTarget,
seekInPage,
+ type PrelaunchedBrowser,
} from "../capture/captureCompositionFrame.js";
import {
auditClipDurations,
@@ -106,6 +107,7 @@ interface PreparedContrast {
// what it sends back. `candidate` is the parsed copy for Node-side reporting.
raw: unknown;
candidate: ContrastCandidate;
+ knownBackdrop: boolean;
anchor: CheckAnchor;
}
@@ -205,6 +207,7 @@ export async function runBrowserCheck(
motion: MotionSpecResolution,
runGrid: RunAuditGrid,
deadline?: CheckDeadline,
+ prelaunched?: PrelaunchedBrowser,
): Promise<CheckBrowserResult> {
const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");
const html = await bundleWithLocalizedFonts(project.dir);
@@ -239,6 +242,7 @@ export async function runBrowserCheck(
navigationTimeoutMs: options.timeout,
renderReadyTimeoutMs: options.timeout,
renderReadyWarningSuffix: "checking the current page state",
+ prelaunched,
browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),
signal: deadline?.signal,
onBrowser: deadline?.ownBrowser,
@@ -1108,20 +1112,13 @@ async function collectContrast(
try {
prepared = parsePreparedContrast(await prepareContrast(page, time));
if (prepared.length === 0 && !snapshotAnnotations) return { entries: [] };
- const region = textRegion(prepared, page.viewport());
// This screenshot is the one contrast math is sampled from below — it must
// stay untouched by the annotation overlay (finishContrast reads real
// painted pixels), so annotation only ever happens on a SECOND shot.
- const measurementShot = await page.screenshot({
- encoding: "base64",
- type: "png",
- omitBackground: true,
- ...(region ? { clip: region.clip, captureBeyondViewport: false } : {}),
- });
- if (typeof measurementShot !== "string") throw new Error("Contrast screenshot was not base64");
+ const { shot, region } = await measurementShot(page, prepared);
const raw = await finishContrast(
page,
- measurementShot,
+ shot,
time,
prepared.map((entry) => entry.raw),
region,
@@ -1154,6 +1151,27 @@ async function collectContrast(
}
}
+async function measurementShot(
+ page: Page,
+ prepared: PreparedContrast[],
+): Promise<{ shot: string | null; region: TextRegion | undefined }> {
+ const frame = plainFrame(page.viewport());
+ const sampled = prepared.filter((entry) => !entry.knownBackdrop);
+ if (frame && sampled.length === 0) {
+ const clip = { x: 0, y: 0, ...frame };
+ return { shot: null, region: { clip, frameWidth: frame.width, frameHeight: frame.height } };
+ }
+ const region = textRegion(sampled, frame);
+ const shot = await page.screenshot({
+ encoding: "base64",
+ type: "png",
+ omitBackground: true,
+ ...(region ? { clip: region.clip, captureBeyondViewport: false } : {}),
+ });
+ if (typeof shot !== "string") throw new Error("Contrast screenshot was not base64");
+ return { shot, region };
+}
+
function contrastFailureAnnotations(
entries: ContrastAuditEntry[],
labelOffset: number,
@@ -1299,12 +1317,18 @@ interface TextRegion {
}
// The smallest whole-pixel rect holding every box contrast samples; undefined means the full frame.
+function plainFrame(
+ viewport: { width: number; height: number; deviceScaleFactor?: number } | null,
+): { width: number; height: number } | undefined {
+ if (!viewport || (viewport.deviceScaleFactor ?? 1) !== 1) return undefined;
+ return { width: viewport.width, height: viewport.height };
+}
+
function textRegion(
prepared: PreparedContrast[],
- viewport: { width: number; height: number; deviceScaleFactor?: number } | null,
+ viewport: { width: number; height: number } | undefined,
): TextRegion | undefined {
- if (!viewport || (viewport.deviceScaleFactor ?? 1) !== 1 || prepared.length === 0)
- return undefined;
+ if (!viewport || prepared.length === 0) return undefined;
const boxes = prepared.map((entry) => entry.candidate.bbox);
const x = Math.max(0, Math.floor(Math.min(...boxes.map((box) => box.x))));
const y = Math.max(0, Math.floor(Math.min(...boxes.map((box) => box.y))));
@@ -1320,14 +1344,14 @@ function textRegion(
async function finishContrast(
page: Page,
- screenshot: string,
+ screenshot: string | null,
time: number,
candidates: unknown[],
region: TextRegion | undefined,
): Promise<unknown[]> {
return page.evaluate(
async (payload: {
- screenshot: string;
+ screenshot: string | null;
time: number;
candidates: unknown[];
region: TextRegion | null;
@@ -1352,10 +1376,19 @@ function parsePreparedContrast(raw: unknown[]): PreparedContrast[] {
const raw = Reflect.get(value, "candidate");
const candidate = parseContrastCandidate(raw);
const anchor = parseAnchor(Reflect.get(value, "anchor"));
- return candidate && anchor ? [{ raw, candidate, anchor }] : [];
+ return candidate && anchor
+ ? [{ raw, candidate, anchor, knownBackdrop: knownBackdrop(raw) }]
+ : [];
});
}
+function knownBackdrop(raw: unknown): boolean {
+ if (!isRecord(raw)) return false;
+ const own = Reflect.get(raw, "ownBg");
+ const solid = Reflect.get(raw, "solidBg");
+ return Array.isArray(solid) || (Array.isArray(own) && own.length >= 4 && own[3] >= 0.99);
+}
+
function parseContrastCandidate(value: unknown): ContrastCandidate | null {
if (!isRecord(value)) return null;
const selector = stringValue(value, "selector");
diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.ts
index 6771a7fef7..2d5efd0343 100644
--- a/packages/cli/src/utils/checkPipeline.ts
+++ b/packages/cli/src/utils/checkPipeline.ts
@@ -7,6 +7,8 @@ import {
} from "./checkSnapshotDirectory.js";
import { findingElementKey, groupSampledFindings } from "./checkFindings.js";
import { mkdirSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import type { PrelaunchedBrowser } from "../capture/captureCompositionFrame.js";
import { join, relative } from "node:path";
import { trackCheckReport, trackCommandFailure } from "../telemetry/events.js";
import { trackLintRun } from "../telemetry/lintRun.js";
@@ -1305,6 +1307,7 @@ export async function runCheckPipeline(
dependencies: CheckDependencies = DEFAULT_DEPENDENCIES,
): Promise<CheckReport> {
beginCheckSnapshots(project.dir);
+ const prelaunched = dependencies.prelaunchBrowser?.(project, options).catch(() => undefined);
try {
let lintResult: ProjectLintResult;
const lintStartedAt = Date.now();
@@ -1363,8 +1366,9 @@ export async function runCheckPipeline(
try {
let browser: CheckBrowserResult;
try {
+ const browserAhead = await prelaunched;
browser = await deadline.run(() =>
- dependencies.runBrowserCheck(project, options, motion, deadline),
+ dependencies.runBrowserCheck(project, options, motion, deadline, browserAhead),
);
} catch (error) {
browser = emptyBrowserResult();
@@ -1415,6 +1419,7 @@ export async function runCheckPipeline(
if (outcome.kind === "failed") throw outcome.error;
return outcome.report;
} finally {
+ await (await prelaunched)?.discard();
await finishCheckSnapshots(project.dir).catch(() => undefined);
}
}
@@ -1868,11 +1873,23 @@ async function runBrowserCheck(
options: CheckOptions,
motion: MotionSpecResolution,
deadline?: CheckDeadline,
+ prelaunched?: PrelaunchedBrowser,
): Promise<CheckBrowserResult> {
const module = await import("./checkBrowser.js");
// runAuditGrid is handed over as a callback so checkBrowser never imports
// this module back (no import cycle).
- return module.runBrowserCheck(project, options, motion, runAuditGrid, deadline);
+ return module.runBrowserCheck(project, options, motion, runAuditGrid, deadline, prelaunched);
+}
+
+// Chrome boots while lint, hdr and bundling run; the source index guesses the bundle's launch arguments.
+async function prelaunchBrowser(
+ project: ProjectDir,
+ options: CheckOptions,
+): Promise<PrelaunchedBrowser | undefined> {
+ const html = await readFile(project.indexPath, "utf8").catch(() => undefined);
+ if (html === undefined) return undefined;
+ const { prelaunchCompositionBrowser } = await import("../capture/captureCompositionFrame.js");
+ return prelaunchCompositionBrowser(html, options.browserGpuMode);
}
async function writeSnapshot(
@@ -1904,6 +1921,7 @@ const DEFAULT_DEPENDENCIES: CheckDependencies = {
lintProject,
resolveMotionSpec,
runBrowserCheck,
+ prelaunchBrowser,
writeSnapshot,
captureFindingCrops,
inspectHdrAutoPromotion,
diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.ts
index 99c1bbc6b9..9081da74d3 100644
--- a/packages/cli/src/utils/checkTypes.ts
+++ b/packages/cli/src/utils/checkTypes.ts
@@ -6,6 +6,7 @@ import type { MotionSpec } from "./motionSpec.js";
import type { ProjectDir } from "./project.js";
import type { BrowserGpuMode } from "../browser/gpuPolicy.js";
import type { HdrAutoPromotion } from "@hyperframes/engine";
+import type { PrelaunchedBrowser } from "../capture/captureCompositionFrame.js";
export interface CheckOptions {
samples: number;
@@ -321,7 +322,12 @@ export interface CheckDependencies {
options: CheckOptions,
motion: MotionSpecResolution,
deadline?: CheckDeadline,
+ prelaunched?: PrelaunchedBrowser,
): Promise<CheckBrowserResult>;
+ prelaunchBrowser?(
+ project: ProjectDir,
+ options: CheckOptions,
+ ): Promise<PrelaunchedBrowser | undefined>;
writeSnapshot(
projectDir: string,
index: number,