PWA & Service Worker (v6)

Caching strategies, offline behavior, and data freshness signaling.

Cache & Strategy Overview

• Cache name: culturesherpa-2045-v6
• Navigation/documents: network-first → cache fallback → offline.html
• Static assets (CSS/JS/images): cache-first, then network; caches on miss
• Runtime JSON (data): stale-while-revalidate for /cultures.json and /enriched_output/*.v3.json

Data Freshness Messaging

When a fresh JSON response is cached, the SW posts a message to all clients:

{
  "type": "DATA_UPDATED",
  "kind": "cultures-index" | "enriched-entry",
  "url": "<request URL>",
  "status": 200,
  "etag": "<ETag or null>",
  "lastModified": "<RFC 1123 date or null>",
  "date": "<ISO 8601 timestamp>"
}
    

The UI (index.js) listens for this message to:

• Update the results info line with “Updated (timestamp)”
• Show a brief success toast (e.g., “Cultures index updated”)

Offline Behavior

• If a navigation request fails, the SW returns offline.html from cache.
• The offline page is referenced relative to the SW scope to ensure consistent resolution.

Update Flow

• On install: pre-cache app shell + key assets; skipWaiting() is called.
• On activate: cleans old caches; clients.claim() takes control.
• On updates: a refresh prompt triggers SKIP_WAITING; page reloads on controllerchange.

Security & CSP

• No inline scripts; strict CSP with allowlisted CDNs (DOMPurify, Leaflet loader)
• All site images load from same-origin /website/ paths

Notes

• SWR means users may briefly see cached data after deploys; the “Updated (timestamp)” indicator confirms when fresh data arrives.
• If you add new data endpoints or tile servers, ensure connect-src includes those hosts in the CSP.