feat(linux): fix overlay window visibility on KDE Plasma Wayland

[ochen1]

Note: Written by Opus. Tested to work on KDE. Not tested for regressions in other environments.

Summary

• Fix overlay window appearing in Alt+Tab on Linux by using toolbar window type
• Fix overlay window not showing on all virtual desktops on KDE Wayland via KWin scripting
• Add runtime KWin D-Bus integration to configure overlay window properties

Problem

On KDE Plasma Wayland, the dictation overlay window had two issues:

1. Appeared in Alt+Tab switcher - The overlay window would show up when users pressed Alt+Tab, which is undesirable for a small utility overlay
2. Only visible on one workspace - Electron's setVisibleOnAllWorkspaces() API doesn't work properly on KDE Wayland, causing the overlay to disappear when switching virtual desktops

These are known issues documented by other Electron applications:

• CherryHQ/cherry-studio - Documents that setVisibleOnAllWorkspaces on Linux (especially KDE Wayland) causes windows to go into a "false popup" state
• Hiram-Wong/ZyPlayer - Uses the same workaround, explicitly skipping the call on Linux

Solution

1. Window Type Change

Changed the window type from normal to toolbar for Linux. Toolbar-type windows are excluded from Alt+Tab on most Linux compositors (GNOME, KDE, Sway, etc.).

// Before
type: process.platform === "darwin" ? "panel" : "normal";

// After
type: process.platform === "darwin" ? "panel" : process.platform === "linux" ? "toolbar" : "normal";

2. KWin Scripting Integration

Created a new kdeIntegration.js helper that uses KWin's D-Bus scripting API to configure the overlay window at runtime:

• Auto-detects KDE Plasma environment via XDG_CURRENT_DESKTOP, DESKTOP_SESSION, and KDE_FULL_SESSION
• Writes a temporary KWin script that finds windows matching "Voice Recorder" or "openwhispr"
• Sets the following properties via KWin API:
  • onAllDesktops = true - Visible on all virtual desktops
  • skipSwitcher = true - Hidden from Alt+Tab
  • skipTaskbar = true - Hidden from taskbar
  • skipPager = true - Hidden from desktop pager
• Supports both Plasma 5 (qdbus) and Plasma 6 (qdbus6)
• Includes retry logic (3 attempts with 500ms delay) to handle window registration timing

3. Standard Linux Fallback

Also added window.setVisibleOnAllWorkspaces(true) in the Linux branch of setupAlwaysOnTop() for X11 and other Wayland compositors where the Electron API does work.

Files Changed

File	Change
src/helpers/windowConfig.js	Changed window type to toolbar for Linux; added setVisibleOnAllWorkspaces call
src/helpers/kdeIntegration.js	New file - KDE Plasma Wayland integration via KWin D-Bus scripting
main.js	Import and initialize KDE integration after window creation
CLAUDE.md	Added documentation for KDE integration

Testing

To test on KDE Plasma Wayland:

1. Run the app
2. Verify the overlay window:
   • Does NOT appear in Alt+Tab or taskbar ✅
   • Appears on all virtual desktops when switching ✅
   • Stays always-on-top ✅

To verify KWin script execution, run with debug logging:

OPENWHISPR_LOG_LEVEL=debug ./openwhispr

Look for [KDEIntegration] log entries showing successful script execution.

Notes

• The KDE integration is non-blocking and fails gracefully - if KWin is unavailable or the script fails, the app continues to work normally
• On non-KDE Linux environments (GNOME, Sway, etc.), the toolbar window type alone should handle Alt+Tab hiding
• No user action required - KDE detection and configuration is automatic

[gabrielste1n]

this is awesome thank you @ochen1 - will review asap