Keyword Alerts System

Relevant source files

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

• src/main/index.ts
• src/preload/index.ts
• src/preload/settings-modal.ts
• CLAUDE.md
• landing-page/src/app/HomeClient.tsx

The Keyword Alerts System is a proactive monitoring feature within Messenger Unleashed that scans incoming messages for specific user-defined terms. When a match is detected, the system triggers a native desktop notification to alert the user, even if the application is not the primary focus.

The system operates across the Electron boundary, utilizing a MutationObserver in the preload script to watch for DOM changes in real-time, while relying on the main process to handle configuration persistence and native system notifications.

System Architecture

The Keyword Alerts System is distributed between the Main process and the Preload script. The Main process manages the persistent storage of keywords and the UI for editing them, while the Preload script handles the heavy lifting of DOM inspection and pattern matching.

Logic Flow Diagram

The following diagram illustrates the lifecycle of a keyword alert from message reception to user notification.

Component Breakdown

Main Process Configuration (src/main/index.ts)

The main process acts as the source of truth for configuration. It provides several IPC handlers and functions to manage the keyword list:

• toggleKeywordAlerts(): Toggles the global enablement state. Sources: src/main/index.ts:1022-1027
• editKeywordAlerts(): Opens a sandboxed input dialog for the user to enter a comma-separated list of keywords. Sources: src/main/index.ts:1030-1055
• pushRendererConfig(): Synchronizes the current keyword list and enablement status with the renderer/preload context. Sources: src/main/index.ts:1074-1087

Preload Script Detection (src/preload/index.ts)

The detection engine resides in the preload script to maintain direct access to the Messenger DOM.

• setupKeywordAlerts(): Initializes a MutationObserver that targets document.body. It uses a WeakSet named seenNodes to ensure each DOM element is only processed once. Sources: src/preload/index.ts:790-826
• notifyHit(text): A helper function that performs the matching logic. It converts incoming text to lowercase and checks if any configured keyword is included as a substring. Sources: src/preload/index.ts:797-809

Data Structures and Configuration

The system relies on a central configuration object that is synchronized via IPC.

Option	Type	Default Value	Description
keywordAlerts	string[]	[]	An array of lowercase strings used for matching.
keywordAlertsEnabled	boolean	false	Global toggle for the keyword monitoring system.

Sources: src/preload/index.ts:15-17, src/main/index.ts:1077-1078

User Interface Interaction

Users configure the system through the "Privacy & Stealth" section of the Settings Modal. The UI provides a toggle to enable the feature and a button to trigger the input dialog.

Implementation Details

DOM Observation

The system scans every new HTMLElement added to the DOM. If a text match occurs, it uses the notification bridge to show the alert.

// src/preload/index.ts:811-820
const observer = new MutationObserver((mutations) => {
  mutations.forEach(m => {
    m.addedNodes.forEach(node => {
      if (!(node instanceof HTMLElement)) return
      if (seenNodes.has(node)) return
      seenNodes.add(node)
      const text = node.innerText || ''
      if (text) notifyHit(text)
    })
  })
})

Notification Triggering

When a hit is detected, the preload script sends an IPC message to the main process. The main process then creates a native Electron Notification object.

// src/main/index.ts:553-575
ipcMain.on("show-notification", (event, data) => {
  if (store.get("doNotDisturb")) return;

  const notification = new Notification({
    title: data.title || "Messenger",
    body: data.body || "",
    silent: data.silent || false,
    icon: iconPath
  });
  notification.show();
});

Summary

The Keyword Alerts System provides an essential power-user feature for monitoring high-priority communications. By combining efficient DOM observation in the preload script with the native capabilities of the Electron main process, it ensures users stay informed of critical mentions without requiring constant manual oversight of the application interface. Sources: CLAUDE.md:65-71, landing-page/src/app/HomeClient.tsx:313-317