refactor: clean up theme system per code review

- Remove generation artifact (IMPLEMENTATION_COMPLETE.md)
- Consolidate duplicate theme checks in settings page
- Simplify theme precedence logic (localStorage > backend)
- Remove all console.log statements from theme code
- Add debounced auto-save (500ms) to prevent API spam
- Centralize theme API with subscriptions and constants
- Improve error handling (silent fails for localStorage)
- Guard all localStorage access for SSR compatibility

Addresses all feedback from @scrrlt review:
- No more redundant theme logic
- Single source of truth for theme operations
- Proper error handling without console noise
- Debounced network calls for better performance

Author: tusharkhatriofficial

IMPLEMENTATION_COMPLETE.md

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import {
   Settings as SettingsIcon,
   Sun,
@@ -30,6 +30,7 @@ import {
 import { apiUrl } from "@/lib/api";
 import { getTranslation } from "@/lib/i18n";
 import { setTheme } from "@/lib/theme";
+import { debounce } from "@/lib/debounce";
 
 import { useGlobal } from "@/context/GlobalContext";
 
@@ -225,6 +226,21 @@ export default function SettingsPage() {
     string | null
   >(null);
 
+  // Create debounced theme save function
+  const debouncedSaveTheme = useRef(
+    debounce(async (themeValue: "light" | "dark", uiSettings: UISettings) => {
+      try {
+        await fetch(apiUrl("/api/v1/settings/ui"), {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ ...uiSettings, theme: themeValue }),
+        });
+      } catch (err) {
+        // Silently fail - theme is still saved to localStorage
+      }
+    }, 500)
+  ).current;
+
   useEffect(() => {
     fetchSettings();
     fetchSettings();
@@ -444,22 +460,18 @@ export default function SettingsPage() {
       const res = await fetch(apiUrl("/api/v1/settings"));
       if (res.ok) {
         const responseData = await res.json();
-        console.log("[settings] fetchSettings - backend ui:", responseData.ui);
         setData(responseData);
         setEditedConfig(JSON.parse(JSON.stringify(responseData.config)));
         if (!editedUI) {
           const uiData = JSON.parse(JSON.stringify(responseData.ui));
-          // If there's a stored theme in localStorage, use it instead of backend default
+          // localStorage takes priority over backend
           const storedTheme = localStorage.getItem('deeptutor-theme');
-          console.log("[settings] fetchSettings - storedTheme from localStorage:", storedTheme);
           if (storedTheme === 'light' || storedTheme === 'dark') {
-            console.log("[settings] Using localStorage theme:", storedTheme, "instead of backend:", uiData.theme);
             uiData.theme = storedTheme;
           }
           setEditedUI(uiData);
-          // Apply the theme (either from localStorage or backend)
+          // Apply theme if present
           if (uiData.theme) {
-            console.log("[settings] Applying theme:", uiData.theme);
             applyTheme(uiData.theme);
           }
         }
@@ -595,8 +607,6 @@ export default function SettingsPage() {
   const applyTheme = (theme: "light" | "dark") => {
     // Persist theme to localStorage and document immediately
     setTheme(theme);
-    // Console log for debugging
-    console.log("Theme changed to:", theme, "and saved to localStorage");
   };
 
   const handleSave = async () => {
@@ -674,12 +684,8 @@ export default function SettingsPage() {
       const newUI = { ...prev, [key]: value };
       if (key === "theme") {
         applyTheme(value);
-        // Auto-save theme to backend immediately
-        fetch(apiUrl("/api/v1/settings/ui"), {
-          method: "PUT",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ ...newUI, [key]: value }),
-        }).catch((err) => console.error("Failed to save theme:", err));
+        // Debounced auto-save to backend
+        debouncedSaveTheme(value, newUI);
       }
       return newUI;
     });

web/app/settings/page.tsx

@@ -9,28 +9,22 @@ export default function ThemeScript() {
     (function() {
       try {
         const stored = localStorage.getItem('deeptutor-theme');
-        console.log('[ThemeScript] localStorage theme:', stored);
         
         if (stored === 'dark') {
-          console.log('[ThemeScript] Applying dark theme from localStorage');
           document.documentElement.classList.add('dark');
         } else if (stored === 'light') {
-          console.log('[ThemeScript] Applying light theme from localStorage');
           document.documentElement.classList.remove('dark');
         } else {
-          console.log('[ThemeScript] No theme in localStorage, checking system preference');
           // Use system preference if not set
           if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
-            console.log('[ThemeScript] System prefers dark, applying dark theme');
             document.documentElement.classList.add('dark');
             localStorage.setItem('deeptutor-theme', 'dark');
           } else {
-            console.log('[ThemeScript] System prefers light, applying light theme');
             localStorage.setItem('deeptutor-theme', 'light');
           }
         }
       } catch (e) {
-        console.error('[ThemeScript] Error:', e);
+        // Silently fail - localStorage may be disabled
       }
     })();
   `;

web/components/ThemeScript.tsx

@@ -270,26 +270,22 @@ export function GlobalProvider({ children }: { children: React.ReactNode }) {
       if (res.ok) {
         const data = await res.json();
         if (data.ui) {
-          // Check if localStorage has a saved theme preference
+          // localStorage takes priority over backend
           const storedTheme = getStoredTheme();
           const themeToUse = storedTheme || data.ui.theme;
 
-          console.log("[GlobalContext] refreshSettings - storedTheme:", storedTheme, "backendTheme:", data.ui.theme, "final:", themeToUse);
-          
           setUiSettings({
             theme: themeToUse,
             language: data.ui.language,
           });
-          // Persist theme to localStorage (will sync with backend on save)
+          // Apply and persist theme
           setTheme(themeToUse);
         }
       }
     } catch (e) {
-      console.error("Failed to load settings from backend", e);
-      // Fall back to localStorage theme
+      // Fall back to localStorage theme on error
       const stored = getStoredTheme();
       if (stored) {
-        console.log("[GlobalContext] Using fallback localStorage theme:", stored);
         setUiSettings((prev) => ({ ...prev, theme: stored }));
       }
     }
@@ -299,7 +295,6 @@ export function GlobalProvider({ children }: { children: React.ReactNode }) {
     // Initialize theme immediately on first render
     if (!isInitialized) {
       const initialTheme = initializeTheme();
-      console.log("[GlobalContext] useEffect - initialized theme:", initialTheme);
       setUiSettings((prev) => ({ ...prev, theme: initialTheme }));
       setIsInitialized(true);
 

web/context/GlobalContext.tsx

@@ -0,0 +1,22 @@
+/**
+ * Debounce utility
+ * Delays function execution until after wait milliseconds have elapsed since the last call
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: NodeJS.Timeout | null = null;
+
+  return function executedFunction(...args: Parameters<T>) {
+    const later = () => {
+      timeout = null;
+      func(...args);
+    };
+
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(later, wait);
+  };
+}