Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): enforce capture screenshot limits and report interruptions (#5171)
Miguel Ángelc7d41dee5acb
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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<CordownloadByteBudget,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<Corawait 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<Corawait 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<Corif (!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<Corawait 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 useconsole.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();},});