perf(cua-driver): use on-screen-only SCShareableContent query for permission probe

[octo-patch]

Fixes #1371

Problem

Permissions.currentStatus() calls SCShareableContent.current to probe the Screen Recording TCC grant. This API enumerates all windows system-wide, including off-screen ones, and resolves the display name of each window's owner process. When a macOS system process (e.g. CursorUIViewService) has crashed and left thousands of zombie windows behind, the name-resolution loop can block for 6+ seconds on M1 hardware.

Solution

Replace SCShareableContent.current with SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true). This limits the query to on-screen windows only, skipping the heavyweight off-screen window enumeration that triggers the slowdown.

The lighter call still throws SCStreamError.userDeclined when the Screen Recording TCC grant is absent, so permission detection remains fully accurate — it just no longer stalls when a rogue system process is present.

Testing

• Verified the API throws when Screen Recording is denied and returns successfully when granted.
• The VideoRecorder and WindowCapture code paths that need full window lists continue to use SCShareableContent.current as-is — this change is scoped to the permission probe only.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced screen recording permission detection to reduce performance stalls when numerous windows are present.

[vercel]

Someone is attempting to deploy a commit to the Cua Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

The Screen Recording permission probe was optimized by replacing SCShareableContent.current with SCShareableContent.excludingDesktopWindows(_:onScreenWindowsOnly:) using onScreenWindowsOnly: true. Documentation updated to explain how limiting enumeration to on-screen windows prevents performance stalls caused by off-screen window enumeration.

Changes

Cohort / File(s)	Summary
Permission Probe Optimization libs/cua-driver/Sources/CuaDriverCore/Permissions/Permissions.swift	Replaced SCShareableContent.current with SCShareableContent.excludingDesktopWindows(_:onScreenWindowsOnly: true) to avoid performance stalls from off-screen window enumeration. Documentation updated to reflect this behavioral change.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 Hoppy hops through the window pane,
No off-screen clutter, no more pain!
Swift as a bunny, screens on sight,
Performance springs, the fix feels right! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: replacing SCShareableContent.current with an on-screen-only query for the permission probe.
Linked Issues check	✅ Passed	The PR fully addresses issue #1371 by replacing SCShareableContent.current with excludingDesktopWindows(false, onScreenWindowsOnly: true) to eliminate performance stalls from off-screen windows.
Out of Scope Changes check	✅ Passed	All changes are focused on the performance optimization objective. Code paths requiring full window enumeration (VideoRecorder and WindowCapture) remain unchanged as intended.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

libs/cua-driver/Sources/CuaDriverCore/Permissions/Permissions.swift (1)

25-31: Doc comment accurately reflects the new behavior.

The rationale for preferring the on-screen-only query over SCShareableContent.current (and still over CGPreflightScreenCaptureAccess()) is clearly captured. Note that WindowCapture.swift still carries a near-duplicate block of commentary about CGPreflightScreenCaptureAccess false negatives; if you want to keep the project's permission-probe rationale discoverable from a single place, consider cross-referencing this doc from WindowCapture.captureDisplay in a follow-up. Non-blocking.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@libs/cua-driver/Sources/CuaDriverCore/Permissions/Permissions.swift` around
lines 25 - 31, Add a brief cross-reference from WindowCapture.captureDisplay to
the Permissions.swift doc comment explaining the on-screen-only
SCShareableContent probe: update the documentation/comment block inside the
WindowCapture.captureDisplay implementation to mention and link (by file/section
name) to the Permissions.swift rationale about using
SCShareableContent.excludingDesktopWindows(_:onScreenWindowsOnly:) vs
CGPreflightScreenCaptureAccess(), so readers can find the single authoritative
explanation without duplicating long commentary.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@libs/cua-driver/Sources/CuaDriverCore/Permissions/Permissions.swift`:
- Around line 25-31: Add a brief cross-reference from
WindowCapture.captureDisplay to the Permissions.swift doc comment explaining the
on-screen-only SCShareableContent probe: update the documentation/comment block
inside the WindowCapture.captureDisplay implementation to mention and link (by
file/section name) to the Permissions.swift rationale about using
SCShareableContent.excludingDesktopWindows(_:onScreenWindowsOnly:) vs
CGPreflightScreenCaptureAccess(), so readers can find the single authoritative
explanation without duplicating long commentary.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bfc3ace9-30cc-4624-8214-8eb295ef9a7b

📥 Commits

Reviewing files that changed from the base of the PR and between 1a53f4b and 07d69ee.

📒 Files selected for processing (1)

• libs/cua-driver/Sources/CuaDriverCore/Permissions/Permissions.swift

[injaneity]

closed as deprecated by #2077