feat: Implement BrowserWindow.getMediaSourceId() and BrowserWindow.moveAbove(mediaSourceId) (#18926)

* feat: Implement BrowserWindow.moveAbove(mediaSourceId)

BrowserWindow.{focus,blur,moveTop}() are not enough in some
situations. For example when implementing an overlay that
follows another window that can lose focus. In that case
it is useful to move the overlay above the tracked window.

sourceId is a string in the format of DesktopCapturerSource.id,
for example "window:1869:0".

Notes: Added BrowserWindow.moveAbove(mediaSourceId)

https://github.com/electron/electron/issues/18922

* feat: Implement BrowserWindow.getMediaSourceId

Return the Window id in the format of DesktopCapturerSource's id.
For example "window🔢0".

https://github.com/electron/electron/issues/16460

Notes: Added BrowserWindow.getMediaSourceId

spec-main/api-browser-window-spec.ts

@@ -653,6 +653,48 @@ describe('BrowserWindow module', () => {
       })
     })
 
+    describe('BrowserWindow.moveAbove(mediaSourceId)', () => {
+      it('should throw an exception if wrong formatting', async () => {
+        const fakeSourceIds = [
+          'none', 'screen:0', 'window:fake', 'window:1234', 'foobar:1:2'
+        ]
+        fakeSourceIds.forEach((sourceId) => {
+          expect(() => {
+            w.moveAbove(sourceId)
+          }).to.throw(/Invalid media source id/)
+        })
+      })
+      it('should throw an exception if wrong type', async () => {
+        const fakeSourceIds = [null as any, 123 as any]
+        fakeSourceIds.forEach((sourceId) => {
+          expect(() => {
+            w.moveAbove(sourceId)
+          }).to.throw(/Error processing argument at index 0 */)
+        })
+      })
+      it('should throw an exception if invalid window', async () => {
+        // It is very unlikely that these window id exist.
+        const fakeSourceIds = ['window:99999999:0', 'window:123456:1',
+          'window:123456:9']
+        fakeSourceIds.forEach((sourceId) => {
+          expect(() => {
+            w.moveAbove(sourceId)
+          }).to.throw(/Invalid media source id/)
+        })
+      })
+      it('should not throw an exception', async () => {
+        const w2 = new BrowserWindow({ show: false, title: 'window2' })
+        const w2Shown = emittedOnce(w2, 'show')
+        w2.show()
+        await w2Shown
+
+        expect(() => {
+          w.moveAbove(w2.getMediaSourceId())
+        }).to.not.throw()
+
+        await closeWindow(w2, { assertNotWindows: false })
+      })
+    })
   })
 
   describe('sizing', () => {
@@ -3363,6 +3405,20 @@ describe('BrowserWindow module', () => {
     })
   })
 
+  describe('window.getMediaSourceId()', () => {
+    afterEach(closeAllWindows)
+    it('returns valid source id', async () => {
+      const w = new BrowserWindow({show: false})
+      const shown = emittedOnce(w, 'show')
+      w.show()
+      await shown
+
+      // Check format 'window:1234:0'.
+      const sourceId = w.getMediaSourceId()
+      expect(sourceId).to.match(/^window:\d+:\d+$/)
+    })
+  })
+
   ifdescribe(!process.env.ELECTRON_SKIP_NATIVE_MODULE_TESTS)('window.getNativeWindowHandle()', () => {
     afterEach(closeAllWindows)
     it('returns valid handle', () => {