Skip to content

Commit 1048a24

Browse files
xuanrulicursoragent
andcommitted
fix(capture): enforce stage budgets and surface evaluate degradation
Bound each scroll/content evaluate with remaining stage time so a wedged page.evaluate cannot outlive the advertised 15s/8s budgets, skip recovery CDP calls after expiry, and return/propagate timed-out animation and screenshot work so caller warnings are reachable. Co-authored-by: Cursor <[email protected]>
1 parent 55de4af commit 1048a24

10 files changed

Lines changed: 308 additions & 123 deletions
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { describe, expect, it, vi } from "vitest";
2+
import { collectAnimationCatalog } from "./animationCataloger.js";
3+
4+
describe("collectAnimationCatalog degradation", () => {
5+
it("surfaces evaluate timeouts via timedOut instead of silent empty success", async () => {
6+
const page = {
7+
evaluate: vi.fn(() => new Promise(() => undefined)),
8+
};
9+
const cdp = {
10+
send: vi.fn(async () => undefined),
11+
};
12+
13+
const outcome = await collectAnimationCatalog(page as never, [], cdp as never, {
14+
scrollBudgetMs: 20,
15+
evaluateBudgetMs: 20,
16+
});
17+
18+
expect(outcome.timedOut).toBe(true);
19+
expect(outcome.catalog.summary.webAnimations).toBe(0);
20+
expect(cdp.send).toHaveBeenCalledWith("Animation.disable");
21+
});
22+
});

‎packages/cli/src/capture/animationCataloger.ts‎

Lines changed: 32 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
*/
1717

1818
import type { Page, CDPSession } from "puppeteer-core";
19-
import { isProtocolEvaluateTimeoutError } from "./captureTimeout.js";
19+
import { isDegradableEvaluateTimeoutError, withRemainingBudget } from "./captureTimeout.js";
2020
import { lazyScrollForCapture } from "./lazyScrollForCapture.js";
2121

