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

> Discover how Freell-MAPI's desktop app delivers a native menu-bar experience on Windows, macOS, and Linux. Enjoy seamless cross-platform integration with system tray support.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/desktop/src/window-chrome.ts) (lines 16-45), the Windows and Linux configuration returns a `backgroundColor` of `#09090b` alongside the hidden menu bar property:

```typescript
// 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```typescript
// 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```typescript
// 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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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.