Update documentation for new features and auth improvements

Expanded documentation to cover the new downloads manager, native context menu, OAuth/SSO and WebAuthn compatibility, and user agent strategy. Updated project structure and core concepts to reflect these features and clarified session and popup handling for authentication. Fixed minor typos and improved feature descriptions for clarity.

README.md

@@ -6,12 +6,16 @@ A customizable and privacy-focused web browser built with Electron. Nebula is de
 
 ## Features
 
-*   **Privacy Control:** Easily clear your browsing data, including history, cookies, and cache.
+*   **Privacy Control:** Easily clear your browsing data (history, cookies, cache, local storage, and more).
-*   **Tab Management:** Open new tabs, and manage them efficiently.
+*   **Tab Management:** Open new tabs, pop a tab out into a new window, and manage them efficiently.
-*   **Bookmarks:** Save your favorite sites.
+*   **Bookmarks:** Save your favorite sites with automatic backup on save.
-*   **History:** Keeps track of your browsing and search history.
+*   **History:** Keeps track of your browsing and search history with one-click clear.
-*   **Performance Monitoring:** Built-in tools to monitor application performance.
+*   **Downloads Manager:** Track downloads, pause/resume/cancel, and open or reveal completed files.
-*   **GPU Acceleration Control:** Advanced settings to manage GPU acceleration and troubleshoot rendering issues.
+*   **Context Menu:** Native right‑click menu with Back/Forward/Reload, open/download links, image actions, and Inspect Element.
+*   **Auth Compatibility:** Improved OAuth/SSO & WebAuthn support (popup windows enabled where needed).
+*   **Performance Monitoring:** Built-in tools to monitor app performance and force GC when needed.
+*   **GPU Acceleration Control:** Diagnostics and safe fallbacks to troubleshoot rendering issues.
+*   **Themes & Customization:** Built-in themes and live editor to craft your own.
 *   **Cross-Platform:** Runs on Windows, macOS, and Linux.
 
 [**Learn more about Nebula's features.**](documentation/FEATURES.md)
@@ -55,6 +59,8 @@ npm run dist
 
 This will create a distributable file in the `dist` directory.
 
+Tip (Windows): If you encounter GPU issues, try starting with `start-gpu-safe.bat` to launch in a safer rendering mode.
+
 ## Project Structure
 
 An overview of the project's structure. For a more detailed explanation, please see the [Project Structure documentation](documentation/PROJECT_STRUCTURE.md).
@@ -91,7 +97,7 @@ This project is licensed under the MIT License. [Read More](documentation/MIT.md
 
 ## Documentation
 
-* [MIT Licese](documentation/MIT.md)
+* [MIT License](documentation/MIT.md)
 * [GPU Fix](documentation/GPU-FIX-README.md)
 * [Features](documentation/FEATURES.md)
 * [Customization](documentation/Customization.md)

documentation/CORE_CONCEPTS.md

@@ -14,7 +14,8 @@ Electron applications have two types of processes: the **main process** and one
 
 Since the main and renderer processes are separate, they need a way to communicate. This is done through Inter-Process Communication (IPC).
 
--   **`ipcMain` and `ipcRenderer`**: Electron provides the `ipcMain` and `ipcRenderer` modules for this purpose. The main process can listen for messages from the renderer process using `ipcMain.handle`, and the renderer process can send messages using `ipcRenderer.invoke`.
+-   **`ipcMain` and `ipcRenderer`**: Electron provides the `ipcMain` and `ipcRenderer` modules for this purpose. The main process listens for messages using `ipcMain.handle`, and the renderer sends messages using `ipcRenderer.invoke`.
+	-   Nebula uses IPC for features like downloads control, bookmarks/history management, performance reports, GPU diagnostics, and window controls.
 
 -   **Context Bridge and Preload Script**: To securely expose APIs from the main process to the renderer process, Electron uses a **preload script** and the **context bridge**. The `preload.js` script runs in a special environment that has access to both the `window` object of the renderer process and Node.js APIs. The `contextBridge` is used to expose specific functions from the preload script to the renderer process, ensuring that the renderer process cannot access powerful Node.js APIs directly.
 
@@ -23,3 +24,9 @@ Since the main and renderer processes are separate, they need a way to communica
 -   **Performance Monitoring**: The `performance-monitor.js` module helps track the application's performance by monitoring metrics like memory usage and page load times. This is essential for identifying and addressing performance bottlenecks.
 
 -   **GPU Configuration**: The `gpu-config.js` and `gpu-fallback.js` modules manage GPU acceleration. Electron uses the system's GPU to render content, which can significantly improve performance. However, GPU drivers can sometimes be a source of instability. These modules allow Nebula to check the GPU status and apply fallbacks (like disabling hardware acceleration) if issues are detected, ensuring a more stable experience.
+
+### Authentication & User Agent Strategy
+
+-   **Auth Flow Compatibility**: Nebula allows popup windows for http/https to preserve OAuth/SSO flows without stripping POST bodies.
+-   **WebAuthn**: Platform authenticator features are enabled where supported, with diagnostics logged to help troubleshoot availability.
+-   **User Agent**: The default Electron token is removed from the UA string to improve site compatibility while appending a `Nebula/<version>` marker.

documentation/FEATURES.md

@@ -32,6 +32,15 @@ Nebula keeps a record of your browsing and search history to help you find your
 -   **Search History:** A list of all the searches you have made.
 -   **Clear History:** You can clear your history at any time from the settings page.
 
+### Downloads Manager
+
+Reliably download files with progress and controls.
+
+-   **Progress & State:** Each download shows received/total bytes and status.
+-   **Pause/Resume/Cancel:** Control active downloads where the server supports resuming.
+-   **Open or Reveal:** Open downloaded files directly or show them in your file manager.
+-   **Safe Filenames:** Files are saved to your OS Downloads folder with automatic de-duplication.
+
 ### Performance Monitoring
 
 Nebula includes built-in tools to help you monitor the browser's performance.
@@ -46,6 +55,22 @@ For advanced users, Nebula provides tools to manage GPU acceleration.
 -   **GPU Diagnostics:** View detailed information about your system's GPU and its status.
 -   **GPU Fallback:** If you experience rendering issues, you can apply a GPU fallback to use a more stable rendering path. This can help resolve visual glitches or crashes.
 
+### Native Context Menu
+
+Nebula provides a native right-click menu across pages and webviews.
+
+-   **Navigation:** Back, Forward, Reload.
+-   **Links:** Open in new tab, Download link, Open externally, Copy address.
+-   **Images:** Open in new tab, Save image as, Copy image address.
+-   **Editing:** Undo/Redo, Cut/Copy/Paste, Select All when applicable.
+-   **Developer:** Inspect Element (opens DevTools docked by default).
+
+### Authentication & Web Compatibility
+
+-   **OAuth/SSO Friendly:** Popup windows are allowed for http/https to support common login flows.
+-   **WebAuthn Diagnostics:** Platform authenticator features are enabled where supported and logged for troubleshooting.
+-   **Sturdy Navigation:** Login POST navigations are not intercepted by the main process.
+
 ### Custom Themes & Customization
 
 Nebula offers extensive customization options to personalize your browsing experience.
@@ -64,3 +89,8 @@ For detailed information about creating and managing themes, see the [Customizat
 Nebula is built with Electron, allowing it to run on multiple operating systems.
 
 -   **Windows, macOS, and Linux:** Enjoy a consistent browsing experience across different platforms.
+
+### Miscellaneous
+
+-   **User Agent Strategy:** Electron token is removed from the default user agent to improve site compatibility while appending a `Nebula/x.y.z` marker. You can opt-in to include the Electron token by setting `NEBULA_DEBUG_ELECTRON_UA=1`.
+-   **Open Local Files:** Use the file picker to open `file://` URLs directly.

documentation/PROJECT_STRUCTURE.md

@@ -3,6 +3,7 @@
 This document provides an in-depth look at the project's file and directory structure.
 
 -   **`main.js`**: This is the heart of the Electron application. It's the main process script that controls the application's lifecycle, creates browser windows, and handles all interactions with the operating system.
+    -   Manages native context menu, downloads, and OAuth/WebAuthn-friendly window behavior.
 
 -   **`renderer/`**: This directory contains all the client-side code and assets for the browser's user interface (the renderer process).
     -   **`index.html`**: The main HTML file that serves as the container for the browser's UI, including the tab bar, address bar, and the webview for displaying web content.
@@ -14,12 +15,14 @@ This document provides an in-depth look at the project's file and directory stru
     -   **`gpu-diagnostics.html`**: The page for displaying GPU information.
     -   **`performance.css`**: Styles for the performance monitoring page.
     -   **`icons.js`**, **`icons.json`**: Files related to managing icons within the UI.
+    -   Other pages: downloads UI and settings integrate with main-process IPC.
 
 -   **`preload.js`**: This script is a crucial part of Electron's security model. It runs in a privileged context before the renderer process's web page is loaded. It's used to selectively expose APIs from the main process to the renderer process via the `contextBridge`.
 
 -   **`performance-monitor.js`**: A Node.js module that runs in the main process to track application performance metrics like memory usage and page load times.
 
 -   **`gpu-config.js`** & **`gpu-fallback.js`**: These modules are responsible for managing GPU-related settings. `gpu-config.js` checks the system's GPU capabilities, and `gpu-fallback.js` provides mechanisms to disable or reduce GPU acceleration if problems are detected.
+    -   `start-gpu-safe.bat` starts the app with safer GPU settings on Windows.
 
 -   **`assets/`**: This directory holds all static assets.
     -   **`images/`**: Contains logos, icons, and other images used in the application.
@@ -32,5 +35,6 @@ This document provides an in-depth look at the project's file and directory stru
     -   **`bookmarks.json`**: Stores the user's bookmarks.
     -   **`site-history.json`**: Stores the user's browsing history.
     -   **`search-history.json`**: Stores the user's search history.
+    -   **`bookmarks.backup.json`**: Auto-created backup of bookmarks on save.
 
 -   **`start-gpu-safe.bat`**: A batch script for Windows users to start the application in a GPU-safe mode.

documentation/oauth-debug.md

@@ -2,23 +2,22 @@
 
 ## Changes Made to Fix Google Sign-in Issues
 
-### 1. Added Proper User Agent
+### 1. User Agent Strategy
-- Set `useragent` attribute on all webviews to identify as Chrome browser
+- Nebula removes the default Electron token from the UA and appends `Nebula/<version>` for better compatibility while still identifying the app.
-- User agent: `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Nebula/1.0.0`
+- The UA is applied at the session level (main/default sessions) so all tabs/webviews inherit it.
+- To debug with Electron visible in UA, set environment variable `NEBULA_DEBUG_ELECTRON_UA=1` before launch.
 
-### 2. Enhanced Webview Security Configuration
+### 2. Webview and Window Behavior
-- Added `webpreferences` attribute with proper security settings
+- Webviews inherit secure defaults from `webPreferences`.
-- Enabled JavaScript and maintained web security while allowing OAuth flows
+- Popup windows opened by sites (e.g., OAuth) are allowed for `http`/`https` URLs to preserve login flows.
 
 ### 3. Session Configuration for OAuth
-- Configured session permissions for OAuth compatibility
+- Configured session permissions for OAuth compatibility.
-- Added cookie change monitoring for Google domains
+- Added cookie change monitoring for Google domains.
-- Enhanced request headers for better OAuth compatibility
+- Enhanced request headers (Accept-Language, Accept) and `Referrer-Policy` for OAuth endpoints.
-- Added referrer policy for OAuth flows
 
 ### 4. Unified Session Partitioning
-- Changed all webviews to use `persist:main` partition instead of `persist:default`
+- The main window uses partition `persist:main`, and sessions are configured consistently so auth/session state is shared across tabs.
-- This ensures session data is shared across tabs for OAuth flows
 
 ## Testing Google Sign-in
 
@@ -28,6 +27,8 @@
 4. **Select your account** - should take you to password/2FA screen
 5. **Complete sign-in** - should successfully sign you in
 
+Note: POST-based navigations are not blocked or intercepted by the main process to avoid stripping request bodies.
+
 ## Debug Information
 
 If issues persist, check the Console (F12) for: