full-page-screenshot

# Full Page Screenshot

Capture a full-page screenshot of any web page via Chrome DevTools Protocol. Produces a single PNG that includes all content — even portions that require scrolling. Zero external dependencies beyond Node.js 22+ and Chrome with remote debugging enabled.

## Prerequisites

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

Check environment readiness:

```bash
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --check
```

If Chrome check fails, instruct user to open `chrome://inspect/#remote-debugging` and enable **"Allow remote debugging for this browser instance"**.

## Workflow

### Option A: Screenshot an already-open tab (recommended for authenticated pages)

1. List available tabs:

```bash
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --list
```

2. Identify the target by title/URL, then capture:

```bash
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" <targetId> /tmp/screenshot.png --width 1200 --dpr 1
```

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

```bash
node "${SKILL_DIR}/scripts/full-page-screenshot.mjs" --url "https://example.com" /tmp/screenshot.png --width 1200 --dpr 1 --wait 15000
```

> **Note:** `--url` mode creates a background tab. Pages requiring authentication (SSO, login walls) should use Option A instead.

### Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `output` | Output PNG file path | `/tmp/screenshot.png` |
| `--width` | Viewport width in CSS pixels (articles: 1200, dashboards: 1440-1920) | 1200 |
| `--dpr` | Device pixel ratio (2 = Retina, but 4x file size) | 1 |
| `--wait` | Page load timeout in ms (`--url` mode only) | 15000 |
| `--css` | Custom CSS to inject before capture (e.g., hide elements) | — |

### Verify Output

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

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

## Core Capabilities

1. **SPA scroll container expansion** — Detects `overflow-y: auto/scroll` containers, scrolls through them to trigger lazy-loading, then removes overflow constraints (including Tailwind `h-[calc(...)]`) so all content renders in a single pass.

2. **DOM stability detection** — After `readyState=complete`, monitors DOM element count until it stabilizes. This ensures SPA frameworks finish rendering dynamic content.

3. **Lazy-load triggering** — Scrolls the viewport incrementally to fire `IntersectionObserver` callbacks, then waits for all `<img>` elements to complete loading.

4. **Tiled capture for very tall pages** — Pages exceeding 16,000px are captured in 8,000px tiles and automatically stitched using Python PIL. Falls back to saving tiles separately if PIL is unavailable.

5. **Auto-discovery of Chrome** — Reads `DevToolsActivePort` file to find the debugging port. Falls back to probing ports 9222, 9229, 9333.

6. **CDP Proxy fallback** — When a CDP proxy holds the browser WebSocket, the script falls back to proxy API endpoints (`/eval`, `/screenshot`, `/scroll`) for capture.

## How It Works

```
1. Discover Chrome debugging port
2. Connect via WebSocket (CDP)
3. Attach to target / create background tab
4. Set viewport width via Emulation domain
5. Wait: readyState + DOM stability
6. Detect & expand scroll containers
7. Scroll through page (trigger lazy-load)
8. Wait for images to complete
9. Measure final content height
10. Page.captureScreenshot (or tiled capture)
11. Stitch tiles if needed (PIL)
12. Restore viewport, detach, clean up
```

## Anti-Patterns

| Do NOT | Do instead |
|--------|-----------|
| Use `--dpr 2` on pages > 10,000px tall | Use `--dpr 1` to avoid Chrome memory issues |
| Use `--url` for authenticated/SSO pages | Use `--list` + targetId on a tab where user is logged in |
| Set `--wait` below 5000 for SPAs | SPAs need time to fetch data and render; use 10000-15000 |
| Capture without checking `--check` first | Always verify Chrome debugging is available |
| Hardcode viewport widths for all pages | Use 1200 for articles, 1440+ for dashboards/tables |
| Skip output verification | Always verify with `sips` or `file` command after capture |

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Cannot find Chrome debugging port" | Remote debugging not enabled | Open `chrome://inspect/#remote-debugging`, enable it |
| "WebSocket connection timeout" | CDP proxy holding the connection | Script auto-falls back to proxy API |
| Blank/white screenshot | Page not loaded yet | Increase `--wait` value |
| Truncated at bottom | Scroll container not expanded | Script handles this automatically; file an issue if it persists |
| Out of memory | Very tall page + high DPR | Reduce `--dpr` to 1 and/or reduce `--width` |
| "PIL not available for stitching" | Python Pillow not installed | Install with `pip3 install Pillow` or accept separate tile files |

## Cross-References

