Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

fix(desktop): a way into the app when macOS hides the tray icon (#807) (#1146)

Tashfeenf02c9ed0886d
diff --git a/desktop/src/__tests__/tray-visibility.test.ts b/desktop/src/__tests__/tray-visibility.test.ts
new file mode 100644
index 00000000..820fc373
--- /dev/null
+++ b/desktop/src/__tests__/tray-visibility.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { trayIsInMenuBar } from '../tray-visibility.js';
+
+// The numbers here are real: both rows were measured on macOS 26.5.2 (build
+// 25F84) by creating a tray, reading tray.getBounds(), then hiding the item the
+// way Tahoe's Menu Bar settings do (`NSStatusItem VisibleCC Item-0` = 0) and
+// reading the bounds again. Nothing about the failure is observable except
+// these coordinates, so they are what the guard is asserted against.
+
+const MAIN_DISPLAY = { bounds: { x: 0, y: 0, width: 1728, height: 1117 } };
+
+describe('tray visibility on macOS', () => {
+ it('treats an item on the menu-bar row as visible', () => {
+ const visible = { x: 1281, y: 0, width: 32, height: 33 };
+ expect(trayIsInMenuBar(visible, [MAIN_DISPLAY])).toBe(true);
+ });
+
+ it('treats the off-screen park position of a hidden item as not visible', () => {
+ const hidden = { x: 0, y: 1117, width: 32, height: 22 };
+ expect(trayIsInMenuBar(hidden, [MAIN_DISPLAY])).toBe(false);
+ });
+
+ it('counts a menu bar living on a second display', () => {
+ // Display above the built-in one: its menu-bar row is at y = -1080, which a
+ // hardcoded `y === 0` check would have called hidden.
+ const external = { bounds: { x: 0, y: -1080, width: 1920, height: 1080 } };
+ const onExternal = { x: 1500, y: -1080, width: 32, height: 33 };
+ expect(trayIsInMenuBar(onExternal, [MAIN_DISPLAY, external])).toBe(true);
+ });
+
+ it('rejects a zero-sized item, whatever its position', () => {
+ expect(trayIsInMenuBar({ x: 0, y: 0, width: 0, height: 0 }, [MAIN_DISPLAY])).toBe(false);
+ });
+});
diff --git a/desktop/src/config.ts b/desktop/src/config.ts
index e33d77f5..a7896abf 100644
--- a/desktop/src/config.ts
+++ b/desktop/src/config.ts
@@ -11,6 +11,10 @@ export interface DesktopConfig {
// on the LAN / Tailscale can reach it (#442, #418). Off by default: exposes
// the API, guarded only by the unified key. Applied at next server start.
lanAccess?: boolean;
+ // App version the "macOS is hiding your menu-bar icon" notice was last shown
+ // for (#807). Explaining the fix once per version is enough; the tray can stay
+ // hidden for as long as the user wants it hidden.
+ trayHiddenNoticeVersion?: string;
}
function configPath(): string {
diff --git a/desktop/src/main.ts b/desktop/src/main.ts
index eb6a750d..9f7237cf 100644
--- a/desktop/src/main.ts
+++ b/desktop/src/main.ts
@@ -1,10 +1,11 @@
import path from 'node:path';
import { fileURLToPath } from 'node:url';
-import { app, dialog, ipcMain, clipboard, nativeTheme, shell } from 'electron';
+import { app, dialog, ipcMain, clipboard, nativeTheme, screen, shell, type Tray } from 'electron';
import { startServer, ensureSessionToken, getUnifiedApiKey } from './server.mjs';
import { loadConfig, saveConfig } from './config.js';
import { installFileLogger } from './logger.js';
import { buildTray, refreshTrayLocale } from './tray.js';
+import { trayIsInMenuBar } from './tray-visibility.js';
import { openDashboard } from './window.js';
import { todayStats, hourlyRequests, successRateToday } from './stats.js';
import { normalizeLocale, nativeStrings, type NativeLocale } from './i18n.js';
@@ -61,6 +62,15 @@ if (!app.requestSingleInstanceLock()) {
if (sessionToken) openDashboard(resolvedPort, sessionToken);
});
+ // Reopening a *running* app on macOS — double-clicking it in Finder, clicking
+ // its Dock icon — is delivered as 'activate'. LaunchServices activates the
+ // live process instead of starting a second one, so 'second-instance' above
+ // never fires for it. Without this handler a user whose tray icon is hidden
+ // or clipped by the menu bar has no way back into the UI at all (#807).
+ app.on('activate', () => {
+ if (sessionToken) openDashboard(resolvedPort, sessionToken);
+ });
+
// The app lives in the tray; closing the dashboard window must not quit.
app.on('window-all-closed', () => {});
@@ -171,6 +181,45 @@ if (!app.requestSingleInstanceLock()) {
app.quit();
}
+ // macOS lays the status item out asynchronously; reading its bounds straight
+ // after `new Tray()` can catch it before it has been placed.
+ const TRAY_PROBE_DELAY_MS = 1500;
+
+ // The app is menu-bar-only, so a tray macOS declines to show leaves it running
+ // with no UI whatsoever — the silent failure behind #807. Say so in the log,
+ // and once per version offer the ways in that do not need the icon.
+ function reportHiddenTray(tray: Tray, port: number): void {
+ let visible: boolean;
+ try {
+ visible = trayIsInMenuBar(tray.getBounds(), screen.getAllDisplays());
+ } catch {
+ return; // a diagnostic must never be the thing that breaks startup
+ }
+ if (visible) return;
+ console.log('[desktop] the menu bar is not showing our tray icon — see #807');
+
+ const cfg = loadConfig();
+ if (cfg.trayHiddenNoticeVersion === app.getVersion()) return;
+ saveConfig({ ...cfg, trayHiddenNoticeVersion: app.getVersion() });
+
+ const choice = dialog.showMessageBoxSync({
+ type: 'info',
+ title: 'FreeLLMAPI has no menu-bar icon',
+ message: 'macOS is not showing the FreeLLMAPI menu-bar icon.',
+ detail:
+ 'The app and its API are running normally, but the icon everything else ' +
+ 'hangs off is not being drawn, so there is nothing to click.\n\n' +
+ 'To bring it back: System Settings > Menu Bar, find FreeLLMAPI and set it ' +
+ 'to Allow. On a Mac with a notch, quitting a few other menu-bar apps can ' +
+ 'also free up the room it needs.\n\n' +
+ 'Until then, relaunching FreeLLMAPI from Finder opens the dashboard.',
+ buttons: ['Open Dashboard', 'Continue in Background'],
+ defaultId: 0,
+ cancelId: 1,
+ });
+ if (choice === 0) openDashboard(port, sessionToken);
+ }
+
app.whenReady().then(async () => {
if (process.platform === 'darwin') app.dock?.hide();
@@ -208,6 +257,9 @@ if (!app.requestSingleInstanceLock()) {
sessionToken = ensureSessionToken();
const tray = buildTray(port, sessionToken, () => locale, () => loadConfig().lanAccess ?? false, toggleLanAccess);
console.log(`[desktop] FreeLLMAPI running on http://${host}:${port}${cfg.lanAccess ? ' (LAN access enabled)' : ''}`);
+ // A tray that macOS refuses to draw still constructs cleanly, so the only
+ // way to notice is to look at where the item landed (#807).
+ if (process.platform === 'darwin') setTimeout(() => reportHiddenTray(tray, port), TRAY_PROBE_DELAY_MS);
// Dev-only UI verification: FREEAPI_SHOT=1 opens the popover and the
// dashboard, captures both to /tmp, and quits. FREEAPI_SHOT=hold opens
diff --git a/desktop/src/tray-visibility.ts b/desktop/src/tray-visibility.ts
new file mode 100644
index 00000000..7b4369aa
--- /dev/null
+++ b/desktop/src/tray-visibility.ts
@@ -0,0 +1,35 @@
+// macOS 26 (Tahoe) gave every user a per-app switch for menu-bar icons in
+// System Settings > Menu Bar. Switching ours off persists
+// `"NSStatusItem VisibleCC Item-0" = 0` in the app's own defaults domain, and
+// from then on `new Tray()` still succeeds — no throw, no log, no crash report
+// — while nothing is drawn. Since the tray is the only entry point into the UI,
+// the app is then alive and serving the API with no way to reach it (#807).
+//
+// What does change is where macOS parks the item. Measured on macOS 26.5.2
+// (build 25F84): a real menu-bar item reports {x: 1281, y: 0}, a hidden one
+// {x: 0, y: 1117} — y is the screen height, i.e. off the bottom of the display.
+// The check is written against display bounds rather than a hardcoded y === 0
+// so that a menu bar living on a second display still counts as visible.
+
+export interface TrayRect {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
+export interface DisplayLike {
+ bounds: TrayRect;
+}
+
+// A couple of pixels of slack: the item's frame starts at the very top edge of
+// whichever display owns the menu bar.
+const TOP_EDGE_SLACK_PX = 2;
+
+export function trayIsInMenuBar(
+ bounds: TrayRect,
+ displays: readonly DisplayLike[],
+): boolean {
+ if (bounds.width <= 0 || bounds.height <= 0) return false;
+ return displays.some((d) => Math.abs(bounds.y - d.bounds.y) <= TOP_EDGE_SLACK_PX);
+}