Skip to content

Commit 07d4b9c

Browse files
authored
fix(engine): redraw a small drawElement frame before failing the serial capture
The serial guard in captureFrameSurface, which segmented capture reaches, threw on any frame under the size floor. It now draws the frame once more and keeps a byte-identical redraw, as the streaming drain guard does, so a flat frame no longer fails a segmented render. Fixes #5685
1 parent 6dba67a commit 07d4b9c

2 files changed

Lines changed: 131 additions & 15 deletions

File tree

‎packages/engine/src/services/frameCapture-freshFallback.test.ts‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,13 +146,67 @@ describe("fresh screenshot fallback", () => {
146146
);
147147

148148
it("rejects a suspect tiny frame without substituting a stale screenshot", async () => {
149-
vi.mocked(captureDrawElementFrame).mockResolvedValueOnce(Buffer.alloc(100));
149+
vi.mocked(captureDrawElementFrame)
150+
.mockResolvedValueOnce(Buffer.alloc(100))
151+
.mockResolvedValueOnce(Buffer.alloc(100, 1));
150152
await expect(captureFrameToBuffer(await session(), 7, 7 / 30)).rejects.toThrow(
151153
"suspect small frame",
152154
);
155+
expect(captureDrawElementFrame).toHaveBeenCalledTimes(2);
153156
expect(pageScreenshotCapture).not.toHaveBeenCalled();
154157
});
155158

159+
// GH #5685: segmented capture reaches only this guard. A flat frame is a small JPEG that redraws
160+
// to the same bytes; the streaming drain guard keeps it, and this guard must keep it too.
161+
describe("a small frame that redraws byte-identically", () => {
162+
const flat = () => Buffer.alloc(13_000, 7);
163+
afterEach(() => vi.mocked(captureDrawElementFrame).mockReset());
164+
165+
it("is kept, and the next identical frame is kept without a redraw", async () => {
166+
vi.mocked(captureDrawElementFrame).mockImplementation(async () => flat());
167+
const s = await session();
168+
expect((await captureFrameToBuffer(s, 465, 465 / 30)).buffer.equals(flat())).toBe(true);
169+
expect(captureDrawElementFrame).toHaveBeenCalledTimes(2);
170+
expect((await captureFrameToBuffer(s, 466, 466 / 30)).buffer.equals(flat())).toBe(true);
171+
expect(captureDrawElementFrame).toHaveBeenCalledTimes(3);
172+
expect(pageScreenshotCapture).not.toHaveBeenCalled();
173+
});
174+
175+
it("lowers the floor to half its size, so a similar flat frame is not redrawn", async () => {
176+
const s = await session();
177+
vi.mocked(captureDrawElementFrame).mockImplementation(async () => flat());
178+
await captureFrameToBuffer(s, 465, 465 / 30);
179+
expect(s.deAbsFloor).toBe(6_500);
180+
vi.mocked(captureDrawElementFrame).mockClear();
181+
vi.mocked(captureDrawElementFrame).mockResolvedValueOnce(Buffer.alloc(12_000, 3));
182+
await captureFrameToBuffer(s, 466, 466 / 30);
183+
expect(captureDrawElementFrame).toHaveBeenCalledTimes(1);
184+
});
185+
186+
it("keeps a full-size redraw in place of a dropped small frame", async () => {
187+
const full = Buffer.alloc(40_000, 9);
188+
vi.mocked(captureDrawElementFrame)
189+
.mockResolvedValueOnce(Buffer.alloc(100))
190+
.mockResolvedValueOnce(full);
191+
const s = await session();
192+
expect((await captureFrameToBuffer(s, 7, 7 / 30)).buffer).toBe(full);
193+
expect(s.deAcceptedSmall).toBeUndefined();
194+
expect(s.deFrameSizes).toEqual([40_000]);
195+
});
196+
197+
it("still throws under BeginFrame control, where a redraw reads the same snapshot", async () => {
198+
vi.mocked(captureDrawElementFrame).mockImplementation(async () => flat());
199+
const s = await session();
200+
s.beginFrameTimeTicks = 1;
201+
const send = vi.fn(async () => ({}));
202+
Object.assign(s.page, {
203+
createCDPSession: async () => ({ send, on: () => {}, off: () => {} }),
204+
});
205+
await expect(captureFrameToBuffer(s, 465, 465 / 30)).rejects.toThrow("suspect small frame");
206+
expect(captureDrawElementFrame).toHaveBeenCalledTimes(1);
207+
});
208+
});
209+
156210
it("returns a normal drawElement frame unchanged", async () => {
157211
const buffer = Buffer.alloc(30_000);
158212
vi.mocked(captureDrawElementFrame).mockResolvedValueOnce(buffer);

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

Lines changed: 76 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -269,6 +269,12 @@ export interface CaptureSession {
269269
* drawElement intermittently returns an anomalously small (blank) frame with no
270270
* throw; a frame far below the running median is re-captured via screenshot. */
271271
deFrameSizes?: number[];
272+
/** Absolute floor of the serial drawElement size guard. Starts at 20000 bytes and drops to
273+
* half of a small frame that redraws byte-identically. */
274+
deAbsFloor?: number;
275+
/** The last small drawElement frame that redrew byte-identically; an equal frame is kept
276+
* without a redraw. */
277+
deAcceptedSmall?: Buffer;
272278
/** Last non-deduped encode result, reused for a static frame on the drawElement
273279
* worker-encode path (mirrors `lastFrameBuffer` on the screenshot path). Only set
274280
* when static-frame dedup is armed on the drawElement path. */
@@ -3962,6 +3968,70 @@ export function resolveSessionMotionBlur(session: CaptureSession): MotionBlurPla
39623968
return plan;
39633969
}
39643970

3971+
/**
3972+
* Size guard for a serial drawElement frame. A frame far below the rolling median may be a
3973+
* dropped paint record, which is intermittent, so the frame is drawn once more: a byte-identical
3974+
* redraw is real content (a flat or dark frame) and is kept, as the streaming drain guard in the
3975+
* producer keeps it. Segmented capture reaches only this guard, so it must judge a small frame
3976+
* the same way, or a render that passes in one pass fails when segmented (GH #5685). A redraw
3977+
* that differs and is still small throws, and the caller restarts on a fresh screenshot page.
3978+
*/
3979+
async function judgeSmallDrawElementFrame(
3980+
session: CaptureSession,
3981+
frameIndex: number,
3982+
buffer: Buffer,
3983+
redraw: () => Promise<Buffer>,
3984+
): Promise<Buffer> {
3985+
const sizes = (session.deFrameSizes ??= []);
3986+
const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
3987+
const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
3988+
const floor = Math.max(session.deAbsFloor ?? 20000, median * 0.12);
3989+
let kept = buffer;
3990+
if (buffer.length < floor && !session.deAcceptedSmall?.equals(buffer)) {
3991+
const suspect = () =>
3992+
new DrawElementCaptureError(
3993+
frameIndex,
3994+
`suspect small frame (${buffer.length}B < ${Math.round(floor)}B)`,
3995+
);
3996+
// Under BeginFrame control the page paints only on the frame already sent for this index,
3997+
// so a second draw reads the same snapshot and cannot tell a drop from real content.
3998+
if (session.beginFrameTimeTicks > 0) throw suspect();
3999+
const retry = await redraw();
4000+
if (retry.equals(buffer)) {
4001+
// Halving the floor keeps a run of similar flat frames from redrawing every frame.
4002+
session.deAbsFloor = Math.min(session.deAbsFloor ?? 20000, Math.floor(buffer.length / 2));
4003+
session.deAcceptedSmall = buffer;
4004+
} else if (retry.length < floor) {
4005+
throw suspect();
4006+
} else {
4007+
kept = retry;
4008+
}
4009+
}
4010+
if (sizes.length >= 60) sizes.shift();
4011+
sizes.push(kept.length);
4012+
return kept;
4013+
}
4014+
4015+
/** Seek to `time` again and draw the frame once more, for {@link judgeSmallDrawElementFrame}. */
4016+
async function redrawDrawElementFrame(
4017+
session: CaptureSession,
4018+
frameIndex: number,
4019+
time: number,
4020+
seekOptions?: HfSeekOptions,
4021+
heldVideoTime?: number,
4022+
): Promise<Buffer> {
4023+
const { page, options } = session;
4024+
await prepareFrameForCapture(session, frameIndex, time, seekOptions, heldVideoTime);
4025+
return captureDrawElementFrame(
4026+
page,
4027+
options.width,
4028+
options.height,
4029+
options.format ?? "jpeg",
4030+
options.quality ?? 80,
4031+
true,
4032+
);
4033+
}
4034+
39654035
/** Frame timings shared by the single-capture and accumulation paths. */
39664036
interface CapturedSurface {
39674037
buffer: Buffer;
@@ -4037,21 +4107,13 @@ async function captureFrameSurface(
40374107
);
40384108
// A tiny JPEG may be a dropped paint record. Never screenshot this page:
40394109
// its injected canvas can still hold the preceding frame's bitmap.
4040-
// Restart on a fresh screenshot page even if this was a simple valid frame.
40414110
if ((options.format ?? "jpeg") !== "png" && process.env.HF_FORCE_DRAWELEMENT !== "1") {
4042-
const sizes = (session.deFrameSizes ??= []);
4043-
const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
4044-
const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
4045-
const floor = Math.max(20000, median * 0.12);
4046-
if (screenshotBuffer.length < floor) {
4047-
throw new DrawElementCaptureError(
4048-
frameIndex,
4049-
`suspect small frame (${screenshotBuffer.length}B < ${Math.round(floor)}B)`,
4050-
);
4051-
} else {
4052-
if (sizes.length >= 60) sizes.shift();
4053-
sizes.push(screenshotBuffer.length);
4054-
}
4111+
screenshotBuffer = await judgeSmallDrawElementFrame(
4112+
session,
4113+
frameIndex,
4114+
screenshotBuffer,
4115+
() => redrawDrawElementFrame(session, frameIndex, time, seekOptions, heldVideoTime),
4116+
);
40554117
}
40564118
} catch (err) {
40574119
// Missing paint records/canvas state require a new screenshot page.

0 commit comments

Comments
 (0)