# Mirage Qt Popup Stack 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:** Replace the current Linux tray menu architecture with a self-controlled popup stack so DDE/X11 scaling no longer breaks submenu hover, positioning, or hit testing.

**Architecture:** Keep `QSystemTrayIcon` only for the icon and activation signal. Keep existing `QAction` and hidden `QMenu` objects as menu data sources, but stop displaying them through `setContextMenu` or native submenus. Introduce custom root and side popup windows that render those actions directly and manage hover, click, close, and positioning in application code.

**Tech Stack:** Qt Widgets (Qt5/Qt6), existing `QAction/QMenu` data model, `tray_ui_logic.*` for pure positioning/state logic, Go bridge and `.deb` packaging unchanged.

---

### Task 1: Add popup stack positioning/state helpers

**Files:**
- 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: Extend failing tests**
- [ ] **Step 2: Verify tests fail**
- [ ] **Step 3: Add minimal pure logic for root popup placement, side popup placement, and popup close guards**
- [ ] **Step 4: Re-run Qt logic tests**

### Task 2: Build custom popup window widgets

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

- [ ] **Step 1: Add a failing smoke test that instantiates the popup window and renders actions**
- [ ] **Step 2: Verify it fails to compile/link**
- [ ] **Step 3: Implement minimal popup row/window widgets that mirror `QAction` lists**
- [ ] **Step 4: Re-run popup smoke test**

### Task 3: Replace native tray context menu with custom root/side popup stack

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

- [ ] **Step 1: Remove `tray_.setContextMenu(&menu_)` as displayed UI path**
- [ ] **Step 2: Keep existing `QAction`/hidden `QMenu` rebuild logic as data sources**
- [ ] **Step 3: Show root popup from tray activation using cursor/screen anchored placement**
- [ ] **Step 4: Show side popup on launcher hover and click**
- [ ] **Step 5: Close the whole popup stack on outside click, escape, or action trigger**
- [ ] **Step 6: Re-run Qt build**

### Task 4: Verify behavior and rebuild package

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

- [ ] **Step 1: Run `go test ./cmd/mirage-qt/...`**
- [ ] **Step 2: Run Qt offscreen tests**
- [ ] **Step 3: Run `go run ./cmd/mirage-qt/mkdeb`**
- [ ] **Step 4: Record package SHA-256**
