diff --git a/openspec/changes/service-workers/.openspec.yaml b/openspec/changes/archive/2026-02-10-service-workers/.openspec.yaml similarity index 100% rename from openspec/changes/service-workers/.openspec.yaml rename to openspec/changes/archive/2026-02-10-service-workers/.openspec.yaml diff --git a/openspec/changes/service-workers/design.md b/openspec/changes/archive/2026-02-10-service-workers/design.md similarity index 100% rename from openspec/changes/service-workers/design.md rename to openspec/changes/archive/2026-02-10-service-workers/design.md diff --git a/openspec/changes/service-workers/proposal.md b/openspec/changes/archive/2026-02-10-service-workers/proposal.md similarity index 100% rename from openspec/changes/service-workers/proposal.md rename to openspec/changes/archive/2026-02-10-service-workers/proposal.md diff --git a/openspec/changes/service-workers/specs/service-worker-performance/spec.md b/openspec/changes/archive/2026-02-10-service-workers/specs/service-worker-performance/spec.md similarity index 100% rename from openspec/changes/service-workers/specs/service-worker-performance/spec.md rename to openspec/changes/archive/2026-02-10-service-workers/specs/service-worker-performance/spec.md diff --git a/openspec/changes/service-workers/tasks.md b/openspec/changes/archive/2026-02-10-service-workers/tasks.md similarity index 100% rename from openspec/changes/service-workers/tasks.md rename to openspec/changes/archive/2026-02-10-service-workers/tasks.md diff --git a/openspec/changes/lighthouse-remediation/.openspec.yaml b/openspec/changes/lighthouse-remediation/.openspec.yaml new file mode 100644 index 0000000..70eb9e0 --- /dev/null +++ b/openspec/changes/lighthouse-remediation/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-10 diff --git a/openspec/specs/service-worker-performance/spec.md b/openspec/specs/service-worker-performance/spec.md new file mode 100644 index 0000000..fe7d69d --- /dev/null +++ b/openspec/specs/service-worker-performance/spec.md @@ -0,0 +1,48 @@ +## 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