full-page-screenshot

---
name: full-page-screenshot
description: Use when capturing full-page screenshots with lazy-loaded content, SPAs, and tall pages via Chrome DevTools Protocol.
category: Engineering
version: 1.0.0
tools: []
---

# Full Page Screenshot via Chrome DevTools Protocol

Capture entire web pages including scroll-required content. Handles SPA scroll containers, lazy-loaded images, and very tall pages. Zero external dependencies beyond Node.js 22+ and Chrome with remote debugging.

## Prerequisites

- Node.js 22+ (built-in WebSocket)
- Chrome/Chromium with remote debugging enabled

## Workflow

### Option A: Screenshot an Open Tab (recommended for authenticated pages)

1. List available tabs:
```bash
node script.mjs --list
```

2. Capture using targetId:
```bash
node script.mjs <targetId> /tmp/screenshot.png --width 1200 --dpr 1
```

### Option B: Screenshot a URL (opens background tab, captures, closes)

```bash
node script.mjs --url "https://example.com" /tmp/screenshot.png --width 1200 --dpr 1 --wait 15000
```

Note: --url mode requires no authentication. Use Option A for SSO/login walls.

## Parameters

| Parameter | Description | Default |
|---|---|---|
| `--width` | Viewport width (1200 articles, 1440+ dashboards) | 1200 |
| `--dpr` | Device pixel ratio (2=Retina, 4x file size) | 1 |
| `--wait` | Page load timeout ms | 15000 |
| `--css` | Custom CSS injection (hide elements) | — |

## Core Capabilities

1. **SPA scroll expansion** — Detects overflow-y containers, scrolls to trigger lazy-load, removes constraints.
2. **DOM stability** — Waits until readyState=complete, monitors element count until stable.
3. **Lazy-load trigger** — Incremental scroll fires IntersectionObserver, waits for `<img>` completion.
4. **Tiling for tall pages** — Pages > 16000px captured in 8000px tiles, auto-stitched (PIL).
5. **Auto-discovery** — Reads DevToolsActivePort, falls back to probing ports 9222, 9229, 9333.
6. **CDP proxy fallback** — When proxy holds WebSocket, uses API endpoints.

## Verification

```bash
# macOS
sips -g pixelWidth -g pixelHeight /tmp/screenshot.png

# Linux
file /tmp/screenshot.png
```

## Anti-Patterns

| Do NOT | Do |
|---|---|
| `--dpr 2` on pages > 10000px | Use `--dpr 1` |
| `--url` for authenticated pages | Use `--list` + targetId on logged-in tab |
| `--wait` below 5000 for SPAs | Use 10000-15000 |
| Skip `--check` | Verify Chrome debugging available |
| Hardcode width for all pages | 1200 articles, 1440+ dashboards |

## Troubleshooting

| Symptom | Fix |
|---|---|
| Chrome port not found | Enable chrome://inspect/#remote-debugging |
| Blank screenshot | Increase `--wait` |
| Truncated bottom | Scroll container auto-expanded; file issue if persists |
| Out of memory | Reduce `--dpr` to 1, reduce `--width` |