Downscale captures too large for the browser to render

[jeremyfelt]

Problem

Browsers refuse to decode an image taller or wider than 32,767px (Skia's kMaxDimension) and render it as a broken/corrupt image — the console reports the image as corrupt. Full-page mobile captures cross this routinely: a narrow viewport stacks content into a very tall page, and a deviceScaleFactor of 2 doubles the pixel height again. The capture PNG on disk is valid; only the browser viewing the report can't paint it, so some screenshots silently fail to load in the report.

What this does

• src/downscale.mjs (new) — an area-filter (box-average) resampler, plus displayDimensions (clamp the longest side to the limit, keep aspect ratio) and downscaleToDisplay. Area averaging keeps shrunk text and 1px borders legible.
• compare writes a downscaled copy of any oversized image to a new .reglance/display/ directory and points the report at it. pixelmatch still runs at full resolution against the originals, and the promoted baseline in controls/ is never modified — only the displayed copy is shrunk.
• Comparison view shows a "Downscaled" banner with the original and shown dimensions whenever an image on screen was shrunk (mode-aware: diff mode reports the diff image's numbers).
• capture warns at screenshot time when it writes a PNG past the limit — read straight from the IHDR header (a 24-byte read, no full decode) — so the cause is visible before the report is built.

Why downscale on display rather than at capture

Keeping the full-resolution capture as the source of truth means pixel diffs stay accurate and the baseline isn't perturbed by a height change crossing the limit. Only the report's rendered copy is shrunk.

Test plan

• npm run lint — clean
• npm test — 124 pass. New coverage for the resampler (flat-color and boundary averaging), displayDimensions clamping/aspect-ratio/guards, the PNG header reader, and the report linking display copies + surfacing scaled.
• Verified end-to-end against a real project whose home-mobile capture was 34,162px tall: it now gets a 748×32767 display copy, the report links it, the banner renders, and pages under the limit are untouched.

🤖 Generated with Claude Code