docs: add offline sync & PWA documentation

feat: improve PWA resilience with SWR and navigation timeouts

public/sw.js

@@ -1,4 +1,4 @@
-const CACHE_NAME = 'whisky-vault-v2'; // Increment version to force update
+const CACHE_NAME = 'whisky-vault-v3'; // Increment version to apply new strategy
 const ASSETS_TO_CACHE = [
     '/manifest.json',
     '/icon-192.png',
@@ -29,6 +29,26 @@ self.addEventListener('activate', (event) => {
     self.clients.claim();
 });
 
+// Helper for Network-First with Timeout
+function fetchWithTimeout(request, timeoutMs = 3000) {
+    return new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            reject(new Error('Network timeout'));
+        }, timeoutMs);
+
+        fetch(request).then(
+            (response) => {
+                clearTimeout(timeoutId);
+                resolve(response);
+            },
+            (err) => {
+                clearTimeout(timeoutId);
+                reject(err);
+            }
+        );
+    });
+}
+
 self.addEventListener('fetch', (event) => {
     const url = new URL(event.request.url);
 
@@ -40,32 +60,47 @@ self.addEventListener('fetch', (event) => {
     const isSupabaseRequest = url.hostname.includes('supabase.co');
 
     if (isAuthRequest || isApiRequest || isSupabaseRequest) {
-        // console.log('[SW] Bypassing cache for:', url.pathname);
         return;
     }
 
-    // Network first for all other requests, especially navigation
-    event.respondWith(
-        fetch(event.request)
-            .then((response) => {
-                // Optionally cache successful GET requests for assets
-                if (
-                    event.request.method === 'GET' &&
-                    response.status === 200 &&
-                    (url.pathname.startsWith('/_next/static/') || ASSETS_TO_CACHE.includes(url.pathname))
-                ) {
-                    const responseClone = response.clone();
-                    caches.open(CACHE_NAME).then((cache) => {
-                        cache.put(event.request, responseClone);
-                    });
-                }
-                return response;
+    // 1. ASSETS & APP SHELL: Stale-While-Revalidate
+    const isAsset = event.request.destination === 'style' ||
+        event.request.destination === 'script' ||
+        event.request.destination === 'worker' ||
+        event.request.destination === 'font' ||
+        event.request.destination === 'image' ||
+        url.pathname.startsWith('/_next/static');
+
+    if (isAsset) {
+        event.respondWith(
+            caches.match(event.request).then((cachedResponse) => {
+                const fetchPromise = fetch(event.request).then((networkResponse) => {
+                    if (networkResponse && networkResponse.status === 200) {
+                        const responseClone = networkResponse.clone();
+                        caches.open(CACHE_NAME).then((cache) => {
+                            cache.put(event.request, responseClone);
+                        });
+                    }
+                    return networkResponse;
+                });
+                return cachedResponse || fetchPromise;
             })
-            .catch((err) => {
-                if (event.request.mode === 'navigate') {
-                    console.log('[SW] Navigation failed, attempting cache fallback for:', url.pathname);
-                }
-                return caches.match(event.request);
-            })
-    );
+        );
+        return;
+    }
+
+    // 2. NAVIGATION: Network-First with 3s Timeout
+    if (event.request.mode === 'navigate') {
+        event.respondWith(
+            fetchWithTimeout(event.request, 3000)
+                .catch(() => {
+                    console.log('[SW] Navigation network failure or timeout, falling back to cache');
+                    return caches.match(event.request);
+                })
+        );
+        return;
+    }
+
+    // Default: Network-Only or default fetch
+    return;
 });