From 146dcf46f5bd78fd4917aff663d1129d450f9e8f Mon Sep 17 00:00:00 2001
From: STDquantum <60764289+STDquantum@users.noreply.github.com>
Date: Fri, 23 Oct 2026 05:17:03 +0800
Subject: [PATCH] fix(browser): capture the full visual viewport (#5621)

* fix(browser): capture the full visual viewport

* fix(browser): preserve surface geometry and high-DPI screenshot bounds

* fix(browser): reject stale screenshot captures
---
 scripts/fixtures/browser-verifier-site.mjs    |   7 +
 .../lib/browser-viewport-screenshot-e2e.mjs   | 195 ++++++
 scripts/verify-real-browser.mjs               |   7 +
 src/browser/CdpScreenshot.ts                  | 170 +++++-
 .../cdpScreenshotDocumentIdentity.test.ts     | 567 ++++++++++++++++++
 tests/fixtures/fakeCdpBrowserResults.ts       |  17 +
 6 files changed, 946 insertions(+), 17 deletions(-)
 create mode 100644 scripts/lib/browser-viewport-screenshot-e2e.mjs

diff --git a/scripts/fixtures/browser-verifier-site.mjs b/scripts/fixtures/browser-verifier-site.mjs
index db660699d8..b86c04fa31 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 0000000000..70945f629c
--- /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 5c199b9eb8..3dec8b42d1 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 59a9e7768d..172d06b055 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 6657769292..33074bfbd4 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 0ea85ed569..e60428b232 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":