astro-website/openspec/changes/lighthouse-remediation/specs/asset-delivery-optimization/spec.md

ADDED Requirements

Requirement: Render-blocking resources are minimized

The site MUST minimize render-blocking resources on the critical path.

Font delivery MUST NOT rely on a render-blocking third-party stylesheet.

Scenario: Homepage avoids render-blocking font CSS

• WHEN Lighthouse audits the homepage
• THEN the Google Fonts stylesheet request is not present as a render-blocking resource (fonts are self-hosted or otherwise delivered without a blocking CSS request)

Requirement: First-party CSS and JS are optimized for Lighthouse

First-party CSS and JS delivered to the browser MUST be minified in production builds.

The site MUST minimize unused CSS and unused JavaScript on the homepage.

Scenario: CSS is minified

• WHEN a production build is served
• THEN styles/global.css (or its replacement) is minified

Scenario: Homepage avoids unused JS penalties

• WHEN Lighthouse audits the homepage
• THEN the amount of unused JavaScript on initial load is below Lighthouse's failing threshold

Requirement: Images are delivered efficiently

Images used on listing surfaces MUST be delivered in a size appropriate to their rendered dimensions.

For thumbnail-like images, the site SHOULD prefer image sources that support resizing or multiple resolutions when feasible.

Scenario: Podcast cover image is not oversized

• WHEN the homepage renders a podcast episode card
• THEN the fetched cover image size is reasonably close to the displayed size (no large wasted bytes flagged by Lighthouse)

Requirement: Cache lifetimes are efficient for first-party assets

First-party static assets (CSS/JS/fonts/images served from the site origin) MUST be served with cache headers that enable efficient repeat visits.

Non-fingerprinted assets MUST be served with revalidation (e.g., no-cache or max-age=0,must-revalidate) to avoid staleness.

Fingerprinted assets (build outputs) MUST be served with a long-lived immutable cache policy.

Scenario: First-party CSS has efficient caching

• WHEN Lighthouse audits the homepage
• THEN first-party CSS cache lifetimes are not flagged as inefficient

Scenario: Service worker script is revalidated

• WHEN the browser checks /sw.js for updates
• THEN the HTTP cache is bypassed or revalidated so an updated service worker can be fetched promptly