From bc8e748ec87152a1657d609a17ccf30baf883ba2 Mon Sep 17 00:00:00 2001
From: Shelley Vohr <shelley.vohr@gmail.com>
Date: Wed, 30 Sep 2026 14:32:56 +0200
Subject: [PATCH] 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 | 15 +++++++++++----
 docs/api/session.md          | 18 +++++++++++++-----
 spec/webview.spec.ts         |  9 +++++----
 3 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md
index 54dbeb1674..2e0ef601ff 100644
--- a/docs/api/desktop-capturer.md
+++ b/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
diff --git a/docs/api/session.md b/docs/api/session.md
index 9b282c7694..770e08500e 100644
--- a/docs/api/session.md
+++ b/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
diff --git a/spec/webview.spec.ts b/spec/webview.spec.ts
index c8bd29bd2e..3f34ad6309 100644
--- a/spec/webview.spec.ts
+++ b/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);
         }
       });