Skip to content

Write HTML. Render video. Built for agents.

fix(cli): enforce capture screenshot limits and report interruptions (#5171)

Miguel Ángelc7d41dee5acb
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 56194666df..ac8bf8c599 100644
--- a/docs/packages/cli.mdx
+++ b/docs/packages/cli.mdx
@@ -236,7 +236,7 @@ thin with counts on it was cut short.
| `--capture-budget` | Budget in ms for everything after the page loads (default 120000). Cooperative — it stops new work, but cannot interrupt work already running. |
| `--skip-assets` | Do not download images and SVGs |
| `--skip-vision` | Do not run AI image captioning |
-| `--max-screenshots` | Accepted, but has no effect — capture picks its own scroll positions. |
+| `--max-screenshots` | Maximum page-capture files, including the full-page plate; derived contact sheets are excluded. Positive integer; default 21. A value of 1 captures only the top viewport. |
| `--json` | Structured output for programmatic use |
| `--video <folder>` | Switch to video-download mode against a captured folder's manifest. Pair with `--list`, `--index`, or `--video-url`. |
diff --git a/packages/cli/src/capture/captureAttempt.ts b/packages/cli/src/capture/captureAttempt.ts
index e4c5f711fe..8f85fb1d79 100644
--- a/packages/cli/src/capture/captureAttempt.ts
+++ b/packages/cli/src/capture/captureAttempt.ts
@@ -17,7 +17,7 @@ import type { DiscoveredLottie } from "./mediaCapture.js";
import { detectLibraries } from "./contentExtractor.js";
import { loadEnvFile, generateProjectScaffold } from "./scaffolding.js";
import { captureProtocolTimeoutMs } from "./captureTimeout.js";
-import { CAPTURE_PHASE_SCHEMA } from "./types.js";
+import { CAPTURE_PHASE_SCHEMA, DEFAULT_MAX_SCREENSHOTS } from "./types.js";
import type {
CaptureOptions,
CapturePhase,
@@ -49,7 +49,7 @@ export async function captureWebsiteAttempt(
viewportHeight = 1080,
timeout = 120000,
settleTime = 3000,
- maxScreenshots: _maxScreenshots = 24,
+ maxScreenshots = DEFAULT_MAX_SCREENSHOTS,
skipAssets = false,
skipVision = false,
postNavigationBudgetMs = DEFAULT_POST_NAVIGATION_BUDGET_MS,
@@ -254,6 +254,7 @@ export async function captureWebsiteAttempt(
screenshots,
downloadByteBudget,
canWrite,
+ maxScreenshots,
});
({
animationCatalog,
@@ -267,7 +268,9 @@ export async function captureWebsiteAttempt(
screenshots,
} = coreResult);
- phase("core-extraction", "completed");
+ const screenshotOutcome = coreResult.screenshotOutcome;
+ if (screenshotOutcome.kind === "complete") phase("core-extraction", "completed");
+ else phase("core-extraction", "degraded", screenshotOutcome.reason);
const postResult = await runPostExtraction({
state,
outputDir,
@@ -310,11 +313,18 @@ export async function captureWebsiteAttempt(
}
phase("scaffold", "completed");
- progress("done", "Capture complete");
- phase("complete", "completed");
+ progress(
+ "done",
+ screenshotOutcome.kind === "failed"
+ ? "Capture failed: no screenshots captured"
+ : "Capture complete",
+ );
+ if (screenshotOutcome.kind === "failed")
+ phase("complete", "degraded", screenshotOutcome.reason);
+ else phase("complete", "completed");
return {
- ok: true,
+ ok: screenshotOutcome.kind !== "failed",
projectDir: outputDir,
url,
httpStatus,
diff --git a/packages/cli/src/capture/coreExtractionPhase.test.ts b/packages/cli/src/capture/coreExtractionPhase.test.ts
new file mode 100644
index 0000000000..bc2b9481bd
--- /dev/null
+++ b/packages/cli/src/capture/coreExtractionPhase.test.ts
@@ -0,0 +1,174 @@
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Page, Browser } from "puppeteer-core";
+import { runCoreExtraction } from "./coreExtractionPhase.js";
+import { createPartialCaptureState } from "./partialCapture.js";
+import { createCaptureDownloadBudget } from "./readBoundedResponse.js";
+import { StageBudgetTimeoutError } from "./captureTimeout.js";
+
+const control = vi.hoisted(() => ({ remaining: 10000, expireLazy: false, throwCatalog: false }));
+vi.mock("./lazyScrollForCapture.js", () => ({
+ lazyScrollForCapture: async () => {
+ if (control.expireLazy) control.remaining = 0;
+ return { steps: 0, timedOut: false };
+ },
+}));
+vi.mock("./animationCataloger.js", () => ({
+ collectAnimationCatalog: async () => {
+ if (control.throwCatalog) throw new StageBudgetTimeoutError("catalog", 0);
+ return { catalog: undefined, timedOut: true };
+ },
+}));
+vi.mock("./tokenExtractor.js", () => ({
+ extractTokens: async () => ({
+ title: "Fixture",
+ description: "",
+ cssVariables: {},
+ fonts: [],
+ colors: [],
+ headings: [],
+ ctas: [],
+ svgs: [],
+ sections: [],
+ }),
+}));
+vi.mock("./designStyleExtractor.js", () => ({
+ extractDesignStyles: async () => ({
+ typography: [],
+ spacing: { observed: [], baseUnit: 0 },
+ radius: [],
+ shadows: [],
+ buttons: [],
+ cards: [],
+ nav: null,
+ }),
+}));
+vi.mock("./assetCataloger.js", () => ({ catalogAssets: async () => [] }));
+vi.mock("./htmlExtractor.js", () => ({
+ extractHtml: async () => ({
+ headHtml: "",
+ bodyHtml: "",
+ cssomRules: "",
+ htmlAttrs: "",
+ viewportWidth: 1920,
+ viewportHeight: 1080,
+ fullPageHeight: 10000,
+ }),
+}));
+vi.mock("./contentExtractor.js", () => ({
+ detectLibraries: async () => [],
+ extractVisibleText: async () => "Fixture",
+}));
+vi.mock("./mediaCapture.js", () => ({
+ saveLottieAnimations: async () => 0,
+ renderLottiePreviews: async () => {},
+ captureVideoManifest: async () => {},
+}));
+
+afterEach(() => {
+ control.remaining = 10000;
+ control.expireLazy = false;
+ control.throwCatalog = false;
+});
+
+async function extract(expireScreenshot = false) {
+ vi.useFakeTimers();
+ const outputDir = mkdtempSync(join(tmpdir(), "hf-core-budget-"));
+ mkdirSync(join(outputDir, "extracted"));
+ const state = createPartialCaptureState({ url: "https://example.com", outputDir });
+ const screenshot = vi.fn(async () => {
+ if (expireScreenshot) control.remaining = 0;
+ return new Uint8Array(24);
+ });
+ const page = {
+ evaluate: async (script: unknown) => {
+ if (String(script).includes("scrollHeight")) return 10000;
+ if (script === "window.innerHeight") return 1080;
+ return [];
+ },
+ screenshot,
+ close: async () => {},
+ } as unknown as Page;
+ try {
+ const pending = runCoreExtraction({
+ page1: page,
+ chromeBrowser: {} as Browser,
+ cdp: { send: async () => {} } as never,
+ cdpAnims: [],
+ state,
+ outputDir,
+ warnings: state.warnings,
+ progress: () => {},
+ remainingMs: () => control.remaining,
+ maxScreenshots: 3,
+ pageContentCheck: {
+ textLength: 200,
+ title: "Fixture",
+ hasChallengeElement: false,
+ bodyChildCount: 2,
+ },
+ contentCheckTimedOut: false,
+ discoveredLotties: [],
+ lottieDiscovery: { run: async () => [] } as never,
+ discoveredVideoUrls: new Set(),
+ animationCatalog: undefined,
+ capturedShaders: undefined,
+ catalogedAssets: [],
+ detectedLibraries: [],
+ visibleTextContent: "",
+ faviconLinks: [],
+ tokens: state.tokens,
+ extracted: state.extracted,
+ screenshots: [],
+ downloadByteBudget: createCaptureDownloadBudget(),
+ canWrite: () => true,
+ });
+ await vi.runAllTimersAsync();
+ const result = await pending;
+ return { result, warnings: state.warnings, screenshot };
+ } finally {
+ vi.useRealTimers();
+ rmSync(outputDir, { recursive: true, force: true });
+ }
+}
+
+describe("core extraction screenshot budget", () => {
+ it.each([false, true])(
+ "names the phase that exhausted the budget with thrown catalog timeout %s",
+ async (throws) => {
+ control.expireLazy = true;
+ control.throwCatalog = throws;
+ const { result, warnings, screenshot } = await extract();
+ expect(result.screenshotOutcome).toEqual({
+ kind: "failed",
+ reason: "budget-exhausted",
+ });
+ expect(warnings).toContain(
+ "0/3 requested screenshot files captured: --capture-budget exhausted during lazy scrolling",
+ );
+ expect(warnings).toContain(
+ "--capture-budget spent before the animation catalog finished; continuing without animation catalog",
+ );
+ expect(warnings).not.toContain(
+ "animation catalog evaluate timed out; continuing without animation catalog",
+ );
+ expect(screenshot).not.toHaveBeenCalled();
+ },
+ );
+ it("keeps a positive partial count and names actual versus requested", async () => {
+ const { result, warnings } = await extract(true);
+ expect(result.screenshots).toHaveLength(1);
+ expect(warnings).toContain(
+ "1/3 requested screenshot files captured: --capture-budget exhausted during screenshots",
+ );
+ expect(result.screenshotOutcome).toEqual({
+ kind: "partial",
+ reason: "budget-exhausted",
+ });
+ expect(warnings).toContain(
+ "animation catalog evaluate timed out; continuing without animation catalog",
+ );
+ });
+});
diff --git a/packages/cli/src/capture/coreExtractionPhase.ts b/packages/cli/src/capture/coreExtractionPhase.ts
index 717923ff33..f279d01569 100644
--- a/packages/cli/src/capture/coreExtractionPhase.ts
+++ b/packages/cli/src/capture/coreExtractionPhase.ts
@@ -1,3 +1,4 @@
+import type { ScreenshotInterruption } from "./screenshotCapture.js";
import type { Browser, Page } from "puppeteer-core";
import type { LottieDiscovery } from "./lottieDiscovery.js";
import type { DiscoveredLottie } from "./mediaCapture.js";
@@ -37,6 +38,7 @@ export interface CoreExtractionInput {
warnings: string[];
progress: (stage: string, detail?: string) => void;
remainingMs: () => number;
+ maxScreenshots: number;
pageContentCheck: {
textLength: number;
title: string;
@@ -70,6 +72,12 @@ export interface CoreExtractionResult {
tokens: DesignTokens;
extracted: ExtractedHtml;
screenshots: string[];
+ screenshotOutcome:
+ | { kind: "complete" }
+ | {
+ kind: "partial" | "failed";
+ reason: ScreenshotInterruption["reason"] | "deadline";
+ };
}
export async function runCoreExtraction(input: CoreExtractionInput): Promise<CoreExtractionResult> {
@@ -100,6 +108,16 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
downloadByteBudget,
canWrite,
} = input;
+ const { maxScreenshots } = input;
+ let exhaustedPhase: string | undefined = remainingMs() <= 0 ? "navigation checks" : undefined;
+ const recordBudget = (phase: string): void => {
+ if (exhaustedPhase === undefined && remainingMs() <= 0) exhaustedPhase = phase;
+ };
+ const animationWarning = (): string =>
+ remainingMs() > 0
+ ? "animation catalog evaluate timed out; continuing without animation catalog"
+ : "--capture-budget spent before the animation catalog finished; continuing without animation catalog";
+ let screenshotOutcome: CoreExtractionResult["screenshotOutcome"] = { kind: "complete" };
const runLazyAndLottie = async (): Promise<void> => {
if (!contentCheckTimedOut && pageContentCheck.textLength < 100) {
const reason =
@@ -125,6 +143,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
await new Promise((r) => setTimeout(r, 300));
};
await runLazyAndLottie();
+ recordBudget("lazy scrolling");
const runAnimationDiscovery = async (): Promise<void> => {
const scanDomLotties = async (): Promise<void> => {
@@ -193,6 +212,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
await saveDiscoveredLotties();
};
await runAnimationDiscovery();
+ recordBudget("animation discovery");
// Save captured WebGL shaders (useful context for shader transitions + library detection)
const runShaderCapture = async (): Promise<void> => {
@@ -220,6 +240,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
}
};
await runShaderCapture();
+ recordBudget("shader capture");
const runTokenExtraction = async (): Promise<void> => {
// Extract DOM data before extractHtml mutates image URLs and removes scripts.
@@ -261,6 +282,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
}
};
await runTokenExtraction();
+ recordBudget("design token extraction");
const runAnimationCapture = async (): Promise<void> => {
progress("animations", "Cataloging animations...");
@@ -271,8 +293,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
});
animationCatalog = animationOutcome.catalog;
if (animationOutcome.timedOut) {
- const message =
- "animation catalog evaluate timed out; continuing without animation catalog";
+ const message = animationWarning();
warnings.push(message);
progress("warn", message);
}
@@ -280,7 +301,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
if (!isDegradableEvaluateTimeoutError(err)) {
throw err;
}
- const message = "animation catalog evaluate timed out; continuing without animation catalog";
+ const message = animationWarning();
warnings.push(message);
progress("warn", message);
try {
@@ -290,24 +311,48 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
}
}
+ recordBudget("animation catalog");
+ };
+ await runAnimationCapture();
+
+ const runScreenshotCapture = async (): Promise<void> => {
progress("screenshots", "Capturing scroll screenshots...");
const { captureScrollScreenshots } = await import("./screenshotCapture.js");
- try {
- if (!canWrite()) return;
- screenshots = await captureScrollScreenshots(page1, outputDir, { remainingMs });
- state.screenshots = screenshots;
- progress("screenshots", `${screenshots.length} scroll screenshots captured`);
- } catch (err) {
- if (!isDegradableEvaluateTimeoutError(err)) {
- throw err;
- }
- const message = "scroll screenshots timed out; continuing without screenshots";
+ if (!canWrite()) {
+ screenshotOutcome = {
+ kind: "failed",
+ reason: "deadline",
+ };
+ return;
+ }
+ screenshots = [];
+ state.screenshots = screenshots;
+ const capture = await captureScrollScreenshots(page1, outputDir, {
+ remainingMs,
+ maxScreenshots,
+ files: screenshots,
+ });
+ if (capture.interruption || screenshots.length === 0) {
+ recordBudget("screenshots");
+ const { reason, message: detail }: ScreenshotInterruption = capture.interruption ?? {
+ reason: "internal-error",
+ message: "screenshot capture produced no files",
+ };
+ const cause =
+ reason === "budget-exhausted"
+ ? `--capture-budget exhausted during ${exhaustedPhase}`
+ : detail;
+ const message = `${screenshots.length}/${maxScreenshots} requested screenshot files captured: ${cause}`;
+ screenshotOutcome = {
+ kind: screenshots.length === 0 ? "failed" : "partial",
+ reason,
+ };
warnings.push(message);
progress("warn", message);
}
+ progress("screenshots", `${screenshots.length} scroll screenshots captured`);
};
- await runAnimationCapture();
-
+ await runScreenshotCapture();
const runHtmlExtraction = async (): Promise<void> => {
// Catalog all assets (must run before extractHtml which converts img src to data URLs)
progress("design", "Cataloging assets...");
@@ -385,6 +430,7 @@ export async function runCoreExtraction(input: CoreExtractionInput): Promise<Cor
await runHtmlExtraction();
return {
+ screenshotOutcome,
animationCatalog,
capturedShaders,
catalogedAssets,
diff --git a/packages/cli/src/capture/screenshotCapture.degrade.test.ts b/packages/cli/src/capture/screenshotCapture.degrade.test.ts
index e181773af1..6348434f5a 100644
--- a/packages/cli/src/capture/screenshotCapture.degrade.test.ts
+++ b/packages/cli/src/capture/screenshotCapture.degrade.test.ts
@@ -7,7 +7,7 @@ import type { Page } from "puppeteer-core";
import { captureScrollScreenshots } from "./screenshotCapture.js";
describe("captureScrollScreenshots degradation", () => {
- it("rethrows protocol evaluate timeouts for the caller warning path", async () => {
+ it("returns protocol evaluate timeout provenance for the caller warning path", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-scroll-degrade-"));
onTestFinished(() => rmSync(dir, { recursive: true, force: true }));
const page = {
@@ -19,8 +19,13 @@ describe("captureScrollScreenshots degradation", () => {
screenshot: vi.fn(),
} as unknown as Page;
- await expect(
- captureScrollScreenshots(page, dir, { remainingMs: () => 5_000 }),
- ).rejects.toBeInstanceOf(TimeoutError);
+ const result = await captureScrollScreenshots(page, dir, { remainingMs: () => 5_000 });
+ expect(result.files).toEqual([]);
+ expect(result.interruption).toEqual({
+ reason: "request-timeout",
+ message:
+ "Runtime.evaluate timed out. Increase the 'protocolTimeout' setting in launch/connect calls for a higher timeout if needed.",
+ });
+ expect(page.screenshot).not.toHaveBeenCalled();
});
});
diff --git a/packages/cli/src/capture/screenshotCapture.test.ts b/packages/cli/src/capture/screenshotCapture.test.ts
index 9fc844ed6f..5093113109 100644
--- a/packages/cli/src/capture/screenshotCapture.test.ts
+++ b/packages/cli/src/capture/screenshotCapture.test.ts
@@ -10,7 +10,7 @@ import {
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import type { Page } from "puppeteer-core";
+import { TimeoutError, type Page } from "puppeteer-core";
import {
captureFullPagePlate,
captureScrollScreenshots,
@@ -44,9 +44,10 @@ function fakePage(
{ docHeight = 8000, plateHeight = 8000 }: { docHeight?: number; plateHeight?: number } = {},
overrides: Record<string, unknown> = {},
) {
- const evaluate = vi.fn(async (script?: unknown) =>
- String(script).includes("scrollHeight") ? docHeight : undefined,
- );
+ const evaluate = vi.fn(async (script?: unknown) => {
+ if (String(script).includes("scrollHeight")) return docHeight;
+ if (script === "window.innerHeight") return 1080;
+ });
const screenshot = vi.fn(async (_opts?: unknown) => pngBuffer(plateHeight));
return { page: { evaluate, screenshot, ...overrides } as unknown as Page, evaluate, screenshot };
}
@@ -58,7 +59,7 @@ describe("captureFullPagePlate — the scroll shot's plate", () => {
const out = await captureFullPagePlate(page, dir);
- expect(out).toBe("screenshots/full-page.png");
+ expect(out).toEqual({ kind: "captured", file: "screenshots/full-page.png" });
expect(screenshot).toHaveBeenCalledWith({ type: "png", fullPage: true });
expect(pngHeight(readFileSync(join(dir, "full-page.png")))).toBe(10962);
});
@@ -80,7 +81,7 @@ describe("captureFullPagePlate — the scroll shot's plate", () => {
const out = await captureFullPagePlate(page, dir);
- expect(out).toBeNull();
+ expect(out).toEqual({ kind: "omitted", reason: "height-limit" });
expect(screenshot).not.toHaveBeenCalled();
expect(existsSync(join(dir, "full-page.png"))).toBe(false);
});
@@ -124,6 +125,150 @@ describe("captureFullPagePlate — the scroll shot's plate", () => {
});
});
+describe("captureScrollScreenshots limits", () => {
+ it.each([1, 3, 21, 105])("caps all screenshot files at %i including the plate", async (limit) => {
+ vi.useFakeTimers();
+ const dir = tempDir("hf-scroll-limit-");
+ const { page } = fakePage(
+ { docHeight: 16000 },
+ {
+ evaluate: vi.fn(async (expression: unknown) => {
+ if (String(expression).includes("scrollHeight")) return 16000;
+ if (expression === "window.innerHeight") return 100;
+ }),
+ },
+ );
+ try {
+ const capture = captureScrollScreenshots(page, dir, { maxScreenshots: limit });
+ await vi.runAllTimersAsync();
+ const { files } = await capture;
+ expect(files).toHaveLength(limit);
+ expect(readdirSync(join(dir, "screenshots"))).toHaveLength(limit);
+ if (limit === 1) expect(files).toEqual(["screenshots/scroll-000.png"]);
+ else expect(files).toContain("screenshots/full-page.png");
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
+
+describe("captureScrollScreenshots interruptions", () => {
+ it.each([
+ [new TimeoutError("protocolTimeout"), "request-timeout"],
+ [new Error("target closed"), "internal-error"],
+ ])("preserves saved files when the next screenshot fails with %s", async (error, reason) => {
+ vi.useFakeTimers();
+ const dir = tempDir("hf-scroll-interrupted-");
+ const screenshot = vi.fn().mockResolvedValueOnce(pngBuffer(1080)).mockRejectedValue(error);
+ const { page } = fakePage(
+ {},
+ {
+ screenshot,
+ },
+ );
+ try {
+ const capture = captureScrollScreenshots(page, dir, { maxScreenshots: 3 });
+ await vi.runAllTimersAsync();
+ const result = await capture;
+ expect(result.files).toEqual(["screenshots/scroll-000.png"]);
+ expect(readdirSync(join(dir, "screenshots"))).toEqual(["scroll-000.png"]);
+ expect(result.interruption).toEqual({ reason, message: error.message });
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("publishes written paths while the next native screenshot is still pending", async () => {
+ vi.useFakeTimers();
+ const dir = tempDir("hf-scroll-pending-");
+ const files: string[] = [];
+ let interrupt!: (error: Error) => void;
+ const screenshot = vi
+ .fn()
+ .mockResolvedValueOnce(pngBuffer(1080))
+ .mockImplementation(
+ () =>
+ new Promise((_resolve, reject) => {
+ interrupt = reject;
+ }),
+ );
+ const { page } = fakePage(
+ {},
+ {
+ screenshot,
+ },
+ );
+ try {
+ const capture = captureScrollScreenshots(page, dir, { maxScreenshots: 3, files });
+ await vi.advanceTimersByTimeAsync(1200);
+ expect(files).toEqual(["screenshots/scroll-000.png"]);
+ interrupt(new TimeoutError("protocolTimeout"));
+ const result = await capture;
+ expect(result.files).toBe(files);
+ expect(result.interruption?.reason).toBe("request-timeout");
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("publishes a written plate before position restoration finishes", async () => {
+ vi.useFakeTimers();
+ const dir = tempDir("hf-plate-pending-");
+ const files: string[] = [];
+ let restore!: () => void;
+ const { page } = fakePage(
+ {},
+ {
+ evaluate: vi.fn(async (script: unknown) => {
+ if (String(script).includes("removeAttribute")) {
+ await new Promise<void>((resolve) => {
+ restore = resolve;
+ });
+ }
+ if (String(script).includes("scrollHeight")) return 1080;
+ if (script === "window.innerHeight") return 1080;
+ }),
+ },
+ );
+ try {
+ const capture = captureScrollScreenshots(page, dir, { maxScreenshots: 3, files });
+ await vi.advanceTimersByTimeAsync(1000);
+ expect(files).toEqual(["screenshots/scroll-000.png", "screenshots/full-page.png"]);
+ restore();
+ expect((await capture).files).toBe(files);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("covers a one-pixel viewport without a zero scroll step", async () => {
+ vi.useFakeTimers();
+ const dir = tempDir("hf-scroll-tiny-viewport-");
+ const { page } = fakePage(
+ {},
+ {
+ evaluate: vi.fn(async (script: unknown) => {
+ if (String(script).includes("scrollHeight")) return 20;
+ if (script === "window.innerHeight") return 1;
+ }),
+ },
+ );
+ try {
+ const capture = captureScrollScreenshots(page, dir, { maxScreenshots: 3 });
+ await vi.runAllTimersAsync();
+ const result = await capture;
+ expect(result.files).toEqual([
+ "screenshots/scroll-000.png",
+ "screenshots/scroll-100.png",
+ "screenshots/full-page.png",
+ ]);
+ expect(result.interruption).toBeNull();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
+
describe("captureScrollScreenshots — capture budget", () => {
it("does not begin page work when the post-navigation budget is exhausted", async () => {
const dir = tempDir("hf-scroll-budget-");
@@ -131,7 +276,9 @@ describe("captureScrollScreenshots — capture budget", () => {
const screenshot = vi.fn(async () => pngBuffer(1080));
const page = { evaluate, screenshot } as unknown as Page;
- const files = await captureScrollScreenshots(page, dir, { remainingMs: () => 0 });
+ const result = await captureScrollScreenshots(page, dir, { remainingMs: () => 0 });
+ const files = result.files;
+ expect(result.interruption?.reason).toBe("budget-exhausted");
expect(files).toEqual([]);
expect(evaluate).not.toHaveBeenCalled();
@@ -156,7 +303,7 @@ describe("captureScrollScreenshots — capture budget", () => {
remainingMs: () => Math.max(0, 600 - Date.now()),
});
await vi.runAllTimersAsync();
- const files = await capture;
+ const { files } = await capture;
expect(files).toEqual([]);
expect(screenshot).not.toHaveBeenCalled();
@@ -186,7 +333,7 @@ describe("captureFullPagePlate — capture budget", () => {
remainingMs: () => Math.max(0, 50 - Date.now()),
});
- expect(plate).toBeNull();
+ expect(plate).toEqual({ kind: "omitted", reason: "budget-exhausted" });
expect(screenshot).not.toHaveBeenCalled();
} finally {
vi.useRealTimers();
@@ -201,7 +348,10 @@ describe("captureFullPagePlate — guards against a silently clipped plate", ()
// pre-scroll number would have passed the guard and emitted a clipped plate.
const { page, screenshot } = fakePage({ docHeight: 20000 });
- expect(await captureFullPagePlate(page, dir)).toBeNull();
+ expect(await captureFullPagePlate(page, dir)).toEqual({
+ kind: "omitted",
+ reason: "height-limit",
+ });
expect(screenshot).not.toHaveBeenCalled();
});
@@ -211,7 +361,10 @@ describe("captureFullPagePlate — guards against a silently clipped plate", ()
// over the cap. Emitting it would be undetectable downstream.
const { page } = fakePage({ docHeight: 16000, plateHeight: MAX_PLATE_HEIGHT_PX + 500 });
- expect(await captureFullPagePlate(page, dir)).toBeNull();
+ expect(await captureFullPagePlate(page, dir)).toEqual({
+ kind: "omitted",
+ reason: "height-limit",
+ });
expect(existsSync(join(dir, "full-page.png"))).toBe(false);
});
@@ -265,7 +418,10 @@ describe("captureFullPagePlate — the guard sees the post-neutralisation page (
const screenshot = vi.fn(async (_opts?: unknown) => pngBuffer(20000));
const page = { evaluate, screenshot } as unknown as Page;
- expect(await captureFullPagePlate(page, dir)).toBeNull();
+ expect(await captureFullPagePlate(page, dir)).toEqual({
+ kind: "omitted",
+ reason: "height-limit",
+ });
expect(screenshot).not.toHaveBeenCalled();
expect(existsSync(join(dir, "full-page.png"))).toBe(false);
// Bailing out early must still hand the page back unmodified.
diff --git a/packages/cli/src/capture/screenshotCapture.ts b/packages/cli/src/capture/screenshotCapture.ts
index bdde074316..76c351cf04 100644
--- a/packages/cli/src/capture/screenshotCapture.ts
+++ b/packages/cli/src/capture/screenshotCapture.ts
@@ -5,6 +5,9 @@
* tsx/esbuild __name injection (see esbuild issue #1031).
*/
+import { DEFAULT_MAX_SCREENSHOTS } from "./types.js";
+import { CaptureDirRefusedError } from "./captureErrors.js";
+import { normalizeErrorMessage } from "../utils/errorMessage.js";
import type { Page } from "puppeteer-core";
import { isDegradableEvaluateTimeoutError } from "./captureTimeout.js";
import { join } from "node:path";
@@ -16,7 +19,7 @@ import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";
* Scrolls down the page in viewport-sized steps (with slight overlap),
* taking a 1920x1080 screenshot at each position. The number of screenshots
* depends on the page height — short pages get fewer, long pages get more.
- * Capped at 20 to avoid excessive output on extremely long pages.
+ * The limit includes the full-page plate.
*
* Unlike the old section-tiling approach, this does NOT disable sticky/fixed
* elements — screenshots show the page in its natural browsing state with
@@ -28,6 +31,20 @@ import { ensureCaptureDirSync, writeCaptureFileSync } from "./captureFile.js";
*/
export const MAX_PLATE_HEIGHT_PX = 16384;
+export type PlateCaptureResult =
+ | { kind: "captured"; file: string }
+ | { kind: "omitted"; reason: "height-limit" | "budget-exhausted" };
+
+export interface ScreenshotInterruption {
+ reason: "budget-exhausted" | "request-timeout" | "internal-error";
+ message: string;
+}
+
+export interface ScreenshotCaptureResult {
+ files: string[];
+ interruption: ScreenshotInterruption | null;
+}
+
/**
* Pixel height Chrome actually produced, read from the PNG's IHDR chunk: 8-byte signature,
* then 4 length + 4 type + 4 width + 4 height. Null when the buffer isn't a PNG.
@@ -55,13 +72,13 @@ export function pngHeight(buf: Uint8Array): number | null {
* one position, so a nav ends up frozen across the middle of the plate. The viewport
* shots keep sticky on purpose (natural browsing state); the plate cannot.
*
- * Returns the relative path, or null when the page is too tall to capture in one piece.
+ * Returns the captured path or the cause for omitting the plate.
*/
export async function captureFullPagePlate(
page: Page,
screenshotsDir: string,
- budget: { remainingMs?: () => number } = {},
-): Promise<string | null> {
+ budget: { remainingMs?: () => number; files?: string[] } = {},
+): Promise<PlateCaptureResult> {
// Record the inline value before overwriting so the page is handed back unchanged — the
// caller keeps using it (asset extraction, DOM reads) after this returns.
await page.evaluate(
@@ -82,8 +99,8 @@ export async function captureFullPagePlate(
const docHeight = (await page.evaluate(
`Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)`,
)) as number;
- if (docHeight > MAX_PLATE_HEIGHT_PX) return null;
- if ((budget.remainingMs?.() ?? 1) <= 0) return null;
+ if (docHeight > MAX_PLATE_HEIGHT_PX) return { kind: "omitted", reason: "height-limit" };
+ if ((budget.remainingMs?.() ?? 1) <= 0) return { kind: "omitted", reason: "budget-exhausted" };
const buffer = await page.screenshot({ type: "png", fullPage: true });
// Confirm what Chrome produced instead of trusting the measurement: the capture itself can
@@ -91,9 +108,11 @@ export async function captureFullPagePlate(
// skill only teaches the tile fallback when the file is *absent* — so emit nothing rather
// than something silently wrong.
const produced = pngHeight(buffer);
- if (produced != null && produced > MAX_PLATE_HEIGHT_PX) return null;
+ if (produced != null && produced > MAX_PLATE_HEIGHT_PX)
+ return { kind: "omitted", reason: "height-limit" };
writeCaptureFileSync(join(screenshotsDir, "full-page.png"), buffer);
- return "screenshots/full-page.png";
+ budget.files?.push("screenshots/full-page.png");
+ return { kind: "captured", file: "screenshots/full-page.png" };
} finally {
// A page that broke mid-capture will fail this too; letting that escape would replace the
// real error with a cleanup one. Nothing to restore if the page is already gone.
@@ -114,15 +133,32 @@ export async function captureFullPagePlate(
export async function captureScrollScreenshots(
page: Page,
outputDir: string,
- budget: { remainingMs?: () => number } = {},
-): Promise<string[]> {
+ budget: {
+ remainingMs?: () => number;
+ maxScreenshots?: number;
+ /** Shared output preserves written paths when a watchdog ends the pending capture. */
+ files?: string[];
+ } = {},
+): Promise<ScreenshotCaptureResult> {
const screenshotsDir = join(outputDir, "screenshots");
ensureCaptureDirSync(outputDir, screenshotsDir);
- const MAX_SCREENSHOTS = 20;
- const filePaths: string[] = [];
+ const maxScreenshots = budget.maxScreenshots ?? DEFAULT_MAX_SCREENSHOTS;
+ const viewportLimit = Math.max(1, maxScreenshots - 1);
+ const filePaths: string[] = budget.files ?? [];
+ filePaths.length = 0;
+ const filenames = new Set<string>();
- if ((budget.remainingMs?.() ?? 1) <= 0) return filePaths;
+ const result: ScreenshotCaptureResult = { files: filePaths, interruption: null };
+ const budgetSpent = (): boolean => {
+ if ((budget.remainingMs?.() ?? 1) > 0) return false;
+ result.interruption = {
+ reason: "budget-exhausted",
+ message: "post-navigation budget exhausted during screenshots",
+ };
+ return true;
+ };
+ if (budgetSpent()) return result;
try {
// Dismiss marketing banners, cookie consents, and popups before scrolling.
@@ -210,40 +246,30 @@ export async function captureScrollScreenshots(
)) as number;
const viewportHeight = (await page.evaluate(`window.innerHeight`)) as number;
- // Calculate scroll positions: step by 70% of viewport (30% overlap between shots)
- const step = Math.floor(viewportHeight * 0.7);
- const positions: number[] = [0];
- for (let y = step; y < scrollHeight - viewportHeight; y += step) {
- positions.push(y);
- }
- // Always include the bottom of the page
+ const step = Math.max(1, Math.floor(viewportHeight * 0.7));
const lastPos = Math.max(0, scrollHeight - viewportHeight);
- if (positions[positions.length - 1] !== lastPos) {
- positions.push(lastPos);
- }
-
- // Downsample if too many positions
- let finalPositions = positions;
- if (positions.length > MAX_SCREENSHOTS) {
- finalPositions = [positions[0]!];
- const stride = (positions.length - 1) / (MAX_SCREENSHOTS - 1);
- for (let i = 1; i < MAX_SCREENSHOTS - 1; i++) {
- finalPositions.push(positions[Math.round(i * stride)]!);
- }
- finalPositions.push(positions[positions.length - 1]!);
+ const positionCount = Math.ceil(lastPos / step) + 1;
+ const count = Math.min(viewportLimit, positionCount);
+ const finalPositions: number[] = [];
+ for (let i = 0; i < count; i++) {
+ const positionIndex = count === 1 ? 0 : Math.round((i * (positionCount - 1)) / (count - 1));
+ finalPositions.push(Math.min(positionIndex * step, lastPos));
}
for (let i = 0; i < finalPositions.length; i++) {
- if ((budget.remainingMs?.() ?? 1) <= 0) break;
+ if (budgetSpent()) break;
await page.evaluate(`window.scrollTo(0, ${finalPositions[i]})`);
await new Promise((r) => setTimeout(r, 400));
const pct = Math.round(
(finalPositions[i]! / Math.max(1, scrollHeight - viewportHeight)) * 100,
);
- const filename = `scroll-${String(Math.min(pct, 100)).padStart(3, "0")}.png`;
+ const stem = `scroll-${String(Math.min(pct, 100)).padStart(3, "0")}`;
+ let filename = `${stem}.png`;
+ if (filenames.has(filename)) filename = `${stem}-${i}.png`;
+ filenames.add(filename);
const filePath = join(screenshotsDir, filename);
- if ((budget.remainingMs?.() ?? 1) <= 0) break;
+ if (budgetSpent()) break;
const buffer = await page.screenshot({ type: "png" });
writeCaptureFileSync(filePath, buffer);
filePaths.push(`screenshots/${filename}`);
@@ -258,16 +284,20 @@ export async function captureScrollScreenshots(
// dropped because 1/8 agents read it and the contact sheet covered the same ground — that
// was about it as a *comprehension* artifact. The scroll shot is a different consumer: it
// needs one continuous plate, which no set of viewport tiles can substitute for.)
- if ((budget.remainingMs?.() ?? 1) > 0) {
- const plate = await captureFullPagePlate(page, screenshotsDir, budget);
- if (plate) filePaths.push(plate);
+ if (filePaths.length < maxScreenshots && !budgetSpent()) {
+ const plate = await captureFullPagePlate(page, screenshotsDir, {
+ ...budget,
+ files: filePaths,
+ });
+ if (plate.kind === "omitted" && plate.reason === "budget-exhausted") budgetSpent();
}
} catch (err) {
- if (isDegradableEvaluateTimeoutError(err)) {
- throw err;
- }
- /* scroll screenshots are non-critical */
+ if (err instanceof CaptureDirRefusedError) throw err;
+ result.interruption = {
+ reason: isDegradableEvaluateTimeoutError(err) ? "request-timeout" : "internal-error",
+ message: normalizeErrorMessage(err),
+ };
}
- return filePaths;
+ return result;
}
diff --git a/packages/cli/src/capture/types.ts b/packages/cli/src/capture/types.ts
index 853b04c18e..0ba2bf3874 100644
--- a/packages/cli/src/capture/types.ts
+++ b/packages/cli/src/capture/types.ts
@@ -20,6 +20,8 @@ export type CapturePhase =
| "scaffold"
| "complete";
+export const DEFAULT_MAX_SCREENSHOTS = 21;
+
export const CAPTURE_PHASE_SCHEMA = "hyperframes.capture.phase.v1" as const;
export interface CapturePhaseProgress {
@@ -52,7 +54,7 @@ export interface CaptureOptions {
timeout?: number;
/** Extra wait after load for JS to settle (default: 3000) */
settleTime?: number;
- /** Maximum screenshots to take (default: 24) */
+ /** Maximum screenshot files including the full-page plate (default: 21) */
maxScreenshots?: number;
/** Skip asset downloads */
skipAssets?: boolean;
diff --git a/packages/cli/src/commands/capture.test.ts b/packages/cli/src/commands/capture.test.ts
index c0ff7ee6e3..42f9e72299 100644
--- a/packages/cli/src/commands/capture.test.ts
+++ b/packages/cli/src/commands/capture.test.ts
@@ -36,7 +36,7 @@ const { captureWebsiteMock } = vi.hoisted(() => ({
screenshots: [],
tokens: { sections: [], fonts: [] },
assets: [],
- warnings: [],
+ warnings: [] as string[],
};
}),
}));
@@ -169,6 +169,71 @@ describe("capture command — vision control", () => {
},
);
+ it.each(["0", "-1", "1.5", "3junk", "", "Infinity"])(
+ "rejects invalid --max-screenshots %s before capture starts",
+ async (value) => {
+ vi.spyOn(console, "log").mockImplementation(() => {});
+ const error = vi.spyOn(console, "error").mockImplementation(() => {});
+ await expect(
+ captureCommand.run!({
+ args: {
+ url: "https://example.com",
+ output: "/tmp/hf-invalid-count",
+ "max-screenshots": value,
+ json: true,
+ },
+ } as never),
+ ).rejects.toBeInstanceOf(CliRuntimeError);
+ expect(error).toHaveBeenCalledWith("--max-screenshots must be a positive integer.");
+ expect(captureWebsiteMock).not.toHaveBeenCalled();
+ },
+ );
+
+ it("passes a validated screenshot limit into capture", async () => {
+ vi.spyOn(console, "log").mockImplementation(() => {});
+ await captureCommand.run!({
+ args: {
+ url: "https://example.com",
+ output: "/tmp/hf-count",
+ "max-screenshots": "3",
+ json: true,
+ },
+ } as never);
+ expect(captureWebsiteMock).toHaveBeenCalledWith(
+ expect.objectContaining({ maxScreenshots: 3 }),
+ undefined,
+ );
+ });
+
+ it("returns a nonzero command result after presenting failed capture JSON once", async () => {
+ const log = vi.spyOn(console, "log").mockImplementation(() => {});
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ captureWebsiteMock.mockResolvedValueOnce({
+ ok: false,
+ projectDir: "/tmp/capture",
+ url: "https://example.com",
+ title: "Example",
+ extracted: {},
+ screenshots: [],
+ tokens: { sections: [], fonts: [] },
+ assets: [],
+ warnings: [
+ "0/3 requested screenshot files captured: --capture-budget exhausted during lazy scrolling",
+ ],
+ });
+ await expect(
+ captureCommand.run!({
+ args: {
+ url: "https://example.com",
+ output: "/tmp/hf-failed-capture",
+ json: true,
+ },
+ } as never),
+ ).rejects.toMatchObject({ result: { exitCode: 1 } });
+ expect(log).toHaveBeenCalledTimes(1);
+ expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({ ok: false, screenshots: 0 });
+ });
+
it("emits a versioned phase record without the captured URL", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
const error = vi.spyOn(console, "error").mockImplementation(() => {});
diff --git a/packages/cli/src/commands/capture.ts b/packages/cli/src/commands/capture.ts
index e7740e0449..c423490a86 100644
--- a/packages/cli/src/commands/capture.ts
+++ b/packages/cli/src/commands/capture.ts
@@ -1,3 +1,4 @@
+import { DEFAULT_MAX_SCREENSHOTS } from "../capture/types.js";
import { failCommand } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import { resolve } from "node:path";
@@ -13,11 +14,15 @@ function emitCapturePhase(event: CapturePhaseProgress): void {
diag.notice(`${CAPTURE_PHASE_PREFIX}${JSON.stringify(event)}`);
}
-function parseCaptureBudget(raw: string | undefined): number | undefined {
+function parsePositiveInteger(
+ raw: string | undefined,
+ flag: string,
+ unit = "",
+): number | undefined {
if (raw === undefined) return undefined;
const parsed = Number(raw);
if (!Number.isInteger(parsed) || parsed <= 0) {
- console.error("--capture-budget must be a positive integer in milliseconds.");
+ console.error(`${flag} must be a positive integer${unit}.`);
failCommand();
}
return parsed;
@@ -65,7 +70,7 @@ export default defineCommand({
},
"max-screenshots": {
type: "string",
- description: "Maximum screenshots to capture (default: 24)",
+ description: `Maximum page-capture files including the full-page plate, excluding derived contact sheets (default: ${DEFAULT_MAX_SCREENSHOTS})`,
},
timeout: {
type: "string",
@@ -128,7 +133,16 @@ export default defineCommand({
failCommand();
}
- const captureBudgetMs = parseCaptureBudget(args["capture-budget"] as string | undefined);
+ const captureBudgetMs = parsePositiveInteger(
+ args["capture-budget"] as string | undefined,
+ "--capture-budget",
+ " in milliseconds",
+ );
+
+ const maxScreenshots = parsePositiveInteger(
+ args["max-screenshots"] as string | undefined,
+ "--max-screenshots",
+ );
const isDefaultOutput = !args.output;
let outputName = (args.output as string | undefined) ?? "capture";
@@ -164,6 +178,7 @@ export default defineCommand({
const { captureWebsite } = await import("../capture/index.js");
+ let captureFailed = false;
try {
const result = await captureWebsite(
{
@@ -171,9 +186,7 @@ export default defineCommand({
outputDir,
skipAssets: args["skip-assets"] as boolean,
skipVision: args["skip-vision"] as boolean,
- maxScreenshots: args["max-screenshots"]
- ? parseInt(args["max-screenshots"] as string)
- : undefined,
+ maxScreenshots,
timeout: args.timeout ? parseInt(args.timeout as string) : undefined,
postNavigationBudgetMs: captureBudgetMs,
captureDeadlineMs: parseCaptureDeadline(process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS),
@@ -198,6 +211,7 @@ export default defineCommand({
},
);
+ captureFailed = !result.ok;
if (isJson) {
// Output structured JSON for Claude Code / programmatic use
console.log(
@@ -227,7 +241,9 @@ export default defineCommand({
} else {
const { c } = await import("../ui/colors.js");
console.log();
- console.log(c.success("◇") + ` Captured ${c.bold(result.title)} → ${c.dim(outputDir)}`);
+ const icon = result.ok ? c.success("◇") : c.error("✗");
+ const status = result.ok ? "Captured" : "Capture failed";
+ console.log(icon + ` ${status} ${c.bold(result.title)} → ${c.dim(outputDir)}`);
console.log();
console.log(` ${c.dim("Screenshots:")} ${result.screenshots.length}`);
console.log(` ${c.dim("Assets:")} ${result.assets.length}`);
@@ -289,5 +305,6 @@ export default defineCommand({
}
failCommand();
}
+ if (captureFailed) failCommand();
},
});