Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(browser): capture the full visual viewport (#5621)

STDquantum146dcf46f5bd
diff --git a/scripts/fixtures/browser-verifier-site.mjs b/scripts/fixtures/browser-verifier-site.mjs
index db660699d..b86c04fa3 100644
--- a/scripts/fixtures/browser-verifier-site.mjs
+++ b/scripts/fixtures/browser-verifier-site.mjs
@@ -55,6 +55,13 @@ export async function startBrowserVerifierSite() {
response.once("close", () => clearTimeout(timer));
return;
}
+ if (request.url === "/screenshot-viewport") {
+ response.setHeader("content-type", "text/html");
+ response.end(
+ `<!doctype html><html style="overflow:hidden"><body style="margin:0;background:#eee"><div style="position:absolute;top:650px;left:0;width:200px;height:50px;background:#c00"></div></body></html>`,
+ );
+ return;
+ }
if (request.url === "/screenshot-noise") {
response.setHeader("content-type", "text/html");
response.end(`<!doctype html><html><body style="margin:0"><canvas width="2048" height="1536"></canvas><script>
diff --git a/scripts/lib/browser-viewport-screenshot-e2e.mjs b/scripts/lib/browser-viewport-screenshot-e2e.mjs
new file mode 100644
index 000000000..70945f629
--- /dev/null
+++ b/scripts/lib/browser-viewport-screenshot-e2e.mjs
@@ -0,0 +1,195 @@
+import assert from "node:assert/strict";
+import { chromium } from "playwright-core";
+import { CdpConnection } from "../../dist/browser/CdpConnection.js";
+import { discoverCdpEndpoint } from "../../dist/browser/CdpEndpoint.js";
+import { captureCdpScreenshot } from "../../dist/browser/CdpScreenshot.js";
+import { comparePngScreenshots } from "../../dist/browser/PngVisualDiff.js";
+import { createWebScreenshotArtifact } from "../../dist/domain/webScreenshot.js";
+
+/** Exercise the production capture boundary on a real, undersized surface. */
+export async function verifyViewportScreenshotE2e(endpoint, origin) {
+ const browser = await chromium.connectOverCDP(endpoint);
+ const context = await browser.newContext({
+ viewport: { width: 800, height: 400 },
+ deviceScaleFactor: 1,
+ });
+ let connection;
+ try {
+ const page = await context.newPage();
+ await page.goto(`${origin}/screenshot-viewport`);
+ const discovery = await discoverCdpEndpoint(
+ endpoint,
+ "capture_web_screenshot",
+ );
+ const target = discovery.targets.find(({ url }) => url === page.url());
+ assert.ok(
+ target?.webSocket,
+ "Owned viewport fixture needs a page CDP endpoint",
+ );
+ connection = await CdpConnection.connect(
+ target.webSocket.url,
+ "capture_web_screenshot",
+ );
+ const emulation = await context.newCDPSession(page);
+ const cases = [];
+ for (const scale of [1, 2]) {
+ await connection.send("Emulation.setDeviceMetricsOverride", {
+ width: 800,
+ height: 400,
+ deviceScaleFactor: 0,
+ mobile: false,
+ });
+ // A capture on another CDP session can restore its own device metrics.
+ // Establish the fixture independently for each page-scale case.
+ await emulation.send("Emulation.clearDeviceMetricsOverride");
+ await emulation.send("Emulation.setDeviceMetricsOverride", {
+ width: 1280,
+ height: 720,
+ deviceScaleFactor: 1,
+ mobile: false,
+ dontSetVisibleSize: true,
+ });
+ await emulation.send("Emulation.setPageScaleFactor", {
+ pageScaleFactor: scale,
+ });
+ const { visualViewport, cssVisualViewport } = await connection.send(
+ "Page.getLayoutMetrics",
+ );
+ assert.equal(
+ cssVisualViewport.clientWidth * cssVisualViewport.scale,
+ 1280,
+ JSON.stringify({ scale, visualViewport }),
+ );
+ assert.equal(
+ cssVisualViewport.clientHeight * cssVisualViewport.scale,
+ 720,
+ JSON.stringify({ scale, visualViewport }),
+ );
+ const captures = [];
+ const send = connection.send.bind(connection);
+ connection.send = (...args) => {
+ const result = send(...args);
+ if (args[0] !== "Page.captureScreenshot") return result;
+ return result.then((reply) => {
+ captures.push({ params: args[1], data: reply.data });
+ return reply;
+ });
+ };
+ try {
+ await assert.rejects(
+ captureCdpScreenshot({
+ connection,
+ discovery,
+ target,
+ input: {
+ cdp_endpoint: endpoint,
+ target_id: target.id,
+ allowed_origins: [origin],
+ },
+ }),
+ (error) => error.reason === "target_changed",
+ "Recovery must reject a viewport changed by another session",
+ );
+ } finally {
+ connection.send = send;
+ }
+ assert.equal(
+ captures.length,
+ 2,
+ "Fixture must exercise cropped recovery",
+ );
+ assert.equal(captures[0].params.captureBeyondViewport, false);
+ assert.equal(captures[0].params.clip, undefined);
+ assert.equal(captures[1].params.captureBeyondViewport, true);
+ assert.ok(captures[1].params.clip, "Recovery must use an explicit clip");
+ const expectedViewport = {
+ width: Math.round(visualViewport.clientWidth * visualViewport.scale),
+ height: Math.round(visualViewport.clientHeight * visualViewport.scale),
+ };
+ const initialBytes = Buffer.from(captures[0].data, "base64");
+ assert.ok(
+ initialBytes.readUInt32BE(16) < expectedViewport.width ||
+ initialBytes.readUInt32BE(20) < expectedViewport.height,
+ "First production capture must actually be undersized",
+ );
+ const recovered = createWebScreenshotArtifact(
+ Buffer.from(captures[1].data, "base64"),
+ );
+ const control = await connection.send("Page.captureScreenshot", {
+ format: "png",
+ fromSurface: true,
+ captureBeyondViewport: true,
+ clip: {
+ x: cssVisualViewport.pageX,
+ y: cssVisualViewport.pageY,
+ width: cssVisualViewport.clientWidth,
+ height: cssVisualViewport.clientHeight,
+ scale: cssVisualViewport.scale,
+ },
+ });
+ const compared = comparePngScreenshots({
+ before: recovered,
+ after: createWebScreenshotArtifact(Buffer.from(control.data, "base64")),
+ channel_threshold: 0,
+ });
+ assert.equal(
+ compared.status,
+ "identical",
+ `Viewport capture must retain every control pixel: ${JSON.stringify({ scale, compared })}`,
+ );
+ // A stable, same-session viewport must still return a normal screenshot.
+ await connection.send("Emulation.setDeviceMetricsOverride", {
+ width: 1280,
+ height: 720,
+ deviceScaleFactor: 0,
+ mobile: false,
+ });
+ await connection.send("Emulation.setPageScaleFactor", {
+ pageScaleFactor: scale,
+ });
+ const screenshot = await captureCdpScreenshot({
+ connection,
+ discovery,
+ target,
+ input: {
+ cdp_endpoint: endpoint,
+ target_id: target.id,
+ allowed_origins: [origin],
+ },
+ });
+ assert.deepEqual(screenshot.viewport, expectedViewport);
+ assert.equal(
+ comparePngScreenshots({
+ before: screenshot.artifact,
+ after: recovered,
+ channel_threshold: 0,
+ }).status,
+ "identical",
+ );
+ cases.push({
+ page_scale: scale,
+ viewport: screenshot.viewport,
+ pixel_control: "identical",
+ clipped_recovery: true,
+ changed_viewport_rejected: true,
+ stable_viewport_accepted: true,
+ });
+ }
+ return {
+ mocked: false,
+ boundary: "captureCdpScreenshot",
+ external_session_emulation: true,
+ cases,
+ };
+ } finally {
+ try {
+ if (connection !== undefined) await connection.close();
+ } finally {
+ try {
+ await context.close();
+ } finally {
+ await browser.close();
+ }
+ }
+ }
+}
diff --git a/scripts/verify-real-browser.mjs b/scripts/verify-real-browser.mjs
index 5c199b9eb..3dec8b42d 100644
--- a/scripts/verify-real-browser.mjs
+++ b/scripts/verify-real-browser.mjs
@@ -42,6 +42,7 @@ import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
import { closeVerifierResources } from "./lib/verifier-cleanup.mjs";
import { requireOrdinaryWindowsVerifierCaller } from "./lib/windows-ordinary-user-verifier.mjs";
import { verifyLargeScreenshotE2e } from "./lib/browser-screenshot-e2e.mjs";
+import { verifyViewportScreenshotE2e } from "./lib/browser-viewport-screenshot-e2e.mjs";
import { verifyPopupEventCoverage } from "./lib/browser-popup-e2e.mjs";
import { verifyBrowserNetworkEvidence } from "./lib/browser-network-e2e.mjs";
import { verifyBrowserScriptExport } from "./lib/browser-script-export-e2e.mjs";
@@ -372,6 +373,11 @@ try {
process.stderr.write("Browser verifier: large screenshot\n");
const largeScreenshot = await verifyLargeScreenshotE2e(endpoint, site.origin);
+ process.stderr.write("Browser verifier: visual viewport screenshot\n");
+ const viewportScreenshot = await verifyViewportScreenshotE2e(
+ endpoint,
+ site.origin,
+ );
process.stderr.write("Browser verifier: popup coverage\n");
const popupEvents = await verifyPopupEventCoverage(executable);
const networkEvidence = await verifyBrowserNetworkEvidence(
@@ -423,6 +429,7 @@ try {
scenarioStorage,
scenarioStorageFingerprints,
scenarioServiceWorkers,
+ viewportScreenshot,
verified: true,
};
} catch (cause) {
diff --git a/src/browser/CdpScreenshot.ts b/src/browser/CdpScreenshot.ts
index 59a9e7768..172d06b05 100644
--- a/src/browser/CdpScreenshot.ts
+++ b/src/browser/CdpScreenshot.ts
@@ -12,6 +12,7 @@ import {
allowedSanitizedUrl,
recordValue,
cdpStringValue,
+ numberValue,
} from "./CdpCaptureValues.js";
import { mainFrameUrl } from "./CdpCaptureDocuments.js";
import { captureFrames } from "./CdpCaptureDocuments.js";
@@ -73,17 +74,45 @@ export const captureCdpScreenshot = async (
if (event.sessionId !== context.sessionId) return;
observeScreenshotNavigation(event, origins, navigation);
});
- let result: ReturnType<typeof recordValue>;
+ const assertCurrentDocument = () => {
+ if (navigation.invalidIdentity)
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ if (navigation.leftScope)
+ throw new BrowserObservationError(
+ "inspect_web_page",
+ "target_not_allowed",
+ );
+ if (navigation.changed)
+ throw new BrowserObservationError("inspect_web_page", "target_changed");
+ };
+ let screenshot: Awaited<ReturnType<typeof captureScreenshotImage>>;
let after: unknown;
try {
- result = recordValue(
- await context.connection.send(
- "Page.captureScreenshot",
- { format: "png", fromSurface: true, captureBeyondViewport: false },
- context.sessionId,
- context.signal,
- ),
- );
+ const viewport = await readScreenshotViewport(context);
+ assertCurrentDocument();
+ screenshot = await captureScreenshotImage(context);
+ assertCurrentDocument();
+ const currentViewport = await readScreenshotViewport(context);
+ assertCurrentDocument();
+ assertSameViewport(viewport, currentViewport);
+ if (!coversViewport(screenshot, currentViewport)) {
+ // Refresh geometry before clipping, and reject a moving viewport rather
+ // than capture a region that is no longer visible.
+ screenshot = await captureScreenshotImage(context, currentViewport.clip);
+ assertCurrentDocument();
+ const recoveredViewport = await readScreenshotViewport(context);
+ assertCurrentDocument();
+ assertSameViewport(currentViewport, recoveredViewport);
+ if (!coversViewport(screenshot, recoveredViewport))
+ throw new BrowserObservationError(
+ "inspect_web_page",
+ "protocol_error",
+ {
+ detail:
+ "The screenshot does not cover the reported visual viewport.",
+ },
+ );
+ }
after = await context.connection.send(
"Page.getFrameTree",
{},
@@ -93,16 +122,9 @@ export const captureCdpScreenshot = async (
} finally {
removeListener();
}
- const screenshot = decodeScreenshot(result);
- if (screenshot === undefined)
- throw new BrowserObservationError("inspect_web_page", "protocol_error");
- if (navigation.invalidIdentity)
- throw new BrowserObservationError("inspect_web_page", "protocol_error");
- if (navigation.leftScope)
- throw new BrowserObservationError("inspect_web_page", "target_not_allowed");
+ assertCurrentDocument();
const afterUrl = mainFrameUrl(after);
if (
- navigation.changed ||
afterUrl !== beforeUrl ||
allowedSanitizedUrl(afterUrl, origins) === undefined
)
@@ -132,6 +154,120 @@ export const captureCdpScreenshot = async (
};
};
+/** Parse CSS clip geometry and device-pixel coverage at their owning boundary. */
+const readScreenshotViewport = async (context: ScreenshotContext) => {
+ const metrics = recordValue(
+ await context.connection.send(
+ "Page.getLayoutMetrics",
+ {},
+ context.sessionId,
+ context.signal,
+ ),
+ );
+ const visualViewport = recordValue(metrics?.visualViewport);
+ const cssViewport = recordValue(metrics?.cssVisualViewport);
+ const pageX = numberValue(cssViewport?.pageX);
+ const pageY = numberValue(cssViewport?.pageY);
+ const width = numberValue(cssViewport?.clientWidth);
+ const height = numberValue(cssViewport?.clientHeight);
+ const scale = numberValue(cssViewport?.scale);
+ const pixelWidth = numberValue(visualViewport?.clientWidth);
+ const pixelHeight = numberValue(visualViewport?.clientHeight);
+ const pixelScale = numberValue(visualViewport?.scale);
+ if (
+ pageX === undefined ||
+ pageY === undefined ||
+ width === undefined ||
+ height === undefined ||
+ scale === undefined ||
+ pixelWidth === undefined ||
+ pixelHeight === undefined ||
+ pixelScale !== scale ||
+ width <= 0 ||
+ height <= 0 ||
+ scale <= 0 ||
+ pixelWidth <= 0 ||
+ pixelHeight <= 0
+ )
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ // Keep ordinary surface captures, including their scrollbars and pixel
+ // density. The visual viewport excludes scrollbars and supplies only a
+ // lower bound on the expected image size, allowing subpixel rounding.
+ const minimumWidth = Math.max(1, Math.floor(pixelWidth * scale));
+ const minimumHeight = Math.max(1, Math.floor(pixelHeight * scale));
+ if (
+ !Number.isSafeInteger(minimumWidth) ||
+ !Number.isSafeInteger(minimumHeight)
+ )
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ return {
+ clip: { x: pageX, y: pageY, width, height, scale },
+ pixelWidth,
+ pixelHeight,
+ minimumWidth,
+ minimumHeight,
+ };
+};
+
+type ScreenshotViewport = Awaited<ReturnType<typeof readScreenshotViewport>>;
+
+const coversViewport = (
+ image: Awaited<ReturnType<typeof captureScreenshotImage>>,
+ viewport: ScreenshotViewport,
+) =>
+ image.dimensions.width >= viewport.minimumWidth &&
+ image.dimensions.height >= viewport.minimumHeight;
+
+const assertSameViewport = (
+ before: ScreenshotViewport,
+ after: ScreenshotViewport,
+): void => {
+ if (
+ before.clip.x !== after.clip.x ||
+ before.clip.y !== after.clip.y ||
+ before.clip.width !== after.clip.width ||
+ before.clip.height !== after.clip.height ||
+ before.clip.scale !== after.clip.scale ||
+ before.pixelWidth !== after.pixelWidth ||
+ before.pixelHeight !== after.pixelHeight
+ )
+ throw new BrowserObservationError("inspect_web_page", "target_changed", {
+ detail: "The visual viewport changed during screenshot capture.",
+ });
+};
+
+interface ScreenshotClip {
+ readonly x: number;
+ readonly y: number;
+ readonly width: number;
+ readonly height: number;
+ readonly scale: number;
+}
+
+/** Decode every capture at the same boundary, including a clipped recovery. */
+const captureScreenshotImage = async (
+ context: ScreenshotContext,
+ clip?: ScreenshotClip,
+) => {
+ const result = recordValue(
+ await context.connection.send(
+ "Page.captureScreenshot",
+ {
+ format: "png",
+ fromSurface: true,
+ captureBeyondViewport: clip !== undefined,
+ ...(clip === undefined ? {} : { clip }),
+ },
+ context.sessionId,
+ context.signal,
+ ),
+ );
+ const screenshot = decodeScreenshot(result);
+ if (screenshot === undefined)
+ throw new BrowserObservationError("inspect_web_page", "protocol_error");
+ return screenshot;
+};
+
const decodeScreenshot = (
result: ReturnType<typeof recordValue>,
):
diff --git a/tests/boundary/browser/cdpScreenshotDocumentIdentity.test.ts b/tests/boundary/browser/cdpScreenshotDocumentIdentity.test.ts
index 665776929..33074bfbd 100644
--- a/tests/boundary/browser/cdpScreenshotDocumentIdentity.test.ts
+++ b/tests/boundary/browser/cdpScreenshotDocumentIdentity.test.ts
@@ -19,6 +19,537 @@ const captureWithFake = async (options: FakeOptions) => {
);
return { browser, result };
};
+
+// These wire tests validate PNG headers; actual rendering has its own browser lane.
+const screenshotData = (width: number, height: number) => {
+ const bytes = Buffer.from(
+ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
+ "base64",
+ );
+ bytes.writeUInt32BE(width, 16);
+ bytes.writeUInt32BE(height, 20);
+ return { data: bytes.toString("base64") };
+};
+
+const withCssViewport = (metrics: Readonly<Record<string, unknown>>) => ({
+ ...metrics,
+ cssVisualViewport: metrics.visualViewport,
+});
+
+describe("screenshot authorization during metrics reads", () => {
+ it.each([
+ { stage: 1, expectedCaptures: 0 },
+ { stage: 2, expectedCaptures: 1 },
+ ])(
+ "stops capture after scope loss during metrics read $stage",
+ async ({ stage, expectedCaptures }) => {
+ let reads = 0;
+ const { browser, result } = await captureWithFake({
+ eventsBeforeReply: ["Page.getLayoutMetrics"],
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 2,
+ clientHeight: 2,
+ scale: 1,
+ },
+ })
+ : undefined,
+ commandEvents: (command) =>
+ command.method === "Page.getLayoutMetrics" && ++reads === stage
+ ? [
+ frameNavigated(command, {
+ id: "frame-main",
+ loaderId: "outside-loader",
+ url: "https://outside.test/",
+ }),
+ ]
+ : undefined,
+ });
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "target_not_allowed" },
+ });
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(expectedCaptures);
+ await expect.poll(() => browser.activeConnectionCount()).toBe(0);
+ },
+ );
+
+ it.each(["navigation", "uncertain identity"])(
+ "stops before the first screenshot after %s during metrics",
+ async (change) => {
+ const { browser, result } = await captureWithFake({
+ eventsBeforeReply: ["Page.getLayoutMetrics"],
+ commandEvents: (command, origin) =>
+ command.method === "Page.getLayoutMetrics"
+ ? [
+ frameNavigated(
+ command,
+ change === "navigation"
+ ? {
+ id: "frame-main",
+ loaderId: "new-loader",
+ url: `${origin}/app`,
+ }
+ : {
+ id: "candidate-root",
+ parentId: "candidate-root",
+ url: `${origin}/app`,
+ },
+ ),
+ ]
+ : undefined,
+ });
+ expect(result).toMatchObject({
+ ok: false,
+ error: {
+ reason: change === "navigation" ? "target_changed" : "protocol_error",
+ },
+ });
+ expect(
+ browser.commands.some(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toBe(false);
+ },
+ );
+});
+
+describe("screenshot viewport freshness", () => {
+ it.each([
+ { phase: "normal capture", stage: 2, imageSize: 4, captures: 1 },
+ { phase: "before recovery", stage: 2, imageSize: 1, captures: 1 },
+ { phase: "during recovery", stage: 3, imageSize: 1, captures: 2 },
+ ])(
+ "rejects viewport changes $phase",
+ async ({ stage, imageSize, captures }) => {
+ let reads = 0;
+ const { browser, result } = await captureWithFake({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: ++reads >= stage ? 50 : 0,
+ clientWidth: 4,
+ clientHeight: 4,
+ scale: 1,
+ },
+ })
+ : method === "Page.captureScreenshot"
+ ? screenshotData(imageSize, imageSize)
+ : undefined,
+ });
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "target_changed" },
+ });
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(captures);
+ },
+ );
+
+ it.each([
+ { label: "resize", css: { clientWidth: 8 }, pixel: { clientWidth: 8 } },
+ { label: "zoom", css: { scale: 2 }, pixel: { scale: 2 } },
+ {
+ label: "device pixel density",
+ css: {},
+ pixel: { clientWidth: 8, clientHeight: 8 },
+ },
+ ])(
+ "rejects $label during recovery even when the image is large enough",
+ async ({ css, pixel }) => {
+ let reads = 0;
+ let captures = 0;
+ const base = {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 4,
+ clientHeight: 4,
+ scale: 1,
+ };
+ const { result } = await captureWithFake({
+ commandResult: ({ method }) => {
+ if (method === "Page.getLayoutMetrics") {
+ const changed = ++reads === 3;
+ return {
+ cssVisualViewport: { ...base, ...(changed ? css : {}) },
+ visualViewport: { ...base, ...(changed ? pixel : {}) },
+ };
+ }
+ return method === "Page.captureScreenshot"
+ ? ++captures === 1
+ ? screenshotData(1, 1)
+ : screenshotData(16, 16)
+ : undefined;
+ },
+ });
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "target_changed" },
+ });
+ expect(captures).toBe(2);
+ },
+ );
+
+ it.each([2, 3])("validates refreshed metrics read %s", async (stage) => {
+ let reads = 0;
+ const { browser, result } = await captureWithFake({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? ++reads === stage
+ ? {}
+ : withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 2,
+ clientHeight: 2,
+ scale: 1,
+ },
+ })
+ : undefined,
+ });
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "protocol_error" },
+ });
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(stage - 1);
+ });
+});
+
+describe("screenshot visual viewport capture", () => {
+ it("recovers a cropped surface using the reported viewport clip and page scale", async () => {
+ let captures = 0;
+ const browser = await startFakeCdpBrowser({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 12,
+ pageY: 34,
+ clientWidth: 640,
+ clientHeight: 360,
+ scale: 2,
+ },
+ })
+ : method === "Page.captureScreenshot"
+ ? ++captures === 1
+ ? screenshotData(320, 180)
+ : screenshotData(1280, 720)
+ : undefined,
+ });
+ onTestFinished(async () => {
+ await browser.close();
+ });
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ }),
+ );
+ expect(result.ok).toBe(true);
+ const layoutMetrics = browser.commands.findIndex(
+ ({ method }) => method === "Page.getLayoutMetrics",
+ );
+ const screenshotIndex = browser.commands.findIndex(
+ ({ method }) => method === "Page.captureScreenshot",
+ );
+ expect(layoutMetrics).toBeGreaterThanOrEqual(0);
+ expect(screenshotIndex).toBeGreaterThan(layoutMetrics);
+ const screenshots = browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ );
+ expect(screenshots).toHaveLength(2);
+ expect(screenshots[0]?.params).toMatchObject({
+ captureBeyondViewport: false,
+ });
+ expect(screenshots[0]?.params).not.toHaveProperty("clip");
+ expect(screenshots[1]?.params).toMatchObject({
+ fromSurface: true,
+ captureBeyondViewport: true,
+ clip: { x: 12, y: 34, width: 640, height: 360, scale: 2 },
+ });
+ if (!result.ok) throw result.error;
+ expect(result.value.viewport).toEqual({ width: 1280, height: 720 });
+ });
+});
+
+describe("screenshot CSS and device-pixel coordinates", () => {
+ it("uses CSS clip coordinates when the reported viewport has twice as many device pixels", async () => {
+ let captures = 0;
+ const browser = await startFakeCdpBrowser({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? {
+ cssVisualViewport: {
+ pageX: 12,
+ pageY: 34,
+ clientWidth: 640,
+ clientHeight: 360,
+ scale: 1,
+ },
+ visualViewport: {
+ pageX: 24,
+ pageY: 68,
+ clientWidth: 1280,
+ clientHeight: 720,
+ scale: 1,
+ },
+ }
+ : method === "Page.captureScreenshot"
+ ? ++captures === 1
+ ? screenshotData(800, 400)
+ : screenshotData(1280, 720)
+ : undefined,
+ });
+ onTestFinished(() => browser.close());
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ }),
+ );
+ expect(result.ok).toBe(true);
+ const screenshots = browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ );
+ expect(screenshots).toHaveLength(2);
+ expect(screenshots[1]?.params.clip).toEqual({
+ x: 12,
+ y: 34,
+ width: 640,
+ height: 360,
+ scale: 1,
+ });
+ });
+});
+
+describe("screenshot surface compatibility", () => {
+ it.each([
+ {
+ label: "scrollbars",
+ width: 2033,
+ height: 1521,
+ imageWidth: 2048,
+ imageHeight: 1536,
+ },
+ {
+ label: "higher pixel density",
+ width: 640,
+ height: 360,
+ imageWidth: 1280,
+ imageHeight: 720,
+ },
+ ])(
+ "preserves the original surface with $label",
+ async ({ width, height, imageWidth, imageHeight }) => {
+ const image = screenshotData(imageWidth, imageHeight);
+ const browser = await startFakeCdpBrowser({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: width,
+ clientHeight: height,
+ scale: 1,
+ },
+ })
+ : method === "Page.captureScreenshot"
+ ? image
+ : undefined,
+ });
+ onTestFinished(() => browser.close());
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ }),
+ );
+ if (!result.ok) throw result.error;
+ expect(result.value.viewport).toEqual({
+ width: imageWidth,
+ height: imageHeight,
+ });
+ expect(result.value.artifact.data_base64).toBe(image.data);
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(1);
+ },
+ );
+
+ it("refuses a clipped recovery that still omits visible content", async () => {
+ const browser = await startFakeCdpBrowser({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 2,
+ clientHeight: 2,
+ scale: 1,
+ },
+ })
+ : undefined,
+ });
+ onTestFinished(() => browser.close());
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ }),
+ );
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "protocol_error" },
+ });
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(2);
+ });
+
+ it("does not retry a cropped surface after the target leaves scope", async () => {
+ const browser = await startFakeCdpBrowser({
+ navigateDuringScreenshotUrl: "https://outside.test/",
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 2,
+ clientHeight: 2,
+ scale: 1,
+ },
+ })
+ : undefined,
+ });
+ onTestFinished(() => browser.close());
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ }),
+ );
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "target_not_allowed" },
+ });
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(1);
+ });
+});
+
+describe("screenshot viewport protocol validation", () => {
+ it.each([
+ ["missing metrics", {}],
+ [
+ "non-numeric coordinates",
+ {
+ visualViewport: {
+ pageX: "unknown",
+ pageY: 0,
+ clientWidth: 10,
+ clientHeight: 10,
+ scale: 1,
+ },
+ },
+ ],
+ [
+ "non-finite coordinates",
+ {
+ visualViewport: {
+ pageX: Number.POSITIVE_INFINITY,
+ pageY: 0,
+ clientWidth: 10,
+ clientHeight: 10,
+ scale: 1,
+ },
+ },
+ ],
+ [
+ "non-positive dimensions",
+ {
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 0,
+ clientHeight: 10,
+ scale: 1,
+ },
+ },
+ ],
+ [
+ "non-positive scale",
+ {
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 10,
+ clientHeight: 10,
+ scale: 0,
+ },
+ },
+ ],
+ ])("rejects %s before screenshot capture", async (_label, metrics) => {
+ const browser = await startFakeCdpBrowser({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport(metrics)
+ : undefined,
+ });
+ onTestFinished(async () => {
+ await browser.close();
+ });
+ const result = await new CdpBrowserProvider().captureScreenshot(
+ captureWebScreenshotInputSchema.parse({
+ cdp_endpoint: browser.endpoint,
+ allowed_origins: [browser.allowedOrigin],
+ target_id: "allowed-page",
+ }),
+ );
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "protocol_error" },
+ });
+ expect(
+ browser.commands.some(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toBe(false);
+ });
+});
+
describe("screenshot committed document identity", () => {
it.each([
["missing screenshot data", {}],
@@ -93,6 +624,42 @@ describe("screenshot committed document identity", () => {
});
describe("screenshot frame identity transitions", () => {
+ it("does not recover a cropped image after uncertain root identity", async () => {
+ const { browser, result } = await captureWithFake({
+ commandResult: ({ method }) =>
+ method === "Page.getLayoutMetrics"
+ ? withCssViewport({
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 2,
+ clientHeight: 2,
+ scale: 1,
+ },
+ })
+ : undefined,
+ commandEvents: (command, origin) =>
+ command.method === "Page.captureScreenshot"
+ ? [
+ frameNavigated(command, {
+ id: "candidate-root",
+ parentId: "candidate-root",
+ url: `${origin}/app`,
+ }),
+ ]
+ : undefined,
+ });
+ expect(result).toMatchObject({
+ ok: false,
+ error: { reason: "protocol_error" },
+ });
+ expect(
+ browser.commands.filter(
+ ({ method }) => method === "Page.captureScreenshot",
+ ),
+ ).toHaveLength(1);
+ });
+
it("rejects a self-parented root candidate as malformed identity", async () => {
const { browser, result } = await captureWithFake({
commandEvents: (command, origin) =>
diff --git a/tests/fixtures/fakeCdpBrowserResults.ts b/tests/fixtures/fakeCdpBrowserResults.ts
index 0ea85ed56..e60428b23 100644
--- a/tests/fixtures/fakeCdpBrowserResults.ts
+++ b/tests/fixtures/fakeCdpBrowserResults.ts
@@ -10,6 +10,23 @@ export const resultFor = (
switch (command.method) {
case "Target.attachToTarget":
return attachToTargetResult(options);
+ case "Page.getLayoutMetrics":
+ return {
+ cssVisualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 1,
+ clientHeight: 1,
+ scale: 1,
+ },
+ visualViewport: {
+ pageX: 0,
+ pageY: 0,
+ clientWidth: 1,
+ clientHeight: 1,
+ scale: 1,
+ },
+ };
case "Page.getFrameTree":
return frameTreeResult(port, options, frameTreeReads);
case "Page.getResourceTree":