2222
export interface AnimationCatalog {
@@ -136,18 +136,26 @@ const EMPTY_ANIMATION_SCAN = {
136136
canvasCount: 0,
137137
};
138138

139+
export interface CollectAnimationCatalogOutcome {
140+
catalog: AnimationCatalog;
141+
timedOut: boolean;
142+
}
143+
139144
export async function collectAnimationCatalog(
140145
page: Page,
141146
cdpAnimations: CdpAnimationEntry[],
142147
cdp: CDPSession,
143-
opts: { scrollBudgetMs?: number } = {},
144-
): Promise<AnimationCatalog> {
148+
opts: { scrollBudgetMs?: number; evaluateBudgetMs?: number } = {},
149+
): Promise<CollectAnimationCatalogOutcome> {
145150
const scrollBudgetMs = opts.scrollBudgetMs ?? 8_000;
146-
await lazyScrollForCapture(page, scrollBudgetMs);
151+
const evaluateBudgetMs = opts.evaluateBudgetMs ?? 15_000;
152+
const scroll = await lazyScrollForCapture(page, scrollBudgetMs);
153+
let timedOut = scroll.degraded || scroll.timedOut;
147154

148155
let result = EMPTY_ANIMATION_SCAN;
149156
try {
150-
result = (await page.evaluate(`(() => {
157+
result = (await withRemainingBudget(
158+
page.evaluate(`(() => {
151159
var webAnimations = [];
152160
var cssDeclarations = [];
153161
@@ -206,11 +214,15 @@ export async function collectAnimationCatalog(
206214
var canvasCount = document.querySelectorAll('canvas').length;
207215
208216
return { webAnimations: webAnimations, cssDeclarations: cssDeclarations, scrollTargets: scrollTargets, canvasCount: canvasCount };
209-
})()`)) as typeof EMPTY_ANIMATION_SCAN;
217+
})()`),
218+
evaluateBudgetMs,
219+
"animation-catalog",
220+
)) as typeof EMPTY_ANIMATION_SCAN;
210221
} catch (err) {
211-
if (!isProtocolEvaluateTimeoutError(err)) {
222+
if (!isDegradableEvaluateTimeoutError(err)) {
212223
throw err;
213224
}
225+
timedOut = true;
214226
}
215227

216228
try {
@@ -220,16 +232,19 @@ export async function collectAnimationCatalog(
220232
}
221233

222234
return {
223-
webAnimations: result.webAnimations,
224-
cssDeclarations: result.cssDeclarations,
225-
scrollTargets: result.scrollTargets,
226-
cdpAnimations,
227-
summary: {
228-
webAnimations: result.webAnimations.length,
229-
cssDeclarations: result.cssDeclarations.length,
230-
scrollTargets: result.scrollTargets.length,
231-
cdpAnimations: cdpAnimations.length,
232-
canvases: result.canvasCount,
235+
catalog: {
236+
webAnimations: result.webAnimations,
237+
cssDeclarations: result.cssDeclarations,
238+
scrollTargets: result.scrollTargets,
239+
cdpAnimations,
240+
summary: {
241+
webAnimations: result.webAnimations.length,
242+
cssDeclarations: result.cssDeclarations.length,
243+
scrollTargets: result.scrollTargets.length,
244+
cdpAnimations: cdpAnimations.length,
245+
canvases: result.canvasCount,
246+
},
233247
},
248+
timedOut,
234249
};
235250
}

‎packages/cli/src/capture/captureTimeout.test.ts‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
import { describe, expect, it } from "vitest";
2+
import { TimeoutError } from "puppeteer-core";
23
import {
4+
PUPPETEER_DEFAULT_PROTOCOL_TIMEOUT_MS,
5+
StageBudgetTimeoutError,
36
captureProtocolTimeoutMs,
47
formatCaptureFailureReason,
8+
isNavigationTimeoutError,
59
isProtocolEvaluateTimeoutError,
10+
withRemainingBudget,
611
} from "./captureTimeout.js";
712

813
describe("captureProtocolTimeoutMs", () => {
@@ -14,13 +19,19 @@ describe("captureProtocolTimeoutMs", () => {
1419
it("floors at 60s", () => {
1520
expect(captureProtocolTimeoutMs(5_000, 5_000)).toBe(60_000);
1621
});
22+
23+
it("uses puppeteer default when inputs are non-finite", () => {
24+
expect(captureProtocolTimeoutMs(Number.POSITIVE_INFINITY, 120_000)).toBe(
25+
PUPPETEER_DEFAULT_PROTOCOL_TIMEOUT_MS,
26+
);
27+
});
1728
});
1829

1930
describe("isProtocolEvaluateTimeoutError", () => {
20-
it("matches Puppeteer evaluate protocol timeouts", () => {
31+
it("matches Puppeteer TimeoutError evaluate timeouts", () => {
2132
expect(
2233
isProtocolEvaluateTimeoutError(
23-
new Error(
34+
new TimeoutError(
2435
"Runtime.evaluate timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.",
2536
),
2637
),
@@ -31,6 +42,30 @@ describe("isProtocolEvaluateTimeoutError", () => {
3142
expect(
3243
isProtocolEvaluateTimeoutError(new Error("Navigation timeout of 30000 ms exceeded")),
3344
).toBe(false);
45+
expect(isNavigationTimeoutError(new Error("Navigation timeout of 30000 ms exceeded"))).toBe(
46+
true,
47+
);
48+
});
49+
});
50+
51+
describe("withRemainingBudget", () => {
52+
it("returns before a never-resolving promise when the budget elapses", async () => {
53+
const never = new Promise<string>(() => undefined);
54+
const started = Date.now();
55+
await expect(withRemainingBudget(never, 20, "never-resolve")).rejects.toBeInstanceOf(
56+
StageBudgetTimeoutError,
57+
);
58+
expect(Date.now() - started).toBeLessThan(200);
59+
});
60+
61+
it("resolves when work finishes inside the budget", async () => {
62+
await expect(withRemainingBudget(Promise.resolve("ok"), 100, "fast")).resolves.toBe("ok");
63+
});
64+
65+
it("fails immediately when no budget remains", async () => {
66+
await expect(withRemainingBudget(Promise.resolve("ok"), 0, "empty")).rejects.toBeInstanceOf(
67+
StageBudgetTimeoutError,
68+
);
3469
});
3570
});
3671

@@ -41,18 +76,11 @@ describe("formatCaptureFailureReason", () => {
4176
);
4277
expect(reason).toMatch(/extraction timed out/i);
4378
expect(reason).not.toMatch(/navigation timed out/i);
44-
expect(reason).not.toMatch(/blocking headless/i);
4579
});
4680

4781
it("keeps navigation timeout wording for nav failures", () => {
4882
expect(formatCaptureFailureReason("Navigation timeout of 30000 ms exceeded")).toMatch(
4983
/navigation timed out/i,
5084
);
5185
});
52-
53-
it("passes through non-timeout failures", () => {
54-
expect(formatCaptureFailureReason("Website capture blocked: HTTP 403")).toBe(
55-
"Capture failed: Website capture blocked: HTTP 403",
56-
);
57-
});
5886
});

‎packages/cli/src/capture/captureTimeout.ts‎

Lines changed: 63 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,82 @@
1+
import { TimeoutError } from "puppeteer-core";
2+
3+
export const PUPPETEER_DEFAULT_PROTOCOL_TIMEOUT_MS = 180_000;
4+
5+
export class StageBudgetTimeoutError extends Error {
6+
readonly budgetMs: number;
7+
8+
constructor(label: string, budgetMs: number) {
9+
super(`stage budget exceeded while ${label} (${budgetMs}ms)`);
10+
this.name = "StageBudgetTimeoutError";
11+
this.budgetMs = budgetMs;
12+
}
13+
}
14+
115
export function captureProtocolTimeoutMs(navTimeoutMs: number, postNavBudgetMs: number): number {
2-
const nav = Number.isFinite(navTimeoutMs) ? Math.max(0, navTimeoutMs) : 0;
3-
const budget = Number.isFinite(postNavBudgetMs) ? Math.max(0, postNavBudgetMs) : 0;
4-
return Math.max(60_000, nav, budget);
16+
if (!Number.isFinite(navTimeoutMs) || !Number.isFinite(postNavBudgetMs)) {
17+
return PUPPETEER_DEFAULT_PROTOCOL_TIMEOUT_MS;
18+
}
19+
return Math.max(60_000, Math.max(0, navTimeoutMs), Math.max(0, postNavBudgetMs));
20+
}
21+
22+
export function isNavigationTimeoutError(err: unknown): boolean {
23+
const msg = err instanceof Error ? err.message : String(err);
24+
return /navigation timeout/i.test(msg);
25+
}
26+
27+
function isStageBudgetTimeoutError(err: unknown): boolean {
28+
return err instanceof StageBudgetTimeoutError;
529
}
630

731
export function isProtocolEvaluateTimeoutError(err: unknown): boolean {
32+
if (isNavigationTimeoutError(err)) {
33+
return false;
34+
}
835
const msg = err instanceof Error ? err.message : String(err);
36+
if (err instanceof TimeoutError) {
37+
return /Runtime\.evaluate timed out|protocolTimeout|protocol timeout/i.test(msg);
38+
}
939
return /Runtime\.evaluate timed out|protocolTimeout|protocol timeout/i.test(msg);
1040
}
1141

12-
function isNavigationTimeoutErrorMessage(errMsg: string): boolean {
13-
return /navigation timeout/i.test(errMsg);
42+
export function isDegradableEvaluateTimeoutError(err: unknown): boolean {
43+
return isStageBudgetTimeoutError(err) || isProtocolEvaluateTimeoutError(err);
44+
}
45+
46+
export async function withRemainingBudget<T>(
47+
work: Promise<T>,
48+
remainingMs: number,
49+
label: string,
50+
): Promise<T> {
51+
if (!(remainingMs > 0)) {
52+
throw new StageBudgetTimeoutError(label, Math.max(0, remainingMs));
53+
}
54+
55+
let timer: ReturnType<typeof setTimeout> | undefined;
56+
try {
57+
return await Promise.race([
58+
work,
59+
new Promise<never>((_resolve, reject) => {
60+
timer = setTimeout(() => {
61+
reject(new StageBudgetTimeoutError(label, remainingMs));
62+
}, remainingMs);
63+
}),
64+
]);
65+
} finally {
66+
if (timer !== undefined) {
67+
clearTimeout(timer);
68+
}
69+
}
1470
}
1571

1672
export function formatCaptureFailureReason(errMsg: string): string {
17-
if (isProtocolEvaluateTimeoutError(errMsg)) {
73+
if (isProtocolEvaluateTimeoutError(errMsg) || /stage budget exceeded/i.test(errMsg)) {
1874
return (
1975
`Page extraction timed out while running in-page script (${errMsg}). ` +
2076
"The page likely opened, but a later capture step hung."
2177
);
2278
}
23-
if (isNavigationTimeoutErrorMessage(errMsg)) {
79+
if (isNavigationTimeoutError(errMsg)) {
2480
return "Page navigation timed out — the site may be blocking headless browsers or requires authentication.";
2581
}
2682
if (/timeout|timed out/i.test(errMsg)) {

‎packages/cli/src/capture/index.ts‎

Lines changed: 41 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,11 @@ import type { VisionCaptionOutcome } from "./contentExtractor.js";
4343
import { loadEnvFile, generateProjectScaffold } from "./scaffolding.js";
4444
import { detectBlockedPage } from "./pageBlockDetection.js";
4545
import { navigateForCapture } from "./navigateForCapture.js";
46-
import { captureProtocolTimeoutMs, isProtocolEvaluateTimeoutError } from "./captureTimeout.js";
46+
import {
47+
captureProtocolTimeoutMs,
48+
isDegradableEvaluateTimeoutError,
49+
withRemainingBudget,
50+
} from "./captureTimeout.js";
4751
import { lazyScrollForCapture } from "./lazyScrollForCapture.js";
4852
import type { CaptureOptions, CapturePhase, CapturePhaseProgress, CaptureResult } from "./types.js";
4953

@@ -269,43 +273,42 @@ export async function captureWebsite(
269273
};
270274
let contentCheckTimedOut = false;
271275
try {
272-
pageContentCheck = (await page1.evaluate(`(() => {
276+
pageContentCheck = (await withRemainingBudget(
277+
page1.evaluate(`(() => {
278+
var text = (document.body && document.body.innerText || "").trim();
273279
var title = document.title || "";
274-
var body = document.body;
275-
var bodyChildCount = body ? body.children.length : 0;
276-
var text = "";
277-
if (body) {
278-
var walk = document.createTreeWalker(body, NodeFilter.SHOW_TEXT, null);
279-
var node;
280-
var guard = 0;
281-
while ((node = walk.nextNode()) && text.length < 800 && guard < 300) {
282-
guard++;
283-
text += node.nodeValue || "";
284-
}
285-
}
286280
var hasCfTurnstile = !!document.querySelector('.cf-turnstile, [data-sitekey], iframe[src*="challenges.cloudflare.com"], #challenge-running, #challenge-form');
287-
return { textLength: text.trim().length, title: title, hasChallengeElement: hasCfTurnstile, bodyChildCount: bodyChildCount };
288-
})()`)) as typeof pageContentCheck;
281+
var bodyChildCount = document.body ? document.body.children.length : 0;
282+
return { textLength: text.length, title: title, hasChallengeElement: hasCfTurnstile, bodyChildCount: bodyChildCount };
283+
})()`),
284+
Math.min(5_000, remainingMs()),
285+
"content-check",
286+
)) as typeof pageContentCheck;
289287
} catch (err) {
290-
if (!isProtocolEvaluateTimeoutError(err)) {
288+
if (!isDegradableEvaluateTimeoutError(err)) {
291289
throw err;
292290
}
293291
contentCheckTimedOut = true;
294292
const message =
295-
"post-navigation content check timed out; skipping blocked-page detection and continuing";
293+
"post-navigation content check timed out; continuing with HTTP-status blocked-page detection only";
296294
warnings.push(message);
297295
progress("warn", message);
298296
}
299297

300-
if (!contentCheckTimedOut) {
301-
const blockedReason = detectBlockedPage({
302-
httpStatus: navigationResponse?.status() ?? null,
303-
...pageContentCheck,
304-
});
305-
if (blockedReason) {
306-
phase("navigation", "degraded", "blocked");
307-
throw new Error(blockedReason);
308-
}
298+
const blockedReason = detectBlockedPage({
299+
httpStatus: navigationResponse?.status() ?? null,
300+
...(contentCheckTimedOut
301+
? {
302+
title: "",
303+
textLength: 0,
304+
bodyChildCount: 0,
305+
hasChallengeElement: false,
306+
}
307+
: pageContentCheck),
308+
});
309+
if (blockedReason) {
310+
phase("navigation", "degraded", "blocked");
311+
throw new Error(blockedReason);
309312
}
310313

311314
phase("navigation", "completed");
@@ -440,11 +443,19 @@ export async function captureWebsite(
440443

441444
progress("animations", "Cataloging animations...");
442445
try {
443-
animationCatalog = await collectAnimationCatalog(page1, cdpAnims, cdp, {
446+
const animationOutcome = await collectAnimationCatalog(page1, cdpAnims, cdp, {
444447
scrollBudgetMs: Math.min(8_000, remainingMs()),
448+
evaluateBudgetMs: Math.min(15_000, remainingMs()),
445449
});
450+
animationCatalog = animationOutcome.catalog;
451+
if (animationOutcome.timedOut) {
452+
const message =
453+
"animation catalog evaluate timed out; continuing without animation catalog";
454+
warnings.push(message);
455+
progress("warn", message);
456+
}
446457
} catch (err) {
447-
if (!isProtocolEvaluateTimeoutError(err)) {
458+
if (!isDegradableEvaluateTimeoutError(err)) {
448459
throw err;
449460
}
450461
const message = "animation catalog evaluate timed out; continuing without animation catalog";
@@ -464,7 +475,7 @@ export async function captureWebsite(
464475
screenshots = await captureScrollScreenshots(page1, outputDir, { remainingMs });
465476
progress("screenshots", `${screenshots.length} scroll screenshots captured`);
466477
} catch (err) {
467-
if (!isProtocolEvaluateTimeoutError(err)) {
478+
if (!isDegradableEvaluateTimeoutError(err)) {
468479
throw err;
469480
}
470481
const message = "scroll screenshots timed out; continuing without screenshots";

0 commit comments

Comments
 (0)