dieter-medium/bidi2pdf/page-screenshots

Screenshots for review with bidi2pdf

A reviewer, human or agent, judges a page from what Chrome draws. Shoot every page that changed at phone width first, then desktop, each in light and dark mode, and hand over the files with the page and the width in their names.

Does not: compare screenshots against a baseline or judge them - it produces them. For a visual regression check, diff the PNGs in your own test (bidi2pdf's contains_pdf_image compares images inside a PDF, see pdf-specs).

Ground rules

• bidi2pdf is the renderer. If it fails, report its error.code, error.hint and exit code;

never make the PDF or screenshot another way (Chrome's own print-to-PDF, another PDF engine).

• Install nothing unasked. Name what is missing and suggest a way (the render-pdf skill's

preflight); run nothing that changes the system without the user's yes.

• bidi2pdf's results first. Read its --json result instead of inspecting the PDF with other

tools.

1. One shot

bidi2pdf diagnose --url http://app:4000/pricing --screenshot pricing.png --media screen --color_scheme dark

The shot is the whole document at the browser's default viewport. Good for "what did Chrome see"; for review sets with fixed widths use the script below.

2. A review set

SKILL_DIR=/absolute/path/to/skills/page-screenshots
ruby "$SKILL_DIR/scripts/screenshots.rb" --base http://app:4000 --pages /,/pricing,/signup \
  --widths 360,1280 --out tmp/screenshots --remote-browser-url http://remote-chrome:3000/session

Set SKILL_DIR first, to the absolute path of this skill's own folder - the folder of this SKILL.md, which the agent (Claude Code, Codex) names when it loads the skill. Nothing guarantees that the variable is already set: without it, the command looks for /scripts/screenshots.rb. In a checkout of bidi2pdf it is "$PWD/claude-plugin/skills/page-screenshots". Run the script by that path, not relative to the project you are shooting.

It writes one PNG for every page, width and colour scheme and prints each path: <page path>-<width>-<scheme>.png, with the page's folders kept (/account/settings becomes account/settings-360-light.png, / becomes index-...). When a page's path holds characters a file name should not, or a query, the name gets a short hash of the path, so no two pages overwrite each other. It sets the viewport, emulates prefers-color-scheme with media: screen, waits for the network to go quiet and captures the full page. Without --remote-browser-url it starts a local chromedriver. It needs the bidi2pdf release with BrowserTab#emulate_media (0.1.23 or later).

• 360 px first. Most layout bugs show at the narrow width; 1280 covers desktop. Add the site's own

breakpoints when they matter (e.g. 768).

• The base URL is seen from the browser. A shared browser in a container cannot reach

localhost on your machine - use a name it resolves.

• A page that needs a login: open it in the Ruby API with a cookie (tab.set_cookie) before

navigating, or shoot a page that does not need one.

3. From Ruby

The same steps for your own test or tool:

tab.emulate_media(media: "screen", color_scheme: "dark")
tab.set_viewport(width: 360, height: 900)
tab.navigate_to("http://app:4000/pricing")
tab.wait_until_network_idle
tab.screenshot("tmp/pricing-360-dark.png")

screenshot(origin: "viewport") captures exactly the viewport instead of the whole page. A full-page shot is as wide as the document, not the viewport: a page laid out by Paged.js comes out at its sheet width (794 px for A4) once Paged.js has finished - a print layout, not a 360 px one. A page that toggles dark mode by a class or data-theme instead of prefers-color-scheme needs that attribute set (tab.execute_script(...)) - emulation changes only the media feature.

4. Hand-over

List the files with page, width and scheme, and say what the reviewer should look at (the changed part). Reviewers need both widths and both schemes; a dark-mode contrast bug never shows in a light screenshot.