IronPad-Docker/docs/system-tray-implementation.md

System Tray Implementation (v0.2.0) ✅

Status: Implemented

Goal: Replace the CMD window with a system tray icon. Users interact via tray menu: "Open in Browser" or "Quit". No console window on Windows.

---

Overview

• Scope: Single codebase, cross-platform. CI/CD unchanged — same build pipeline produces one binary per OS.
• Crate: tray-item = "0.10" (cross-platform tray icon with simple API)
• Windows icon: windows-sys = "0.52" for loading the standard application icon via LoadIconW

---

What Was Implemented

1. Dependencies (backend/Cargo.toml)

# System tray (production mode)
tray-item = "0.10"

# Windows system icon loading (for tray icon)
[target.'cfg(target_os = "windows")'.dependencies]
windows-sys = { version = "0.52", features = ["Win32_UI_WindowsAndMessaging"] }

2. Windows: Hide Console Window (backend/src/main.rs)

#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]

• Debug builds (cargo run): Console remains for logs.
• Release builds (cargo build --release): No CMD window on Windows.

3. Restructured main() for Dual-Mode Operation

main()
├── Development mode (no static/index.html next to exe)
│   └── Normal tokio runtime on main thread, API-only, no tray
└── Production mode (static/index.html exists)
    └── run_with_tray()
        ├── Background thread: tokio runtime + Axum server
        ├── mpsc channel: server sends bound port back to main thread
        ├── Auto-open browser (400ms delay)
        └── Main thread: tray icon + event loop

4. Tray Icon (Platform-Specific)

Platform	Icon Source
Windows	IDI_APPLICATION via LoadIconW (standard system app icon)
macOS	IconSource::Resource("") (default icon)
Linux	IconSource::Resource("application-x-executable") (icon theme)

5. Tray Menu

• "Open in Browser" — calls webbrowser::open() with http://localhost:{port}
• "Quit" — calls std::process::exit(0) to shut down server and exit

6. Threading Model

The tray event loop runs on the main thread (required on macOS, safe on all platforms). The Axum server runs on a background thread with its own tokio::runtime::Runtime. Port discovery uses std::sync::mpsc::channel.

---

Behaviour Summary

Before (v0.1.0)	After (v0.2.0)
CMD window visible	No console window (Windows release)
Browser opens on start	Browser opens on start + via tray
Quit via Ctrl+C	Quit via tray menu or Ctrl+C (dev)

---

Testing Checklist

• Backend compiles with new dependencies (cargo check)
• Windows: No CMD window when running release binary
• Windows: Tray icon appears; "Open in Browser" opens correct URL
• Windows: "Quit" exits cleanly
• macOS: Tray icon in menu bar; menu works
• Linux: Tray icon in system tray; menu works
• Development mode (cargo run): Behaviour unchanged (no tray, API-only)

---

Icon Asset

Currently using platform default icons (Windows system app icon, macOS default, Linux icon theme). To use a custom branded icon:

1. Create a 16×16 or 32×32 PNG/ICO
2. On Windows: embed via .rc resource file and build.rs, use IconSource::Resource("icon-name")
3. On macOS/Linux: use IconSource::Data { width, height, data } with raw RGBA bytes

---

References

• tray-item crate
• tray-icon crate (alternative, heavier)
• #![windows_subsystem = "windows"] — Rust conditional compilation