Chat Heads Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Chat Heads Implementation in Messenger Unleashed provides a persistent, floating UI component that allows users to maintain access to their active conversation even when the main application window is minimized or hidden. This feature mimics mobile "bubbles" by creating a small, frameless, and transparent BrowserWindow that displays the avatar of the current chat partner.
This system relies on a coordination between the Main process (to manage window state and IPC), the Preload script (to scrape DOM data from messenger.com), and a dedicated Chat Head window that renders a lightweight HTML overlay.
Core Architecture
The system is split into three functional layers: Data Scraping, Window Management, and the UI Overlay.
Data Scraping (Preload)
The application periodically scrapes the active conversation's metadata from the Messenger web interface. This is handled by scrapeActiveChat() in the preload script, which searches for avatar images in navigation links or headers.
Sources: src/preload/index.ts:1049-1065, src/main/chat-head.ts:12-25
Window Management (Main Process)
The Main process handles the lifecycle of the Chat Head window. It is triggered to show when the main window is minimized or hidden, and it is hidden when the main window is restored or focused.
Sources: src/main/index.ts:1342-1360, src/main/chat-head.ts:34-42
Messaging Flow
The following sequence diagram illustrates how chat information travels from the Messenger web view to the floating Chat Head:
Component Details
The Chat Head Window
The Chat Head is a specialized BrowserWindow with strict visual constraints to ensure it feels like a native desktop widget.
| Property | Value | Description |
|---|---|---|
| Size | 70x70 | Fixed dimensions for the floating bubble. |
| Frame | false | Removes standard window borders and title bars. |
| Transparency | true | Allows the circular avatar to float over other apps. |
| Always on Top | true | Ensures visibility regardless of other open windows. |
| Skip Taskbar | true | Prevents the Chat Head from appearing as a separate app in the taskbar/dock. |
Sources: src/main/chat-head.ts:54-66
IPC Communication
The feature uses several IPC channels to synchronize state between the background Messenger process and the foreground UI.
update-active-chat: Sent by the preload script to the main process containing thesrcof the current avatar.update-head: Sent by the main process to the Chat Head window to update the rendered image.chat-head-clicked: Sent by the Chat Head window to the main process when the user clicks the bubble, triggering the main window to restore.
Sources: src/main/chat-head.ts:12-28, src/preload/index.ts:1049-1050
Implementation Logic
Avatar Extraction
The extraction logic is designed to be resilient against Messenger's dynamic DOM by checking multiple potential locations for the partner's image.
function getAvatarSrc(container) {
if (!container) return null
const img =
container.querySelector('img') ||
container.querySelector('svg image') ||
container.querySelector('svg mask image') ||
container.querySelector('image')
if (!img) return null
return (
img.src ||
img.getAttribute('href') ||
img.getAttribute('xlink:href') ||
null
)
}
Sources: src/preload/index.ts:1068-1082
Visual Styling
The Chat Head renders a raw HTML string containing a div styled as a circle. It uses -webkit-app-region: drag on the body to allow moving the bubble, but -webkit-app-region: no-drag on the avatar itself to allow click events to pass through to the application logic.
Sources: src/main/chat-head.ts:74-95
Configuration and Persistence
The system persists the last known chat head avatar URL to the local store. This allows the Chat Head to display the correct person immediately upon being shown, even if the preload script hasn't performed a fresh scrape yet.
- Store Key:
lastChatHeadSrc - Default Behavior: If no active chat info is available, it defaults to a generic "M" placeholder.
Sources: src/main/chat-head.ts:15, src/main/chat-head.ts:45-50, CLAUDE.md:23-28
Conclusion
The Chat Heads implementation leverages Electron's ability to create transparent, always-on-top windows to enhance the desktop messaging experience. By combining active DOM scraping with IPC-driven window management, it provides a seamless transition between the full application and a minimalist floating interface.