@flighthq/tray 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tray';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './tray';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC"}

package/dist/tray.d.ts

@@ -0,0 +1,26 @@
+import type { MenuItemTemplate, RectangleLike, TrayBackend, TrayBalloonOptions, TrayCapabilities, TrayEventData, TrayIcon, TrayIconOptions } from '@flighthq/types';
+import type { Vector2Like } from '@flighthq/types';
+export declare function createTrayIcon(options?: Readonly<TrayIconOptions>): TrayIcon | null;
+export declare function createWebTrayBackend(): TrayBackend;
+export declare function destroyTrayIcon(tray: TrayIcon): void;
+export declare function displayTrayBalloon(tray: TrayIcon, options: Readonly<TrayBalloonOptions>): void;
+export declare function getTrayBackend(): TrayBackend;
+export declare function getTrayCapabilities(): Readonly<TrayCapabilities>;
+export declare function getTrayIconBounds(tray: TrayIcon): Readonly<RectangleLike> | null;
+export declare function getTrayIcons(): readonly TrayIcon[];
+export declare function getTrayIconTitle(tray: TrayIcon): string;
+export declare function getTrayIconTooltip(tray: TrayIcon): string;
+export declare function isTrayDestroyed(tray: TrayIcon): boolean;
+export declare function onTrayEvent(listener: (event: Readonly<TrayEventData>) => void): () => void;
+export declare function popupTrayContextMenu(tray: TrayIcon, position?: Readonly<Vector2Like>): void;
+export declare function removeTrayBalloon(tray: TrayIcon): void;
+export declare function setTrayBackend(backend: TrayBackend | null): void;
+export declare function setTrayIcon(tray: TrayIcon, icon: string): void;
+export declare function setTrayIconContextMenu(tray: TrayIcon, items: readonly MenuItemTemplate[]): void;
+export declare function setTrayIconTemplate(tray: TrayIcon, isTemplate: boolean): void;
+export declare function setTrayIconTitle(tray: TrayIcon, title: string): void;
+export declare function setTrayIconTooltip(tray: TrayIcon, tooltip: string): void;
+export declare function setTrayIgnoreDoubleClickEvents(tray: TrayIcon, ignore: boolean): void;
+export declare function setTrayPressedIcon(tray: TrayIcon, icon: string): void;
+export declare function startTrayIconAnimation(tray: TrayIcon, frames: readonly string[], intervalMs: number): () => void;
+//# sourceMappingURL=tray.d.ts.map

package/dist/tray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tray.d.ts","sourceRoot":"","sources":["../src/tray.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,eAAe,EAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAcnD,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,eAAe,CAAC,GAAG,QAAQ,GAAG,IAAI,CAGnF;AAKD,wBAAgB,oBAAoB,IAAI,WAAW,CAmElD;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAEpD;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE9F;AAGD,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAKD,wBAAgB,mBAAmB,IAAI,QAAQ,CAAC,gBAAgB,CAAC,CAEhE;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,IAAI,CAEhF;AAGD,wBAAgB,YAAY,IAAI,SAAS,QAAQ,EAAE,CAIlD;AAGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAGD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEzD;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAEvD;AAKD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAE1F;AAKD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,IAAI,CAE3F;AAGD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAEtD;AAGD,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEhE;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9D;AAID,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAE/F;AAKD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI,CAE7E;AAGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpE;AAGD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAExE;AAID,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAEpF;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAErE;AAOD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,IAAI,CAShH"}

package/dist/tray.js

