Settings Modal & UI
Relevant source files
The following files were used as context for generating this wiki page:
The Settings Modal & UI in Messenger Unleashed is a central hub for configuring application behavior, privacy enhancements, and visual customizations. It is implemented as a custom-built, injected DOM element within the Electron renderer process, bridging user interactions to the main process via Inter-Process Communication (IPC). The UI allows users to toggle stealth features, switch between 17+ built-in themes, and manage system-level integrations like "Always on Top" and "Launch at Login."
Sources: src/preload/settings-modal.ts, src/main/index.ts:1210-1240, CLAUDE.md:20-30
Architecture and Data Flow
The settings system follows a decoupled architecture where the main process maintains the source of truth (via electron-store), and the preload script handles the rendering and UI logic. When a user requests the settings, the main process gathers the current configuration and sends it to the renderer.
Communication Flow
- Trigger: User selects "Open Settings" from the application menu or a shortcut.
- Gathering:
openSettingsUI()in the main process compiles the current state from the store. - Transmission: The main process sends an
open-settings-modalIPC message with the full configuration object. - Rendering: The preload script receives the event and dynamically generates the modal HTML/CSS.
- Updates: UI interactions (like toggling a switch) trigger
update-settingor specific action IPC messages back to the main process.
Sources: src/main/index.ts:1145-1175, src/preload/settings-modal.ts:5-10
The following diagram illustrates the sequence of events when a user modifies a setting within the modal:
UI Components and Categories
The Settings Modal is organized into logical panels, each focusing on a specific functional area of the application.
| Category | Key Features | Source File Reference |
|---|---|---|
| Privacy & Stealth | Read Receipts, Active Status, Typing Indicators, Keyword Alerts | src/preload/settings-modal.ts:250-300 |
| Appearance | Modern Look, Floating Glass, Theme Selection, Custom CSS | src/preload/settings-modal.ts:310-345 |
| System & Tools | Do Not Disturb, Always on Top, Launch at Login, Spell Check | src/preload/settings-modal.ts:348-380 |
| Power Tools | Quiet Hours, Quick Replies, Scheduled Messages | src/preload/settings-modal.ts:383-420 |
| Shortcuts | Global Hotkey Recording and Assignment | src/preload/settings-modal.ts:423-500 |
| Experimental | Typing Overlay, Android Bubbles (Unlocked via acknowledgement) | src/preload/settings-modal.ts:515-550 |
Dynamic Styling and Themes
The modal features a reactive design that adjusts to the system color scheme (dark/light mode). It utilizes CSS injection to apply styles dynamically. Themes are managed through the THEME_OPTIONS array and applied using applyThemeCSS(), which extracts blocks from a themes.css file using regex patterns.
Sources: src/preload/settings-modal.ts:15-100, src/main/themes.ts:7-35
Implementation Details
Setting Toggles
Toggles are implemented using the createToggleRow helper function in the preload script. When clicked, they toggle a local CSS class for visual feedback and immediately send the update to the main process.
// src/preload/settings-modal.ts:160-178
toggle.onclick = () => {
const active = toggle.classList.toggle("active")
ipcRenderer.send("update-setting", { key, value: active })
}
Keyboard Shortcut Recorder
The UI includes a sophisticated shortcut recorder that listens for keydown events when an action is selected. It captures modifiers (Cmd, Ctrl, Alt, Shift) and the primary key to form a valid Electron Accelerator string.
Experimental Access Guard
Certain "risky" features are hidden behind an Experimental Access guard. To unlock these, users must interact with a specific row in the System section that triggers a confirmation dialog requiring the input of a specific string ("I acknowledge").
Sources: src/preload/settings-modal.ts:182-205, src/main/index.ts:1242-1265
Conclusion
The Settings Modal & UI serves as the primary interface for users to personalize their Messenger experience. By utilizing a hybrid approach of dynamic DOM injection in the preload script and persistent state management in the main process, the system provides a native-feeling customization layer over the standard Messenger web interface while ensuring settings survive application restarts.
Sources: CLAUDE.md:65-75, AGENTS.md:10-15