catalog/shoot: optional imageScale — capture the page image at device pixel density while boxIDs stay CSS-pixel

[wittjeff]

Summary

Proposal: an optional imageScale report field so the in-catalog page image can be captured at a device's native pixel density while boxIDs stay in CSS pixels.

shoot.js currently captures with scale: 'css' — one image pixel per CSS pixel regardless of the emulated device. For scans that emulate high-DPR devices (iPhone DPR 3, common Android profiles at fractional DPRs like 2.625), the page image is a downsample of what the device would actually render, and it looks soft when displayed on high-DPI screens.

Proposal

When report.imageScale > 1:

• launch the catalog's browser context with deviceScaleFactor: report.imageScale, and
• capture the page image with page.screenshot({scale: 'device'}) instead of 'css'.

The image then has imageScale × the pixels of the CSS layout, while getBoundingClientRect (and therefore every catalog boxID) remains CSS-pixel by definition — consumers map coordinates onto the image by multiplying by imageScale. Omitted or 1 keeps today's behavior byte-identical.

Two implementation notes from testing this in production:

• A Playwright context deviceScaleFactor cleanly overrides the --force-device-scale-factor=1 launch arg used for chromium head emulation, and rect values are unaffected — verified empirically.
• Fractional scales work exactly: a 2.625 capture of a 1280-CSS-px page yields a 3360-pixel-wide image (1280 × 2.625), boxIDs unchanged.

A natural policy for callers (ours): set imageScale to the scan device's own windowOptions.deviceScaleFactor, so the page image is what the emulated device natively renders and the catalog page's DPR matches the test pages' (same srcset / image-set resource selection).

Scope: only getCatalog's launch and shoot() call sites change; test acts and their launches are untouched. We're running this as a patch in production; happy to submit a PR.

[jrpool]

Thanks, @wittjeff, for this valuable suggestion.

Am I mistaken that a user using this feature to make the device scale factor different from 1 would doom the testaro rule engine’s motion test by ensuring that the screenshot made by it differs from the one made along with the catalog?

[wittjeff]

You're not mistaken — you're right. motion compares its fresh shot against report.images[0] and fails fast on any size mismatch, so an imageScale > 1 catalog image would guarantee a "Page size changes spontaneously" false positive under the proposal as I originally wrote it.

I went to our fleet data expecting to confirm the false positive empirically and found something more interesting: it has never actually fired for us, because motion has never completed at all. Every scan either had no catalog image, or hit motion's 5-second rule budget before the comparison ran (4 of 4 image-bearing scans timed out — the rule's own full-page screenshot has a 4-second internal allowance, leaving almost nothing for decoding two full-page PNGs and pixelmatching). So the defect you predicted is real but was masked by a second one. I've filed the timeout observation separately as #76.

Revised proposal, now implemented in PR #75, which removes the coupling entirely:

• images[0] keeps its contract — the catalog always captures it at scale: 'css', exactly as today. motion is untouched and invariant to imageScale: both of its comparands are CSS-scale (Playwright's scale: 'css' divides out the context's deviceScaleFactor), so dimensions match regardless of the device profile.
• When report.imageScale > 1, the catalog takes one additional screenshot at scale: 'device' and appends it as images[1], with imageScale× the pixels of the CSS layout. Consumers read its density from report.imageScale; boxIDs stay CSS-pixel and map onto it by multiplying by the factor.
• Omitted or 1 keeps today's behavior byte-identical — no images[1], no context override. images is already an array, so no schema change; the README documents the semantics.

Verified end-to-end (chromium, 1280×800): imageScale: 2 → images[0] 1280×800 + images[1] 2560×1600; fractional 2.625 → 3360×2100 exactly; no imageScale → one CSS-scale image as today. This also composes with #50/#71/#74: the disclosure expansion happens before both shots.