From 95f523461395889eb9934ece52b43ea3fcaa275e Mon Sep 17 00:00:00 2001 From: Andrew Zambazos Date: Mon, 8 Sep 2025 18:39:35 +1200 Subject: [PATCH] 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 | 20 +++++++++++++------- documentation/CORE_CONCEPTS.md | 9 ++++++++- documentation/FEATURES.md | 30 ++++++++++++++++++++++++++++++ documentation/PROJECT_STRUCTURE.md | 4 ++++ documentation/oauth-debug.md | 25 +++++++++++++------------ 5 files changed, 68 insertions(+), 20 deletions(-) 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: