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.
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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/<version>` 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:
|
||||
|
||||
Reference in New Issue
Block a user