Add an opt-in image cache to capture

[jeremyfelt]

What

Adds an opt-in imageCache option to reglance.json so capture runs answer repeat image requests from a local disk cache instead of re-fetching every image from the origin once per viewport per parallel context.

"imageCache": true                  // per-run cache, cleared each capture
"imageCache": { "persist": true }   // kept across runs; clear with --fresh-images

How

No proxy server and no URL rewriting. Image requests are intercepted with the same context.route() hook already used for blockHosts and fulfilled from .reglance/image-cache/, so nothing in the DOM, the HTML snapshots, or the screenshots changes:

• Cache key = the full request URL, query string included — CDN resize variants (photo.jpg?w=400 vs ?w=800) are distinct entries. Covers srcset, <picture>, and CSS background images automatically since interception happens at the network layer.
• In-flight coalescing — parallel contexts requesting the same image at the same moment share one origin fetch, so even a cold first run only hits the origin once per distinct URL.
• Scope is deliberately narrow — only GET image requests, only 2xx responses cached. Documents/CSS/JS are the content under test and always load from the origin; a broken image stays broken in the capture.
• Failure-safe — any cache error hands the request back to the browser; a damaged entry reads as a miss; a failed disk write warns and serves the response uncached.

The default per-run mode is cleared at the start of every capture, so there is zero risk of a stale cached image masking a real origin change between control and compare runs. Persistence is a conscious opt-in for rapid re-capture loops, with --fresh-images as the escape hatch (documented trade-off in the README).

Verification

• 118 tests pass (13 new: cache roundtrip, query-string keys, coalescing, non-2xx passthrough, rejection recovery, clear-on-open, stats, and config normalization); lint clean.
• End-to-end smoke test against a local request-counting server, 2 viewports × 4 distinct image URLs:
  • Cold run: each image URL fetched from the origin exactly once (4 fetches, 4 served locally).
  • Warm persistent run: 0 origin image fetches, all 8 served locally; the HTML document still loaded fresh each navigation.
  • --fresh-images: cache cleared and re-seeded, one fetch per URL again.

🤖 Generated with Claude Code