# `@mailpouch/tray-native`

Native cross-platform system-tray binding for mailpouch. Wraps the
[tauri-apps/tray-icon](https://github.com/tauri-apps/tray-icon) Rust
crate via [napi-rs](https://napi.rs/) so mailpouch's tray renders
correctly on every modern desktop without a Go runtime, an Electron
bundle, or the `systray2` Go binary's GNOME quirks (3-dot ellipsis
fallback, hardcoded `tray_linux_release` Title, missing
`IconThemePath`).

## Why this exists

`systray2` is the de-facto Node tray library, but its bundled Go
binary has unresolved bugs on modern GNOME — confirmed live during
mailpouch's tray work (see PRs #88, #89). The Tauri team's
`tray-icon` crate doesn't have those bugs because it's the same
code path Tauri uses in production across thousands of apps.

## Architecture

- `src/lib.rs` — napi-rs binding. Exposes a `Tray` class with
  `setMenu` / `setIcon` / `setTooltip` / `destroy` methods plus an
  `onClick` callback. All commands are non-blocking from JS;
  internally a dedicated thread owns the native tray and pumps the
  GTK / Cocoa / Win32 event loop.
- `Cargo.toml` — pins `tray-icon`, `muda`, and `napi`/`napi-derive`.
  Linux pulls in `gtk` and `glib` for main-loop pumping; macOS and
  Windows use tray-icon's bundled native event-loop integration.
- `index.js` / `index.d.ts` — auto-generated by napi-rs on every
  build; loads the right `.node` for the current platform.

## Building locally

```
cd native/tray
cargo build --release       # one-time check the source compiles
npx @napi-rs/cli@^2 build --release --platform
```

Linux build needs:
```
sudo apt install libgtk-3-dev libayatana-appindicator3-dev libxdo-dev
```

End users do **not** need any of these at runtime — the prebuilt
`.node` is dynamically linked against `libgtk-3.so.0` and
`libayatana-appindicator3.so.1`, both standard on Ubuntu / Fedora /
most desktop Linux distros.

## Distribution

The committed `.node` files in this directory are the prebuilds for
each target the project supports. Currently:

- `index.linux-x64-gnu.node` ✓ committed
- `index.linux-arm64-gnu.node` — produced by CI (TODO)
- `index.darwin-x64.node` — produced by CI (TODO)
- `index.darwin-arm64.node` — produced by CI (TODO)
- `index.win32-x64-msvc.node` — produced by CI (TODO)
- `index.win32-arm64-msvc.node` — produced by CI (TODO)

Until CI lands prebuilts for every target, mailpouch on
non-x64-Linux platforms falls back to the `systray2` backend (see
`src/utils/tray.ts` — the `_loadNativeTray` failure path). systray2
works fine on macOS/Windows; the GNOME-specific bug only affects
Linux desktop users, who are covered by the committed prebuilt.
