catalog/shoot: optional imageScale for a device-pixel page image, motion-safe (fixes #51)

[wittjeff]

Implements #51 with the revised, motion-safe design (see my reply there answering your question about the motion rule — you were right, and this design removes the coupling entirely).

What it does

When report.imageScale is a number > 1:

• the catalog's browser context is launched with deviceScaleFactor: imageScale (via a new contextOverrides pass-through in launch()), and
• after the usual CSS-scale page image is captured as images[0], a second image is captured at scale: 'device' and appended as images[1] — imageScale× the pixels of the CSS layout in each dimension.

images[0] keeps its contract: always CSS-pixel scale, exactly as today. The motion rule — which compares its own CSS-scale screenshot against images[0] and fails fast on any dimension mismatch — is therefore unaffected by imageScale. (The originally proposed single-shot design would have made every motion comparison under imageScale > 1 a guaranteed size-mismatch false positive; this is the fix for the problem you spotted.)

boxIDs remain CSS-pixel by definition; consumers map them onto images[1] by multiplying by imageScale. Omitted, 1, or invalid values keep behavior byte-identical to today, including no images[1].

Changes

• procs/launch.js: launch()/launchOnce() accept contextOverrides — extra Playwright context options spread after the defaults (used here for deviceScaleFactor; the launch-arg --force-device-scale-factor=1 is cleanly overridden by the context option, verified empirically).
• procs/shoot.js: shoot() accepts scale ('css' default, or 'device'), passed to page.screenshot.
• procs/catalog.js: validates report.imageScale, applies the context override, and takes the supplemental device-scale shot when applicable.
• README.md: documents the imageScale job property and the images[1] semantics.

Verification

End-to-end getCatalog runs on a synthetic page (chromium, viewport 1280×800):

imageScale	images[0]	images[1]
(absent)	1280×800	— (array length 1, as today)
2	1280×800	2560×1600
2.625	1280×800	3360×2100 (exact)

Box IDs are CSS-pixel in all cases, and the closed-<details> expansion from #71 is visible in both images (both shots happen after it).

One note for completeness: when imageScale differs from the emulated device's own DSF, images[0] is a CSS-scale downsample of a higher-DPR render while motion's own shot renders at the test context's DPR — same dimensions, near-identical pixels; pixelmatch's default antialiasing exclusion absorbs the rendering difference. Setting imageScale to the device's deviceScaleFactor (the natural policy suggested in the issue) makes the two rendering pipelines identical.

🤖 Generated with Claude Code

[jrpool]

Thank you, @wittjeff, for adding this option and making it non-interfering with other functionalities.