## Context

This change introduces a Service Worker to improve perceived load time and reduce network usage on repeat visits by caching critical assets in the browser.

The site is a static Astro build. That means:
- The Service Worker should live at the site root (`/sw.js`) so it can control all routes.
- Navigations (HTML documents) should not be cached in a way that causes indefinite staleness after new deploys.

## Goals / Non-Goals

**Goals:**
- Improve repeat-visit performance by pre-caching the critical site shell assets.
- Add runtime caching for media assets (images) with bounded storage usage.
- Ensure safe update behavior: cache versioning and cleanup on activate.
- Keep local development predictable by not registering the Service Worker in dev by default.

**Non-Goals:**
- Full offline-first experience for all routes/content.
- Background sync, push notifications, or complex offline fallbacks.
- Server-side caching (handled by separate changes, if desired).

## Decisions

1. **Implement a lightweight, custom Service Worker (no Workbox)**
Rationale: The project already outputs static assets and the needed caching strategies are straightforward. A small custom `/sw.js` avoids adding a build-time dependency and keeps behavior explicit.
Alternatives considered:
- Workbox: powerful, but adds dependency surface area and build configuration overhead.

2. **Cache strategy by request type**
Rationale: Different resources have different freshness requirements.
- Navigations (HTML documents): **Network-first**, fallback to cache on failure. This minimizes stale HTML risks while still helping resiliency.
- Static shell assets (CSS/JS/fonts/icons): **Pre-cache** on install and serve from cache for speed.
- Images/media: **Cache-first** with a size bound and eviction to avoid unbounded storage.

3. **Versioned caches + activation cleanup**
Rationale: Static sites frequently redeploy; versioning ensures updates can be picked up and old assets are not served after deploy. On activate, the SW deletes prior version caches.
Implementation approach:
- Use cache names like `shell-v<version>` and `media-v<version>`.
- Update the version string on build (initially a constant; later can be automated).

4. **Disable SW registration in development by default**
Rationale: Service worker caching can confuse local iteration and cause stale assets during development.
Implementation approach:
- Register SW only when `import.meta.env.PROD` is true (Astro build-time flag) or an explicit runtime guard is met.

## Risks / Trade-offs

- **[Stale or broken assets after deploy]** → Use versioned caches and delete old caches during activation. Prefer network-first for navigations.
- **[Over-caching HTML causes outdated content]** → Do not use cache-first for navigation; do not pre-cache HTML pages.
- **[Storage growth due to images]** → Enforce a max-entry limit with eviction for media cache.
- **[Browser compatibility gaps]** → Service worker is progressive enhancement; site must still function without it.