@@ -0,0 +1,203 @@
+// Web tray capability constants. Web has no system tray — all capabilities are false.
+const WEB_CAPABILITIES = {
+    balloon: false,
+    bounds: false,
+    clickEvents: false,
+    dropFiles: false,
+    pressedIcon: false,
+    title: false,
+};
+// Creates a tray icon, or null when the host has no system tray (e.g. web). The backend returns -1 to
+// signal no tray; this translates that to a null sentinel for the caller.
+export function createTrayIcon(options) {
+    const id = getTrayBackend().create(options ?? {});
+    return id < 0 ? null : { id };
+}
+// Builds the default web backend. Web has no system tray, so create returns -1 and the tray mutators
+// are no-ops — a native host (Electron's Tray, Tauri) is required for the tray icon itself. (The
+// application/dock badge lives in @flighthq/app's setAppBadgeCount, not here.)
+export function createWebTrayBackend() {
+    return {
+        create() {
+            // No tray on web. -1 signals "unsupported"; createTrayIcon maps it to null.
+            return -1;
+        },
+        destroy() {
+            // No-op: web has no tray icon to destroy.
+        },
+        displayBalloon() {
+            // No-op: balloon notifications require a native host (Windows only).
+        },
+        getBounds() {
+            // No tray on web; null signals unavailable.
+            return null;
+        },
+        getCapabilities() {
+            return WEB_CAPABILITIES;
+        },
+        getTitle() {
+            // No tray on web.
+            return '';
+        },
+        getTooltip() {
+            // No tray on web.
+            return '';
+        },
+        isDestroyed() {
+            // No tray icons exist on web; treat every id as destroyed.
+            return true;
+        },
+        listIds() {
+            // No tray icons exist on web.
+            return [];
+        },
+        popUpContextMenu() {
+            // No-op: web has no context menu to pop up.
+        },
+        removeBalloon() {
+            // No-op: balloon notifications require a native host (Windows only).
+        },
+        setContextMenu() {
+            // No-op: web has no tray icon — a native host (Electron/Tauri) is required.
+        },
+        setIcon() {
+            // No-op: web has no tray icon to update.
+        },
+        setIgnoreDoubleClickEvents() {
+            // No-op: web has no tray icon double-click behavior to configure.
+        },
+        setPressedIcon() {
+            // No-op: web has no tray icon; pressed icon is macOS-specific.
+        },
+        setTemplate() {
+            // No-op: template images are a macOS menu-bar concept; irrelevant on web.
+        },
+        setTitle() {
+            // No-op: web has no tray icon to update.
+        },
+        setTooltip() {
+            // No-op: web has no tray icon to update.
+        },
+        subscribe() {
+            // No tray on web — a native host (Electron/Tauri) is required to emit tray events.
+            return () => { };
+        },
+    };
+}
+// Destroys a tray icon and frees its host resource. No-op when the host has no tray.
+export function destroyTrayIcon(tray) {
+    getTrayBackend().destroy(tray.id);
+}
+// Displays a Windows balloon notification from the tray icon. No-op on macOS/Linux and on web.
+// Balloon lifecycle events (balloonShow/balloonClick/balloonClose) are emitted via onTrayEvent.
+export function displayTrayBalloon(tray, options) {
+    getTrayBackend().displayBalloon(tray.id, options);
+}
+// The active tray backend, or a lazily-created web default. There is always a backend.
+export function getTrayBackend() {
+    if (_backend === null)
+        _backend = createWebTrayBackend();
+    return _backend;
+}
+// Returns the capability flags for the active tray backend. Use before calling APIs that may
+// silently no-op — for example, check capabilities.balloon before displayTrayBalloon, or
+// capabilities.bounds before getTrayIconBounds. On web all flags are false.
+export function getTrayCapabilities() {
+    return getTrayBackend().getCapabilities();
+}
+// Returns the screen bounds of the tray icon (x/y/width/height), or null when the platform does not
+// expose icon geometry (Linux/AppIndicator, web). Use for anchoring popovers or windows to the icon.
+export function getTrayIconBounds(tray) {
+    return getTrayBackend().getBounds(tray.id);
+}
+// Returns all live tray icon handles known to the active backend. On web this is always empty.
+export function getTrayIcons() {
+    return getTrayBackend()
+        .listIds()
+        .map((id) => ({ id }));
+}
+// Returns the current title text of a tray icon, or an empty string when unavailable (web, non-macOS).
+export function getTrayIconTitle(tray) {
+    return getTrayBackend().getTitle(tray.id);
+}
+// Returns the current hover tooltip text of a tray icon, or an empty string when unavailable (web).
+export function getTrayIconTooltip(tray) {
+    return getTrayBackend().getTooltip(tray.id);
+}
+// Returns whether a tray icon has been destroyed. Returns true on web (no trays exist).
+// Use this to guard calls after destroyTrayIcon when the tray lifecycle is unclear.
+export function isTrayDestroyed(tray) {
+    return getTrayBackend().isDestroyed(tray.id);
+}
+// Subscribes to tray icon events, delivering a rich TrayEventData payload (id, type, bounds,
+// position, modifier keys, and drop payloads). Returns an unsubscribe function. On web this
+// never fires (no tray); a native host is required.
+export function onTrayEvent(listener) {
+    return getTrayBackend().subscribe(listener);
+}
+// Programmatically shows the attached context menu, optionally at a specific screen position.
+// On web this is a no-op. Useful for showing the menu in response to a custom gesture or shortcut
+// without waiting for the user to right-click the tray icon.
+export function popupTrayContextMenu(tray, position) {
+    getTrayBackend().popUpContextMenu(tray.id, position);
+}
+// Dismisses the currently-displayed Windows balloon notification. No-op on macOS/Linux and web.
+export function removeTrayBalloon(tray) {
+    getTrayBackend().removeBalloon(tray.id);
+}
+// Installs a native host tray backend; pass null to fall back to the web default.
+export function setTrayBackend(backend) {
+    _backend = backend;
+}
+// Sets the image for the tray icon. Accepts the same icon path/data-URI accepted by createTrayIcon.
+// Use this for runtime status updates (indicators, spinners, theme changes).
+export function setTrayIcon(tray, icon) {
+    getTrayBackend().setIcon(tray.id, icon);
+}
+// Sets the context menu attached to a tray icon. Shown on right-click (or popupTrayContextMenu).
+// No-op when the host has no tray.
+export function setTrayIconContextMenu(tray, items) {
+    getTrayBackend().setContextMenu(tray.id, items);
+}
+// Marks the tray icon as a macOS template image. Template images auto-invert for light/dark menu
+// bars. No-op on Windows/Linux and on web. Set iconTemplate:true on TrayIconOptions at creation to
+// combine with the initial icon, or call this after creation to update the flag dynamically.
+export function setTrayIconTemplate(tray, isTemplate) {
+    getTrayBackend().setTemplate(tray.id, isTemplate);
+}
+// Sets the title text displayed next to the tray icon (macOS menu bar only). No-op on other platforms.
+export function setTrayIconTitle(tray, title) {
+    getTrayBackend().setTitle(tray.id, title);
+}
+// Sets the hover tooltip for the tray icon. No-op when the host has no tray.
+export function setTrayIconTooltip(tray, tooltip) {
+    getTrayBackend().setTooltip(tray.id, tooltip);
+}
+// Sets whether the host should collapse double-click events into individual click events (macOS).
+// No-op on Windows/Linux and on web.
+export function setTrayIgnoreDoubleClickEvents(tray, ignore) {
+    getTrayBackend().setIgnoreDoubleClickEvents(tray.id, ignore);
+}
+// Sets the image shown when the tray icon is pressed (macOS only). Electron calls this
+// setPressedImage. No-op on Windows/Linux and on web.
+export function setTrayPressedIcon(tray, icon) {
+    getTrayBackend().setPressedIcon(tray.id, icon);
+}
+// Starts an animated icon sequence by cycling through the given frames at the specified interval.
+// The caller owns the timer — this function is a thin helper over setTrayIcon that starts an
+// interval and returns a stop function. Call the returned function (or stopTrayIconAnimation) to
+// cancel. The tray icon is not destroyed when the animation stops.
+// Note: interval timing is best-effort; the actual frame rate depends on the host event loop.
+export function startTrayIconAnimation(tray, frames, intervalMs) {
+    if (frames.length === 0)
+        return () => { };
+    let index = 0;
+    setTrayIcon(tray, frames[index]);
+    const handle = setInterval(() => {
+        index = (index + 1) % frames.length;
+        setTrayIcon(tray, frames[index]);
+    }, intervalMs);
+    return () => clearInterval(handle);
+}
+let _backend = null;
+//# sourceMappingURL=tray.js.map

