State & Preferences Persistence

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/state.ts
• src/main/index.ts
• src/preload/settings-modal.ts
• src/preload/index.ts
• AGENTS.md
• CLAUDE.md

State and preferences persistence in Messenger Unleashed is the system responsible for managing user configurations, window states, and feature toggles across application restarts. The system ensures that user customizations—such as themes, privacy blocks, and keyboard shortcuts—remain consistent without requiring reconfiguration on every launch.

The architecture relies primarily on electron-store for file-based persistence, storing data in a config.json file located in platform-specific application support directories. The main process acts as the central authority for reading and writing these settings, while the renderer and preload processes synchronize with this state via Inter-Process Communication (IPC).

Sources: AGENTS.md, CLAUDE.md

Core Persistence Architecture

The application uses a centralized store-based persistence pattern. All settings are defined with default values in src/main/state.ts and managed by the electron-store library. This store persists data to a local JSON file:

• macOS: ~/Library/Application Support/messenger-unleashed/config.json
• Windows: %APPDATA%/messenger-unleashed/config.json

Sources: CLAUDE.md

Data Flow for Settings Updates

When a user modifies a setting via the Settings UI (rendered in the preload context), the change follows a specific flow:

1. UI Interaction: User toggles a switch or changes a value in the Settings Modal.
2. IPC Signal: The preload script sends an update-setting event to the main process.
3. Store Update: The main process receives the event, validates the key, and updates the local store using store.set(key, value).
4. Side Effects: The main process triggers necessary side effects (e.g., updating the application menu, injecting CSS, or refreshing global shortcuts).
5. Synchronization: Updated configurations are pushed back to the renderer via the update-config IPC channel to ensure the UI reflects the current state.

Sources: src/main/index.ts:1335-1418, src/preload/settings-modal.ts:153-176

Persistence Flow Diagram

This diagram illustrates how settings move from the User Interface to the physical storage and back.

Managed Settings and Defaults

The application persists a wide range of settings categorized into privacy, appearance, system, and power tools.

Configuration Schema

The following table summarizes key settings persisted by the system:

Setting Key	Type	Description
theme	string	Current visual theme (e.g., 'default', 'oled', 'nord').
windowBounds	object	Persisted width and height of the main window.
blockReadReceipts	boolean	Blocks outgoing read receipt signals.
blockTypingIndicator	boolean	Prevents others from seeing "typing..." status.
shortcuts	object	Custom keybindings for application actions.
quickReplies	array	Custom message templates for rapid responses.
quietHoursEnabled	boolean	Automatically enables Do Not Disturb on a schedule.
experimentalEnabled	boolean	Unlocks unstable or ToS-breaking features.

Sources: src/main/index.ts:1210-1238, src/preload/settings-modal.ts:285-325

Window State Persistence

The system specifically tracks the windowBounds to ensure the application returns to its previous size on launch. This is handled via the resize event on the mainWindow.

// src/main/index.ts:1193-1196
mainWindow.on("resize", () => {
  const { width, height } = mainWindow.getBounds();
  store.set("windowBounds", { width, height });
});

Sources: src/main/index.ts:1193-1196

Synchronization Mechanisms

IPC Channels for State Management

The persistence system utilizes several IPC channels to synchronize state across Electron processes.

Channel Name	Process Direction	Purpose
update-setting	Preload -> Main	Request the main process to update a specific persistent key.
update-config	Main -> Preload	Notify the renderer of a global configuration change.
open-settings-modal	Main -> Preload	Send the current full configuration to populate the settings UI.
update-shortcut	Preload -> Main	Update and re-register a specific keyboard shortcut.

Sources: src/main/index.ts:1335-1450, src/preload/index.ts:101-103

Preload State Sync

The preload script maintains its own local config object which is kept in sync with the main store. This local state is used for high-frequency operations like clipboard sanitization and keyword alerting without needing synchronous calls to the main process.

Session Management Persistence

Beyond settings, the application manages session persistence via Electron's session API. This allows users to export and import their login state (cookies), effectively persisting their authenticated session independently of the standard configuration.

Session Persistence Operations

• Export Cookies: Scrapes cookies from messenger.com and facebook.com and saves them to a JSON file.
• Import Cookies: Reads a JSON file and sets cookies into the default session, allowing for session migration or backup.
• Clear Session: Wipes all local storage data, equivalent to a full logout.

Sources: src/main/index.ts:1455-1510

Conclusion

The State & Preferences Persistence system provides a robust framework for maintaining a customized user experience. By centralizing settings in electron-store and utilizing a clear IPC-based synchronization flow, the application ensures that complex features like theme hot-swapping, stealth mode configurations, and keyboard shortcuts remain consistent across sessions and process boundaries.