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";
 
@@ -287,3 +296,23 @@ 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({} as Page, cdp, {
+        format: "jpeg",
+        scale: 1,
+      }).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

@@ -201,6 +201,8 @@ const withoutTreeDataPayloads = (tree: string) =>
 const SNAPSHOT_TIMEOUT_MS = 10_000;
 // How long a frame in another process gets to answer; one that crashed never does.
 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;
 
 // Values the page draws as dots (password fields, and text fields whose CSS
 // draws dots), normalized like accessible text. Open shadow roots included.
@@ -234,6 +236,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.";
 
 /** A frame in another process keeps one CDP session, so none pile up across snapshots. */
@@ -469,18 +477,15 @@ const readPageMetrics = async (cdp: CDPSession) => {
   );
 };
 
-// Scaled captures repaint live screencasts, so callers pause them. Clips use document offsets.
-export const captureViewport = async (
-  page: Page,
-  cdp: CDPSession,
-  options: {
-    readonly format: "png" | "jpeg";
-    readonly quality?: number;
-    readonly scale: number;
-    readonly viewport?: Viewport;
-    readonly offset?: { readonly x: number; readonly y: number } | undefined;
-  },
-) => {
+type CaptureOptions = {
+  readonly format: "png" | "jpeg";
+  readonly quality?: number;
+  readonly scale: number;
+  readonly viewport?: Viewport;
+  readonly offset?: { readonly x: number; readonly y: number } | undefined;
+};
+
+const readViewport = async (page: Page, cdp: CDPSession, options: CaptureOptions) => {
   let clip;
   if (options.scale < 1) {
     const viewport = options.viewport ?? page.viewportSize() ?? { width: 1280, height: 800 };
@@ -504,6 +509,19 @@ export const captureViewport = async (
   return data;
 };
 
+// Scaled captures repaint live screencasts, so callers pause them. Clips use document offsets.
+export const captureViewport = async (page: Page, cdp: CDPSession, options: CaptureOptions) => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(noFrame()), CAPTURE_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([readViewport(page, cdp, options), expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
 type SnapshotInput = {
   readonly page: Page;
   readonly cdp: CDPSession;