@devries-cameron20 / t3code-1 / commits / 2e8b5b9de0
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(server): desktop-drawn preview snapshots match the page's scale and viewport (#19913)

Co-authored-by: Julius Marminge <julius@t3.gg> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: Julius Marminge <julius0216@outlook.com>

Scott Norteman committed Oct 20, 2026 at 01:08 UTC 2e8b5b9de0b9ccbff5aa2d46db3021f061d3c64f
4 files changed +260 -13
apps/server/src/preview/ServerBrowser.test.ts
+112 -1
@@ -75,6 +75,14 @@ function makeFrame() {
75 return frame;
76 }
77
78 +const PNG_HEADER = (() => {
79 + const header = Buffer.alloc(24);
80 + header.write("IHDR", 12);
81 + header.writeUInt32BE(1280, 16);
82 + header.writeUInt32BE(800, 20);
83 + return header.toString("base64");
84 +})();
85 +
86 function makeSession(frame?: ReturnType<typeof makeFrame>) {
87 const events = new NodeEvents.EventEmitter();
88 return {
@@ -84,7 +92,10 @@ function makeSession(frame?: ReturnType<typeof makeFrame>) {
92 send: vi.fn(async (method: string, input?: unknown): Promise<Record<string, unknown>> => {
93 if (method === "Page.getNavigationHistory") return { currentIndex: 0, entries: [{}] };
94 if (method === "Page.getLayoutMetrics") return { cssVisualViewport: { pageX: 0, pageY: 0 } };
87 - if (method === "Page.captureScreenshot") return { data: "ZnJhbWU=" };
95 + if (method === "Page.captureScreenshot") {
96 + // A snapshot sizes its screenshot from the PNG header; viewers get JPEG frames as-is.
97 + return { data: (input as { format: string }).format === "png" ? PNG_HEADER : "ZnJhbWU=" };
98 + }
99 if (method === "Page.getFrameTree") return { frameTree: { frame: { id: "main" } } };
100 // Snapshots read password fields from their own isolated world in each frame.
101 if (method === "Page.createIsolatedWorld") {
@@ -2264,3 +2275,103 @@ it.live("a desktop page that comes back reconnects without waiting for a viewer"
2275 }),
2276 ).pipe(Effect.provide(layer)),
2277 );
2278 +
2279 +// Chromium sizes a capture by the clip, its scale, and the display ratio net of page zoom.
2280 +it.live.each([
2281 + {
2282 + name: "desktop at display ratio 1.5",
2283 + desktop: true,
2284 + page: { ratio: 1.5, width: 1280, height: 800, zoom: 1 },
2285 + scrollY: 0,
2286 + size: { width: 1280, height: 800 },
2287 + clipY: 0,
2288 + },
2289 + {
2290 + name: "desktop resized to a phone",
2291 + desktop: true,
2292 + page: { ratio: 1, width: 390, height: 844, zoom: 1 },
2293 + scrollY: 0,
2294 + size: { width: 390, height: 844 },
2295 + clipY: undefined,
2296 + },
2297 + {
2298 + name: "desktop zoom changes during a scrolled snapshot",
2299 + desktop: true,
2300 + page: { ratio: 3, width: 640, height: 400, zoom: 2 },
2301 + scrollY: 100,
2302 + size: { width: 1280, height: 800 },
2303 + clipY: 200,
2304 + },
2305 + {
2306 + name: "headless",
2307 + desktop: false,
2308 + page: { ratio: 2, width: 1280, height: 800, zoom: 1 },
2309 + scrollY: 0,
2310 + size: { width: 640, height: 400 },
2311 + clipY: 0,
2312 + },
2313 +])("snapshot captures the page's own viewport: $name", ({ desktop, page, scrollY, size, clipY }) =>
2314 + Effect.scoped(
2315 + Effect.gen(function* () {
2316 + desktopRendersNext = desktop;
2317 + const { browser, broker, tabId } = yield* ready;
2318 + yield* browser.attachViewer(viewerInput(tabId, false));
2319 + const context = desktop ? desktopConnections[0]!.context : contexts[0]!;
2320 + const display = desktop ? page.ratio / page.zoom : 1;
2321 + let zoom = 1;
2322 + const clips: Array<{ y: number } | undefined> = [];
2323 + let metricsReads = 0;
2324 + for (const session of context.sessions) {
2325 + const send = session.send.getMockImplementation()!;
2326 + session.send.mockImplementation(async (method, input) => {
2327 + if (
2328 + method === "Runtime.evaluate" &&
2329 + String((input as { expression?: string })?.expression).includes("devicePixelRatio")
2330 + ) {
2331 + metricsReads += 1;
2332 + const value = {
2333 + ratio: page.ratio * (zoom / page.zoom),
2334 + width: page.width * (page.zoom / zoom),
2335 + height: page.height * (page.zoom / zoom),
2336 + };
2337 + // Desktop zoom applies after this renderer read, before the next layout reply.
2338 + zoom = page.zoom;
2339 + return { result: { value } };
2340 + }
2341 + if (method === "Page.getLayoutMetrics") {
2342 + return { cssVisualViewport: { pageX: 0, pageY: scrollY, zoom } };
2343 + }
2344 + if (method === "Page.captureScreenshot") {
2345 + const clip = (
2346 + input as { clip?: { y: number; width: number; height: number; scale: number } }
2347 + )?.clip;
2348 + clips.push(clip);
2349 + const header = Buffer.alloc(24);
2350 + header.write("IHDR", 12);
2351 + header.writeUInt32BE(
2352 + Math.round((clip ? clip.width * clip.scale : page.width * page.zoom) * display),
2353 + 16,
2354 + );
2355 + header.writeUInt32BE(
2356 + Math.round((clip ? clip.height * clip.scale : page.height * page.zoom) * display),
2357 + 20,
2358 + );
2359 + return { data: header.toString("base64") };
2360 + }
2361 + return send(method, input);
2362 + });
2363 + }
2364 + const result = yield* broker.invoke<PreviewAutomationSnapshot>({
2365 + scope,
2366 + tabId,
2367 + operation: "snapshot",
2368 + input: {},
2369 + });
2370 + const png = Buffer.from(result.screenshot.data, "base64");
2371 + expect(result.screenshot).toMatchObject(size);
2372 + expect({ width: png.readUInt32BE(16), height: png.readUInt32BE(20) }).toEqual(size);
2373 + expect(clips.map((clip) => clip?.y)).toEqual([clipY]);
2374 + if (!desktop) expect(metricsReads).toBe(0);
2375 + }),
2376 + ).pipe(Effect.provide(layer)),
2377 +);
apps/server/src/preview/ServerBrowser.ts
+4 -1
@@ -1961,7 +1961,10 @@ const make = Effect.gen(function* () {
1961 }
1962 case "snapshot": {
1963 return withScreencastsPaused(tab, () =>
1964 - ServerBrowserPage.snapshot({ ...tab, renderScale: RENDER_SCALE }),
1964 + ServerBrowserPage.snapshot({
1965 + ...tab,
1966 + renderScale: tab.desktop ? "display" : RENDER_SCALE,
1967 + }),
1968 );
1969 }
1970 case "click": {
apps/server/src/preview/ServerBrowserPage.test.ts
+55
@@ -369,3 +369,58 @@ describe("server browser drag", () => {
369 }
370 });
371 });
372 +
373 +it("captures the native display viewport after page script reassigns the globals", async () => {
374 + // Context deviceScaleFactor changes DPR but does not scale raw CDP captures.
375 + const browser = await chromium.launch({
376 + headless: true,
377 + args: ["--force-device-scale-factor=1.5", "--window-size=1280,800"],
378 + });
379 + try {
380 + const context = await browser.newContext({ viewport: null });
381 + const page = await context.newPage();
382 + const cdp = await context.newCDPSession(page);
383 + await page.setContent(
384 + "<script>devicePixelRatio = -1.5; innerWidth = 99999; innerHeight = 1e7;</script>",
385 + );
386 + expect(await page.evaluate("[devicePixelRatio, innerWidth, innerHeight]")).toEqual([
387 + -1.5, 99999, 1e7,
388 + ]);
389 + const snapshotSize = async () => {
390 + const { screenshot } = await ServerBrowserPage.snapshot({
391 + page,
392 + cdp,
393 + renderScale: "display",
394 + consoleEntries: [],
395 + networkEntries: [],
396 + actionTimeline: [],
397 + });
398 + const png = Buffer.from(screenshot.data, "base64");
399 + const size = { width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
400 + expect(screenshot).toMatchObject(size);
401 + return size;
402 + };
403 + expect(await snapshotSize()).toEqual({ width: 1280, height: 800 });
404 + expect(await ServerBrowserPage.readPageMetrics(cdp)).toEqual({
405 + ratio: 1.5,
406 + width: 1280,
407 + height: 800,
408 + zoom: 1,
409 + offset: { x: 0, y: 0 },
410 + });
411 + const { windowId } = await cdp.send("Browser.getWindowForTarget");
412 + // CDP acknowledges the bounds change before the renderer applies the resize.
413 + const resize = await page.evaluateHandle(`({
414 + done: new Promise(resolve => window.addEventListener("resize", () => resolve(), { once: true })),
415 + })`);
416 + await cdp.send("Browser.setWindowBounds", {
417 + windowId,
418 + bounds: { width: 390, height: 844 },
419 + });
420 + await resize.evaluate("resize => resize.done");
421 + await resize.dispose();
422 + expect(await snapshotSize()).toEqual({ width: 585, height: 1266 });
423 + } finally {
424 + await browser.close();
425 + }
426 +});
apps/server/src/preview/ServerBrowserPage.ts
+89 -11
@@ -373,19 +373,77 @@ const maskTree = (tree: string, dotted: RegExp) =>
373 })
374 .join("\n");
375
376 +/** Chromium sizes the capture, so the reported size is read from the PNG header. */
377 +const pngSize = (base64: string) => {
378 + const header = Buffer.from(base64.slice(0, 32), "base64");
379 + return { width: header.readUInt32BE(16), height: header.readUInt32BE(20) };
380 +};
381 +
382 +type Viewport = { readonly width: number; readonly height: number };
383 +
384 +/**
385 + * A page's display ratio and CSS viewport, read in an isolated world since page script can
386 + * reassign `devicePixelRatio`, `innerWidth`, and `innerHeight` in its own, and its page zoom.
387 + */
388 +export const readPageMetrics = async (cdp: CDPSession) => {
389 + const { frameTree } = await cdp.send("Page.getFrameTree");
390 + const { executionContextId } = await cdp.send("Page.createIsolatedWorld", {
391 + frameId: frameTree.frame.id,
392 + worldName: "t3-preview-metrics",
393 + });
394 + let { cssVisualViewport } = await cdp.send("Page.getLayoutMetrics");
395 + // Desktop zoom applies asynchronously; bracket the CSS metrics to reject a torn read.
396 + for (let attempt = 0; attempt < 3; attempt += 1) {
397 + const zoom = cssVisualViewport.zoom ?? 1;
398 + const { result } = await cdp.send("Runtime.evaluate", {
399 + expression: "({ ratio: devicePixelRatio, width: innerWidth, height: innerHeight })",
400 + contextId: executionContextId,
401 + returnByValue: true,
402 + });
403 + ({ cssVisualViewport } = await cdp.send("Page.getLayoutMetrics"));
404 + if ((cssVisualViewport.zoom ?? 1) === zoom) {
405 + const { ratio, width, height } = result.value as {
406 + readonly ratio: number;
407 + readonly width: number;
408 + readonly height: number;
409 + };
410 + return {
411 + ratio,
412 + width,
413 + height,
414 + zoom,
415 + offset: { x: cssVisualViewport.pageX * zoom, y: cssVisualViewport.pageY * zoom },
416 + };
417 + }
418 + }
419 + throw new Error(
420 + "The page's zoom kept changing while the snapshot read its size. Try the snapshot again.",
421 + );
422 +};
423 +
424 // Scaled captures repaint live screencasts, so callers pause them. Clips use document offsets.
425 export const captureViewport = async (
426 page: Page,
427 cdp: CDPSession,
380 - options: { readonly format: "png" | "jpeg"; readonly quality?: number; readonly scale: number },
428 + options: {
429 + readonly format: "png" | "jpeg";
430 + readonly quality?: number;
431 + readonly scale: number;
432 + readonly viewport?: Viewport;
433 + readonly offset?: { readonly x: number; readonly y: number } | undefined;
434 + },
435 ) => {
436 let clip;
437 if (options.scale < 1) {
384 - const viewport = page.viewportSize() ?? { width: 1280, height: 800 };
385 - const { cssVisualViewport } = await cdp.send("Page.getLayoutMetrics");
438 + const viewport = options.viewport ?? page.viewportSize() ?? { width: 1280, height: 800 };
439 + let offset = options.offset;
440 + if (!offset) {
441 + const { cssVisualViewport } = await cdp.send("Page.getLayoutMetrics");
442 + const zoom = cssVisualViewport.zoom ?? 1;
443 + offset = { x: cssVisualViewport.pageX * zoom, y: cssVisualViewport.pageY * zoom };
444 + }
445 clip = {
387 - x: cssVisualViewport.pageX,
388 - y: cssVisualViewport.pageY,
446 + ...offset,
447 ...viewport,
448 scale: options.scale,
449 };
@@ -401,18 +459,39 @@ export const captureViewport = async (
459 type SnapshotInput = {
460 readonly page: Page;
461 readonly cdp: CDPSession;
404 - readonly renderScale: number;
462 + /** Headless pages render at the scale the server set; a desktop page at its display's. */
463 + readonly renderScale: number | "display";
464 readonly consoleEntries: ReadonlyArray<PreviewAutomationConsoleEntry>;
465 readonly networkEntries: ReadonlyArray<PreviewAutomationNetworkEntry>;
466 readonly actionTimeline: PreviewAutomationSnapshot["actionTimeline"];
467 };
468
469 +/** The scale a page renders at and its viewport in device-independent pixels, a clip's units. */
470 +const renderingOf = async (input: SnapshotInput) => {
471 + if (input.renderScale !== "display") {
472 + const viewport = input.page.viewportSize() ?? { width: 1280, height: 800 };
473 + return { renderScale: input.renderScale, viewport, offset: undefined };
474 + }
475 + // The display ratio a desktop page reports includes its page zoom, and its sizes are CSS pixels.
476 + const page = await readPageMetrics(input.cdp);
477 + return {
478 + renderScale: page.ratio / page.zoom,
479 + offset: page.offset,
480 + viewport: {
481 + width: Math.round(page.width * page.zoom),
482 + height: Math.round(page.height * page.zoom),
483 + },
484 + };
485 +};
486 +
487 const capture = async (
488 input: SnapshotInput,
489 deadline: number,
490 ): Promise<PreviewAutomationSnapshot> => {
414 - const viewport = input.page.viewportSize() ?? { width: 1280, height: 800 };
415 - const scale = Math.min(1, MAX_SCREENSHOT_WIDTH / (viewport.width * input.renderScale));
491 + const { renderScale, viewport, offset } = await renderingOf(input);
492 + // A late metrics reply must not begin a capture after viewers have resumed.
493 + if (Date.now() >= deadline) throw tooBusy();
494 + const scale = Math.min(1, MAX_SCREENSHOT_WIDTH / (viewport.width * renderScale));
495 const state = refsFor(input.page);
496 invalidateRefs(input.page);
497 const generation = state.generation;
@@ -427,7 +506,7 @@ const capture = async (
506 "url" | "title" | "loading" | "visibleText" | "interactiveElements"
507 >
508 >,
430 - captureViewport(input.page, input.cdp, { format: "png", scale }),
509 + captureViewport(input.page, input.cdp, { format: "png", scale, viewport, offset }),
510 ]);
511 void pageAndScreenshot.catch(constVoid);
512 // Leaves time for the second read; a frame that never loads holds the tree until then.
@@ -474,8 +553,7 @@ const capture = async (
553 screenshot: {
554 mimeType: "image/png",
555 data,
477 - width: Math.round(viewport.width * input.renderScale * scale),
478 - height: Math.round(viewport.height * input.renderScale * scale),
556 + ...pngSize(data),
557 },
558 };
559 };