Heads-up: CDP screenshot sizing with HiDPI/scaled displays

[gwpl]

AI Assistant:

Summary

This is a helpful heads-up about a CDP behavior that might be useful for documentation or troubleshooting guidance. When taking screenshots on systems with HiDPI/scaled displays, users may encounter unexpected white/black borders or images larger than expected.

Platform: Linux (X11 + possibly Wayland). macOS and Windows handle HiDPI differently and may not exhibit this exact behavior.

The Issue

System DPI scaling (e.g., Xft.dpi: 144 = 1.5x scaling) affects what Chrome reports via CDP, even when deviceScaleFactor: 1 is set in Emulation.setDeviceMetricsOverride. This means Page.getLayoutMetrics returns dimensions scaled by the system DPI.

How to Detect

# X11
xrdb -query | grep -i dpi
# Xft.dpi: 144 means 1.5x scaling (144/96 = 1.5)

# GNOME
gsettings get org.gnome.desktop.interface text-scaling-factor
# 1.5

# Wayland may use these instead:
# GDK_SCALE, QT_SCALE_FACTOR environment variables

The Solution

When capturing screenshots, use the requested dimensions directly in the clip parameter instead of using the dimensions reported by Page.getLayoutMetrics:

// DON'T use reported dimensions (affected by system DPI)
const metrics = await send('Page.getLayoutMetrics');
// metrics.result.visualViewport might be 1.5x larger than expected

// DO use your requested dimensions directly
await send('Page.captureScreenshot', {
  clip: {
    x: 0, y: 0,
    width: YOUR_REQUESTED_WIDTH,   // e.g., 1536
    height: YOUR_REQUESTED_HEIGHT, // e.g., 1024
    scale: 1
  }
});

Suggestion

This might be worth adding to FAQ/troubleshooting documentation for users who encounter unexpected screenshot dimensions. The fix is counterintuitive (ignore what CDP tells you about dimensions), so documenting it could save debugging time for users with HiDPI setups.

---

Found this while debugging screenshot issues on a Linux system with 1.5x display scaling. Thought it might be helpful for others!