SW implementation done

openspec/changes/archive/2026-02-10-service-workers/specs/service-worker-performance/spec.md

@@ -0,0 +1,45 @@
+## ADDED 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
+