home page updated

openspec/changes/service-workers/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-10

openspec/changes/service-workers/design.md

@@ -0,0 +1,52 @@
+## 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.
+

openspec/changes/service-workers/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+Improve page load performance (especially repeat visits) by caching key assets closer to the user and reducing unnecessary network requests.
+
+## What Changes
+
+- Add a Service Worker to the site so the browser can cache and serve core assets efficiently.
+- Pre-cache the critical shell (CSS, JS, fonts, icons) and use a runtime caching strategy for images and other large assets.
+- Ensure safe update behavior on deploy (new service worker activates and old caches are cleaned up).
+- Keep development experience predictable (service worker disabled or bypassed in dev by default).
+
+## Capabilities
+
+### New Capabilities
+
+- `service-worker-performance`: Provide a service worker-based caching strategy that improves perceived load time and reduces network usage on repeat visits, while ensuring safe updates on new deploys.
+
+### Modified Capabilities
+
+- (none)
+
+## Impact
+
+- Adds new client-side assets for the service worker (e.g., `sw.js`) and registration logic in the site layout.
+- Changes browser caching behavior; must avoid serving stale HTML indefinitely and ensure caches are versioned/invalidated on deploy.
+- Service workers require a secure context (HTTPS) in production; local dev behavior should be explicitly controlled to avoid confusing caching during iteration.
+

openspec/changes/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
+

openspec/changes/service-workers/tasks.md

@@ -0,0 +1,22 @@
+## 1. Setup
+
+- [x] 1.1 Add `sw.js` to site root output (place in `site/public/sw.js`)
+- [x] 1.2 Add service worker registration to the base layout (register only in production)
+
+## 2. Pre-cache Site Shell
+
+- [x] 2.1 Implement versioned cache names and an explicit cache version constant
+- [x] 2.2 Implement `install` handler to pre-cache critical shell assets
+- [x] 2.3 Implement `activate` handler to delete old version caches
+
+## 3. Runtime Caching
+
+- [x] 3.1 Implement network-first strategy for navigation/document requests with cache fallback
+- [x] 3.2 Implement cache-first strategy for images/media with network fallback
+- [x] 3.3 Add a bounded eviction policy for media cache size
+
+## 4. Verification
+
+- [ ] 4.1 Verify service worker registers in production build and does not register in dev
+- [ ] 4.2 Verify repeat navigation and asset loads hit cache (Chrome DevTools Application tab)
+- [ ] 4.3 Verify a new deploy triggers cache version update and old caches are removed