Editorial review: Add documentation for Screen Capture extensions, element capture and region capture

files/en-us/web/api/browsercapturemediastreamtrack/clone/index.md

@@ -29,9 +29,14 @@ A {{domxref("BrowserCaptureMediaStreamTrack")}} instance.
 ## Examples
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create crop target from DOM element
 const demoElem = document.querySelector("#demo");
-const cropTarget = await CropTarget.fromElement(demoArea);
+const cropTarget = await CropTarget.fromElement(demoElem);
 
 // Capture video stream from user's webcam and isolate video track
 const stream =

files/en-us/web/api/browsercapturemediastreamtrack/cropto/index.md

@@ -38,9 +38,14 @@ The promise will reject if:
 ### Basic cropping example
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create crop target from DOM element
 const demoElem = document.querySelector("#demo");
-const cropTarget = await CropTarget.fromElement(demoArea);
+const cropTarget = await CropTarget.fromElement(demoElem);
 
 // Capture video stream from user's webcam and isolate video track
 const stream =

files/en-us/web/api/browsercapturemediastreamtrack/restrictto/index.md

@@ -38,6 +38,11 @@ The promise will reject if:
 ### Basic restriction example
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create restriction target from DOM element
 const demoElem = document.querySelector("#demo");
 const restrictionTarget = await RestrictionTarget.fromElement(demoElem);

files/en-us/web/api/croptarget/fromelement_static/index.md

@@ -30,9 +30,14 @@ A {{jsxref("Promise")}} that resolves to a {{domxref("CropTarget")}} object inst
 ## Examples
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create crop target from DOM element
 const demoElem = document.querySelector("#demo");
-const cropTarget = await CropTarget.fromElement(demoArea);
+const cropTarget = await CropTarget.fromElement(demoElem);
 
 // Capture video stream from user's webcam and isolate video track
 const stream =

files/en-us/web/api/croptarget/index.md

@@ -21,9 +21,14 @@ The **`CropTarget`** interface of the {{domxref("Screen Capture extensions", "Sc
 ## Examples
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create crop target from DOM element
 const demoElem = document.querySelector("#demo");
-const cropTarget = await CropTarget.fromElement(demoArea);
+const cropTarget = await CropTarget.fromElement(demoElem);
 
 // Capture video stream from user's webcam and isolate video track
 const stream =

files/en-us/web/api/restrictiontarget/fromelement_static/index.md

@@ -43,6 +43,11 @@ The promise will reject if the restriction target element is not eligible for re
 ## Examples
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create restriction target from DOM element
 const demoElem = document.querySelector("#demo");
 const restrictionTarget = await RestrictionTarget.fromElement(demoElem);

files/en-us/web/api/restrictiontarget/index.md

@@ -21,6 +21,11 @@ The **`RestrictionTarget`** interface of the {{domxref("Screen Capture extension
 ## Examples
 
 ```js
+// Options for getDisplayMedia()
+const displayMediaOptions = {
+  preferCurrentTab: true,
+};
+
 // Create restriction target from DOM element
 const demoElem = document.querySelector("#demo");
 const restrictionTarget = await RestrictionTarget.fromElement(demoElem);

files/en-us/web/api/screen_capture_extensions/element_region_capture/index.md

@@ -173,14 +173,13 @@ To use the Element Capture API, we first grab a reference to a DOM element that
 const demoElem = document.querySelector("#demo");
 ```
 
-Next, in the options object passed into `getDisplayMedia()` when we invoke it, we set [`preferCurrentTab: true`](/en-US/docs/Web/API/MediaDevices/getDisplayMedia#prefercurrenttab). This instructs the browser to offer the user's current tab as the most prominent capture source in the dialog that asks them what to share. Chrome, for example, only gives them this option.
+Next, in the options object passed into `getDisplayMedia()` when we invoke it, we set [`preferCurrentTab: true`](/en-US/docs/Web/API/MediaDevices/getDisplayMedia#prefercurrenttab). This hint suggests that the browser should offer the user's current tab as the most prominent capture source in the dialog that asks them what to share. Chrome, for example, only gives them this option when `preferCurrentTab: true` is set.
 
 ```js
 const displayMediaOptions = {
   video: {
     displaySurface: "window",
   },
-  audio: false,
   preferCurrentTab: true,
 };
 ```
@@ -282,14 +281,21 @@ const demoElem = document.querySelector("#demo");
 Now let's examine the Region Capture demo's `startCapture()` function:
 
 ```js
+const displayMediaOptions = {
+  video: {
+    displaySurface: "window",
+  },
+  preferCurrentTab: true,
+};
+
 async function startCapture() {
   logElem.textContent = "";
 
   try {
     const stream =
       await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
     const [track] = stream.getVideoTracks();
-    const cropTarget = await CropTarget.fromElement(demoArea);
+    const cropTarget = await CropTarget.fromElement(demoElem);
     await track.cropTo(cropTarget);
 
     videoElem.srcObject = stream;
@@ -340,13 +346,15 @@ Apart from that, the restrictions on what elements can be cropped are as follows
 
 ## Element Capture versus Region Capture
 
-As explained above, the Element Capture captures the element itself, whereas Region Capture captures the area of the screen the element is rendered in. This means that Element Capture will always show just the captured element, even if other DOM content overlaps it, whereas Region Capture can result in overlapping content being shown over the top of the content you intended to share.
+As explained above, Element Capture captures the element itself, whereas Region Capture captures the area of the screen the element is rendered in. This means that Element Capture will always show just the captured element, even if other DOM content overlaps it, whereas Region Capture can result in overlapping content being shown over the top of the content you intended to share.
 
-This could be a major problem if that content is private, for example message notifications or speaker notes. If you can't guarantee that your app can keep private content from being shared, then you may lose trust in your users.
+There are legitimate use cases for both:
 
-As a result, it is generally recommended that you use the newer Element Capture API over the older Region Capture API, unless you need to support older browser versions that do not support Element Capture.
+- If you need to keep the capture specific to one element, and occlude anything outside it, then you should use the Element Capture API. For example, if you've got private content appearing such as a set of message notifications or a speaker notes UI, you won't want it showing up in the capture.
+- However, if you really do want to capture a region of the screen, regardless of what is shown in it, you should use the Region Capture API. The [Region Capture Demo](https://region-capture-demo.glitch.me/) shows a useful possibility — zooming in on a particular section of the screen as you show multiple users around on an interactive walkthrough of some kind.
 
 ## See also
 
 - [Screen Capture extensions](/en-US/docs/Web/API/Screen_Capture_extensions)
 - [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Element Capture Demo](https://element-capture-demo.glitch.me/)

files/en-us/web/api/screen_capture_extensions/index.md

@@ -44,6 +44,8 @@ See [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Scre
 
 For demos, see our [Screen Capture API demos](https://mdn.github.io/dom-examples/screen-capture-api) GitHub directory. See [Using the Element Capture and Region Capture APIs](/en-US/docs/Web/API/Screen_Capture_extensions/Element_Region_Capture) for code explanation.
 
+See also [Element Capture Demo](https://element-capture-demo.glitch.me/) and [Region Capture Demo](https://region-capture-demo.glitch.me/).
+
 ## Specifications
 
 {{Specifications}}