From b4fc4736d7934b1d783fe8aefc6799b1828e4e6b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A4rten=20Tropp?= <137708101+martentropp@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:52:38 +0000 Subject: [PATCH] fix(engine): a frame's pixels no longer depend on the frames drawn before it (#7181) --- docs/concepts/determinism.mdx | 5 + .../src/services/browserManager.test.ts | 20 ++++ .../engine/src/services/browserManager.ts | 8 +- .../frameIndependence.browser.test.ts | 112 ++++++++++++++++++ 4 files changed, 143 insertions(+), 2 deletions(-) create mode 100644 packages/engine/src/services/frameIndependence.browser.test.ts diff --git a/docs/concepts/determinism.mdx b/docs/concepts/determinism.mdx index a8a27c0412..c3e63841bf 100644 --- a/docs/concepts/determinism.mdx +++ b/docs/concepts/determinism.mdx @@ -61,6 +61,11 @@ write your own, it must follow the order, nothing resolves after the frame is committed, and the lifecycle stays `init` → `seekFrame` (many times) → `destroy`. +With screenshot capture, Chrome redraws each changed raster tile whole, so a frame's +pixels don't depend on what the page drew before it. The worker count, chunk boundaries +and seek order don't change them. [Motion blur](/guides/motion-blur#cost-and-limits) is +the exception. + ## Rule out your machine as a variable Fonts and Chrome versions differ between computers, so a local render can shift diff --git a/packages/engine/src/services/browserManager.test.ts b/packages/engine/src/services/browserManager.test.ts index 46a701d02c..1124477c03 100644 --- a/packages/engine/src/services/browserManager.test.ts +++ b/packages/engine/src/services/browserManager.test.ts @@ -272,6 +272,22 @@ describe("buildChromeArgs browser GPU mode", () => { ).not.toContain("--disable-gpu-compositing"); }); + // HF#7111: partial raster makes a frame's pixels depend on the frames drawn before it. + it.each(["software", "hardware"] as const)( + "disables partial raster for %s screenshot capture", + (browserGpuMode) => { + expect(buildChromeArgs({ ...base, captureMode: "screenshot" }, { browserGpuMode })).toContain( + "--disable-partial-raster", + ); + }, + ); + + it("leaves partial raster alone under BeginFrame control", () => { + expect(buildChromeArgs({ ...base, captureMode: "beginframe" })).not.toContain( + "--disable-partial-raster", + ); + }); + it("uses Metal-backed ANGLE for hardware browser GPU mode on macOS", () => { const args = buildChromeArgs({ ...base, platform: "darwin" }, { browserGpuMode: "hardware" }); expect(args).toContain("--enable-unsafe-webgpu"); @@ -1856,5 +1872,9 @@ describe.runIf(process.platform === "linux")("BeginFrame launch on a slow first expect(result.captureMode).toBe("screenshot"); expect(launch).toHaveBeenCalledTimes(3); + // HF#7111: this browser captures by screenshot, though its args were built for BeginFrame. + const fallbackArgs = launch.mock.lastCall?.[0]?.args; + expect(fallbackArgs).toContain("--disable-partial-raster"); + expect(fallbackArgs).not.toContain("--enable-begin-frame-control"); }); }); diff --git a/packages/engine/src/services/browserManager.ts b/packages/engine/src/services/browserManager.ts index 3ee7dd2d12..783dd981aa 100644 --- a/packages/engine/src/services/browserManager.ts +++ b/packages/engine/src/services/browserManager.ts @@ -341,10 +341,12 @@ const BEGINFRAME_ONLY_FLAGS = new Set([ "--enable-surface-synchronization", ]); -function stripBeginFrameFlags(args: string[]): string[] { +function stripBeginFrameFlags(args: readonly string[]): string[] { return args.filter((a) => !BEGINFRAME_ONLY_FLAGS.has(a)); } +const WHOLE_TILE_RASTER_FLAG = "--disable-partial-raster"; + /** * Probe the complete HeadlessExperimental.beginFrame runtime contract. * @@ -979,7 +981,7 @@ async function launchBrowser( `${result.detail}; falling back to screenshot mode.`, ); captureMode = "screenshot"; - browser = await launch(stripBeginFrameFlags([...fingerprint.args])); + browser = await launch([...stripBeginFrameFlags(fingerprint.args), WHOLE_TILE_RASTER_FLAG]); } } @@ -1234,6 +1236,8 @@ export function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuCon "--disable-image-animation-resync", "--enable-surface-synchronization", ); + } else { + chromeArgs.push(WHOLE_TILE_RASTER_FLAG); } if (gpuDisabled) { diff --git a/packages/engine/src/services/frameIndependence.browser.test.ts b/packages/engine/src/services/frameIndependence.browser.test.ts new file mode 100644 index 0000000000..12daa14418 --- /dev/null +++ b/packages/engine/src/services/frameIndependence.browser.test.ts @@ -0,0 +1,112 @@ +import { spawnSync } from "node:child_process"; +import puppeteer, { type Browser, type Page } from "puppeteer-core"; +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import { decodePng } from "../utils/alphaBlit.js"; +import { buildChromeArgs, resolveHeadlessShellPath } from "./browserManager.js"; +import { closeTestChrome } from "./__fixtures__/loopback.js"; +import { pageScreenshotCapture } from "./screenshotService.js"; + +const chromePath = resolveHeadlessShellPath(); +const hasBrowser = chromePath !== undefined && spawnSync(chromePath, ["--version"]).status === 0; + +const WIDTH = 640; +const HEIGHT = 360; +const FRAMES = 60; +const FPS = 30; +const CAPTURE = { width: WIDTH, height: HEIGHT, fps: { num: FPS, den: 1 }, format: "png" } as const; + +// Why screenshot browsers launch with --disable-partial-raster. Partial raster redraws only the +// invalidated part of a tile over its previous contents, and antialiased edges inside that region +// come out slightly different from a whole raster. A frame's pixels then depend on which frames the +// page drew first, so 1 and 3 workers disagree from the second worker's first frame onward, as do +// repeated and backward seeks. A whole tile redraw is a function of the content alone. +// +// HF#7111's scene: rotated boxes beside text whose opacity changes every frame. +const SCENE = ` +
+

${"j".repeat(60)}

+

AAAA

+
`; + +async function captureAt(page: Page, frame: number): Promise { + await page.evaluate((time: number) => { + document.querySelectorAll("span").forEach((span, i) => { + const progress = (time - 0.2 - i * 0.02) / 0.05; + span.style.opacity = String(Math.min(1, Math.max(0, progress))); + }); + }, frame / FPS); + const png = await pageScreenshotCapture(page, CAPTURE); + return Buffer.from(decodePng(png).data); +} + +/** The frames that differ from the same frame drawn on a page with no history. */ +async function framesDifferingFromFresh( + browser: Browser, + shots: ReadonlyMap, +): Promise { + const differing: number[] = []; + for (const [frame, pixels] of shots) { + const page = await browser.newPage(); + await page.setViewport({ width: WIDTH, height: HEIGHT }); + await page.setContent(SCENE); + const fresh = await captureAt(page, frame); + await page.close(); + if (!fresh.equals(pixels)) differing.push(frame); + } + return differing; +} + +// The GPU modes a test machine can launch: Metal exists on every macOS runner, and SwiftShader +// exists everywhere. +const gpuModes = + process.platform === "darwin" ? (["hardware", "software"] as const) : (["software"] as const); + +describe.skipIf(!hasBrowser).each(gpuModes)( + "frame independence on %s screenshot capture", + (mode) => { + let browser: Browser | undefined; + + beforeAll(async () => { + browser = await puppeteer.launch({ + executablePath: chromePath, + headless: true, + args: buildChromeArgs( + { width: WIDTH, height: HEIGHT, captureMode: "screenshot" }, + { browserGpuMode: mode }, + ), + }); + }); + + afterAll(async () => { + await closeTestChrome(browser); + }); + + async function drawnInOrder(order: readonly number[]): Promise> { + if (!browser) throw new Error("browser not launched"); + const page = await browser.newPage(); + await page.setViewport({ width: WIDTH, height: HEIGHT }); + await page.setContent(SCENE); + const shots = new Map(); + for (const frame of order) shots.set(frame, await captureAt(page, frame)); + await page.close(); + return shots; + } + + it("draws each frame of a forward run the same as on a page with no history", async () => { + const order = Array.from({ length: FRAMES }, (_, frame) => frame); + const shots = await drawnInOrder(order); + expect(await framesDifferingFromFresh(browser as Browser, shots)).toEqual([]); + }, 120_000); + + it("draws a frame reached backward the same as on a page with no history", async () => { + const order = Array.from({ length: FRAMES }, (_, i) => FRAMES - 1 - i); + const shots = await drawnInOrder(order); + expect(await framesDifferingFromFresh(browser as Browser, shots)).toEqual([]); + }, 120_000); + }, +);