Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.mjsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.jsindex 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, regiaa.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 livediff --git a/packages/cli/src/commands/contrast-solid.browser.test.ts b/packages/cli/src/commands/contrast-solid.browser.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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,