# Mirage Qt Win-Parity Rebuild Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Rebuild the Linux Qt tray client so its tray menu structure, popup behavior, dialogs, and state-sync feel as close as practical to the current Windows Mirage GUI.

**Architecture:** Keep the existing Go bridge and Linux packaging flow, but replace the unstable tray interaction layer with a state-driven popup stack that is fully controlled by the Qt frontend instead of relying on desktop-managed tray context menus. Use the Windows GUI implementation in `cmd/mirage/gui_windows.go` as the behavior reference for menu grouping, visible/hidden states, tooltip/icon behavior, dialogs, and watch-driven state updates.

**Tech Stack:** Go, Qt5/Qt6, QSystemTrayIcon, custom popup widgets, LocalAPI bridge, Debian packaging

---

### Task 1: Lock Rebuild Boundary

**Files:**
- Modify: `cmd/mirage-qt/qt/src/main.cpp`
- Modify: `cmd/mirage-qt/qt/src/tray_ui_logic.h`
- Modify: `cmd/mirage-qt/qt/src/tray_ui_logic.cpp`
- Test: `cmd/mirage-qt/qt/src/tray_ui_logic_test.cpp`

- [ ] **Step 1: Write failing tests for Win-style open/close semantics**
- [ ] **Step 2: Implement stable root popup open/close rules without relying on tray context menu**
- [ ] **Step 3: Re-run logic tests and popup smoke tests**

### Task 2: Rebuild Menu Structure

**Files:**
- Modify: `cmd/mirage-qt/qt/src/main.cpp`
- Modify: `cmd/mirage-qt/qt/src/tray_ui_logic.h`
- Modify: `cmd/mirage-qt/qt/src/tray_ui_logic.cpp`
- Test: `cmd/mirage-qt/qt/src/tray_ui_logic_test.cpp`

- [ ] **Step 1: Write failing tests for root menu visibility by backend state**
- [ ] **Step 2: Match Windows root menu grouping and launcher composition**
- [ ] **Step 3: Match side menu content ordering for account/self/peers/exit/prefs**
- [ ] **Step 4: Re-run logic tests**

### Task 3: Rebuild Popup Stack

**Files:**
- Modify: `cmd/mirage-qt/qt/src/popup_menu_window.h`
- Modify: `cmd/mirage-qt/qt/src/popup_menu_window.cpp`
- Modify: `cmd/mirage-qt/qt/src/main.cpp`
- Test: `cmd/mirage-qt/qt/src/popup_menu_window_smoke_test.cpp`

- [ ] **Step 1: Write failing tests for deterministic sizing and placement**
- [ ] **Step 2: Implement root popup + side popup stack with Win-like hover behavior**
- [ ] **Step 3: Re-run popup tests**

### Task 4: Align UX Details

**Files:**
- Modify: `cmd/mirage-qt/qt/src/main.cpp`
- Modify: `cmd/mirage-qt/qt/src/tray_visuals.cpp`
- Modify: `cmd/mirage-qt/qt/src/desktop_integration.cpp`
- Test: `cmd/mirage-qt/qt/src/tray_visuals_test.cpp`
- Test: `cmd/mirage-qt/qt/src/desktop_integration_test.cpp`

- [ ] **Step 1: Match Windows tooltip/icon/notification semantics**
- [ ] **Step 2: Match Windows dialog wording and about/login flows where practical**
- [ ] **Step 3: Re-run visual and desktop tests**

### Task 5: Verify and Package

**Files:**
- Modify: `cmd/mirage-qt/mkdeb/main.go` (only if packaging inputs change)
- Output: `cmd/mirage-qt/build/deb/mirage-qt_<version>_amd64.deb`

- [ ] **Step 1: Run `go test ./cmd/mirage-qt/...`**
- [ ] **Step 2: Build Qt frontend in `/tmp/mirage-qt-verify`**
- [ ] **Step 3: Run all Qt offscreen tests**
- [ ] **Step 4: Run `go run ./cmd/mirage-qt/mkdeb`**
- [ ] **Step 5: Record package path and checksums**
