Skip to content

Commit 3bb0a9a

Browse files
perf(engine): skip the screenshot on frames the page reports unchanged in beginframe capture (#7027)
* perf(engine): skip the screenshot on frames the page reports unchanged in beginframe capture * fix(engine): beginframe reuse never returns a frame older than a cross-frame page change * fix(engine): the BeginFrame reuse test gets a headless shell in the flake gate * fix(ci): run the headless shell installer through its package * fix(ci): install the headless shell with bunx, npx finds no bin in the workspace
1 parent 472b750 commit 3bb0a9a

5 files changed

Lines changed: 139 additions & 6 deletions

File tree

‎.github/actions/setup-test-workspace/action.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,16 @@ inputs:
77
engine:
88
description: Build @hyperframes/engine.
99
default: "false"
10+
headless-shell:
11+
description: Install chrome-headless-shell (path in the headless-shell-path output), the only build with BeginFrame.
12+
default: "false"
1013
outputs:
1114
chrome-path:
1215
description: Path of the installed Chrome, when `chrome` is true.
1316
value: ${{ steps.chrome.outputs.chrome-path }}
17+
headless-shell-path:
18+
description: Path of chrome-headless-shell, when `headless-shell` is true.
19+
value: ${{ steps.shell.outputs.path }}
1420
runs:
1521
using: composite
1622
steps:
@@ -27,6 +33,13 @@ runs:
2733
chrome-version: stable
2834
- shell: bash
2935
run: bash scripts/ci/install-workspace-dependencies.sh
36+
- id: shell
37+
if: inputs.headless-shell == 'true'
38+
shell: bash
39+
run: |
40+
dir="$RUNNER_TEMP/headless-shell"
41+
bunx @puppeteer/[email protected] install chrome-headless-shell@stable --path "$dir"
42+
echo "path=$(find "$dir" -type f -name chrome-headless-shell | head -n 1)" >> "$GITHUB_OUTPUT"
3043
- shell: bash
3144
run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
3245
- shell: bash

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -641,9 +641,11 @@ jobs:
641641
with:
642642
chrome: "true"
643643
engine: "true"
644+
headless-shell: "true"
644645
- if: steps.plan.outputs.any == 'true'
645646
env:
646647
HYPERFRAMES_BROWSER_PATH: ${{ steps.workspace.outputs.chrome-path }}
648+
HF_BEGINFRAME_SHELL: ${{ steps.workspace.outputs.headless-shell-path }}
647649
run: node scripts/ci/flake-gate.mjs --base "${{ steps.plan.outputs.base }}"
648650

649651
test:
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import { spawnSync } from "node:child_process";
2+
import { basename } from "node:path";
3+
import puppeteer, { type Browser } from "puppeteer-core";
4+
import { afterAll, beforeAll, describe, expect, it } from "vitest";
5+
import { resolveHeadlessShellPath } from "./browserManager.js";
6+
import { beginFrameCapture, forgetBeginFrameCapture } from "./screenshotService.js";
7+
import { closeTestChrome } from "./__fixtures__/loopback.js";
8+
9+
const resolved = resolveHeadlessShellPath();
10+
const chromePath =
11+
process.env.HF_BEGINFRAME_SHELL ??
12+
(resolved && basename(resolved).startsWith("chrome-headless-shell") ? resolved : undefined);
13+
const hasBrowser = chromePath !== undefined && spawnSync(chromePath, ["--version"]).status === 0;
14+
const INTERVAL = 1000 / 30;
15+
const options = { width: 160, height: 90, fps: { num: 30, den: 1 }, format: "jpeg" as const };
16+
17+
describe.skipIf(!hasBrowser)("beginFrameCapture reuse", () => {
18+
let browser: Browser;
19+
beforeAll(async () => {
20+
browser = await puppeteer.launch({
21+
executablePath: chromePath,
22+
headless: true,
23+
args: [
24+
"--no-sandbox",
25+
"--disable-dev-shm-usage",
26+
"--deterministic-mode",
27+
"--enable-begin-frame-control",
28+
"--disable-new-content-rendering-timeout",
29+
"--run-all-compositor-stages-before-draw",
30+
],
31+
});
32+
}, 30_000);
33+
afterAll(() => closeTestChrome(browser));
34+
35+
it("reuses a frame only when the page reports no change, never a stale one", async () => {
36+
const page = await browser.newPage();
37+
await page.setViewport({ width: 160, height: 90 });
38+
await page.setContent(
39+
`<body style="margin:0"><div id="b" style="width:160px;height:90px;background:#f00"></div></body>`,
40+
);
41+
const grab = (tick: number) => beginFrameCapture(page, options, tick * INTERVAL, INTERVAL);
42+
const paint = (color: string) =>
43+
page.evaluate(
44+
(c) => ((document.getElementById("b") as HTMLElement).style.background = c),
45+
color,
46+
);
47+
48+
// The first ticks after load may still report paint settling; reuse starts once it ends.
49+
let tick = 1;
50+
let last = await grab(tick);
51+
expect(last.hasDamage).toBe(true);
52+
let held = await grab(++tick);
53+
while (held.hasDamage && tick < 8) {
54+
last = held;
55+
held = await grab(++tick);
56+
}
57+
expect(held.hasDamage).toBe(false);
58+
expect(held.buffer.equals(last.buffer)).toBe(true);
59+
const first = held;
60+
61+
await paint("#00f");
62+
const changed = await grab(++tick);
63+
expect(changed.hasDamage).toBe(true);
64+
expect(changed.buffer.equals(first.buffer)).toBe(false);
65+
await page.close();
66+
}, 30_000);
67+
68+
it("never returns a frame older than a change the page commits across frames", async () => {
69+
const page = await browser.newPage();
70+
await page.setViewport({ width: 160, height: 90 });
71+
await page.setContent(
72+
`<body style="margin:0"><div id="b" style="width:160px;height:90px;background:#f00"></div></body>`,
73+
);
74+
const grab = (tick: number) => beginFrameCapture(page, options, tick * INTERVAL, INTERVAL);
75+
let tick = 1;
76+
for (let settled = 0; settled < 3 && tick < 12; tick++) {
77+
settled = (await grab(tick)).hasDamage ? 0 : settled + 1;
78+
}
79+
// Each rAF callback runs in a later frame than the one before it.
80+
await page.evaluate(() => {
81+
const paint = (c: string) =>
82+
((document.getElementById("b") as HTMLElement).style.background = c);
83+
requestAnimationFrame(() => {
84+
paint("#0f0");
85+
requestAnimationFrame(() => {
86+
paint("#00f");
87+
requestAnimationFrame(() => paint("#ff0"));
88+
});
89+
});
90+
});
91+
const frames = [await grab(tick++), await grab(tick++), await grab(tick++), await grab(tick++)];
92+
forgetBeginFrameCapture(page);
93+
const fresh = await grab(tick);
94+
expect(frames.at(-1)?.buffer.equals(fresh.buffer)).toBe(true);
95+
await page.close();
96+
}, 30_000);
97+
});

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ import {
7171
} from "./browserManager.js";
7272
import {
7373
beginFrameCapture,
74+
forgetBeginFrameCapture,
7475
ensureRenderFrameSiblings,
7576
getCdpSession,
7677
pageContentExceedsCaptureHeight,
@@ -4504,6 +4505,7 @@ async function captureFrameSurface(
45044505
interval: session.beginFrameIntervalMs,
45054506
noDisplayUpdates: false,
45064507
});
4508+
forgetBeginFrameCapture(page);
45074509
session.beginFrameSeekPresented = true;
45084510
}
45094511
const result = await beginFrameCapture(

‎packages/engine/src/services/screenshotService.ts‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -108,12 +108,16 @@ export async function probeBeginFrameLiveness(
108108
* Requires chrome-headless-shell with --enable-begin-frame-control and
109109
* --deterministic-mode flags.
110110
*/
111-
// Cache the last valid screenshot buffer per page for hasDamage=false frames.
112-
// When Chrome reports no visual change, we reuse the previous frame rather than
113-
// attempting Page.captureScreenshot (which times out in beginFrame mode since
114-
// the compositor is paused).
111+
// The last buffer beginFrameCapture returned per page. A screenshot BeginFrame always
112+
// reports damage, so a frame is reused only when a screenshot-less BeginFrame right after
113+
// the seek reports none. Any BeginFrame sent elsewhere moves the display past this buffer:
114+
// call forgetBeginFrameCapture first.
115115
const lastFrameCache = new WeakMap<Page, Buffer>();
116116

117+
export function forgetBeginFrameCapture(page: Page): void {
118+
lastFrameCache.delete(page);
119+
}
120+
117121
const PENDING_FRAME_RETRIES = 5;
118122

119123
async function sendBeginFrame(
@@ -156,14 +160,29 @@ export async function beginFrameCapture(
156160
optimizeForSpeed: true,
157161
} as const;
158162

159-
const result = await sendBeginFrame(client, { frameTimeTicks, interval, screenshot });
163+
// With a cached buffer, a screenshot-less BeginFrame first draws the seek and reports
164+
// whether it changed anything. The screenshot after it is not displayed: a displayed
165+
// screenshot frame leaves damage the next probe would report, and a settle frame to
166+
// absorb it would draw page changes that nothing captures.
167+
const cached = lastFrameCache.get(page);
168+
let screenshotTicks = frameTimeTicks;
169+
if (cached) {
170+
const probe = await sendBeginFrame(client, { frameTimeTicks, interval });
171+
if (!probe.hasDamage) return { buffer: cached, hasDamage: false };
172+
screenshotTicks = frameTimeTicks + interval / 2;
173+
}
174+
const result = await sendBeginFrame(client, {
175+
frameTimeTicks: screenshotTicks,
176+
interval,
177+
screenshot,
178+
noDisplayUpdates: cached !== undefined,
179+
});
160180

161181
let buffer: Buffer;
162182
if (result.screenshotData) {
163183
buffer = Buffer.from(result.screenshotData, "base64");
164184
lastFrameCache.set(page, buffer);
165185
} else {
166-
const cached = lastFrameCache.get(page);
167186
if (cached) {
168187
buffer = cached;
169188
} else {

0 commit comments

Comments
 (0)