fix(server): a preview capture that never answers no longer blocks the tab

apps/server/src/preview/ServerBrowserPage.test.ts

@@ -5,7 +5,16 @@ import {
   type CDPSession,
   type Page,
 } from "playwright-core";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vite-plus/test";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vite-plus/test";
 
 import * as ServerBrowserPage from "./ServerBrowserPage.ts";
 
@@ -388,3 +397,20 @@ describe("server browser drag", () => {
     }
   });
 });
+
+describe("server browser capture", () => {
+  it("fails a capture the page never answers instead of waiting for it", async () => {
+    vi.useFakeTimers();
+    try {
+      const cdp = { send: () => new Promise(() => {}) } as unknown as CDPSession;
+      const capture = ServerBrowserPage.captureViewport(cdp, { format: "jpeg" }).then(
+        () => null,
+        (error: unknown) => error,
+      );
+      await vi.advanceTimersByTimeAsync(5_000);
+      expect(await capture).toMatchObject({ tag: "PreviewAutomationTimeoutError" });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

apps/server/src/preview/ServerBrowserPage.ts

@@ -206,6 +206,8 @@ const withoutTreeDataPayloads = (tree: string) =>
 // The broker waits 15s for the host; a snapshot, retry included, answers well before.
 const SNAPSHOT_TIMEOUT_MS = 10_000;
 const FRAME_ANSWER_MS = 1_000;
+// A tab that draws no frames never answers a screenshot, and callers hold the tab's queue while waiting.
+const CAPTURE_TIMEOUT_MS = 5_000;
 
 // Include password and CSS-masked text in open shadow roots, normalized like accessible text.
 const DOTTED_SCRIPT = `(() => {
@@ -238,6 +240,12 @@ const tooBusy = () =>
     "The page was too busy to capture a snapshot in time. Wait for it to settle and take another snapshot.",
   );
 
+const noFrame = () =>
+  new ServerBrowserOperationError(
+    "PreviewAutomationTimeoutError",
+    "The page drew no frame to capture in time. Try again once the tab is showing or has settled.",
+  );
+
 const VALUE_TOO_LONG = "A password field holds a value too long to hide, so no snapshot was taken.";
 
 /** Reuse one CDP session per out-of-process frame across snapshots. */
@@ -450,11 +458,19 @@ export const captureViewport = async (
   cdp: CDPSession,
   options: { readonly format: "png" | "jpeg"; readonly quality?: number },
 ) => {
-  const { data } = await cdp.send("Page.captureScreenshot", {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(noFrame()), CAPTURE_TIMEOUT_MS);
+  });
+  const captured = cdp.send("Page.captureScreenshot", {
     format: options.format,
     ...(options.quality === undefined ? {} : { quality: options.quality }),
   });
-  return data;
+  try {
+    return (await Promise.race([captured, expired])).data;
+  } finally {
+    clearTimeout(timer);
+  }
 };
 
 /** Runs in the page's own isolated world, as the server has no image library. */