fix(macOS): add NSScreenCaptureUsageDescription and screen-capture entitlement

[creazyfrog]

What

Fixes #548

Adds the missing NSScreenCaptureUsageDescription key to the macOS extendInfo block in electron-builder.json5, and adds the com.apple.security.device.screen-capture entitlement to macos.entitlements.

Root cause

macOS 10.15+ enforces TCC (Transparency, Consent, and Control) for screen recording. When an app calls desktopCapturer.getSources(), the OS checks for NSScreenCaptureUsageDescription in Info.plist to show the permission prompt. If the key is absent, the API fails silently — no error, no prompt, no sources returned — causing window detection to break completely.

All other permission keys were already present:

• ✅ NSAudioCaptureUsageDescription
• ✅ NSMicrophoneUsageDescription
• ✅ NSCameraUsageDescription
• ❌ NSScreenCaptureUsageDescription ← was missing

Changes

electron-builder.json5 — one line added to mac.extendInfo:

"NSScreenCaptureUsageDescription": "OpenScreen needs screen recording permission to detect and capture windows."

macos.entitlements — one entitlement added alongside the existing camera and audio-input entries:

<!-- Screen recording (required for desktopCapturer.getSources() on macOS 10.15+) -->
<key>com.apple.security.device.screen-capture</key>
<true/>

Testing

Build the macOS DMG and launch on a clean macOS 10.15+ machine (or one where OpenScreen has not previously been granted screen recording access). On first launch, macOS should now display the screen recording permission prompt. Once granted, desktopCapturer.getSources() returns window sources and window detection works correctly.

Summary by CodeRabbit

• New Features
  • Enabled screen capture functionality on macOS with proper permission handling and security entitlements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 176ca8f3-903f-408b-8a38-4b656aac7692

📥 Commits

Reviewing files that changed from the base of the PR and between 899504f and f47fa6b.

📒 Files selected for processing (2)

• electron-builder.json5
• macos.entitlements

---

📝 Walkthrough

Walkthrough

This PR adds the missing macOS screen recording permission infrastructure—the OS entitlement that enables the capability and the user-facing permission description string. These changes directly address window detection failures on macOS by properly declaring the required permissions.

Changes

macOS Screen Recording Permissions

Layer / File(s)	Summary
OS Entitlements macos.entitlements	Added com.apple.security.device.screen-capture entitlement set to true, enabling the OS-level capability for screen recording access.
Permission Prompt Configuration electron-builder.json5	Added NSScreenCaptureUsageDescription under mac.extendInfo to provide the permission prompt text when macOS requests screen recording access.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

Screen captures flow now with proper might,
Entitlements declare, prompts shine bright,
macOS grants access, windows are found,
Two config lines make the whole thing sound. 🎬

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title accurately and concisely describes the two core changes: adding NSScreenCaptureUsageDescription and the screen-capture entitlement for macOS.
Description check	✅ Passed	Description covers purpose, root cause analysis, specific changes, and testing instructions. Some template sections (Type of Change, Checklist) are implicit but not formally checked off.
Linked Issues check	✅ Passed	All objectives from #548 are met: NSScreenCaptureUsageDescription added to Info.plist via electron-builder.json5, screen-capture entitlement added to macos.entitlements, silent failure resolved.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing #548. Only two config files modified with targeted additions; no unrelated refactoring or extraneous changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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 and usage tips.}