Files
hyperframes/packages/cli/src/capture/captureTimeout.ts
T
Xuanru LiandCursor 43dba22057 fix(capture): bound scroll/evaluate timeouts so heavy pages keep capturing (#3236)
* fix(capture): bound scroll/evaluate timeouts so heavy pages keep capturing

Fonts/Vercel-class sites were failing after navigation when a single in-page
scroll/evaluate hung until protocolTimeout. Drive lazy scroll from Node,
degrade on evaluate timeouts, and stop labeling those failures as bot blocks.

Co-authored-by: Cursor <cursoragent@cursor.com>

* 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 <cursoragent@cursor.com>

* fix(capture): prefer TimeoutError instanceof for timeout classification

Use puppeteer-core TimeoutError as the primary signal for navigation vs
evaluate/protocol timeouts, with message checks only as a fallback for
string formatting and non-TimeoutError cases.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 18:26:22 -07:00

98 lines
3.0 KiB
TypeScript

import { TimeoutError } from "puppeteer-core";
export const PUPPETEER_DEFAULT_PROTOCOL_TIMEOUT_MS = 180_000;
export class StageBudgetTimeoutError extends Error {
readonly budgetMs: number;
constructor(label: string, budgetMs: number) {
super(`stage budget exceeded while ${label} (${budgetMs}ms)`);
this.name = "StageBudgetTimeoutError";
this.budgetMs = budgetMs;
}
}
export function captureProtocolTimeoutMs(navTimeoutMs: number, postNavBudgetMs: number): number {
if (!Number.isFinite(navTimeoutMs) || !Number.isFinite(postNavBudgetMs)) {
return PUPPETEER_DEFAULT_PROTOCOL_TIMEOUT_MS;
}
return Math.max(60_000, Math.max(0, navTimeoutMs), Math.max(0, postNavBudgetMs));
}
function errorMessage(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
function hasNavigationTimeoutMessage(msg: string): boolean {
return /navigation timeout/i.test(msg);
}
function hasProtocolEvaluateTimeoutMessage(msg: string): boolean {
return /Runtime\.evaluate timed out|protocolTimeout|protocol timeout/i.test(msg);
}
export function isNavigationTimeoutError(err: unknown): boolean {
if (err instanceof TimeoutError) {
return hasNavigationTimeoutMessage(err.message);
}
// String path used by BLOCKED.md formatting.
return typeof err === "string" && hasNavigationTimeoutMessage(err);
}
function isStageBudgetTimeoutError(err: unknown): boolean {
return err instanceof StageBudgetTimeoutError;
}
export function isProtocolEvaluateTimeoutError(err: unknown): boolean {
if (err instanceof TimeoutError) {
return !hasNavigationTimeoutMessage(err.message);
}
return hasProtocolEvaluateTimeoutMessage(errorMessage(err));
}
export function isDegradableEvaluateTimeoutError(err: unknown): boolean {
return isStageBudgetTimeoutError(err) || isProtocolEvaluateTimeoutError(err);
}
export async function withRemainingBudget<T>(
work: Promise<T>,
remainingMs: number,
label: string,
): Promise<T> {
if (!(remainingMs > 0)) {
throw new StageBudgetTimeoutError(label, Math.max(0, remainingMs));
}
let timer: ReturnType<typeof setTimeout> | undefined;
try {
return await Promise.race([
work,
new Promise<never>((_resolve, reject) => {
timer = setTimeout(() => {
reject(new StageBudgetTimeoutError(label, remainingMs));
}, remainingMs);
}),
]);
} finally {
if (timer !== undefined) {
clearTimeout(timer);
}
}
}
export function formatCaptureFailureReason(errMsg: string): string {
if (hasProtocolEvaluateTimeoutMessage(errMsg) || /stage budget exceeded/i.test(errMsg)) {
return (
`Page extraction timed out while running in-page script (${errMsg}). ` +
"The page likely opened, but a later capture step hung."
);
}
if (hasNavigationTimeoutMessage(errMsg)) {
return "Page navigation timed out — the site may be blocking headless browsers or requires authentication.";
}
if (/timeout|timed out/i.test(errMsg)) {
return `Capture timed out: ${errMsg}`;
}
return `Capture failed: ${errMsg}`;
}