refactor: add full documentation and fix theme loading robustness

- Add JSDoc comments across frontend and backend modules
- Improve code readability and maintainability with consistent documentation style
- Document Electron IPC handlers, UI utilities, and theme system
- Add missing function/class documentation in theme loader and app services
- Minor structural improvements and cleanup across Electron main process modules
- Minor fixes on variable names

public/script/settingsPanel.js

@@ -1,66 +1,105 @@
+/**
+ * Settings panel DOM elements used to control application feature flags
+ * and configuration UI interactions.
+ */
 const settingsPanel = document.getElementById("settings-panel");
 const settingsModal = document.querySelector(".settings-modal");
-
 const settingsButton = document.getElementById("settings-button");
 
+/**
+ * Tracks current settings panel state.
+ * NOTE: actual visibility is derived from DOM style in current implementation.
+ */
 let isOpen = false;
 
+/**
+ * Toggles visibility of the settings panel when clicking the settings button.
+ */
 settingsButton.addEventListener("click", () => {
-    const isOpen = settingsPanel.style.display === "block";
-    settingsPanel.style.display = isOpen ? "none" : "block";
+  const currentlyOpen = settingsPanel.style.display === "block";
+  settingsPanel.style.display = currentlyOpen ? "none" : "block";
 });
 
+/**
+ * Closes the settings panel and resets internal state.
+ */
 function closePanel() {
-    isOpen = false;
-    settingsPanel.style.display = "none";
+  isOpen = false;
+  settingsPanel.style.display = "none";
 }
 
-
+/**
+ * Loads feature flags from Electron backend and syncs them
+ * with corresponding UI controls (checkboxes, selects).
+ *
+ * Also registers change listeners to persist updates in real time.
+ */
 async function loadSettings() {
   const features = await window.electronAPI.getFeatures();
 
-  document.querySelectorAll(".settings-section input, .settings-section select").forEach(el => {
-    const key = el.dataset.key;
-    if (features[key] !== undefined) {
-      if (el.type === "checkbox") el.checked = features[key];
-      else if (el.tagName === "SELECT") el.value = features[key];
-    }
+  document
+    .querySelectorAll(".settings-section input, .settings-section select")
+    .forEach((el) => {
+      const key = el.dataset.key;
+      if (!key) return;
 
-    el.addEventListener("change", () => {
-      if (key === "theme") return;
-      let value = el.type === "checkbox" ? el.checked : el.value;
-      window.electronAPI.setFeature(key, value);
+      if (features[key] !== undefined) {
+        if (el.type === "checkbox") el.checked = features[key];
+        else if (el.tagName === "SELECT") el.value = features[key];
+      }
+
+      el.addEventListener("change", () => {
+        if (key === "theme") return;
+
+        const value = el.type === "checkbox" ? el.checked : el.value;
+        window.electronAPI.setFeature(key, value);
+      });
     });
-  });
 }
 
-// Open The JSON
-document.getElementById("open-json-btn").addEventListener("click", () => {
-  window.topbarAPI.openConfig();
+/**
+ * Opens configuration JSON file via Electron topbar API.
+ */
+document.getElementById("open-json-btn")
+  ?.addEventListener("click", () => {
+    window.topbarAPI.openConfig();
+  });
+
+/**
+ * Opens theme directory via Electron topbar API.
+ */
+document.getElementById("open-theme")
+  ?.addEventListener("click", () => {
+    window.topbarAPI.openTheme();
+  });
+
+/**
+ * Refreshes theme list and updates UI selector with a short animation.
+ */
+document.getElementById("refresh-themes-btn")
+  ?.addEventListener("click", function () {
+    this.classList.add("spinning");
+    window.refreshThemes();
+
+    setTimeout(() => {
+      this.classList.remove("spinning");
+    }, 600);
+  });
+
+/**
+ * Clicking the overlay outside the modal closes the settings panel.
+ */
+settingsPanel?.addEventListener("click", closePanel);
+
+/**
+ * Prevents modal clicks from closing the settings panel
+ * by stopping event propagation to the overlay.
+ */
+settingsModal?.addEventListener("click", (e) => {
+  e.stopPropagation();
 });
 
-// Open Theme Folder
-document.getElementById("open-theme").addEventListener("click", () => {
-  window.topbarAPI.openTheme();
-});
-
-// Refresh Themes
-document.getElementById("refresh-themes-btn").addEventListener("click", function() {
-  this.classList.add("spinning");
-  window.refreshThemes();
-  
-  setTimeout(() => {
-    this.classList.remove("spinning");
-  }, 600);
-});
-
-
-/* clic sur l'overlay = fermer */
-settingsPanel.addEventListener("click", closePanel);
-
-/* clic dans la modal = stop propagation */
-settingsModal.addEventListener("click", (e) => {
-    e.stopPropagation();
-});
-
-loadSettings();
+/**
+ * Initializes settings UI by loading backend feature flags.
+ */
+loadSettings();