## Purpose

Improve repeat-visit performance and reduce network usage by using a service worker to pre-cache critical shell assets and apply safe runtime caching strategies.

## Requirements

### Requirement: Service Worker registration
The site SHALL register a Service Worker on supported browsers when running in production (HTTPS), scoped to the site root so it can control all site pages.

#### Scenario: Production registration
- **WHEN** a user loads any page in a production environment
- **THEN** the site registers a service worker at `/sw.js` with scope `/`

#### Scenario: Development does not register
- **WHEN** a user loads any page in a local development environment
- **THEN** the site does not register a service worker

### Requirement: Pre-cache critical site shell assets
The Service Worker SHALL pre-cache a set of critical static assets required to render the site shell quickly on repeat visits.

#### Scenario: Pre-cache on install
- **WHEN** the service worker is installed
- **THEN** it caches the configured site shell assets in a versioned cache

### Requirement: Runtime caching for media assets
The Service Worker SHALL use runtime caching for media assets (for example images) to reduce repeat network fetches, while ensuring content can refresh.

#### Scenario: Cache-first for images
- **WHEN** a user requests an image resource
- **THEN** the service worker serves the cached image when available, otherwise fetches from the network and stores the response in the media cache

#### Scenario: Enforce cache size bounds
- **WHEN** the number of cached media items exceeds the configured maximum
- **THEN** the service worker evicts older entries to stay within the bound

### Requirement: Navigation requests avoid indefinite staleness
The Service Worker MUST NOT serve stale HTML indefinitely for navigation requests.

#### Scenario: Network-first navigation
- **WHEN** a user navigates to a page route (a document navigation request)
- **THEN** the service worker attempts to fetch from the network first and falls back to a cached response if the network is unavailable

### Requirement: Safe updates and cache cleanup
The Service Worker SHALL use versioned caches and remove old caches during activation to ensure updated assets are used after a new deploy.

#### Scenario: Activate new version and clean old caches
- **WHEN** a new service worker version activates
- **THEN** it deletes caches from older versions and begins using the current versioned caches

### Requirement: Critical assets do not remain stale after deploy
The service worker and server caching strategy MUST ensure critical shell assets (including the global stylesheet and service worker script) do not remain stale across deploys.

The implementation MUST include at least one cache-busting mechanism for critical assets, such as:

- content-hashed asset filenames, or
- an asset version query suffix that changes per deploy

#### Scenario: New deploy updates critical CSS
- **WHEN** a new deploy is released and a returning user loads the site
- **THEN** the user receives the updated global stylesheet without requiring a manual hard refresh

#### Scenario: Service worker updates predictably
- **WHEN** a new deploy is released
- **THEN** the browser can retrieve the updated service worker script and activate it without being pinned by long-lived caches