html-cut

HTML Cut

Render a webpage URL or local HTML page into a high-definition PNG screenshot, outputting a full-page screenshot by default.

Common examples

Commands should be run in the root directory of this skill; on success, stdout outputs only the absolute path of the screenshot.

Remote webpages and light/dark color schemes

# 默认按亮色偏好渲染，全页高清截图
python3 scripts/capture.py https://example.com /tmp/example.png

# 指定暗色偏好
python3 scripts/capture.py https://example.com /tmp/example-dark.png --color-scheme dark

Local development service

If the page has entrance animations or API requests, allow extra rendering time:

python3 scripts/capture.py http://localhost:5173 /tmp/home.png \
  --width 1440 --height 900 --scale 2 --wait 2000

Local HTML file

file:/// must be followed by an absolute path:

python3 scripts/capture.py "file:///Users/name/project/dist/index.html" \
  /tmp/page.png --wait 500

Capture only the first screen

python3 scripts/capture.py https://example.com /tmp/viewport.png \
  --width 390 --height 844 --scale 3 --no-full-page

Wait for SPA network stability

python3 scripts/capture.py http://localhost:3000 /tmp/app.png \
  --wait-until networkidle --wait 1000

Parameters

Parameter	Description
url	Webpage URL; can be omitted, defaults to http://localhost:2020/
output	PNG output path; can be omitted, defaults to the current directory screenshot.png
--scale N	Device pixel ratio, defaults to 4; the larger the value, the clearer the image and the larger the file
--width N	Viewport width, defaults to 1280
--height N	Viewport height, defaults to 900
--wait MS	Extra wait time after navigation completes, defaults to 5000; can be increased for dynamic pages
--timeout MS	Navigation timeout, defaults to 45000
--wait-until load|domcontentloaded|networkidle|commit	Navigation completion condition, defaults to load
--color-scheme dark|light	Simulate the system light/dark color scheme preference, defaults to light
--full-page / --no-full-page	Whether to capture the full page; defaults to full page, otherwise only the current viewport is captured
--visible	Show the Chromium window, convenient for troubleshooting rendering issues

Workflow

1. Confirm the target URL is accessible; use an absolute path for local files file:/// URL
2. Select the output path and viewport size according to the target image
3. If dynamic content has not stabilized, add --wait or switch to --wait-until networkidle
4. After the screenshot is taken, check the PNG path and image dimensions in stdout

Output conventions

• The output format is PNG
• A non-existent output parent directory will be created automatically
• Full-page screenshot by default, preserving the page's complete vertical content
• By default 1280×900 logical viewport,4x device pixel ratio; the actual image pixels will increase with the page and scale
• Does not modify webpage source code, and does not upload page content

Troubleshooting

Symptom	Handling
缺少 Playwright	Run python3 -m pip install playwright
Chromium not found	Run python3 -m playwright install chromium
Page timeout	Check the URL; appropriately increase --timeout, or change --wait-until domcontentloaded
Screenshot is missing asynchronous content	Increase --wait; if necessary, use --visible to inspect the page
Image too large	Lower --scale, or add --no-full-page

Agent notes

• When the user has not given a path, output to a temporary directory to avoid overwriting existing files in the project
• Prefer to screenshot the local development service; local HTML must be converted to an absolute file:/// URL
• After the screenshot is completed, report the absolute PNG path; do not paste binary image content into the reply