Show recording overlay in macOS fullscreen apps, and when switching between spaces

[dannysmith]

Problem

Handy shows no visual feedback when recording in fullscreen apps on macOS, as the current Recording Overlay is not shown (#277). Similarly, the overlay is not shown when the user switches spaces (#278).

On macOS Big Sur+, standard NSWindow with .always_on_top(true) uses NSFloatingWindowLevel (level 3). Fullscreen apps run at NSMainMenuWindowLevel + 1 (level 25+), so standard windows appear behind fullscreen content.

Relevant Tauri Issues:

• Show window on top of full-screen app #5793
• visibleOnAllWorkspaces not working with fullscreen #11488

Solution

Use NSPanel instead of NSWindow. Only NSPanel windows can appear above fullscreen apps.

Implementation

Uses tauri-nspanel plugin (v2.1), which seems to be the best option here. Cap and Overlayed both use it in prod, and any other options add significantly more macOS-specific code.

Only create_recording_overlay() needs to be platform-conditional. Other overlay functions (show, hide, update_position, etc.) can remain platform-agnostic because PanelBuilder creates a standard Tauri window first, then converts it to NSPanel — the window remains registered in Tauri's manager, accessible via get_webview_window().

The NSPanel has:

• High window level (PanelLevel::Status - level 25)
• canJoinAllSpaces - appears in all Mission Control spaces
• fullScreenAuxiliary - works alongside fullscreen apps

Changes

1. src-tauri/Cargo.toml - Added tauri-nspanel dependency for macOS builds
2. src-tauri/src/lib.rs - Initialize plugin on macOS
3. src-tauri/src/overlay.rs - Platform-conditional panel creation

• No frontend changes – React/CSS overlay components untouched.
• macOSPrivateApi: true required in tauri.conf.json (this was already enabled)

What I've tested

Build tested on macOS Tahoe 26.0.1 (Apple Silicon):

• [x] Works accross fullscreen apps (closes #277)
• [x] Works when switching spaces while recording overlay is active (closes #278)
• [x] No changes to existing UI or behavior (that I could find at least)

What I can't test

• [ ] Builds for Win/Linux still work fine
• [ ] Signed builds for macOS actually work (coz urgh Tauri can sometimes be annoying here)

References

• tauri-nspanel documentation
• macOS Window Levels
• NSWindow.CollectionBehavior
• Stack Overflow: NSPanel above fullscreen

[dannysmith]

Also...

1. Have included an unrelated commit to gitignore *.local.* because it didn't seem worth a separate PR.
2. @cjpais thanks for making this - appreciate the work mate 🙏

[cjpais]

well works for me, we can make tweaks later. im gonna merge it, thanks!