diff --git a/README.md b/README.md index ce4ac93..8b12342 100644 --- a/README.md +++ b/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. -* **Tab Management:** Open new tabs, and manage them efficiently. -* **Bookmarks:** Save your favorite sites. -* **History:** Keeps track of your browsing and search history. -* **Performance Monitoring:** Built-in tools to monitor application performance. -* **GPU Acceleration Control:** Advanced settings to manage GPU acceleration and troubleshoot rendering issues. +* **Privacy Control:** Easily clear your browsing data (history, cookies, cache, local storage, and more). +* **Tab Management:** Open new tabs, pop a tab out into a new window, and manage them efficiently. +* **Bookmarks:** Save your favorite sites with automatic backup on save. +* **History:** Keeps track of your browsing and search history with one-click clear. +* **Downloads Manager:** Track downloads, pause/resume/cancel, and open or reveal completed files. +* **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) diff --git a/documentation/CORE_CONCEPTS.md b/documentation/CORE_CONCEPTS.md index dae843a..96d90e7 100644 --- a/documentation/CORE_CONCEPTS.md +++ b/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/` marker. diff --git a/documentation/FEATURES.md b/documentation/FEATURES.md index f4237d6..b545d71 100644 --- a/documentation/FEATURES.md +++ b/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. diff --git a/documentation/PROJECT_STRUCTURE.md b/documentation/PROJECT_STRUCTURE.md index 35a80df..6cacbd2 100644 --- a/documentation/PROJECT_STRUCTURE.md +++ b/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. diff --git a/documentation/oauth-debug.md b/documentation/oauth-debug.md index e6a0535..33547d2 100644 --- a/documentation/oauth-debug.md +++ b/documentation/oauth-debug.md @@ -2,23 +2,22 @@ ## Changes Made to Fix Google Sign-in Issues -### 1. Added Proper User Agent -- Set `useragent` attribute on all webviews to identify as Chrome browser -- 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` +### 1. User Agent Strategy +- Nebula removes the default Electron token from the UA and appends `Nebula/` for better compatibility while still identifying the app. +- 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 -- Added `webpreferences` attribute with proper security settings -- Enabled JavaScript and maintained web security while allowing OAuth flows +### 2. Webview and Window Behavior +- Webviews inherit secure defaults from `webPreferences`. +- 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 -- Added cookie change monitoring for Google domains -- Enhanced request headers for better OAuth compatibility -- Added referrer policy for OAuth flows +- Configured session permissions for OAuth compatibility. +- Added cookie change monitoring for Google domains. +- Enhanced request headers (Accept-Language, Accept) and `Referrer-Policy` for OAuth endpoints. ### 4. Unified Session Partitioning -- Changed all webviews to use `persist:main` partition instead of `persist:default` -- This ensures session data is shared across tabs for OAuth flows +- The main window uses partition `persist:main`, and sessions are configured consistently so auth/session state is shared across tabs. ## 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: