Offline/UX: real connectivity probe, anti-hang on load, remove Documentation from app nav

- Connectivity is now decided by actively probing the API /health (5s timeout) rather than
  trusting navigator.onLine, which a misconfigured NIC/captive portal can get wrong. Re-probed
  on navigator events and every 25s; offline→online transition flushes the queue.
- Auth check is time-bounded (8s) so a stuck/slow network can't leave the app stuck on
  'loading'; it also distinguishes a 401 (logged out → no user) from a network error/timeout
  (offline → keep the cached user). Service worker navigations time out at 4s and fall back to
  the cached page, so slow mobile networks don't hang.
- Removed the Documentation link from the signed-in sidebar (still public at /docs, linked from
  /legal and the README).

Author: softpython2884

apps/web/public/sw.js

@@ -50,21 +50,24 @@ self.addEventListener('fetch', (event) => {
     return;
   }
 
-  // Page navigations: network-first, falling back to the cached page or the app shell.
+  // Page navigations: network-first with a short timeout (so a slow mobile network falls back to
+  // the cached page instead of hanging), then the cached page or the app shell.
   if (req.mode === 'navigate') {
     event.respondWith(
-      fetch(req)
-        .then((res) => {
+      Promise.race([
+        fetch(req).then((res) => {
           const copy = res.clone();
           caches.open(SHELL).then((c) => c.put(req, copy)).catch(() => {});
           return res;
-        })
-        .catch(() =>
-          caches
-            .match(req)
-            .then((r) => r || caches.match('/'))
-            .then((r) => r || Response.error()),
-        ),
+        }),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 4000)),
+      ]).catch(() =>
+        caches
+          .match(req)
+          .then((r) => r || caches.match('/'))
+          .then((r) => r || fetch(req))
+          .catch(() => Response.error()),
+      ),
     );
   }
 });

apps/web/src/app/(app)/layout.tsx

@@ -3,7 +3,7 @@
 import Link from 'next/link';
 import { usePathname, useRouter } from 'next/navigation';
 import { useEffect, useState } from 'react';
-import { FolderLock, Share2, Globe, Settings, ShieldCheck, LogOut, Menu, X, Trash2, BookOpen } from 'lucide-react';
+import { FolderLock, Share2, Globe, Settings, ShieldCheck, LogOut, Menu, X, Trash2 } from 'lucide-react';
 import { useAuth } from '@/lib/auth';
 import { useT } from '@/lib/i18n';
 import { Wordmark } from '@/components/Wordmark';
@@ -17,7 +17,6 @@ const NAV = [
   { href: '/shares', labelKey: 'nav.shares', icon: Share2 },
   { href: '/remote', labelKey: 'nav.remote', icon: Globe },
   { href: '/trash', labelKey: 'nav.trash', icon: Trash2 },
-  { href: '/docs', labelKey: 'nav.docs', icon: BookOpen },
 ];
 
 export default function AppLayout({ children }: { children: React.ReactNode }) {

apps/web/src/lib/auth.tsx

@@ -6,7 +6,7 @@
  */
 import { createContext, useCallback, useContext, useEffect, useState } from 'react';
 import type { PublicUser } from '@opencoperlock/shared/client';
-import { login as apiLogin, logout as apiLogout, me } from './api';
+import { login as apiLogin, logout as apiLogout, me, ApiError } from './api';
 
 interface AuthState {
   user: PublicUser | null;
@@ -24,17 +24,22 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
   const refresh = useCallback(async () => {
     try {
-      const res = await me();
+      // Bound the check so a stuck/slow network can never leave the app on "loading" forever.
+      const res = await Promise.race([
+        me(),
+        new Promise<never>((_, reject) => setTimeout(() => reject(new TypeError('auth timeout')), 8000)),
+      ]);
       setUser(res.user);
       try {
         localStorage.setItem('ocl_user', JSON.stringify(res.user));
       } catch {
         /* storage unavailable */
       }
-    } catch {
-      // Offline: keep the last-known user so the app still loads (read-only / queue uploads).
+    } catch (err) {
+      // A real HTTP response (e.g. 401) means we're logged out → no user. A network failure or
+      // timeout means we're probably offline → keep the last-known user so the app still loads.
       let cached: PublicUser | null = null;
-      if (typeof navigator !== 'undefined' && !navigator.onLine) {
+      if (!(err instanceof ApiError)) {
         try {
           const raw = localStorage.getItem('ocl_user');
           if (raw) cached = JSON.parse(raw) as PublicUser;

apps/web/src/lib/offline.tsx

@@ -7,7 +7,7 @@
  */
 import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
 import { FAST_UPLOAD_FOLDER_NAME } from '@opencoperlock/shared/client';
-import { api } from './api';
+import { api, API_URL } from './api';
 import { useAuth } from './auth';
 import { useT } from './i18n';
 import { toast } from '@/components/ui/overlays';
@@ -83,32 +83,52 @@ export function OfflineProvider({ children }: { children: React.ReactNode }) {
     }
   }, [refresh, reloadItems, t]);
 
+  // Real connectivity = can we actually reach the API, not just what navigator.onLine claims
+  // (a misconfigured NIC or captive portal can lie). We probe /health with a short timeout and
+  // use that as the source of truth; navigator events and a timer just trigger a re-probe.
+  const onlineRef = useRef(true);
+  const probe = useCallback(async (): Promise<boolean> => {
+    try {
+      const ctrl = new AbortController();
+      const to = setTimeout(() => ctrl.abort(), 5000);
+      const res = await fetch(`${API_URL}/health`, { method: 'GET', cache: 'no-store', credentials: 'omit', signal: ctrl.signal });
+      clearTimeout(to);
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }, []);
+
+  const recheck = useCallback(async () => {
+    const ok = await probe();
+    const was = onlineRef.current;
+    onlineRef.current = ok;
+    setOnline(ok);
+    if (ok && !was) void flush(); // transitioned offline → online
+  }, [probe, flush]);
+
   useEffect(() => {
-    setOnline(navigator.onLine);
     void reloadItems();
-    const goOnline = () => {
-      setOnline(true);
-      void flush();
-    };
-    const goOffline = () => setOnline(false);
-    window.addEventListener('online', goOnline);
-    window.addEventListener('offline', goOffline);
-    // Catch a connection that came back before this mounted.
-    if (navigator.onLine) void flush();
+    void recheck();
+    const onEvt = () => void recheck();
+    window.addEventListener('online', onEvt);
+    window.addEventListener('offline', onEvt);
+    const iv = setInterval(() => void recheck(), 25000);
     return () => {
-      window.removeEventListener('online', goOnline);
-      window.removeEventListener('offline', goOffline);
+      window.removeEventListener('online', onEvt);
+      window.removeEventListener('offline', onEvt);
+      clearInterval(iv);
     };
-  }, [flush, reloadItems]);
+  }, [recheck, reloadItems]);
 
   const enqueueFiles = useCallback(
     async (files: FileList | File[], folderId: string, folderName: string) => {
       for (const file of Array.from(files)) {
         await enqueue({ blob: file, name: file.name, type: file.type, folderId, folderName, createdAt: Date.now() });
       }
       await reloadItems();
-      // If we're actually online (e.g. flaky), try to flush right away.
-      if (navigator.onLine) void flush();
+      // If we're actually reachable, try to flush right away.
+      if (onlineRef.current) void flush();
     },
     [reloadItems, flush],
   );