docs: document denying a display media request and fix a webview spec (#54587)

* docs: document how to deny a display media request

* test: make the webview printToPDF() bad parameter spec reach the type checks

The spec loaded another <webview id="webview"> on every pass of its loop, so
from the second pass on `webview` named a collection of elements and the call
was rejected with "webview.printToPDF is not a function". Only the first of
the ten parameters was checked. Load the webview once, and require the
rejection to name the parameter.

docs/api/desktop-capturer.md

@@ -17,10 +17,17 @@ app.whenReady().then(() => {
 
   session.defaultSession.setDisplayMediaRequestHandler(
     (request, callback) => {
-      desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
-        // Grant access to the first screen found.
-        callback({ video: sources[0], audio: 'loopback' })
-      })
+      desktopCapturer.getSources({ types: ['screen'] }).then(
+        (sources) => {
+          // Grant access to the first screen found.
+          callback({ video: sources[0], audio: 'loopback' })
+        },
+        () => {
+          // Deny the request if no sources could be retrieved, for example
+          // when the user cancels the PipeWire picker on Linux.
+          callback(null)
+        }
+      )
       // If true, use the system picker if available.
       // Note: this is currently experimental. If the system picker
       // is available, it will be used and the media request handler

docs/api/session.md

@@ -1215,7 +1215,8 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents,
     * `audioRequested` Boolean - true if the web content requested an audio stream.
     * `userGesture` Boolean - Whether a user gesture was active when this request was triggered.
   * `callback` Function
-    * `streams` Object
+    * `streams` Object | null - Pass `null` to deny the request, which rejects
+      the `getDisplayMedia()` promise with an `AbortError`.
       * `video` Object | [WebFrameMain](web-frame-main.md) (optional)
         * `id` String - The id of the stream being granted. This will usually
           come from a [DesktopCapturerSource](structures/desktop-capturer-source.md)
@@ -1249,10 +1250,17 @@ const { session, desktopCapturer } = require('electron')
 
 session.defaultSession.setDisplayMediaRequestHandler(
   (request, callback) => {
-    desktopCapturer.getSources({ types: ['screen'] }).then((sources) => {
-      // Grant access to the first screen found.
-      callback({ video: sources[0] })
-    })
+    desktopCapturer.getSources({ types: ['screen'] }).then(
+      (sources) => {
+        // Grant access to the first screen found.
+        callback({ video: sources[0] })
+      },
+      () => {
+        // Deny the request if no sources could be retrieved, for example
+        // when the user cancels the PipeWire picker on Linux.
+        callback(null)
+      }
+    )
     // Use the system picker if available.
     // Note: this is currently experimental. If the system picker
     // is available, it will be used and the media request handler

spec/webview.spec.ts

@@ -2474,13 +2474,14 @@ describe('<webview> tag', function () {
           preferCSSPageSize: 'no'
         };
 
+        await loadWebView(w, { src: 'data:text/html,%3Ch1%3EHello%2C%20World!%3C%2Fh1%3E' });
+
         // These will hard crash in Chromium unless we type-check
         for (const [key, value] of Object.entries(badTypes)) {
           const param = { [key]: value };
-
-          const src = 'data:text/html,%3Ch1%3EHello%2C%20World!%3C%2Fh1%3E';
-          await loadWebView(w, { src });
-          await expect(w.executeJavaScript(`webview.printToPDF(${JSON.stringify(param)})`)).to.eventually.be.rejected();
+          await expect(
+            w.executeJavaScript(`webview.printToPDF(${JSON.stringify(param)})`)
+          ).to.eventually.be.rejectedWith(key);
         }
       });