feat(desktop): port desktop app and platform integrations to macOS

[saivinay1805]

Summary

This pull request ports the NectarLink desktop application to macOS, delivering on the roadmap goal in docs/PLAN.md §10.7 to bring the Qt Quick + Rust desktop core cross-platform.

It incorporates maintainer feedback from PR #24 and PR #23:

• Rebased on top of main (incorporating PR core, desktop, android: cross-platform Linux preparation & USB session reliability #23 Unix groundwork and USB session fixes).
• Follows the single-file layout of Linux PR feat(linux): Linux desktop & CLI implementation (stacked on #23) #12 for shared modules (storage.rs, pc_audio_stream.rs, pc_mirror.rs, and play_on_phone.rs) with internal #[cfg] blocks.
• Employs strict capability negotiation: features not implemented on macOS are not advertised, so the capability matrix cleanly presents them as unavailable on both apps.

---

Feature Scope on macOS

Supported Today

• Pairing & Security: Core discovery, QR / nearby code pairing, mutual TLS 1.3 authentication and device-key storage restricted to the current user.
• Files & Photos: Two-way file and folder transfers, photo roll browser, timeline photo thumbnails, and full-resolution photo downloads.
• Continuity Camera: Document scanning and camera photo capture directly to the Mac.
• Clipboard: Two-way text clipboard synchronization; incoming image pasteboard copying (Phone → Mac) via AppleScript with format conversion.
• Calls & Messages: In-call alerts, call history browsing, contacts search, and SMS conversation viewing & sending.
• Device Controls: Phone quick toggles (volume, ringer, DND, etc.) and battery/ring interactions.
• Diagnostics: System Connection Doctor network and firewall checks.

Intentionally Not Advertised / Not Supported Yet

• Phone screen mirroring (video decoding): mirror.view is removed from BASE_CAPABILITIES and restricted to Windows, preventing unhandled video stream initiation.
• MP4 recording & PC audio streaming: Explicit Err returns on unsupported stream initialization rather than silent success stubs.
• System Media Transport Controls (media.control): Omitted from macOS desktop capabilities.
• Phone storage mounting in Finder: Cloud Files sync root (storage.mount) is Windows-only.
• Virtual webcam: Windows MF virtual camera driver only.

---

Key Changes

1. macOS Platform Subsystem (desktop/app/src/mac/):

   • Implemented native modules matching the desktop application platform contracts:
     • clipboard: Two-way text synchronization via pbcopy/pbpaste, plus AppleScript «class PNGf» pasteboard image writing with automatic format conversion and collision-free temporary files.
     • image: Real bitmap decoding using Qt QImage::loadFromData into BGRA pixels.
     • audio: Syntax-safe AppleScript speaker volume and mute status query parser.
     • single_instance: Unix domain socket-based single instance detection (nectarlink.sock) with automatic stale socket cleanup and activation wakeups.
     • toast: Native macOS system notifications via osascript.
     • http, browser, shell, autostart, doctor, and wol.
     • Explicit unsupported error handling in h264.rs, mp4.rs, and audio_out.rs.

2. Module Layout (matching PR feat(linux): Linux desktop & CLI implementation (stacked on #23) #12):

   • Kept storage.rs, pc_audio_stream.rs, pc_mirror.rs, and play_on_phone.rs as single files with internal #[cfg(windows)] and #[cfg(not(windows))] blocks.
   • Platform module mounted in main.rs via #[cfg(target_os = "macos")] #[path = "mac/mod.rs"] mod win;.

3. Capability Negotiation:

   • Removed mirror.view from BASE_CAPABILITIES in nectarlink-core so non-decoding desktop builds can opt out.
   • Scoped Windows-only capabilities (media.control, storage.mount, vcam, etc.) to #[cfg(windows)] in core_host.rs.
   • Desktop reports os: std::env::consts::OS.into() ("macos").
   • Added unit tests in core (macos_desktop_matrix_reflects_supported_and_unsupported_features) and desktop (macos_advertises_only_supported_capabilities).

4. Warnings & CI:

   • Removed blanket #![cfg_attr(not(windows), allow(unused))] across desktop and spike crates.
   • Preserved desktop-macos GitHub Actions CI workflow with Qt 6.12.

5. Documentation:

   • Updated README.md with macOS build requirements and a comprehensive Platform Support matrix.

---

Testing & Verification

• cargo test -p nectarlink-protocol: 62 passed; 0 failed
• cargo test -p nectarlink-core --lib: 112 passed; 0 failed
• cargo test -p nectarlink-desktop: 148 passed; 0 failed
• cargo clippy --locked -p nectarlink-desktop --all-targets -- -D warnings: 0 warnings
• cargo clippy --locked -p s1-qt-rust --all-targets -- -D warnings: 0 warnings
• cargo fmt --all --check & cargo xtask strings --check: Clean
• git diff --check: Clean
• All commits signed off (Signed-off-by) adhering to DCO guidelines.

[saivinay1805]

Closed for local testing

[jochenkirstaetter]

Hello @saivinay1805

Cool stuff.
Maybe you might have a look at the code changes in core provided in #23 which prepares the common areas for Linux? Eventually this could assist your work as a stacked branch like it does for my Linux port?

Really like seeing this.

Cheers

[saivinay1805]

Thanks for reaching out @jochenkirstaetter !

I looked through #23 — having the shared core/QML changes (Unix key permissions, window geometry persistence, RPC timeouts, and std::env::consts::OS) broken out is super clean and directly benefits macOS too.

Once #23 lands in main, rebasing the macOS platform layer on top of it will make everything even smoother. Really appreciate you preparing the common foundations!

[saivinay1805]

Reopening after successful local testing on macOS (tested device pairing, UI, and test suite on Apple Silicon).

[thtbee]

Thanks for this, and for testing it on Apple Silicon. A macOS build is something people have asked for, so it's great to see it started.

Before you go further, a few things about how it should fit in, so the work doesn't have to be redone later:

1. Base it on core, desktop, android: cross-platform Linux preparation & USB session reliability #23. core, desktop, android: cross-platform Linux preparation & USB session reliability #23 holds the shared groundwork for other platforms and will land first. Please wait for it to merge, then rebase onto main.

2. Use the same structure as the Linux port. feat(linux): Linux desktop & CLI implementation (stacked on #23) #12 adds Linux by putting its platform code in desktop/app/src/linux/, mounted in place of win with the same functions, and keeps the shared modules (pc_mirror.rs, pc_audio_stream.rs, play_on_phone.rs, storage.rs) as single files with cfg blocks. This PR splits those four into windows.rs / non_windows.rs folders instead, which conflicts with feat(linux): Linux desktop & CLI implementation (stacked on #23) #12 on the same files and leaves the project with two patterns. Please follow the Linux layout: mac/ in place of win, and the shared modules kept as they are.

3. No silent stubs. Several functions do nothing and report nothing, for example everything in mac/input.rs, and pc_mirror / play_on_phone outside Windows. A phone's remote mouse, keyboard or Deck tiles would then look as if they work on a Mac and quietly do nothing. The rule in this project is that the app never offers a feature that can't work: anything not implemented on macOS should not advertise its capability, so the capability matrix shows it as unavailable on both apps (see docs/architecture/capabilities.md).

4. No crate-wide allow(unused). #![cfg_attr(not(windows), allow(unused))] in main.rs hides warnings on every non-Windows build, Linux included. Please scope cfg attributes to the items that need them instead.

5. Scope in the description. A short list of what works on macOS today and what doesn't yet would help reviewing, and the README, since we can't test on a Mac ourselves. The desktop-macos CI job is a good start.

If it helps, splitting it like #23 and #12 (shared changes first, then the macOS code) also makes it much easier to review. Happy to answer questions on any of this.

[thtbee]

Hi @saivinay1805, #23 is merged now, so main has the shared groundwork for other platforms. Whenever you're ready, rebase onto main and follow the Linux layout from #12 as described above. Happy to look at it again then.

[saivinay1805]

Hi @thtbee,

Thanks for merging #23! I have rebased this PR cleanly onto main and addressed your feedback:

1. Module Layout (matching Linux feat(linux): Linux desktop & CLI implementation (stacked on #23) #12):

   • Restored storage.rs, pc_audio_stream.rs, pc_mirror.rs, and play_on_phone.rs back to single files with internal #[cfg(windows)] and #[cfg(not(windows))] blocks.
   • Cleaned up macOS platform dispatch in main.rs via #[cfg(target_os = "macos")] #[path = "mac/mod.rs"] mod win;.
   • Removed blanket crate-wide allow(unused) attributes across desktop and spike crates.

2. Capability Negotiation & Honest Error Handling:

   • Removed mirror.view from BASE_CAPABILITIES in core so non-decoding desktop platforms can cleanly opt out.
   • Scoped Windows-only desktop capabilities (media.control, storage.mount, vcam, etc.) to #[cfg(windows)] in core_host.rs and report "macos" as the OS.
   • Added unit tests in core (macos_desktop_matrix_reflects_supported_and_unsupported_features) and desktop (macos_advertises_only_supported_capabilities) asserting that unsupported features evaluate to unavailable and are not advertised.
   • Replaced silent success stubs with explicit unsupported Err returns for H.264 decoding, MP4 recordings, and streamed audio playback.
   • Implemented real bitmap decoding via Qt QImage::loadFromData and AppleScript pasteboard image copy with automatic format conversion and collision-free temp files.

3. Documentation & Validation:

   • Added macOS build requirements and a comprehensive Platform Support matrix to README.md.
   • Updated PR description.
   • Local validation: 148 desktop tests, 112 core tests, and 62 protocol tests all passing; Clippy strict zero warnings; cargo fmt clean. All commits signed off per DCO.

Local checks passed; awaiting CI approval and review whenever convenient!

[thtbee]

Thanks for the rebase. I compared the four wrapped files with main, and the Windows code is the same apart from the cfg wrapper and rustfmt.

What needs fixing:

1. Windows x64 CI fails clippy: decode_image is unused on Windows, and use super::* in core_host's tests is unused there since the only test is macOS-only.
2. Clipboard privacy. Sending the PC clipboard is on by default, and the macOS watcher reads pbpaste without checking org.nspasteboard.ConcealedType / TransientType, so a password copied from a password manager goes to the phone. Windows skips those (Clip::Private). NSPasteboard would fix it, and its changeCount avoids starting a process twice a second. The first poll also sends whatever is on the clipboard at startup.
3. Close to tray is on by default and the tray is a stub, so closing the window leaves the app running with no way back. Turn it off on macOS or handle the Dock reopen.
4. Some stubs still report success: the Doctor firewall/network checks and fix_firewall, elevated::start, wol::wake (and pc.wake is advertised with no adapters), and lock(), which doesn't check whether osascript was allowed. These should return unsupported or not be offered.

Smaller: stop_ringing kills every afplay the user has running, unmuting the mic sets 75 instead of the old level, query_live_speaker_state needs real audio hardware, the LaunchAgent plist doesn't escape the path, and mac/mod.rs still has a blanket allow(dead_code, unused_imports).

[alexfoxtm]

Hi @saivinay1805 and @thtbee — are additional contributors welcome?

We’re working locally from this macOS port, targeting Apple silicon Macs and Galaxy Fold phones. We’d like to contribute reusable macOS fixes and features, along with Android app improvements, back upstream rather than maintain a separate implementation.

Happy to coordinate and submit small, focused PRs that follow the project’s architecture and contribution guidelines. Are there particular areas or priorities you’d prefer us to help with, so we avoid duplicating ongoing work?

[saivinay1805]

Updated in e71dee4:

• Windows CI Clippy: Scoped macOS unit tests and bridge functions with platform cfgs and conditional shadowing, eliminating all dead-code and unused-mut warnings under -D warnings.
• Clipboard & Privacy: Replaced subprocess calls with native C++ NSPasteboard helpers querying changeCount, wrapped in autorelease pools for thread safety, respecting ConcealedType privacy markers, and ignoring startup clipboard state.
• Window Geometry: Implemented NativeWindow::setScreenByName to cleanly restore saved screen placement without QML QScreen* type mismatches, and resolved the visibility change binding.
• Honest Stubs: Removed pc.wake from macOS capabilities, returned explicit unsupported errors for doctor/elevation/WoL, and tracked individual child PIDs for sound ringing.
• macOS Tray Fallbacks: Defaulted and enforced close_to_tray: false on macOS (quitting cleanly on window close), disabled the tray toggle in Settings on macOS, and removed --minimized from the autostart LaunchAgent plist.
• Audio & Animations: Preserved exact microphone volume restoration on unmute and restored comb_motion preference initialization.

All local checks pass (112 core unit tests, 148 desktop tests, zero Clippy warnings, fmt, and whitespace checks). Awaiting CI approval and review.

[thtbee]

Thanks, this covers the last review. I read the NSPasteboard code: the concealed/transient check and recording changeCount at startup look right, and the stubs fail honestly now.

What's left:

1. It conflicts with main in MainWindow.qml. I pushed a fix there this morning (e4b279a): on Windows the window from #29 didn't open at all, because NativeWindow's QML type doesn't expose onWindowVisibilityChanged or screen. Main now uses a Connections block like yours and drops the screen assignment, since a position in desktop coordinates already picks the monitor. Please take main's version when you rebase. setScreenByName shouldn't be needed then; if macOS does need it to move between monitors, call it after bringToFront().
2. #34 (Linux part 1) changes 16 of the same files in a different way. I'd like to merge this one first, since it has had two rounds and is close, and then have #34 rebase onto it. Your #[cfg(windows)] mod imp with one #[cfg(not(windows))] stub module works well for that, since Linux can start from the same stubs and replace them part by part.

Small: I think CGSession is gone since Big Sur, so lock() will always take the osascript path. That's fine, but the comment says otherwise.

[thtbee]

@alexfoxtm yes, welcome. Small, focused PRs are the best way to do it.

To avoid doing the same work twice: #24 is the macOS port and #34 starts the Linux series. For macOS, it's best to wait until #24 is merged and then pick up what it leaves unsupported, like screen mirroring and H.264 decoding, PC audio streaming, and the tray. For Android, including Fold layouts, please open an issue first with what you have in mind so we can agree on the approach before you write it. CONTRIBUTING.md has the rest (sign-off and checks).

[thtbee]

Heads-up for the rebase: main now has photo backup and joining the phone's hotspot, which add a few things under crate::win that macOS will need stubs for: win::local_offset_ms, win::free_space and the win::wifi module (saved_networks, scan, reach, connect, Reach). photo_backup.rs also opens the folder with explorer.exe. Returning 0, None, an empty list and an unsupported error is fine for now.

[saivinay1805]

Rebased onto main (5bdcadb) and updated in 749b7fd:

• MainWindow & Screen Placement: Rebased cleanly onto main, taking main's MainWindow.qml without conflict, and removed NativeWindow::setScreenByName as desktop coordinate placement handles monitors.
• Screen Lock: Updated the comment in mac/shell.rs to clarify that CGSession was removed after Big Sur (macOS 11), with modern macOS taking the osascript keycode path.
• Upstream Feature Support:
  • Added mac/wifi.rs stubs for Instant Hotspot.
  • Implemented local_offset_ms (via QTimeZone) and free_space (via QStorageInfo) for Photo Backup.
  • Handled the full-drive edge case in free_space: query failures return None, while a 100% full drive returns Some(0), ensuring photo backup's free-space margin checks work correctly.

All local checks pass (164 desktop tests, 112 core tests, zero Clippy warnings, fmt, and whitespace checks).

[thtbee]

Thanks, the rebase looks right: MainWindow.qml is the same as main's, nothing from main was undone, and local_offset_ms and free_space through QTimeZone and QStorageInfo look good. CI is green, including the new UI check.

Two small things: photo backup's Open button runs explorer.exe directly (bridge/photo_backup.rs, open_folder), so on macOS it does nothing; going through a shell::open_folder on each platform would fix it. And native_window.h still has a stray blank line from the removed setScreenByName.

Jochen is checking how #34 and the rest of the Linux series line up with this, so I'll wait for that before merging either one.

[jochenkirstaetter]

Hi @thtbee

It, meaning #34 , lines up beautifully and matches this PR's structure perfectly. It's ready for review and waiting for your feedback.

Cheers

[thtbee]

Went through it once more as a whole: the Windows code in the shared files is the same as main's apart from the cfg wrappers, the updater's Windows path is unchanged, and CI is green on all three platforms. Thanks for sticking with all the rounds.