How the Freell-MAPI Desktop App Provides a Native Menu-Bar Experience

The desktop Freell-MAPI application leverages Electron’s platform-specific APIs to suppress the default browser-style menu bar on Windows and Linux while implementing native macOS title-bar styling and system-tray integration, creating a seamless cross-platform menu experience.

The tashfeenahmed/freellmapi repository delivers a desktop interface built on Electron that prioritizes platform-native user interface conventions. Rather than displaying the stock Electron menu bar across all operating systems, the codebase implements conditional logic that detects the host platform and applies appropriate chrome configurations. This ensures Windows and Linux users receive a clean, auto-hiding menu bar, while macOS users benefit from integrated system menus and tray-based accessibility.

Platform-Specific Window Chrome Configuration

The application centralizes its window decoration logic in desktop/src/window-chrome.ts, exporting a platformChrome() function that returns distinct configuration objects based on the detected operating system.

Windows and Linux: Auto-Hiding the Default Menu Bar

On Windows and Linux, Electron typically renders a persistent File / Edit / View menu bar that clashes with modern application design. Freell-MAPI disables this default behavior by passing autoHideMenuBar: true during BrowserWindow instantiation. This setting hides the menu bar by default, revealing it only when the user presses the Alt key, which preserves essential clipboard shortcuts while maintaining a minimalist interface.

According to the source code in desktop/src/window-chrome.ts (lines 16-45), the Windows and Linux configuration returns a backgroundColor of #09090b alongside the hidden menu bar property:

// desktop/src/window-chrome.ts – Windows & Linux configuration
export function platformChrome(platform: NodeJS.Platform | string): PlatformChrome {
  if (platform === 'darwin') {
    // macOS handled separately
    return { /* ... */ };
  }
  // Windows & Linux – hide the default Electron menu bar
  return {
    backgroundColor: '#09090b',
    autoHideMenuBar: true,
  };
}

macOS: Native Title Bar and Vibrancy Effects

macOS handles application menus at the system level rather than inside the window frame, so the application suppresses the embedded menu entirely. Instead, desktop/src/window-chrome.ts (lines 24-35) supplies macOS-specific options including titleBarStyle: 'hiddenInset' to create a hidden title bar that blends with the content area, and vibrancy: 'sidebar' to achieve the translucent, materials-based appearance consistent with native macOS applications.

The configuration also sets visualEffectState: 'followWindow' to ensure the vibrancy effect updates dynamically as the window moves between monitors with different appearance settings:

// desktop/src/window-chrome.ts – macOS configuration
if (platform === 'darwin') {
  return {
    titleBarStyle: 'hiddenInset',
    vibrancy: 'sidebar',
    visualEffectState: 'followWindow',
    backgroundColor: '#00000000',
  };
}

System Tray Integration for Native Accessibility

Beyond window-level chrome, Freell-MAPI extends the native menu experience to the system tray via desktop/src/tray.ts. This module creates a persistent tray icon that provides instant access to core application functions without requiring the user to open the main window.

Template Images for Automatic Dark Mode Support

On macOS, the tray implementation utilizes nativeImage.createFromPath() combined with setTemplateImage(true) to ensure the icon automatically adapts to both light and dark menu bar appearances. Template images allow macOS to apply appropriate tinting based on the system theme, preventing visibility issues when users switch between appearance modes.

Context Menu Construction

The tray context menu mirrors the functionality available in the traditional menu bar, providing actions such as opening the dashboard or quitting the application. The implementation uses Electron’s Menu.buildFromTemplate() API to construct native context menus that respect platform conventions:

// desktop/src/tray.ts – native tray menu implementation
const icon = nativeImage.createFromPath('resources/icon.png');
icon.setTemplateImage(true);               // auto‑tint for macOS dark/light mode

const tray = new Tray(icon);
tray.setToolTip('Freell‑MAPI');
tray.setContextMenu(Menu.buildFromTemplate([
  { label: 'Open Dashboard', click: () => /* window management logic */ },
  { type: 'separator' },
  { label: 'Quit', role: 'quit' },
]));

Implementation Architecture

The desktop/src/main.ts entry point orchestrates these components by importing the platformChrome configuration and applying it during BrowserWindow instantiation. This ensures that the platform-specific menu handling and visual styling are established before the renderer process loads.

Additionally, desktop/src/i18n.ts provides localized string resources that feed into both the tray context menu and any in-window menu selectors, ensuring consistent labeling across the native interface elements regardless of the user's system language.

Summary

• desktop/src/window-chrome.ts centralizes platform detection logic, returning autoHideMenuBar: true for Windows/Linux and titleBarStyle: 'hiddenInset' with vibrancy effects for macOS.
• desktop/src/tray.ts creates a system-native tray icon using template images (setTemplateImage(true)) to support macOS dark mode, with a context menu built via Menu.buildFromTemplate().
• The application relies on Electron APIs rather than Tauri, utilizing BrowserWindow options to suppress the default menu bar where appropriate and embrace system-level menus on macOS.
• The platformChrome() function abstracts all per-platform differences, allowing main.ts to apply the correct configuration through a single unified interface.

Frequently Asked Questions

How does the app handle menu bars differently on Windows versus macOS?

On Windows and Linux, the application sets autoHideMenuBar: true in the BrowserWindow constructor options, hiding the default Electron menu until the user presses the Alt key. On macOS, the app leaves the system menu bar untouched and instead configures the window chrome using titleBarStyle: 'hiddenInset' and vibrancy: 'sidebar' to achieve a native, frameless appearance that integrates with the macOS menu system.

Why does the tray icon use setTemplateImage?

The setTemplateImage(true) call in desktop/src/tray.ts marks the tray icon as a template image on macOS, which strips color information and allows the operating system to apply appropriate tinting automatically. This ensures the icon remains visible and aesthetically consistent when users switch between light and dark menu bar modes without requiring separate image assets for each theme.

Where is the platform detection logic centralized?

The platformChrome() function exported from desktop/src/window-chrome.ts serves as the single source of truth for platform-specific window configurations. This function accepts the Node.js platform string and returns a PlatformChrome object containing the appropriate titleBarStyle, vibrancy, and autoHideMenuBar settings that desktop/src/main.ts applies during application startup.

Does Freell-MAPI use Electron or Tauri for its desktop implementation?

Analysis of the source code reveals an Electron architecture, evidenced by the use of electron/nativeImage, electron/Tray, BrowserWindow options such as autoHideMenuBar, and Node.js platform detection. The implementation relies on Electron’s native API bindings rather than Tauri’s Rust-based WebView approach to achieve its menu-bar and tray functionality.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}