- [`engineering/browser-automation`](../browser-automation/SKILL.md) — General browser automation patterns via CDP/Playwright
- [`engineering/performance-profiler`](../performance-profiler/SKILL.md) — Performance analysis that may complement visual captures

{
  "format": "aiskill/v1",
  "skill": {
    "name": "full-page-screenshot",
    "slug": "full-page-screenshot",
    "version": "1.0.0",
    "description": "Use when the user asks to capture a full-page screenshot, long screenshot, or complete page capture of a web page. Handles SPA scroll containers, lazy-loaded images, and very tall pages via Chrome DevTools Protocol with zero external dependencies.",
    "category": "Development",
    "tags": [
      "engineering",
      "devops"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Full Page Screenshot\r\n\r\nCapture a full-page screenshot of any web page via Chrome DevTools Protocol. Produces a single PNG that includes all content — even portions that require scrolling. Zero external dependencies beyond Node.js 22+ and Chrome with remote debugging enabled.\r\n\r\n## Prerequisites\r\n\r\n- **Node.js 22+** (uses built-in `WebSocket`)\r\n- **Chrome/Chromium** with remote debugging enabled\r\n\r\nCheck environment readiness:\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" --check\r\n```\r\n\r\nIf Chrome check fails, instruct user to open `chrome://inspect/#remote-debugging` and enable **\"Allow remote debugging for this browser instance\"**.\r\n\r\n## Workflow\r\n\r\n### Option A: Screenshot an already-open tab (recommended for authenticated pages)\r\n\r\n1. List available tabs:\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" --list\r\n```\r\n\r\n2. Identify the target by title/URL, then capture:\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" <targetId> /tmp/screenshot.png --width 1200 --dpr 1\r\n```\r\n\r\n### Option B: Screenshot a URL (opens a background tab, captures, closes)\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" --url \"https://example.com\" /tmp/screenshot.png --width 1200 --dpr 1 --wait 15000\r\n```\r\n\r\n> **Note:** `--url` mode creates a background tab. Pages requiring authentication (SSO, login walls) should use Option A instead.\r\n\r\n### Parameters\r\n\r\n| Parameter | Description | Default |\r\n|-----------|-------------|---------|\r\n| `output` | Output PNG file path | `/tmp/screenshot.png` |\r\n| `--width` | Viewport width in CSS pixels (articles: 1200, dashboards: 1440-1920) | 1200 |\r\n| `--dpr` | Device pixel ratio (2 = Retina, but 4x file size) | 1 |\r\n| `--wait` | Page load timeout in ms (`--url` mode only) | 15000 |\r\n| `--css` | Custom CSS to inject before capture (e.g., hide elements) | — |\r\n\r\n### Verify Output\r\n\r\n```bash\r\n# macOS\r\nsips -g pixelWidth -g pixelHeight /tmp/screenshot.png\r\n\r\n# Linux\r\nfile /tmp/screenshot.png\r\n```\r\n\r\n## Core Capabilities\r\n\r\n1. **SPA scroll container expansion** — Detects `overflow-y: auto/scroll` containers, scrolls through them to trigger lazy-loading, then removes overflow constraints (including Tailwind `h-[calc(...)]`) so all content renders in a single pass.\r\n\r\n2. **DOM stability detection** — After `readyState=complete`, monitors DOM element count until it stabilizes. This ensures SPA frameworks finish rendering dynamic content.\r\n\r\n3. **Lazy-load triggering** — Scrolls the viewport incrementally to fire `IntersectionObserver` callbacks, then waits for all `<img>` elements to complete loading.\r\n\r\n4. **Tiled capture for very tall pages** — Pages exceeding 16,000px are captured in 8,000px tiles and automatically stitched using Python PIL. Falls back to saving tiles separately if PIL is unavailable.\r\n\r\n5. **Auto-discovery of Chrome** — Reads `DevToolsActivePort` file to find the debugging port. Falls back to probing ports 9222, 9229, 9333.\r\n\r\n6. **CDP Proxy fallback** — When a CDP proxy holds the browser WebSocket, the script falls back to proxy API endpoints (`/eval`, `/screenshot`, `/scroll`) for capture.\r\n\r\n## How It Works\r\n\r\n```\r\n1. Discover Chrome debugging port\r\n2. Connect via WebSocket (CDP)\r\n3. Attach to target / create background tab\r\n4. Set viewport width via Emulation domain\r\n5. Wait: readyState + DOM stability\r\n6. Detect & expand scroll containers\r\n7. Scroll through page (trigger lazy-load)\r\n8. Wait for images to complete\r\n9. Measure final content height\r\n10. Page.captureScreenshot (or tiled capture)\r\n11. Stitch tiles if needed (PIL)\r\n12. Restore viewport, detach, clean up\r\n```\r\n\r\n## Anti-Patterns\r\n\r\n| Do NOT | Do instead |\r\n|--------|-----------|\r\n| Use `--dpr 2` on pages > 10,000px tall | Use `--dpr 1` to avoid Chrome memory issues |\r\n| Use `--url` for authenticated/SSO pages | Use `--list` + targetId on a tab where user is logged in |\r\n| Set `--wait` below 5000 for SPAs | SPAs need time to fetch data and render; use 10000-15000 |\r\n| Capture without checking `--check` first | Always verify Chrome debugging is available |\r\n| Hardcode viewport widths for all pages | Use 1200 for articles, 1440+ for dashboards/tables |\r\n| Skip output verification | Always verify with `sips` or `file` command after capture |\r\n\r\n## Troubleshooting\r\n\r\n| Symptom | Cause | Fix |\r\n|---------|-------|-----|\r\n| \"Cannot find Chrome debugging port\" | Remote debugging not enabled | Open `chrome://inspect/#remote-debugging`, enable it |\r\n| \"WebSocket connection timeout\" | CDP proxy holding the connection | Script auto-falls back to proxy API |\r\n| Blank/white screenshot | Page not loaded yet | Increase `--wait` value |\r\n| Truncated at bottom | Scroll container not expanded | Script handles this automatically; file an issue if it persists |\r\n| Out of memory | Very tall page + high DPR | Reduce `--dpr` to 1 and/or reduce `--width` |\r\n| \"PIL not available for stitching\" | Python Pillow not installed | Install with `pip3 install Pillow` or accept separate tile files |\r\n\r\n## Cross-References\r\n\r\n- [`engineering/browser-automation`](../browser-automation/SKILL.md) — General browser automation patterns via CDP/Playwright\r\n- [`engineering/performance-profiler`](../performance-profiler/SKILL.md) — Performance analysis that may complement visual captures",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The full-page-screenshot/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/full-page-screenshot",
    "exported_at": "2026-11-03T07:45:10.618Z"
  }
}

format: aiskill/v1
skill:
  name: full-page-screenshot
  slug: full-page-screenshot
  version: 1.0.0
  description: >-
    Use when the user asks to capture a full-page screenshot, long screenshot, or complete page
    capture of a web page. Handles SPA scroll containers, lazy-loaded images, and very tall pages
    via Chrome DevTools Protocol with zero external dependencies.
  category: Development
  tags:
    - engineering
    - devops
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Full Page Screenshot\r\n\r\nCapture a full-page screenshot of any web page via Chrome DevTools Protocol. Produces a single PNG that includes all content — even portions that require scrolling. Zero external dependencies beyond Node.js 22+ and Chrome with remote debugging enabled.\r\n\r\n## Prerequisites\r\n\r\n- **Node.js 22+** (uses built-in `WebSocket`)\r\n- **Chrome/Chromium** with remote debugging enabled\r\n\r\nCheck environment readiness:\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" --check\r\n```\r\n\r\nIf Chrome check fails, instruct user to open `chrome://inspect/#remote-debugging` and enable **\"Allow remote debugging for this browser instance\"**.\r\n\r\n## Workflow\r\n\r\n### Option A: Screenshot an already-open tab (recommended for authenticated pages)\r\n\r\n1. List available tabs:\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" --list\r\n```\r\n\r\n2. Identify the target by title/URL, then capture:\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" <targetId> /tmp/screenshot.png --width 1200 --dpr 1\r\n```\r\n\r\n### Option B: Screenshot a URL (opens a background tab, captures, closes)\r\n\r\n```bash\r\nnode \"${SKILL_DIR}/scripts/full-page-screenshot.mjs\" --url \"https://example.com\" /tmp/screenshot.png --width 1200 --dpr 1 --wait 15000\r\n```\r\n\r\n> **Note:** `--url` mode creates a background tab. Pages requiring authentication (SSO, login walls) should use Option A instead.\r\n\r\n### Parameters\r\n\r\n| Parameter | Description | Default |\r\n|-----------|-------------|---------|\r\n| `output` | Output PNG file path | `/tmp/screenshot.png` |\r\n| `--width` | Viewport width in CSS pixels (articles: 1200, dashboards: 1440-1920) | 1200 |\r\n| `--dpr` | Device pixel ratio (2 = Retina, but 4x file size) | 1 |\r\n| `--wait` | Page load timeout in ms (`--url` mode only) | 15000 |\r\n| `--css` | Custom CSS to inject before capture (e.g., hide elements) | — |\r\n\r\n### Verify Output\r\n\r\n```bash\r\n# macOS\r\nsips -g pixelWidth -g pixelHeight /tmp/screenshot.png\r\n\r\n# Linux\r\nfile /tmp/screenshot.png\r\n```\r\n\r\n## Core Capabilities\r\n\r\n1. **SPA scroll container expansion** — Detects `overflow-y: auto/scroll` containers, scrolls through them to trigger lazy-loading, then removes overflow constraints (including Tailwind `h-[calc(...)]`) so all content renders in a single pass.\r\n\r\n2. **DOM stability detection** — After `readyState=complete`, monitors DOM element count until it stabilizes. This ensures SPA frameworks finish rendering dynamic content.\r\n\r\n3. **Lazy-load triggering** — Scrolls the viewport incrementally to fire `IntersectionObserver` callbacks, then waits for all `<img>` elements to complete loading.\r\n\r\n4. **Tiled capture for very tall pages** — Pages exceeding 16,000px are captured in 8,000px tiles and automatically stitched using Python PIL. Falls back to saving tiles separately if PIL is unavailable.\r\n\r\n5. **Auto-discovery of Chrome** — Reads `DevToolsActivePort` file to find the debugging port. Falls back to probing ports 9222, 9229, 9333.\r\n\r\n6. **CDP Proxy fallback** — When a CDP proxy holds the browser WebSocket, the script falls back to proxy API endpoints (`/eval`, `/screenshot`, `/scroll`) for capture.\r\n\r\n## How It Works\r\n\r\n```\r\n1. Discover Chrome debugging port\r\n2. Connect via WebSocket (CDP)\r\n3. Attach to target / create background tab\r\n4. Set viewport width via Emulation domain\r\n5. Wait: readyState + DOM stability\r\n6. Detect & expand scroll containers\r\n7. Scroll through page (trigger lazy-load)\r\n8. Wait for images to complete\r\n9. Measure final content height\r\n10. Page.captureScreenshot (or tiled capture)\r\n11. Stitch tiles if needed (PIL)\r\n12. Restore viewport, detach, clean up\r\n```\r\n\r\n## Anti-Patterns\r\n\r\n| Do NOT | Do instead |\r\n|--------|-----------|\r\n| Use `--dpr 2` on pages > 10,000px tall | Use `--dpr 1` to avoid Chrome memory issues |\r\n| Use `--url` for authenticated/SSO pages | Use `--list` + targetId on a tab where user is logged in |\r\n| Set `--wait` below 5000 for SPAs | SPAs need time to fetch data and render; use 10000-15000 |\r\n| Capture without checking `--check` first | Always verify Chrome debugging is available |\r\n| Hardcode viewport widths for all pages | Use 1200 for articles, 1440+ for dashboards/tables |\r\n| Skip output verification | Always verify with `sips` or `file` command after capture |\r\n\r\n## Troubleshooting\r\n\r\n| Symptom | Cause | Fix |\r\n|---------|-------|-----|\r\n| \"Cannot find Chrome debugging port\" | Remote debugging not enabled | Open `chrome://inspect/#remote-debugging`, enable it |\r\n| \"WebSocket connection timeout\" | CDP proxy holding the connection | Script auto-falls back to proxy API |\r\n| Blank/white screenshot | Page not loaded yet | Increase `--wait` value |\r\n| Truncated at bottom | Scroll container not expanded | Script handles this automatically; file an issue if it persists |\r\n| Out of memory | Very tall page + high DPR | Reduce `--dpr` to 1 and/or reduce `--width` |\r\n| \"PIL not available for stitching\" | Python Pillow not installed | Install with `pip3 install Pillow` or accept separate tile files |\r\n\r\n## Cross-References\r\n\r\n- [`engineering/browser-automation`](../browser-automation/SKILL.md) — General browser automation patterns via CDP/Playwright\r\n- [`engineering/performance-profiler`](../performance-profiler/SKILL.md) — Performance analysis that may complement visual captures"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The full-page-screenshot/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/full-page-screenshot
  exported_at: "2026-11-03T07:45:10.618Z"