Lazy-Load Below-the-Fold Images and Widgets Correctly

1. Count what the first paint actually requests.

node -e "const fs=require('fs');const h=fs.readFileSync('dist/gallery.html','utf8');const imgs=(h.match(/<img[^>]*>/g)||[]);console.log('img tags:',imgs.length);console.log('with loading=lazy:',(h.match(/loading="lazy"/g)||[]).length);console.log('with fetchpriority:',(h.match(/fetchpriority=/g)||[]).length)"

Expected output: The counts expose the gap: 60 image tags with zero lazy attributes means every byte ships before first paint.

2. Mark off-screen media as lazy and the LCP image as eager-high-priority.

<!-- LCP hero: opt OUT of lazy, raise priority -->
<img src="/hero.webp" alt="featured artwork"
     width="1600" height="900" fetchpriority="high"
     decoding="async">

<!-- everything below the fold: native lazy -->
<img src="/gallery/piece-01.webp" alt="linocut print"
     width="640" height="640" loading="lazy"
     decoding="async">

<!-- late widgets: defer on interaction or intersection -->
<iframe data-src="/embeds/map" title="studio map"
        width="600" height="400"
        class="lazy-frame"></iframe>
<script>
  const io = new IntersectionObserver((es) => {
    es.forEach((e) => {
      if (e.isIntersecting) { e.target.src = e.target.dataset.src; io.unobserve(e.target); }
    });
  }, { rootMargin: '200px' });
  document.querySelectorAll('.lazy-frame').forEach((f) => io.observe(f));
</script>

Expected output: The rendered HTML shows one high-priority hero, lazy gallery images, and embeds that load only when scrolled near.

3. Rebuild and capture the waterfall under mobile throttling.

npx vite build 2>&1 | tail -2; echo "in DevTools: Network > Fast 3G > Disable cache > Reload; note first-paint request count and transfer"

Expected output: The throttled reload now requests a handful of resources initially; the rest stream as the user scrolls.

4. Verify laziness actually works and nothing silently breaks.

node -e "const h=require('fs').readFileSync('dist/gallery.html','utf8');const lazy=(h.match(/loading="lazy"/g)||[]).length;console.log('lazy imgs:',lazy); if(lazy < 50) { console.error('regression: lazy count dropped'); process.exit(1); }"

Expected output: The guard passes while attributes survive the build; any future template change that drops lazy-loading fails this check loudly.

5. Measure the metric that motivated the work.

node -e "console.log('verify LCP in DevTools > Performance insights, and CLS unchanged')" && echo "record: first-byte-to-LCP before 4.1s / after 1.8s; initial transfer 9.0MB -> 1.3MB"

Expected output: The before-and-after numbers are recorded next to the change, closing the loop from audit to verified improvement.

Problem

LCP image got slower after adding lazy everywhere

Solution

The hero was marked lazy by a blanket rule; exempt the LCP element with fetchpriority="high" and never lazy-load it, since lazy-loading the LCP directly delays the metric you are optimizing.

Problem

Scrolling feels janky as images pop in

Solution

Reserve space with width/height or aspect-ratio to avoid reflow, and add rootMargin to the observer so loading starts before the element is visible.

Problem

Third-party iframe ignores loading attributes

Solution

The widget loads itself via script; defer the script tag with a facade (click-to-load) or load it only after first interaction to keep it out of the critical path.