package/dist/tray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tray.js","sourceRoot":"","sources":["../src/tray.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/tray",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Tray icon and application badge over a swappable web/native backend",
+  "sideEffects": false
+}

package/src/tray.test.ts

@@ -0,0 +1,647 @@
+import type {
+  MenuItemTemplate,
+  TrayBackend,
+  TrayBalloonOptions,
+  TrayCapabilities,
+  TrayEventData,
+  TrayEventType,
+  TrayIconOptions,
+} from '@flighthq/types';
+
+import {
+  createTrayIcon,
+  createWebTrayBackend,
+  destroyTrayIcon,
+  displayTrayBalloon,
+  getTrayBackend,
+  getTrayCapabilities,
+  getTrayIconBounds,
+  getTrayIcons,
+  getTrayIconTitle,
+  getTrayIconTooltip,
+  isTrayDestroyed,
+  onTrayEvent,
+  popupTrayContextMenu,
+  removeTrayBalloon,
+  setTrayBackend,
+  setTrayIcon,
+  setTrayIconContextMenu,
+  setTrayIconTemplate,
+  setTrayIconTitle,
+  setTrayIconTooltip,
+  setTrayIgnoreDoubleClickEvents,
+  setTrayPressedIcon,
+  startTrayIconAnimation,
+} from './tray';
+
+// Fake backend state per icon.
+interface FakeTray {
+  balloon: TrayBalloonOptions | null;
+  contextMenu: readonly MenuItemTemplate[] | null;
+  destroyed: boolean;
+  icon: string;
+  id: number;
+  ignoreDoubleClick: boolean;
+  isTemplate: boolean;
+  options: TrayIconOptions;
+  pressedIcon: string;
+  title: string;
+  tooltip: string;
+}
+
+// Full fake backend implementing every TrayBackend method for test control.
+function fakeBackend(caps: Partial<TrayCapabilities> = {}): TrayBackend & {
+  capabilities: TrayCapabilities;
+  fireEvent(event: TrayEventData): void;
+  lastPopupPosition: { x: number; y: number } | null;
+  trays: Map<number, FakeTray>;
+} {
+  const capabilities: TrayCapabilities = {
+    balloon: caps.balloon ?? true,
+    bounds: caps.bounds ?? true,
+    clickEvents: caps.clickEvents ?? true,
+    dropFiles: caps.dropFiles ?? false,
+    pressedIcon: caps.pressedIcon ?? true,
+    title: caps.title ?? true,
+  };
+  let nextId = 1;
+  let eventListener: ((event: Readonly<TrayEventData>) => void) | null = null;
+  const trays = new Map<number, FakeTray>();
+
+  return {
+    capabilities,
+    trays,
+    lastPopupPosition: null,
+    create(options) {
+      const id = nextId++;
+      trays.set(id, {
+        balloon: null,
+        contextMenu: null,
+        destroyed: false,
+        icon: options.icon ?? '',
+        id,
+        ignoreDoubleClick: false,
+        isTemplate: options.iconTemplate ?? false,
+        options,
+        pressedIcon: '',
+        title: options.title ?? '',
+        tooltip: options.tooltip ?? '',
+      });
+      return id;
+    },
+    destroy(id) {
+      const tray = trays.get(id);
+      if (tray) tray.destroyed = true;
+    },
+    displayBalloon(id, options) {
+      const tray = trays.get(id);
+      if (tray) tray.balloon = options;
+    },
+    getBounds(id) {
+      if (!trays.has(id)) return null;
+      return { height: 22, width: 22, x: 100, y: 0 };
+    },
+    getCapabilities() {
+      return capabilities;
+    },
+    getTitle(id) {
+      return trays.get(id)?.title ?? '';
+    },
+    getTooltip(id) {
+      return trays.get(id)?.tooltip ?? '';
+    },
+    isDestroyed(id) {
+      const tray = trays.get(id);
+      return tray === undefined || tray.destroyed;
+    },
+    listIds() {
+      return Array.from(trays.keys()).filter((id) => !trays.get(id)!.destroyed);
+    },
+    popUpContextMenu(id, position) {
+      this.lastPopupPosition = position ? { x: position.x, y: position.y } : null;
+    },
+    removeBalloon(id) {
+      const tray = trays.get(id);
+      if (tray) tray.balloon = null;
+    },
+    setContextMenu(id, items) {
+      const tray = trays.get(id);
+      if (tray) tray.contextMenu = items;
+    },
+    setIcon(id, icon) {
+      const tray = trays.get(id);
+      if (tray) tray.icon = icon;
+    },
+    setIgnoreDoubleClickEvents(id, ignore) {
+      const tray = trays.get(id);
+      if (tray) tray.ignoreDoubleClick = ignore;
+    },
+    setPressedIcon(id, icon) {
+      const tray = trays.get(id);
+      if (tray) tray.pressedIcon = icon;
+    },
+    setTemplate(id, isTemplate) {
+      const tray = trays.get(id);
+      if (tray) tray.isTemplate = isTemplate;
+    },
+    setTitle(id, title) {
+      const tray = trays.get(id);
+      if (tray) tray.title = title;
+    },
+    setTooltip(id, tooltip) {
+      const tray = trays.get(id);
+      if (tray) tray.tooltip = tooltip;
+    },
+    subscribe(listener) {
+      eventListener = listener;
+      return () => {
+        eventListener = null;
+      };
+    },
+    fireEvent(event) {
+      eventListener?.(event);
+    },
+  };
+}
+
+function makeTrayEvent(overrides: Partial<TrayEventData> = {}): TrayEventData {
+  return {
+    altKey: false,
+    bounds: null,
+    ctrlKey: false,
+    dropFiles: null,
+    dropText: null,
+    id: 1,
+    metaKey: false,
+    position: null,
+    shiftKey: false,
+    type: 'click',
+    ...overrides,
+  };
+}
+
+afterEach(() => setTrayBackend(null));
+
+describe('createTrayIcon', () => {
+  it('creates a tray via the active backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ tooltip: 'App' });
+    expect(tray).not.toBeNull();
+    expect(backend.trays.get(tray!.id)!.options.tooltip).toBe('App');
+  });
+
+  it('passes iconTemplate option to backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'icon.png', iconTemplate: true });
+    expect(backend.trays.get(tray!.id)!.isTemplate).toBe(true);
+  });
+
+  it('returns null on the web backend (no tray)', () => {
+    expect(createTrayIcon()).toBeNull();
+  });
+});
+
+describe('createWebTrayBackend', () => {
+  it('returns sentinels without throwing (web has no tray)', () => {
+    const backend = createWebTrayBackend();
+    expect(backend.create({})).toBe(-1);
+    expect(() => backend.destroy(0)).not.toThrow();
+    expect(() => backend.setTooltip(0, 'x')).not.toThrow();
+    expect(() => backend.setTitle(0, 'x')).not.toThrow();
+    expect(() => backend.setContextMenu(0, [])).not.toThrow();
+    expect(() => backend.setIcon(0, 'icon.png')).not.toThrow();
+    expect(() => backend.setTemplate(0, true)).not.toThrow();
+    expect(() => backend.setPressedIcon(0, 'pressed.png')).not.toThrow();
+    expect(() => backend.setIgnoreDoubleClickEvents(0, true)).not.toThrow();
+    expect(() => backend.popUpContextMenu(0)).not.toThrow();
+    expect(() => backend.displayBalloon(0, { title: 'T', text: 'B' })).not.toThrow();
+    expect(() => backend.removeBalloon(0)).not.toThrow();
+    expect(backend.getBounds(0)).toBeNull();
+    expect(backend.getTitle(0)).toBe('');
+    expect(backend.getTooltip(0)).toBe('');
+    expect(backend.isDestroyed(0)).toBe(true);
+    expect(backend.listIds()).toEqual([]);
+    expect(typeof backend.subscribe(() => {})).toBe('function');
+  });
+
+  it('web capabilities are all false', () => {
+    const backend = createWebTrayBackend();
+    const caps = backend.getCapabilities();
+    expect(caps.balloon).toBe(false);
+    expect(caps.bounds).toBe(false);
+    expect(caps.clickEvents).toBe(false);
+    expect(caps.dropFiles).toBe(false);
+    expect(caps.pressedIcon).toBe(false);
+    expect(caps.title).toBe(false);
+  });
+});
+
+describe('destroyTrayIcon', () => {
+  it('destroys the tray via the active backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    destroyTrayIcon(tray);
+    expect(backend.trays.get(tray.id)!.destroyed).toBe(true);
+  });
+});
+
+describe('displayTrayBalloon', () => {
+  it('passes balloon options to the backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    const opts: TrayBalloonOptions = { title: 'Alert', text: 'Something happened' };
+    displayTrayBalloon(tray, opts);
+    expect(backend.trays.get(tray.id)!.balloon).toStrictEqual(opts);
+  });
+
+  it('accepts optional balloon fields', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    const opts: TrayBalloonOptions = {
+      title: 'Alert',
+      text: 'Body',
+      iconType: 'warning',
+      largeIcon: true,
+      noSound: true,
+      respectQuietTime: true,
+    };
+    displayTrayBalloon(tray, opts);
+    expect(backend.trays.get(tray.id)!.balloon?.iconType).toBe('warning');
+  });
+
+  it('is a no-op on the web backend', () => {
+    expect(() => displayTrayBalloon({ id: 0 }, { title: 'T', text: 'B' })).not.toThrow();
+  });
+});
+
+describe('getTrayBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getTrayBackend()).not.toBeNull();
+  });
+
+  it('returns the registered backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    expect(getTrayBackend()).toBe(backend);
+  });
+});
+
+describe('getTrayCapabilities', () => {
+  it('returns capabilities from the active backend', () => {
+    const backend = fakeBackend({ balloon: true, bounds: false });
+    setTrayBackend(backend);
+    const caps = getTrayCapabilities();
+    expect(caps.balloon).toBe(true);
+    expect(caps.bounds).toBe(false);
+  });
+
+  it('returns all-false capabilities on web', () => {
+    const caps = getTrayCapabilities();
+    expect(Object.values(caps).every((v) => v === false)).toBe(true);
+  });
+});
+
+describe('getTrayIconBounds', () => {
+  it('returns bounds from the backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    const bounds = getTrayIconBounds(tray);
+    expect(bounds).not.toBeNull();
+    expect(bounds!.width).toBeGreaterThan(0);
+    expect(bounds!.height).toBeGreaterThan(0);
+  });
+
+  it('returns null on web', () => {
+    expect(getTrayIconBounds({ id: 0 })).toBeNull();
+  });
+});
+
+describe('getTrayIcons', () => {
+  it('returns all live tray icons', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const t1 = createTrayIcon()!;
+    const t2 = createTrayIcon()!;
+    const icons = getTrayIcons();
+    expect(icons.map((t) => t.id)).toContain(t1.id);
+    expect(icons.map((t) => t.id)).toContain(t2.id);
+  });
+
+  it('excludes destroyed tray icons', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const t1 = createTrayIcon()!;
+    destroyTrayIcon(t1);
+    const icons = getTrayIcons();
+    expect(icons.map((t) => t.id)).not.toContain(t1.id);
+  });
+
+  it('returns empty array on web', () => {
+    expect(getTrayIcons()).toEqual([]);
+  });
+});
+
+describe('getTrayIconTitle', () => {
+  it('returns the current title', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayIconTitle(tray, 'MyApp');
+    expect(getTrayIconTitle(tray)).toBe('MyApp');
+  });
+
+  it('returns empty string on web', () => {
+    expect(getTrayIconTitle({ id: 0 })).toBe('');
+  });
+});
+
+describe('getTrayIconTooltip', () => {
+  it('returns the current tooltip', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayIconTooltip(tray, 'Hover tip');
+    expect(getTrayIconTooltip(tray)).toBe('Hover tip');
+  });
+
+  it('returns empty string on web', () => {
+    expect(getTrayIconTooltip({ id: 0 })).toBe('');
+  });
+});
+
+describe('isTrayDestroyed', () => {
+  it('returns false for a live tray', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    expect(isTrayDestroyed(tray)).toBe(false);
+  });
+
+  it('returns true after destroyTrayIcon', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    destroyTrayIcon(tray);
+    expect(isTrayDestroyed(tray)).toBe(true);
+  });
+
+  it('returns true on web (no trays exist)', () => {
+    expect(isTrayDestroyed({ id: 0 })).toBe(true);
+  });
+});
+
+describe('onTrayEvent', () => {
+  it('delivers rich TrayEventData via the active backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    let received: TrayEventData | null = null;
+    onTrayEvent((event) => {
+      received = event;
+    });
+    const evt = makeTrayEvent({
+      id: 7,
+      type: 'rightClick',
+      bounds: { x: 100, y: 0, width: 22, height: 22 },
+      shiftKey: true,
+    });
+    backend.fireEvent(evt);
+    expect(received).not.toBeNull();
+    expect(received!.id).toBe(7);
+    expect(received!.type).toBe('rightClick');
+    expect(received!.bounds).toMatchObject({ x: 100, y: 0 });
+    expect(received!.shiftKey).toBe(true);
+  });
+
+  it('delivers drop events with file payloads', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    let received: TrayEventData | null = null;
+    onTrayEvent((e) => {
+      received = e;
+    });
+    backend.fireEvent(makeTrayEvent({ type: 'dropFiles', dropFiles: ['/path/to/file.txt'] }));
+    expect(received!.dropFiles).toEqual(['/path/to/file.txt']);
+  });
+
+  it('returns an unsubscribe that stops delivery', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    let count = 0;
+    const unsubscribe = onTrayEvent(() => {
+      count += 1;
+    });
+    backend.fireEvent(makeTrayEvent({ type: 'click' }));
+    unsubscribe();
+    backend.fireEvent(makeTrayEvent({ type: 'click' }));
+    expect(count).toBe(1);
+  });
+
+  it('delivers balloon events', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const types: TrayEventType[] = [];
+    onTrayEvent((e) => {
+      types.push(e.type);
+    });
+    backend.fireEvent(makeTrayEvent({ type: 'balloonShow' }));
+    backend.fireEvent(makeTrayEvent({ type: 'balloonClick' }));
+    backend.fireEvent(makeTrayEvent({ type: 'balloonClose' }));
+    expect(types).toEqual(['balloonShow', 'balloonClick', 'balloonClose']);
+  });
+});
+
+describe('popupTrayContextMenu', () => {
+  it('pops up the context menu without a position', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    popupTrayContextMenu(tray);
+    // No error thrown; position was unset
+    expect(backend.lastPopupPosition).toBeNull();
+  });
+
+  it('pops up the context menu at a given position', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    popupTrayContextMenu(tray, { x: 200, y: 50 });
+    expect(backend.lastPopupPosition).toEqual({ x: 200, y: 50 });
+  });
+
+  it('is a no-op on web', () => {
+    expect(() => popupTrayContextMenu({ id: 0 }, { x: 0, y: 0 })).not.toThrow();
+  });
+});
+
+describe('removeTrayBalloon', () => {
+  it('removes the active balloon', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    displayTrayBalloon(tray, { title: 'T', text: 'B' });
+    removeTrayBalloon(tray);
+    expect(backend.trays.get(tray.id)!.balloon).toBeNull();
+  });
+
+  it('is a no-op on web', () => {
+    expect(() => removeTrayBalloon({ id: 0 })).not.toThrow();
+  });
+});
+
+describe('setTrayBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setTrayBackend(fakeBackend());
+    setTrayBackend(null);
+    expect(getTrayBackend()).not.toBeNull();
+  });
+});
+
+describe('setTrayIcon', () => {
+  it('updates the icon at runtime', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'idle.png' })!;
+    setTrayIcon(tray, 'active.png');
+    expect(backend.trays.get(tray.id)!.icon).toBe('active.png');
+  });
+
+  it('is a no-op on web', () => {
+    expect(() => setTrayIcon({ id: 0 }, 'icon.png')).not.toThrow();
+  });
+});
+
+describe('setTrayIconContextMenu', () => {
+  it('sets the context menu via the active backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    const items: readonly MenuItemTemplate[] = [{ id: 'quit', label: 'Quit' }];
+    setTrayIconContextMenu(tray, items);
+    expect(backend.trays.get(tray.id)!.contextMenu).toBe(items);
+  });
+});
+
+describe('setTrayIconTemplate', () => {
+  it('marks the icon as a template image', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayIconTemplate(tray, true);
+    expect(backend.trays.get(tray.id)!.isTemplate).toBe(true);
+  });
+
+  it('clears the template flag', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ iconTemplate: true })!;
+    setTrayIconTemplate(tray, false);
+    expect(backend.trays.get(tray.id)!.isTemplate).toBe(false);
+  });
+
+  it('is a no-op on web', () => {
+    expect(() => setTrayIconTemplate({ id: 0 }, true)).not.toThrow();
+  });
+});
+
+describe('setTrayIconTitle', () => {
+  it('sets the title via the active backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayIconTitle(tray, 'Hello');
+    expect(backend.trays.get(tray.id)!.title).toBe('Hello');
+  });
+});
+
+describe('setTrayIconTooltip', () => {
+  it('sets the tooltip via the active backend', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayIconTooltip(tray, 'Tip');
+    expect(backend.trays.get(tray.id)!.tooltip).toBe('Tip');
+  });
+});
+
+describe('setTrayIgnoreDoubleClickEvents', () => {
+  it('sets the ignore double-click flag', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayIgnoreDoubleClickEvents(tray, true);
+    expect(backend.trays.get(tray.id)!.ignoreDoubleClick).toBe(true);
+  });
+
+  it('is a no-op on web', () => {
+    expect(() => setTrayIgnoreDoubleClickEvents({ id: 0 }, true)).not.toThrow();
+  });
+});
+
+describe('setTrayPressedIcon', () => {
+  it('sets the pressed icon image', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    setTrayPressedIcon(tray, 'pressed.png');
+    expect(backend.trays.get(tray.id)!.pressedIcon).toBe('pressed.png');
+  });
+
+  it('is a no-op on web', () => {
+    expect(() => setTrayPressedIcon({ id: 0 }, 'pressed.png')).not.toThrow();
+  });
+});
+
+describe('startTrayIconAnimation', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('cycles through frames at the given interval', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon({ icon: 'frame0.png' })!;
+    const frames = ['frame0.png', 'frame1.png', 'frame2.png'];
+    startTrayIconAnimation(tray, frames, 100);
+    // Initial frame set immediately
+    expect(backend.trays.get(tray.id)!.icon).toBe('frame0.png');
+    vi.advanceTimersByTime(100);
+    expect(backend.trays.get(tray.id)!.icon).toBe('frame1.png');
+    vi.advanceTimersByTime(100);
+    expect(backend.trays.get(tray.id)!.icon).toBe('frame2.png');
+    vi.advanceTimersByTime(100);
+    // Wraps around
+    expect(backend.trays.get(tray.id)!.icon).toBe('frame0.png');
+  });
+
+  it('stop function cancels animation', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    const frames = ['a.png', 'b.png'];
+    const stop = startTrayIconAnimation(tray, frames, 50);
+    vi.advanceTimersByTime(50);
+    expect(backend.trays.get(tray.id)!.icon).toBe('b.png');
+    stop();
+    vi.advanceTimersByTime(200);
+    // Frame stays at b.png after stop
+    expect(backend.trays.get(tray.id)!.icon).toBe('b.png');
+  });
+
+  it('returns a no-op stop for empty frames', () => {
+    const backend = fakeBackend();
+    setTrayBackend(backend);
+    const tray = createTrayIcon()!;
+    const stop = startTrayIconAnimation(tray, [], 100);
+    expect(() => stop()).not.toThrow();
+  });
+});