Optimize website loading and eliminate layout shifts

[johnnygreco]

The Dev Notes index downloaded full-resolution PNGs for thumbnails, including both theme variants of the featured hero. In the same cold Chromium measurement, local image downloads fall from 7.30 MB to 56 KB (99.2% less); the featured light hero is now about 12 KB.

The documentation build generates responsive WebP variants with native srcset/sizes, intrinsic dimensions, asynchronous decoding, lazy body images, and compressed video posters. SVGs retain their vector sources and receive intrinsic dimensions. Original full-size links and published Markdown remain intact. Initial palette selection prevents downloading hidden theme variants, system fonts remove external font requests, and transcript data/DOM construction waits until the reader approaches the viewer or opens a source link.

The site-wide audit also removes three sources of visible movement: the Dev Notes filter toolbar appearing after load, unfiltered cards flashing on shared filter links, and unsized SVG heroes/diagrams. The transcript viewer reserves its responsive frame during loading and model switches; collapse and no-JavaScript behavior remain available. Fixes use standard image attributes and CSS layout, with no new client-side framework or measurement controller.

Validation:

• Clean documentation build passed, including renderer, rendered Markdown, SEO, navigation, 404, and image optimizer checks. JavaScript syntax and git diff --check passed.
• Browser suite: 424 passed. Chromium/WebKit, light/dark themes, five desktop/tablet/phone viewports. Coverage includes every non-redirect generated page (23), delayed images and scripts, filtered reloads, search, saved navigation, homepage links, heroes, video playback, and deferred transcript loading/tab changes. Chromium also checks loading layout shifts with normal animations enabled.
• All three external author avatars returned HTTP 200 with 1.3–2.5 KB payloads.
• Inspected desktop and phone screenshots; separate narrow-phone probes covered transcript menus, keyboard controls, collapse, and no-JavaScript fallbacks.
• Three-reviewer follow-up panel found no actionable correctness, UX, build/test, or complexity issues. Native dimensions, visibility, flex layout, and browser loading primitives were preferred over additional runtime machinery.

Generated image variants are not committed. Browser checks remain on demand, outside CI. Byte measurements and profiling are local, not production-latency guarantees; deterministic browser checks block external avatars and embeds.

[github-actions]

Documentation preview

The preview has been removed.