fix(macos): stop HUD dialogs painting a grey rectangle over the desktop

[EtienneLescot]

Problem

On macOS, every message box owned by the HUD shows up as a sheet, and AppKit dims the whole owning window behind a sheet. The HUD is a ~907×696 transparent window around a ~60 px bar, so each dialog it owns greys out a large, otherwise invisible area of the desktop. This covers the screen and accessibility permission dialogs, and every showMessageBox in main.ts that falls back to mainWindow.

Found while testing #302 on a Mac.

Fix

A new electron/messageBox.ts decides which window owns a message box:

• macOS + a transparent overlay (HUD, source selector, countdown): no owner. An unowned alert is app-modal and sits at the modal-panel level, above the HUD's floating level, so it still appears in front.
• Everywhere else: behaviour is unchanged. On Windows and most Linux WMs an unowned dialog opens behind the always-on-top HUD (the reason main.ts's showMessageBox gives the dialog an owner in the first place).

The three windows are marked in windows.ts, and main.ts's showMessageBox (About, updates, diagnostics) goes through showMessageBoxOver.

Verified

• Packaged, Developer-ID-signed build on macOS 26: the "Screen Recording permission is required" and "Screen Recording permission granted / Restart" dialogs show in front of the HUD, with no grey rectangle. Before the fix, the grey rectangle filled the HUD's whole transparent area.
• tsc, biome check, vitest run electron (822 passed), plus new unit tests for the owner decision.

Rebased onto #735

#735 replaced the two permission dialogs this PR first touched in ipc/handlers.ts with the permissions window, so that part of the diff is gone. What is left is main.ts's dialogs.

Summary by CodeRabbit

• Bug Fixes
  • On macOS, message boxes opened from HUD, source-selector, and countdown-overlay windows no longer appear as sheets attached to those windows.
  • Message boxes continue to be attached to their parent window on Windows and Linux, and on macOS when opened from other windows.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 8c051c2c-ae3d-4453-9598-8652b90dd313

📥 Commits

Reviewing files that changed from the base of the PR and between 4099a32 and 65fcd70.

📒 Files selected for processing (1)

• electron/main.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds shared message-box owner selection. On macOS, marked sheetless windows are not used as owners. HUD, source-selector, and countdown-overlay windows are marked, and the main-process wrapper uses the new helper.

Changes

Message Box Ownership

Layer / File(s)	Summary
Owner selection and sheetless windows electron/messageBox.ts, electron/windows.ts, electron/main.ts, electron/messageBox.test.ts	The helper tracks sheetless windows, selects an owner based on platform and window state, and displays message boxes. Three overlay windows are marked as sheetless. The main-process wrapper uses the helper, and tests cover owner selection.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: atharva9167j

Merge Risk: ⚪ Minimal · up to 65fcd

On macOS, dialogs for marked transparent overlays avoid using those overlays as owners, addressing the reported dimming behavior. The hidden-window fallback is preserved, and no actionable merge risk remains.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description explains the problem, fix, platform behavior, and testing results. However, it does not use the required template sections and omits the required type of change, release impact, deskto…	Rewrite the description using the repository template. Include Summary, Related issue, Type of change, Release impact, Desktop impact, Screenshots / video, and Testing sections. Select the applicable checkboxes and use an accepted issue ref…

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the macOS bug fix and the visible desktop-dimming symptom. It accurately summarizes the main change.

Full details: Description check

Explanation

The description explains the problem, fix, platform behavior, and testing results. However, it does not use the required template sections and omits the required type of change, release impact, desktop impact, and screenshots or video sections. The related issue is also not formatted with the required reference syntax.

Resolution

Rewrite the description using the repository template. Include Summary, Related issue, Type of change, Release impact, Desktop impact, Screenshots / video, and Testing sections. Select the applicable checkboxes and use an accepted issue reference such as "Refs #302" if the change is related but does not fully resolve the issue.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}