docs: add documentation

docs/api/desktop-capturer.md

@@ -16,6 +16,14 @@ app.whenReady().then(() => {
   const mainWindow = new BrowserWindow()
 
   session.defaultSession.setDisplayMediaRequestHandler((request, callback) => {
+    // If we should use the system picker
+    // Note: this is currently experimental
+    if (desktopCapturer.isDisplayMediaSystemPickerAvailable()) {
+      desktopCapturer.getNativePickerSource().then((source) => {
+        callback({ video: source })
+        return
+      })
+    }
     desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
       // Grant access to the first screen found.
       callback({ video: sources[0], audio: 'loopback' })
@@ -98,6 +106,22 @@ which can detected by [`systemPreferences.getMediaAccessStatus`][].
 [`navigator.mediaDevices.getUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia
 [`systemPreferences.getMediaAccessStatus`]: system-preferences.md#systempreferencesgetmediaaccessstatusmediatype-windows-macos
 
+### `desktopCapturer.isDisplayMediaSystemPickerAvailable()` _Experimental_ _MacOS_
+
+Returns `Boolean`, whether or not requesting desktop content via
+the system picker is supported on this platform.
+
+Currently this will only return `true` on macOS 14.4 and higher. When
+true, use the `getNativePickerSource` method to return the system picker's
+selected media stream. Not doing so may cause a warning dialog to your users
+on macOS 15 and higher.
+
+### `desktopCapturer.getNativePickerSource` _Experimental_ _Readonly_ _MacOS_
+
+A `DesktopCapturerSource` property that should be used in conjunction with
+[`session.setDisplayMediaRequestHandler`](./session.md#sessetdisplaymediarequesthandlerhandler) to use the system picker instead
+of providing a specific video source from `getSources`.
+
 ## Caveats
 
 `navigator.mediaDevices.getUserMedia` does not work on macOS for audio capture due to a fundamental limitation whereby apps that want to access the system's audio require a [signed kernel extension](https://developer.apple.com/library/archive/documentation/Security/Conceptual/System_Integrity_Protection_Guide/KernelExtensions/KernelExtensions.html). Chromium, and by extension Electron, does not provide this.