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): Windows tray icon (.ico, no template image) and left-click opens dashboard (#1353) (#1355)

Tashfeenef141d92f6fe
diff --git a/desktop/assets/tray.ico b/desktop/assets/tray.ico
new file mode 100644
index 00000000..c2d18265
Binary files /dev/null and b/desktop/assets/tray.ico differ
diff --git a/desktop/assets/tray.png b/desktop/assets/tray.png
new file mode 100644
index 00000000..f847acfb
Binary files /dev/null and b/desktop/assets/tray.png differ
diff --git a/desktop/scripts/make-tray-icons.mjs b/desktop/scripts/make-tray-icons.mjs
new file mode 100644
index 00000000..f58c1ed2
--- /dev/null
+++ b/desktop/scripts/make-tray-icons.mjs
@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// Regenerates the non-macOS tray icons from assets/appicon_1024.png (#1353).
+//
+// The macOS tray uses trayTemplate.png, a black-on-transparent template image
+// that the menu bar tints for light/dark. Windows and Linux do not tint, so
+// that glyph would be black on a dark taskbar, and Shell_NotifyIcon wants a
+// multi-size .ico anyway. The app icon (dark tile, light dot, grey arc) reads
+// on both dark and light taskbars, so the tray icons are cut from it:
+//
+// assets/tray.ico Windows, 16/20/24/32/40/48/64 px (100% to 400% DPI)
+// assets/tray.png Linux, 32 px (panels scale it to their 22-24 px slot)
+//
+// The outputs are committed; run this only when the app icon changes:
+// node desktop/scripts/make-tray-icons.mjs
+// sharp is resolved from the monorepo's node_modules (a server dependency).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
+
+const assets = path.join(path.dirname(fileURLToPath(import.meta.url)), '../assets');
+const SOURCE = path.join(assets, 'appicon_1024.png');
+// appicon_1024.png is a 824 px tile inset 100 px on every side; a tray slot is
+// tiny, so drop the transparent margin and let the tile fill it.
+const TILE = { left: 100, top: 100, width: 824, height: 824 };
+const ICO_SIZES = [16, 20, 24, 32, 40, 48, 64];
+const LINUX_SIZE = 32;
+
+async function rgba(size) {
+ const { data } = await sharp(SOURCE)
+ .extract(TILE)
+ .resize(size, size, { kernel: 'lanczos3' })
+ .ensureAlpha()
+ .raw()
+ .toBuffer({ resolveWithObject: true });
+ return data;
+}
+
+// One ICO image entry as a classic 32-bit DIB (BITMAPINFOHEADER + bottom-up
+// BGRA + 1-bit AND mask). PNG-in-ICO is only guaranteed for 256 px entries, so
+// the small sizes use the format every Windows icon loader understands.
+function dib(size, data) {
+ const header = Buffer.alloc(40);
+ header.writeUInt32LE(40, 0); // biSize
+ header.writeInt32LE(size, 4); // biWidth
+ header.writeInt32LE(size * 2, 8); // biHeight: XOR + AND masks
+ header.writeUInt16LE(1, 12); // biPlanes
+ header.writeUInt16LE(32, 14); // biBitCount
+ header.writeUInt32LE(0, 16); // biCompression = BI_RGB
+
+ const xor = Buffer.alloc(size * size * 4);
+ const maskStride = Math.ceil(size / 32) * 4;
+ const and = Buffer.alloc(maskStride * size);
+ for (let y = 0; y < size; y++) {
+ const row = size - 1 - y; // DIB rows run bottom-up
+ for (let x = 0; x < size; x++) {
+ const src = (y * size + x) * 4;
+ const dst = (row * size + x) * 4;
+ xor[dst] = data[src + 2];
+ xor[dst + 1] = data[src + 1];
+ xor[dst + 2] = data[src];
+ xor[dst + 3] = data[src + 3];
+ if (data[src + 3] === 0) and[row * maskStride + (x >> 3)] |= 0x80 >> (x & 7);
+ }
+ }
+ return Buffer.concat([header, xor, and]);
+}
+
+async function buildIco() {
+ const images = [];
+ for (const size of ICO_SIZES) images.push(dib(size, await rgba(size)));
+
+ const dir = Buffer.alloc(6 + 16 * images.length);
+ dir.writeUInt16LE(0, 0); // reserved
+ dir.writeUInt16LE(1, 2); // type: icon
+ dir.writeUInt16LE(images.length, 4);
+ let offset = dir.length;
+ images.forEach((img, i) => {
+ const size = ICO_SIZES[i];
+ const e = 6 + 16 * i;
+ dir.writeUInt8(size >= 256 ? 0 : size, e);
+ dir.writeUInt8(size >= 256 ? 0 : size, e + 1);
+ dir.writeUInt8(0, e + 2); // palette colours
+ dir.writeUInt8(0, e + 3); // reserved
+ dir.writeUInt16LE(1, e + 4); // planes
+ dir.writeUInt16LE(32, e + 6); // bits per pixel
+ dir.writeUInt32LE(img.length, e + 8);
+ dir.writeUInt32LE(offset, e + 12);
+ offset += img.length;
+ });
+ return Buffer.concat([dir, ...images]);
+}
+
+fs.writeFileSync(path.join(assets, 'tray.ico'), await buildIco());
+await sharp(SOURCE)
+ .extract(TILE)
+ .resize(LINUX_SIZE, LINUX_SIZE, { kernel: 'lanczos3' })
+ .png({ compressionLevel: 9 })
+ .toFile(path.join(assets, 'tray.png'));
+console.log(`wrote assets/tray.ico (${ICO_SIZES.join('/')} px) and assets/tray.png (${LINUX_SIZE} px)`);
diff --git a/desktop/src/__tests__/tray-platform.test.ts b/desktop/src/__tests__/tray-platform.test.ts
new file mode 100644
index 00000000..6b2f3ff9
--- /dev/null
+++ b/desktop/src/__tests__/tray-platform.test.ts
@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { shouldOpenDashboardOnLaunch, trayPlatform } from '../tray-platform.js';
+
+// #1353: on Windows the tray failed with "Unable to create status tray icon"
+// because every platform got the macOS template PNG. The Windows branch never
+// runs on the mac this repo is developed on, so it is asserted here.
+
+const yaml = createRequire(import.meta.url)('js-yaml');
+const desktopRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const assets = join(desktopRoot, 'assets');
+
+// ICONDIR + ICONDIRENTRY widths (0 means 256).
+function icoSizes(buf: Buffer): number[] {
+ expect(buf.readUInt16LE(0)).toBe(0);
+ expect(buf.readUInt16LE(2)).toBe(1);
+ const count = buf.readUInt16LE(4);
+ return Array.from({ length: count }, (_, i) => buf.readUInt8(6 + 16 * i) || 256);
+}
+
+describe('tray per platform (#1353)', () => {
+ it('keeps the macOS menu bar on the tinted template image and the popover', () => {
+ expect(trayPlatform('darwin')).toEqual({
+ iconFile: 'trayTemplate.png',
+ templateImage: true,
+ leftClick: 'popover',
+ });
+ });
+
+ it('gives Windows an .ico, no template flag, and a left-click that opens the dashboard', () => {
+ expect(trayPlatform('win32')).toEqual({
+ iconFile: 'tray.ico',
+ templateImage: false,
+ leftClick: 'dashboard',
+ });
+ });
+
+ it('gives Linux the full-colour PNG rather than the black template glyph', () => {
+ const linux = trayPlatform('linux');
+ expect(linux.iconFile).toBe('tray.png');
+ expect(linux.templateImage).toBe(false);
+ });
+
+ it('ships every tray icon it names inside the packaged assets', () => {
+ for (const platform of ['darwin', 'win32', 'linux'] as const) {
+ expect(existsSync(join(assets, trayPlatform(platform).iconFile))).toBe(true);
+ }
+ // tray.ts resolves ../assets from build/, so assets/ must be packed.
+ const config = yaml.load(readFileSync(join(desktopRoot, 'electron-builder.yml'), 'utf8')) as {
+ files?: string[];
+ };
+ expect(config.files).toContain('assets/**/*');
+ });
+
+ it('ships a multi-size Windows .ico covering 100% to 400% DPI', () => {
+ const sizes = icoSizes(readFileSync(join(assets, 'tray.ico')));
+ for (const size of [16, 20, 24, 32, 40, 48, 64]) expect(sizes).toContain(size);
+ });
+});
+
+describe('opening the dashboard at launch (#1353)', () => {
+ it('opens it once on a first Windows launch', () => {
+ expect(shouldOpenDashboardOnLaunch('win32', { trayBuilt: true, welcomedBefore: false })).toBe(true);
+ expect(shouldOpenDashboardOnLaunch('win32', { trayBuilt: true, welcomedBefore: true })).toBe(false);
+ });
+
+ it('leaves macOS and Linux launching quietly into the tray', () => {
+ expect(shouldOpenDashboardOnLaunch('darwin', { trayBuilt: true, welcomedBefore: false })).toBe(false);
+ expect(shouldOpenDashboardOnLaunch('linux', { trayBuilt: true, welcomedBefore: false })).toBe(false);
+ });
+
+ it('always opens it when the tray could not be built, since nothing else is visible', () => {
+ for (const platform of ['win32', 'darwin', 'linux'] as const) {
+ expect(shouldOpenDashboardOnLaunch(platform, { trayBuilt: false, welcomedBefore: true })).toBe(true);
+ }
+ });
+});
diff --git a/desktop/src/config.ts b/desktop/src/config.ts
index 86b6e31c..493a256e 100644
--- a/desktop/src/config.ts
+++ b/desktop/src/config.ts
@@ -19,6 +19,10 @@ export interface DesktopConfig {
// icon alone is a poor "is it running?" signal, and macOS 26 can hide it
// outright (#807). Users who want the lean menu-bar-only look turn it off.
showInDock?: boolean;
+ // Set once the dashboard has been opened at startup to show a first-time
+ // Windows user the app is running; the tray icon starts out hidden in the
+ // overflow flyout there (#1353).
+ launchDashboardShown?: boolean;
}
function configPath(): string {
diff --git a/desktop/src/main.ts b/desktop/src/main.ts
index a2619749..fc43090a 100644
--- a/desktop/src/main.ts
+++ b/desktop/src/main.ts
@@ -6,6 +6,7 @@ import { loadConfig, saveConfig } from './config.js';
import { installFileLogger } from './logger.js';
import { buildTray, refreshTrayLocale } from './tray.js';
import { trayIsInMenuBar } from './tray-visibility.js';
+import { shouldOpenDashboardOnLaunch } from './tray-platform.js';
import { openDashboard } from './window.js';
import { todayStats, hourlyRequests, successRateToday } from './stats.js';
import { normalizeLocale, nativeStrings, type NativeLocale } from './i18n.js';
@@ -278,25 +279,44 @@ if (!app.requestSingleInstanceLock()) {
resolvedPort = port;
saveConfig({ ...cfg, port });
sessionToken = ensureSessionToken();
- const tray = buildTray(
- port,
- sessionToken,
- () => locale,
- () => loadConfig().lanAccess ?? false,
- toggleLanAccess,
- () => loadConfig().showInDock ?? true,
- toggleShowInDock,
- );
+ // The server is already up, so a tray that fails to build must not take
+ // the app down with it: fall back to the dashboard window (#1353).
+ let tray: Tray | null = null;
+ try {
+ tray = buildTray(
+ port,
+ sessionToken,
+ () => locale,
+ () => loadConfig().lanAccess ?? false,
+ toggleLanAccess,
+ () => loadConfig().showInDock ?? true,
+ toggleShowInDock,
+ );
+ } catch (err) {
+ console.warn('[desktop] could not create the tray icon:', err);
+ }
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);
+ if (tray && process.platform === 'darwin') {
+ const built = tray;
+ setTimeout(() => reportHiddenTray(built, port), TRAY_PROBE_DELAY_MS);
+ }
+
+ const welcomedBefore = loadConfig().launchDashboardShown ?? false;
+ if (
+ !process.env.FREEAPI_SHOT
+ && shouldOpenDashboardOnLaunch(process.platform, { trayBuilt: tray !== null, welcomedBefore })
+ ) {
+ openDashboard(port, sessionToken);
+ if (!welcomedBefore) saveConfig({ ...loadConfig(), launchDashboardShown: true });
+ }
// Dev-only UI verification: FREEAPI_SHOT=1 opens the popover and the
// dashboard, captures both to /tmp, and quits. FREEAPI_SHOT=hold opens
// the popover and keeps it pinned (blur ignored) so a real screen
// capture can include the compositor's vibrancy. Never set when packaged.
- if (process.env.FREEAPI_SHOT && !app.isPackaged) {
+ if (tray && process.env.FREEAPI_SHOT && !app.isPackaged) {
const fs = await import('node:fs');
const { togglePopover, getPopoverWindow } = await import('./popover.js');
const { getDashboardWindow } = await import('./window.js');
diff --git a/desktop/src/tray-platform.ts b/desktop/src/tray-platform.ts
new file mode 100644
index 00000000..4c56b5e0
--- /dev/null
+++ b/desktop/src/tray-platform.ts
@@ -0,0 +1,45 @@
+// Per-platform tray behaviour, kept free of Electron imports so it can be
+// asserted on the mac this repo is developed on (#1353).
+//
+// The tray was written for the macOS menu bar: a black template PNG that the
+// system tints, and a left-click glass popover. On Windows that combination
+// failed outright. Shell_NotifyIcon wants an .ico, a template image is a
+// macOS-only concept, and the result was "Unable to create status tray icon"
+// with an app that looked like it had crashed.
+
+export interface TrayPlatform {
+ // File under desktop/assets/ to build the tray icon from.
+ iconFile: string;
+ // nativeImage.setTemplateImage(true): only the macOS menu bar honours it.
+ templateImage: boolean;
+ // What a plain left-click does. The popover is a macOS menu-bar idiom (and
+ // its vibrancy material is macOS-only); a Windows tray click is expected to
+ // bring up the app itself.
+ leftClick: 'popover' | 'dashboard';
+}
+
+export function trayPlatform(platform: NodeJS.Platform): TrayPlatform {
+ if (platform === 'darwin') {
+ return { iconFile: 'trayTemplate.png', templateImage: true, leftClick: 'popover' };
+ }
+ if (platform === 'win32') {
+ // Multi-size .ico (16 to 64 px) so every DPI scale gets a crisp frame.
+ return { iconFile: 'tray.ico', templateImage: false, leftClick: 'dashboard' };
+ }
+ // Linux panels do not tint either, and most are dark, where the black
+ // template glyph disappears; use the full-colour icon instead.
+ return { iconFile: 'tray.png', templateImage: false, leftClick: 'popover' };
+}
+
+// Windows tucks new tray icons into the overflow flyout, so a first launch can
+// look like nothing happened at all (#1353). Open the dashboard once there so
+// the user sees the app is up; after that the tray is the way in. A tray that
+// failed to build leaves no other visible entry point, so that case opens it
+// on every platform and every launch.
+export function shouldOpenDashboardOnLaunch(
+ platform: NodeJS.Platform,
+ opts: { trayBuilt: boolean; welcomedBefore: boolean },
+): boolean {
+ if (!opts.trayBuilt) return true;
+ return platform === 'win32' && !opts.welcomedBefore;
+}
diff --git a/desktop/src/tray.ts b/desktop/src/tray.ts
index 454de3e2..df96f068 100644
--- a/desktop/src/tray.ts
+++ b/desktop/src/tray.ts
@@ -5,16 +5,18 @@ import { togglePopover } from './popover.js';
import { openDashboard } from './window.js';
import { openLogsFolder, openBackupsFolder } from './logger.js';
import { dt, type NativeLocale } from './i18n.js';
+import { trayPlatform } from './tray-platform.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
let tray: Tray | null = null;
-// Left-click opens the glass popover; right-click keeps a minimal native
-// menu as an escape hatch (quit even if the popover renderer breaks). The menu
-// is rebuilt on every right-click, so reading the live locale via getLocale()
-// keeps its labels current after a language switch; the static tooltip is
-// refreshed separately (refreshTrayLocale).
+// Left-click opens the glass popover (the dashboard itself on Windows, see
+// tray-platform.ts); right-click keeps a minimal native menu as an escape
+// hatch (quit even if the popover renderer breaks). The menu is rebuilt on
+// every right-click, so reading the live locale via getLocale() keeps its
+// labels current after a language switch; the static tooltip is refreshed
+// separately (refreshTrayLocale).
export function buildTray(
port: number,
token: string,
@@ -24,14 +26,22 @@ export function buildTray(
getShowInDock: () => boolean,
onToggleShowInDock: () => void,
): Tray {
- const iconPath = path.join(__dirname, '../assets/trayTemplate.png');
+ const platform = trayPlatform(process.platform);
+ const iconPath = path.join(__dirname, '../assets', platform.iconFile);
const icon = nativeImage.createFromPath(iconPath);
- icon.setTemplateImage(true); // auto light/dark tint in the macOS menu bar
+ if (icon.isEmpty()) console.warn(`[desktop] tray icon did not load from ${iconPath}`);
+ // Auto light/dark tint in the macOS menu bar. Elsewhere it is meaningless,
+ // and Windows rejected the image it produced (#1353).
+ if (platform.templateImage) icon.setTemplateImage(true);
tray = new Tray(icon);
tray.setToolTip(dt(getLocale(), 'tooltip'));
- tray.on('click', () => togglePopover(tray!));
+ if (platform.leftClick === 'dashboard') {
+ tray.on('click', () => openDashboard(port, token));
+ } else {
+ tray.on('click', () => togglePopover(tray!));
+ }
tray.on('right-click', () => {
const locale = getLocale();
const lanOn = getLanAccess();