Bump v13.0.0-beta.28

* clearer heading rules

* docs: clarify documentation style guide rules

* Update docs/styleguide.md

Co-authored-by: Mark Lee <malept@users.noreply.github.com>

* fixes

Co-authored-by: Erick Zhao <erick@hotmail.ca>
Co-authored-by: Mark Lee <malept@users.noreply.github.com>

.circleci/config.yml

@@ -85,17 +85,17 @@ machine-linux-2xlarge: &machine-linux-2xlarge
 
 machine-mac: &machine-mac
   macos:
-    xcode: "12.2.0"
+    xcode: "12.4.0"
 
 machine-mac-large: &machine-mac-large
   resource_class: large
   macos:
-    xcode: "12.2.0"
+    xcode: "12.4.0"
 
 machine-mac-large-arm: &machine-mac-large-arm
   resource_class: large
   macos:
-    xcode: "12.2.0"
+    xcode: "12.4.0"
 
 machine-mac-arm64: &machine-mac-arm64
   resource_class: electronjs/macos-arm64
@@ -230,6 +230,18 @@ step-maybe-notify-slack-success: &step-maybe-notify-slack-success
       fi
     when: on_success
 
+step-maybe-cleanup-arm64-mac: &step-maybe-cleanup-arm64-mac
+  run:
+    name: Cleanup after testing
+    command: |
+      if  [ "$TARGET_ARCH" == "arm64" ] &&[ "`uname`" == "Darwin" ]; then
+        killall Electron || echo "No Electron processes left running"
+        killall Safari || echo "No Safari processes left running"
+        rm -rf ~/Library/Application\ Support/Electron*
+        rm -rf ~/Library/Application\ Support/electron*
+      fi
+    when: always
+
 step-checkout-electron: &step-checkout-electron
   checkout:
     path: src/electron
@@ -266,7 +278,7 @@ step-gclient-sync: &step-gclient-sync
           if ! git diff-index --quiet HEAD --; then
             # There are changes to the patches. Make a git commit with the updated patches
             git add patches
-            GIT_COMMITTER_NAME="Electron Bot" GIT_COMMITTER_EMAIL="electron@github.com" git commit -m "update patches" --author="Electron Bot <electron@github.com>"
+            GIT_COMMITTER_NAME="PatchUp" GIT_COMMITTER_EMAIL="73610968+patchup[bot]@users.noreply.github.com" git commit -m "chore: update patches" --author="PatchUp <73610968+patchup[bot]@users.noreply.github.com>"
             # Export it
             mkdir -p ../../patches
             git format-patch -1 --stdout --keep-subject --no-stat --full-index > ../../patches/update-patches.patch
@@ -313,9 +325,10 @@ step-setup-goma-for-build: &step-setup-goma-for-build
       npm install
       mkdir third_party
       node -e "require('./src/utils/goma.js').downloadAndPrepare({ gomaOneForAll: true })"
-      node -e "require('./src/utils/goma.js').ensure()"
+      third_party/goma/goma_ctl.py ensure_start
       echo 'export GN_GOMA_FILE='`node -e "console.log(require('./src/utils/goma.js').gnFilePath)"` >> $BASH_ENV
       echo 'export LOCAL_GOMA_DIR='`node -e "console.log(require('./src/utils/goma.js').dir)"` >> $BASH_ENV
+      echo 'export GOMA_FALLBACK_ON_AUTH_FAILURE=true' >> $BASH_ENV
       cd ..
 
 step-restore-brew-cache: &step-restore-brew-cache
@@ -517,7 +530,9 @@ step-electron-build: &step-electron-build
         ninja -C out/Default electron:electron_mksnapshot_zip -j $NUMBER_OF_NINJA_PROCESSES
         ninja -C out/Default tools/v8_context_snapshot -j $NUMBER_OF_NINJA_PROCESSES
         gn desc out/Default v8:run_mksnapshot_default args > out/Default/mksnapshot_args
+        rm -rf out/Default/clang_x64_v8_arm64/gen
         rm -rf out/Default/clang_x64_v8_arm64/obj
+        rm -rf out/Default/clang_x64/obj
 
         # Regenerate because we just deleted some ninja files 
         gn gen out/Default --args="import(\"$GN_CONFIG\") import(\"$GN_GOMA_FILE\") $GN_EXTRA_ARGS $GN_BUILDFLAG_ARGS"
@@ -840,7 +855,7 @@ step-maybe-zip-symbols: &step-maybe-zip-symbols
       export BUILD_PATH="$PWD/out/Default"
       ninja -C out/Default electron:licenses
       ninja -C out/Default electron:electron_version
-      electron/script/zip-symbols.py -b $BUILD_PATH
+      DELETE_DSYMS_AFTER_ZIP=1 electron/script/zip-symbols.py -b $BUILD_PATH
 
 step-symbols-store: &step-symbols-store
   store_artifacts:
@@ -1018,7 +1033,7 @@ step-minimize-workspace-size-from-checkout: &step-minimize-workspace-size-from-c
     name: Remove some unused data to avoid storing it in the workspace/cache
     command: |
       rm -rf src/android_webview
-      rm -rf src/ios
+      rm -rf src/ios/chrome
       rm -rf src/third_party/blink/web_tests
       rm -rf src/third_party/blink/perf_tests
       rm -rf src/third_party/WebKit/LayoutTests
@@ -1340,6 +1355,8 @@ steps-tests: &steps-tests
 
     - *step-maybe-notify-slack-failure
 
+    - *step-maybe-cleanup-arm64-mac
+
 steps-test-nan: &steps-test-nan
   steps:
     - attach_workspace:
@@ -2311,7 +2328,7 @@ jobs:
     <<: *steps-tests
 
   linux-x64-testing-asan-tests:
-    <<: *machine-linux-medium
+    <<: *machine-linux-xlarge
     environment:
       <<: *env-linux-medium
       <<: *env-headless-testing
@@ -2595,15 +2612,19 @@ workflows:
     - osx-publish-x64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
     - mas-publish-x64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
     - osx-publish-arm64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
     - mas-publish-arm64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
 
   lint:
     when: << pipeline.parameters.run-lint >>

.env.example

@@ -4,4 +4,3 @@
 APPVEYOR_CLOUD_TOKEN=
 CIRCLE_TOKEN=
 ELECTRON_GITHUB_TOKEN=
-VSTS_TOKEN=

.gitignore

@@ -68,4 +68,6 @@ ts-gen
 .depshash-target
 
 # Used to accelerate builds after sync
-patches/mtime-cache.json
+patches/mtime-cache.json
+
+spec/fixtures/logo.png

BUILD.gn

@@ -402,7 +402,10 @@ source_set("electron_lib") {
   }
 
   if (!is_mas_build) {
-    deps += [ "//components/crash/core/app" ]
+    deps += [
+      "//components/crash/core/app",
+      "//components/crash/core/browser",
+    ]
   }
 
   sources = filenames.lib_sources
@@ -440,6 +443,7 @@ source_set("electron_lib") {
   if (is_mac) {
     deps += [
       "//components/remote_cocoa/app_shim",
+      "//components/remote_cocoa/browser",
       "//content/common:mac_helpers",
       "//ui/accelerated_widget_mac",
     ]
@@ -619,6 +623,9 @@ source_set("electron_lib") {
       "//chrome/services/printing/public/mojom",
       "//components/printing/common:mojo_interfaces",
     ]
+    if (is_mac) {
+      deps += [ "//chrome/services/mac_notifications/public/mojom" ]
+    }
   }
 
   if (enable_electron_extensions) {
@@ -632,6 +639,7 @@ source_set("electron_lib") {
       "//components/zoom",
       "//extensions/browser",
       "//extensions/browser:core_api_provider",
+      "//extensions/browser/updater",
       "//extensions/common",
       "//extensions/common:core_api_provider",
       "//extensions/renderer",

DEPS

@@ -14,11 +14,11 @@ gclient_gn_args = [
 
 vars = {
   'chromium_version':
-    '1f252b391a40e2681b0d9aff6497b7401863d1fc',
+    '91.0.4472.38',
   'node_version':
     'v14.16.0',
   'nan_version':
-    '2c4ee8a32a299eada3cd6e468bbd0a473bfea96d',
+    'v2.14.2',
   'squirrel.mac_version':
     'cdc0729c8bf8576bfef18629186e1e9ecf1b0d9f',
 
@@ -48,6 +48,8 @@ vars = {
   # It's only needed to parse the native tests configurations.
   'checkout_pyyaml': False,
 
+  'use_rts': False,
+
   'mac_xcode_version': 'default',
 
   # To allow running hooks without parsing the DEPS tree

ELECTRON_VERSION

@@ -1 +1 @@
-13.0.0-nightly.20210303
+13.0.0-beta.28

README.md

@@ -5,7 +5,7 @@
 [![devDependency Status](https://david-dm.org/electron/electron/dev-status.svg)](https://david-dm.org/electron/electron?type=dev)
 [![Electron Discord Invite](https://img.shields.io/discord/745037351163527189?color=%237289DA&label=chat&logo=discord&logoColor=white)](https://discord.com/invite/electron)
 
-:memo: Available Translations: 🇨🇳 🇹🇼 🇧🇷 🇪🇸 🇰🇷 🇯🇵 🇷🇺 🇫🇷 🇹🇭 🇳🇱 🇹🇷 🇮🇩 🇺🇦 🇨🇿 🇮🇹 🇵🇱.
+:memo: Available Translations: 🇨🇳 🇧🇷 🇪🇸 🇯🇵 🇷🇺 🇫🇷 🇺🇸 🇩🇪.
 View these docs in other languages at [electron/i18n](https://github.com/electron/i18n/tree/master/content/).
 
 The Electron framework lets you write cross-platform desktop applications

appveyor.yml

@@ -36,6 +36,7 @@ environment:
   ELECTRON_ENABLE_STACK_DUMPING: 1
   MOCHA_REPORTER: mocha-multi-reporters
   MOCHA_MULTI_REPORTERS: mocha-appveyor-reporter, tap
+  GOMA_FALLBACK_ON_AUTH_FAILURE: true
 notifications:
   - provider: Webhook
     url: https://electron-mission-control.herokuapp.com/rest/appveyor-hook

build/args/all.gn

@@ -19,4 +19,12 @@ enable_basic_printing = true
 angle_enable_vulkan_validation_layers = false
 dawn_enable_vulkan_validation_layers = false
 
+# This breaks native node modules
+libcxx_abi_unstable = false
+
+# These are disabled because they cause the zip manifest to differ between
+# testing and release builds.
+# See https://chromium-review.googlesource.com/c/chromium/src/+/2774898.
+enable_pseudolocales = false
+
 is_cfi = false

build/mac/make_locale_dirs.py

@@ -8,6 +8,7 @@
 # require any direct Cocoa locale support.
 
 import os
+import errno
 import sys
 
 
@@ -16,7 +17,7 @@ def main(args):
     try:
       os.makedirs(dirname)
     except OSError as e:
-      if e.errno == os.errno.EEXIST:
+      if e.errno == errno.EEXIST:
         # It's OK if it already exists
         pass
       else:

build/npm-run.py

@@ -15,12 +15,6 @@ args = [cmd, "run",
 try:
     subprocess.check_output(args, stderr=subprocess.STDOUT)
 except subprocess.CalledProcessError as e:
-    print(
-        "NPM script '"
-        + sys.argv[2]
-        + "' failed with code '"
-        + str(e.returncode)
-        + "':\n"
-        + e.output
-    )
+    error_msg = "NPM script '{}' failed with code '{}':\n".format(sys.argv[2], e.returncode)
+    print(error_msg + e.output.decode('ascii'))
     sys.exit(e.returncode)

build/webpack/webpack.config.base.js

@@ -163,7 +163,7 @@ if ((globalThis.process || binding.process).argv.includes("--profile-electron-in
         setImmediate: false
       },
       optimization: {
-        minimize: true,
+        minimize: env.mode === 'production',
         minimizer: [
           new TerserPlugin({
             terserOptions: {

build/webpack/webpack.gni

@@ -22,6 +22,11 @@ template("webpack_build") {
                "//electron/typings/internal-electron.d.ts",
              ] + invoker.inputs
 
+    mode = "development"
+    if (is_official_build) {
+      mode = "production"
+    }
+
     args = [
       "--config",
       rebase_path(invoker.config_file),
@@ -29,6 +34,7 @@ template("webpack_build") {
       "--output-path=" + rebase_path(get_path_info(invoker.out_file, "dir")),
       "--env.buildflags=" +
           rebase_path("$target_gen_dir/buildflags/buildflags.h"),
+      "--env.mode=" + mode,
     ]
     deps += [ "buildflags" ]
 

build/zip.py

@@ -39,6 +39,7 @@ PATHS_TO_SKIP = [
   './crashpad_handler',
   # Skip because these are outputs that we don't need.
   'resources/inspector',
+  'gen/third_party/devtools-frontend/src'
 ]
 
 def skip_path(dep, dist_zip, target_cpu):

chromium_src/BUILD.gn

@@ -2,6 +2,7 @@
 # Use of this source code is governed by the MIT license that can be
 # found in the LICENSE file.
 
+import("//build/config/ozone.gni")
 import("//build/config/ui.gni")
 import("//components/spellcheck/spellcheck_build_features.gni")
 import("//electron/buildflags/buildflags.gni")
@@ -16,8 +17,6 @@ static_library("chrome") {
     "//chrome/browser/accessibility/accessibility_ui.h",
     "//chrome/browser/browser_process.cc",
     "//chrome/browser/browser_process.h",
-    "//chrome/browser/crash_upload_list/crash_upload_list_crashpad.cc",
-    "//chrome/browser/crash_upload_list/crash_upload_list_crashpad.h",
     "//chrome/browser/devtools/devtools_contents_resizing_strategy.cc",
     "//chrome/browser/devtools/devtools_contents_resizing_strategy.h",
     "//chrome/browser/devtools/devtools_embedder_message_dispatcher.cc",
@@ -46,7 +45,6 @@ static_library("chrome") {
     "//chrome/browser/predictors/resolve_host_client_impl.h",
     "//chrome/browser/ssl/security_state_tab_helper.cc",
     "//chrome/browser/ssl/security_state_tab_helper.h",
-    "//chrome/browser/ssl/tls_deprecation_config.cc",
     "//chrome/browser/ui/views/autofill/autofill_popup_view_utils.cc",
     "//chrome/browser/ui/views/autofill/autofill_popup_view_utils.h",
     "//extensions/browser/app_window/size_constraints.cc",
@@ -95,12 +93,18 @@ static_library("chrome") {
 
   if (is_linux) {
     sources += [ "//chrome/browser/icon_loader_auralinux.cc" ]
+    if (use_x11 || use_ozone) {
+      sources +=
+          [ "//chrome/browser/extensions/global_shortcut_listener_linux.cc" ]
+    }
     if (use_x11) {
       sources += [
         "//chrome/browser/extensions/global_shortcut_listener_x11.cc",
         "//chrome/browser/extensions/global_shortcut_listener_x11.h",
       ]
-    } else if (use_ozone) {
+    }
+    if (use_ozone) {
+      deps += [ "//ui/ozone" ]
       sources += [
         "//chrome/browser/extensions/global_shortcut_listener_ozone.cc",
         "//chrome/browser/extensions/global_shortcut_listener_ozone.h",
@@ -191,7 +195,7 @@ static_library("chrome") {
     }
 
     if (is_linux) {
-      sources += [ "//chrome/browser/media/webrtc/window_icon_util_x11.cc" ]
+      sources += [ "//chrome/browser/media/webrtc/window_icon_util_linux.cc" ]
     }
   }
 
@@ -253,8 +257,12 @@ static_library("chrome") {
       "//chrome/browser/picture_in_picture/picture_in_picture_window_manager.h",
       "//chrome/browser/ui/views/overlay/back_to_tab_image_button.cc",
       "//chrome/browser/ui/views/overlay/back_to_tab_image_button.h",
+      "//chrome/browser/ui/views/overlay/back_to_tab_label_button.cc",
       "//chrome/browser/ui/views/overlay/close_image_button.cc",
       "//chrome/browser/ui/views/overlay/close_image_button.h",
+      "//chrome/browser/ui/views/overlay/constants.h",
+      "//chrome/browser/ui/views/overlay/hang_up_button.cc",
+      "//chrome/browser/ui/views/overlay/hang_up_button.h",
       "//chrome/browser/ui/views/overlay/overlay_window_views.cc",
       "//chrome/browser/ui/views/overlay/overlay_window_views.h",
       "//chrome/browser/ui/views/overlay/playback_image_button.cc",
@@ -263,6 +271,10 @@ static_library("chrome") {
       "//chrome/browser/ui/views/overlay/resize_handle_button.h",
       "//chrome/browser/ui/views/overlay/skip_ad_label_button.cc",
       "//chrome/browser/ui/views/overlay/skip_ad_label_button.h",
+      "//chrome/browser/ui/views/overlay/toggle_camera_button.cc",
+      "//chrome/browser/ui/views/overlay/toggle_camera_button.h",
+      "//chrome/browser/ui/views/overlay/toggle_microphone_button.cc",
+      "//chrome/browser/ui/views/overlay/toggle_microphone_button.h",
       "//chrome/browser/ui/views/overlay/track_image_button.cc",
       "//chrome/browser/ui/views/overlay/track_image_button.h",
     ]

chromium_src/chrome/browser/certificate_manager_model.cc

@@ -90,7 +90,7 @@ CertificateManagerModel::~CertificateManagerModel() = default;
 int CertificateManagerModel::ImportFromPKCS12(
     PK11SlotInfo* slot_info,
     const std::string& data,
-    const base::string16& password,
+    const std::u16string& password,
     bool is_extractable,
     net::ScopedCERTCertificateList* imported_certs) {
   return cert_db_->ImportFromPKCS12(slot_info, data, password, is_extractable,

chromium_src/chrome/browser/certificate_manager_model.h

@@ -12,7 +12,6 @@
 #include "base/callback.h"
 #include "base/macros.h"
 #include "base/memory/ref_counted.h"
-#include "base/strings/string16.h"
 #include "net/cert/nss_cert_database.h"
 
 namespace content {
@@ -46,7 +45,7 @@ class CertificateManagerModel {
   // Returns a net error code on failure.
   int ImportFromPKCS12(PK11SlotInfo* slot_info,
                        const std::string& data,
-                       const base::string16& password,
+                       const std::u16string& password,
                        bool is_extractable,
                        net::ScopedCERTCertificateList* imported_certs);
 

default_app/default_app.ts

@@ -41,14 +41,14 @@ ipcMain.handle('bootstrap', (event) => {
   return isTrustedSender(event.sender) ? electronPath : null;
 });
 
-async function createWindow () {
+async function createWindow (backgroundColor?: string) {
   await app.whenReady();
 
   const options: Electron.BrowserWindowConstructorOptions = {
     width: 960,
     height: 620,
     autoHideMenuBar: true,
-    backgroundColor: '#2f3241',
+    backgroundColor,
     webPreferences: {
       preload: path.resolve(__dirname, 'preload.js'),
       contextIsolation: true,
@@ -96,7 +96,7 @@ export const loadURL = async (appUrl: string) => {
 };
 
 export const loadFile = async (appPath: string) => {
-  mainWindow = await createWindow();
+  mainWindow = await createWindow(appPath === 'index.html' ? '#2f3241' : undefined);
   mainWindow.loadFile(appPath);
   mainWindow.focus();
 };

docs/README.md

@@ -59,6 +59,7 @@ an issue:
   * [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
   * [Performance Strategies](tutorial/performance.md)
   * [Security Strategies](tutorial/security.md)
+  * [Process Sandboxing](tutorial/sandbox.md)
 * [Accessibility](tutorial/accessibility.md)
   * [Manually Enabling Accessibility Features](tutorial/accessibility.md#manually-enabling-accessibility-features)
 * [Testing and Debugging](tutorial/application-debugging.md)
@@ -68,6 +69,7 @@ an issue:
   * [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
   * [DevTools Extension](tutorial/devtools-extension.md)
   * [Automated Testing with a Custom Driver](tutorial/automated-testing-with-a-custom-driver.md)
+  * [REPL](tutorial/repl.md)
 * [Distribution](tutorial/application-distribution.md)
   * [Supported Platforms](tutorial/support.md#supported-platforms)
   * [Code Signing](tutorial/code-signing.md)
@@ -126,6 +128,8 @@ These individual tutorials expand on topics discussed in the guide above.
 * [ipcMain](api/ipc-main.md)
 * [Menu](api/menu.md)
 * [MenuItem](api/menu-item.md)
+* [MessageChannelMain](api/message-channel-main.md)
+* [MessagePortMain](api/message-port-main.md)
 * [net](api/net.md)
 * [netLog](api/net-log.md)
 * [nativeTheme](api/native-theme.md)
@@ -135,6 +139,7 @@ These individual tutorials expand on topics discussed in the guide above.
 * [protocol](api/protocol.md)
 * [screen](api/screen.md)
 * [session](api/session.md)
+* [ShareMenu](api/share-menu.md)
 * [systemPreferences](api/system-preferences.md)
 * [TouchBar](api/touch-bar.md)
 * [Tray](api/tray.md)
@@ -144,15 +149,14 @@ These individual tutorials expand on topics discussed in the guide above.
 ### Modules for the Renderer Process (Web Page):
 
 * [contextBridge](api/context-bridge.md)
-* [desktopCapturer](api/desktop-capturer.md)
 * [ipcRenderer](api/ipc-renderer.md)
-* [remote](api/remote.md)
 * [webFrame](api/web-frame.md)
 
 ### Modules for Both Processes:
 
 * [clipboard](api/clipboard.md)
 * [crashReporter](api/crash-reporter.md)
+* [desktopCapturer](api/desktop-capturer.md)
 * [nativeImage](api/native-image.md)
 * [shell](api/shell.md)
 

docs/api/accelerator.md

@@ -35,7 +35,7 @@ Linux and Windows to define some accelerators.
 Use `Alt` instead of `Option`. The `Option` key only exists on macOS, whereas
 the `Alt` key is available on all platforms.
 
-The `Super` key is mapped to the `Windows` key on Windows and Linux and
+The `Super` (or `Meta`) key is mapped to the `Windows` key on Windows and Linux and
 `Cmd` on macOS.
 
 ## Available modifiers
@@ -48,6 +48,7 @@ The `Super` key is mapped to the `Windows` key on Windows and Linux and
 * `AltGr`
 * `Shift`
 * `Super`
+* `Meta`
 
 ## Available key codes
 

docs/api/app.md

@@ -753,7 +753,8 @@ Overrides the current application's name.
 
 ### `app.getLocale()`
 
-Returns `String` - The current application locale. Possible return values are documented [here](locales.md).
+Returns `String` - The current application locale, fetched using Chromium's `l10n_util` library.
+Possible return values are documented [here](https://source.chromium.org/chromium/chromium/src/+/master:ui/base/l10n/l10n_util.cc).
 
 To set the locale, you'll want to use a command line switch at app startup, which may be found [here](https://github.com/electron/electron/blob/master/docs/api/command-line-switches.md).
 
@@ -929,6 +930,10 @@ re-add a removed item to a custom category earlier than that will result in the
 entire custom category being omitted from the Jump List. The list of removed
 items can be obtained using `app.getJumpListSettings()`.
 
+**Note:** The maximum length of a Jump List item's `description` property is
+260 characters. Beyond this limit, the item will not be added to the Jump
+List, nor will it be displayed.
+
 Here's a very simple example of creating a custom Jump List:
 
 ```javascript

docs/api/browser-view.md

@@ -1,14 +1,16 @@
-## Class: BrowserView
-
-> Create and control views.
-
-Process: [Main](../glossary.md#main-process)
+# BrowserView
 
 A `BrowserView` can be used to embed additional web content into a
 [`BrowserWindow`](browser-window.md). It is like a child window, except that it is positioned
 relative to its owning window. It is meant to be an alternative to the
 `webview` tag.
 
+## Class: BrowserView
+
+> Create and control views.
+
+Process: [Main](../glossary.md#main-process)
+
 ### Example
 
 ```javascript

docs/api/browser-window.md

@@ -238,7 +238,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     window shadow and window animations. Default is `true`.
   * `vibrancy` String (optional) - Add a type of vibrancy effect to the window, only on
     macOS. Can be `appearance-based`, `light`, `dark`, `titlebar`, `selection`,
-    `menu`, `popover`, `sidebar`, `medium-light`, `ultra-dark`, `header`, `sheet`, `window`, `hud`, `fullscreen-ui`, `tooltip`, `content`, `under-window`, or `under-page`.  Please note that using `frame: false` in combination with a vibrancy value requires that you use a non-default `titleBarStyle` as well. Also note that `appearance-based`, `light`, `dark`, `medium-light`, and `ultra-dark` are deprecated and have been removed in macOS Catalina (10.15).
+    `menu`, `popover`, `sidebar`, `medium-light`, `ultra-dark`, `header`, `sheet`, `window`, `hud`, `fullscreen-ui`, `tooltip`, `content`, `under-window`, or `under-page`. Please note that `appearance-based`, `light`, `dark`, `medium-light`, and `ultra-dark` are deprecated and have been removed in macOS Catalina (10.15).
   * `zoomToPageWidth` Boolean (optional) - Controls the behavior on macOS when
     option-clicking the green stoplight button on the toolbar or by clicking the
     Window > Zoom menu item. If `true`, the window will grow to the preferred
@@ -267,12 +267,12 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       be the absolute file path to the script.
       When node integration is turned off, the preload script can reintroduce
       Node global symbols back to the global scope. See example
-      [here](process.md#event-loaded).
+      [here](context-bridge.md#exposing-node-global-symbols).
     * `sandbox` Boolean (optional) - If set, this will sandbox the renderer
       associated with the window, making it compatible with the Chromium
       OS-level sandbox and disabling the Node.js engine. This is not the same as
       the `nodeIntegration` option and the APIs available to the preload script
-      are more limited. Read more about the option [here](sandbox-option.md).
+      are more limited. Read more about the option [here](../tutorial/sandbox.md).
     * `enableRemoteModule` Boolean (optional) - Whether to enable the [`remote`](remote.md) module.
       Default is `false`.
     * `session` [Session](session.md#class-session) (optional) - Sets the session used by the
@@ -1301,7 +1301,7 @@ can be be used to listen to changes to tablet mode.
 
 #### `win.getMediaSourceId()`
 
-Returns `String` - Window id in the format of DesktopCapturerSource's id. For example "window:1234:0".
+Returns `String` - Window id in the format of DesktopCapturerSource's id. For example "window:1324:0".
 
 More precisely the format is `window:id:other_id` where `id` is `HWND` on
 Windows, `CGWindowID` (`uint64_t`) on macOS and `Window` (`unsigned long`) on
@@ -1319,6 +1319,8 @@ The native type of the handle is `HWND` on Windows, `NSView*` on macOS, and
 
 * `message` Integer
 * `callback` Function
+  * `wParam` any - The `wParam` provided to the WndProc
+  * `lParam` any - The `lParam` provided to the WndProc
 
 Hooks a windows message. The `callback` is called when
 the message is received in the WndProc.
@@ -1371,7 +1373,7 @@ Returns `Boolean` - Whether the window's document has been edited.
 
 Returns `Promise<NativeImage>` - Resolves with a [NativeImage](native-image.md)
 
-Captures a snapshot of the page within `rect`. Omitting `rect` will capture the whole visible page.
+Captures a snapshot of the page within `rect`. Omitting `rect` will capture the whole visible page. If the page is not visible, `rect` may be empty.
 
 #### `win.loadURL(url[, options])`
 

docs/api/command-line-switches.md

@@ -80,6 +80,12 @@ This switch can not be used in `app.commandLine.appendSwitch` since it is parsed
 earlier than user's app is loaded, but you can set the `ELECTRON_ENABLE_LOGGING`
 environment variable to achieve the same effect.
 
+### --force-fieldtrials=`trials`
+
+Field trials to be forcefully enabled or disabled.
+
+For example: `WebRTC-Audio-Red-For-Opus/Enabled/`
+
 ### --host-rules=`rules`
 
 A comma-separated list of `rules` that control how hostnames are mapped.
@@ -136,7 +142,8 @@ proxy server flags that are passed.
 
 ### --no-sandbox
 
-Disables Chromium sandbox, which is now enabled by default.
+Disables the Chromium [sandbox](https://www.chromium.org/developers/design-documents/sandbox).
+Forces renderer process and Chromium helper processes to run un-sandboxed.
 Should only be used for testing.
 
 ### --proxy-bypass-list=`hosts`

docs/api/context-bridge.md

@@ -33,7 +33,7 @@ page you load in your renderer executes code in this world.
 
 ### Isolated World
 
-When `contextIsolation` is enabled in your `webPreferences`, your `preload` scripts run in an
+When `contextIsolation` is enabled in your `webPreferences` (this is the default behavior since Electron 12.0.0), your `preload` scripts run in an
 "Isolated World".  You can read more about context isolation and what it affects in the
 [security](../tutorial/security.md#3-enable-context-isolation-for-remote-content) docs.
 
@@ -110,3 +110,22 @@ has been included below for completeness:
 | `Symbol` | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped |
 
 If the type you care about is not in the above table, it is probably not supported.
+
+### Exposing Node Global Symbols
+
+The `contextBridge` can be used by the preload script to give your renderer access to Node APIs.
+The table of supported types described above also applies to Node APIs that you expose through `contextBridge`.
+Please note that many Node APIs grant access to local system resources.
+Be very cautious about which globals and APIs you expose to untrusted remote content.
+
+```javascript
+const { contextBridge } = require('electron')
+const crypto = require('crypto')
+contextBridge.exposeInMainWorld('nodeCrypto', {
+  sha256sum (data) {
+    const hash = crypto.createHash('sha256')
+    hash.update(data)
+    return hash.digest('hex')
+  }
+})
+```

docs/api/cookies.md

@@ -45,6 +45,8 @@ The following events are available on instances of `Cookies`:
 
 #### Event: 'changed'
 
+Returns:
+
 * `event` Event
 * `cookie` [Cookie](structures/cookie.md) - The cookie that was changed.
 * `cause` String - The cause of the change with one of the following values:

docs/api/crash-reporter.md

@@ -77,7 +77,8 @@ The `crashReporter` module has the following methods:
 ### `crashReporter.start(options)`
 
 * `options` Object
-  * `submitURL` String - URL that crash reports will be sent to as POST.
+  * `submitURL` String (optional) - URL that crash reports will be sent to as
+    POST. Required unless `uploadToServer` is `false`.
   * `productName` String (optional) - Defaults to `app.name`.
   * `companyName` String (optional) _Deprecated_ - Deprecated alias for
     `{ globalExtra: { _companyName: ... } }`.

docs/api/dialog.md

@@ -154,7 +154,7 @@ dialog.showOpenDialog(mainWindow, {
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)
 * `options` Object
-  * `title` String (optional)
+  * `title` String (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
   * `defaultPath` String (optional) - Absolute directory path, absolute file
     path, or file name to use by default.
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
@@ -185,7 +185,7 @@ The `filters` specifies an array of file types that can be displayed, see
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)
 * `options` Object
-  * `title` String (optional)
+  * `title` String (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
   * `defaultPath` String (optional) - Absolute directory path, absolute file
     path, or file name to use by default.
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when

docs/api/frameless-window.md

@@ -83,8 +83,10 @@ win.show()
   blur effect to the content below the window (i.e. other applications open on
   the user's system).
 * The window will not be transparent when DevTools is opened.
-* On Windows operating systems, transparent windows will not work when DWM is
+* On Windows operating systems,
+  * transparent windows will not work when DWM is
   disabled.
+  * transparent windows can not be maximized using the Windows system menu or by double clicking the title bar. The reasoning behind this can be seen on [this pull request](https://github.com/electron/electron/pull/28207).
 * On Linux, users have to put `--enable-transparent-visuals --disable-gpu` in
   the command line to disable GPU and allow ARGB to make transparent window,
   this is caused by an upstream bug that [alpha channel doesn't work on some

docs/api/locales.md

@@ -1,142 +0,0 @@
-# Locales
-
-> Locale values returned by `app.getLocale()`.
-
-Electron uses Chromium's `l10n_util` library to fetch the locale. Possible
-values are listed below:
-
-| Language Code | Language Name |
-|---------------|---------------|
-| af | Afrikaans |
-| am | Amharic |
-| ar | Arabic |
-| az | Azerbaijani |
-| be | Belarusian |
-| bg | Bulgarian |
-| bh | Bihari |
-| bn | Bengali |
-| br | Breton |
-| bs | Bosnian |
-| ca | Catalan |
-| co | Corsican |
-| cs | Czech |
-| cy | Welsh |
-| da | Danish |
-| de | German |
-| de-AT | German (Austria) |
-| de-CH | German (Switzerland) |
-| de-DE | German (Germany) |
-| el | Greek |
-| en | English |
-| en-AU | English (Australia) |
-| en-CA | English (Canada) |
-| en-GB | English (UK) |
-| en-NZ | English (New Zealand) |
-| en-US | English (US) |
-| en-ZA | English (South Africa) |
-| eo | Esperanto |
-| es | Spanish |
-| es-419 | Spanish (Latin America) |
-| et | Estonian |
-| eu | Basque |
-| fa | Persian |
-| fi | Finnish |
-| fil | Filipino |
-| fo | Faroese |
-| fr | French |
-| fr-CA | French (Canada) |
-| fr-CH | French (Switzerland) |
-| fr-FR | French (France) |
-| fy | Frisian |
-| ga | Irish |
-| gd | Scots Gaelic |
-| gl | Galician |
-| gn | Guarani |
-| gu | Gujarati |
-| ha | Hausa |
-| haw | Hawaiian |
-| he | Hebrew |
-| hi | Hindi |
-| hr | Croatian |
-| hu | Hungarian |
-| hy | Armenian |
-| ia | Interlingua |
-| id | Indonesian |
-| is | Icelandic |
-| it | Italian |
-| it-CH | Italian (Switzerland) |
-| it-IT | Italian (Italy) |
-| ja | Japanese |
-| jw | Javanese |
-| ka | Georgian |
-| kk | Kazakh |
-| km | Cambodian |
-| kn | Kannada |
-| ko | Korean |
-| ku | Kurdish |
-| ky | Kyrgyz |
-| la | Latin |
-| ln | Lingala |
-| lo | Laothian |
-| lt | Lithuanian |
-| lv | Latvian |
-| mk | Macedonian |
-| ml | Malayalam |
-| mn | Mongolian |
-| mo | Moldavian |
-| mr | Marathi |
-| ms | Malay |
-| mt | Maltese |
-| nb | Norwegian (Bokmal) |
-| ne | Nepali |
-| nl | Dutch |
-| nn | Norwegian (Nynorsk) |
-| no | Norwegian |
-| oc | Occitan |
-| om | Oromo |
-| or | Oriya |
-| pa | Punjabi |
-| pl | Polish |
-| ps | Pashto |
-| pt | Portuguese |
-| pt-BR | Portuguese (Brazil) |
-| pt-PT | Portuguese (Portugal) |
-| qu | Quechua |
-| rm | Romansh |
-| ro | Romanian |
-| ru | Russian |
-| sd | Sindhi |
-| sh | Serbo-Croatian |
-| si | Sinhalese |
-| sk | Slovak |
-| sl | Slovenian |
-| sn | Shona |
-| so | Somali |
-| sq | Albanian |
-| sr | Serbian |
-| st | Sesotho |
-| su | Sundanese |
-| sv | Swedish |
-| sw | Swahili |
-| ta | Tamil |
-| te | Telugu |
-| tg | Tajik |
-| th | Thai |
-| ti | Tigrinya |
-| tk | Turkmen |
-| to | Tonga |
-| tr | Turkish |
-| tt | Tatar |
-| tw | Twi |
-| ug | Uighur |
-| uk | Ukrainian |
-| ur | Urdu |
-| uz | Uzbek |
-| vi | Vietnamese |
-| xh | Xhosa |
-| yi | Yiddish |
-| yo | Yoruba |
-| zh | Chinese |
-| zh-CN | Chinese (Simplified) |
-| zh-TW | Chinese (Traditional) |
-| zu | Zulu |

docs/api/menu.md

@@ -1,3 +1,5 @@
+# Menu
+
 ## Class: Menu
 
 > Create native application menus and context menus.

docs/api/message-channel-main.md

@@ -9,12 +9,15 @@ channel messaging.
 
 ## Class: MessageChannelMain
 
+> Channel interface for channel messaging in the main process.
+
 Process: [Main](../glossary.md#main-process)
 
 Example:
 
 ```js
 // Main process
+const { MessageChannelMain } = require('electron')
 const { port1, port2 } = new MessageChannelMain()
 w.webContents.postMessage('port', null, [port2])
 port1.postMessage({ some: 'message' })

docs/api/message-port-main.md

@@ -14,6 +14,8 @@ channel messaging.
 
 ## Class: MessagePortMain
 
+> Port interface for channel messaging in the main process.
+
 Process: [Main](../glossary.md#main-process)
 
 ### Instance Methods

docs/api/process.md

@@ -30,11 +30,13 @@ In sandboxed renderers the `process` object contains only a subset of the APIs:
 * `arch`
 * `platform`
 * `sandboxed`
+* `contextIsolated`
 * `type`
 * `version`
 * `versions`
 * `mas`
 * `windowsStore`
+* `contextId`
 
 ## Events
 
@@ -43,19 +45,6 @@ In sandboxed renderers the `process` object contains only a subset of the APIs:
 Emitted when Electron has loaded its internal initialization script and is
 beginning to load the web page or the main script.
 
-It can be used by the preload script to add removed Node global symbols back to
-the global scope when node integration is turned off:
-
-```javascript
-// preload.js
-const _setImmediate = setImmediate
-const _clearImmediate = clearImmediate
-process.once('loaded', () => {
-  global.setImmediate = _setImmediate
-  global.clearImmediate = _clearImmediate
-})
-```
-
 ## Properties
 
 ### `process.defaultApp` _Readonly_
@@ -93,6 +82,11 @@ A `String` representing the path to the resources directory.
 A `Boolean`. When the renderer process is sandboxed, this property is `true`,
 otherwise it is `undefined`.
 
+### `process.contextIsolated` _Readonly_
+
+A `Boolean` that indicates whether the current renderer context has `contextIsolation` enabled.
+It is `undefined` in the main process.
+
 ### `process.throwDeprecation`
 
 A `Boolean` that controls whether or not deprecation warnings will be thrown as
@@ -133,6 +127,13 @@ A `String` representing Electron's version string.
 A `Boolean`. If the app is running as a Windows Store app (appx), this property is `true`,
 for otherwise it is `undefined`.
 
+### `process.contextId` _Readonly_
+
+A `String` (optional) representing a globally unique ID of the current JavaScript context.
+Each frame has its own JavaScript context. When contextIsolation is enabled, the isolated
+world also has a separate JavaScript context.
+This property is only available in the renderer process.
+
 ## Methods
 
 The `process` object has the following methods:

docs/api/sandbox-option.md

@@ -1,182 +0,0 @@
-# `sandbox` Option
-
-> Create a browser window with a sandboxed renderer. With this
-option enabled, the renderer must communicate via IPC to the main process in order to access node APIs.
-
-One of the key security features of Chromium is that all blink rendering/JavaScript
-code is executed within a sandbox. This sandbox uses OS-specific features to ensure
-that exploits in the renderer process cannot harm the system.
-
-In other words, when the sandbox is enabled, the renderers can only make changes
-to the system by delegating tasks to the main process via IPC.
-[Here's](https://www.chromium.org/developers/design-documents/sandbox) more
-information about the sandbox.
-
-Since a major feature in Electron is the ability to run Node.js in the
-renderer process (making it easier to develop desktop applications using web
-technologies), the sandbox is disabled by electron. This is because
-most Node.js APIs require system access. `require()` for example, is not
-possible without file system permissions, which are not available in a sandboxed
-environment.
-
-Usually this is not a problem for desktop applications since the code is always
-trusted, but it makes Electron less secure than Chromium for displaying
-untrusted web content. For applications that require more security, the
-`sandbox` flag will force Electron to spawn a classic Chromium renderer that is
-compatible with the sandbox.
-
-A sandboxed renderer doesn't have a Node.js environment running and doesn't
-expose Node.js JavaScript APIs to client code. The only exception is the preload script,
-which has access to a subset of the Electron renderer API.
-
-Another difference is that sandboxed renderers don't modify any of the default
-JavaScript APIs. Consequently, some APIs such as `window.open` will work as they
-do in Chromium (i.e. they do not return a [`BrowserWindowProxy`](browser-window-proxy.md)).
-
-## Example
-
-To create a sandboxed window, pass `sandbox: true` to `webPreferences`:
-
-```js
-let win
-app.whenReady().then(() => {
-  win = new BrowserWindow({
-    webPreferences: {
-      sandbox: true
-    }
-  })
-  win.loadURL('http://google.com')
-})
-```
-
-In the above code the [`BrowserWindow`](browser-window.md) that was created has Node.js disabled and can communicate
-only via IPC. The use of this option stops Electron from creating a Node.js runtime in the renderer. Also,
-within this new window `window.open` follows the native behavior (by default Electron creates a [`BrowserWindow`](browser-window.md)
-and returns a proxy to this via `window.open`).
-
-[`app.enableSandbox`](app.md#appenablesandbox) can be used to force `sandbox: true` for all `BrowserWindow` instances.
-
-```js
-let win
-app.enableSandbox()
-app.whenReady().then(() => {
-  // no need to pass `sandbox: true` since `app.enableSandbox()` was called.
-  win = new BrowserWindow()
-  win.loadURL('http://google.com')
-})
-```
-
-## Preload
-
-An app can make customizations to sandboxed renderers using a preload script.
-Here's an example:
-
-```js
-let win
-app.whenReady().then(() => {
-  win = new BrowserWindow({
-    webPreferences: {
-      sandbox: true,
-      preload: path.join(app.getAppPath(), 'preload.js')
-    }
-  })
-  win.loadURL('http://google.com')
-})
-```
-
-and preload.js:
-
-```js
-// This file is loaded whenever a javascript context is created. It runs in a
-// private scope that can access a subset of Electron renderer APIs. Without
-// contextIsolation enabled, it's possible to accidentally leak privileged
-// globals like ipcRenderer to web content.
-const { ipcRenderer } = require('electron')
-
-const defaultWindowOpen = window.open
-
-window.open = function customWindowOpen (url, ...args) {
-  ipcRenderer.send('report-window-open', location.origin, url, args)
-  return defaultWindowOpen(url + '?from_electron=1', ...args)
-}
-```
-
-Important things to notice in the preload script:
-
-- Even though the sandboxed renderer doesn't have Node.js running, it still has
-  access to a limited node-like environment: `Buffer`, `process`, `setImmediate`,
-  `clearImmediate` and `require` are available.
-- The preload script must be contained in a single script, but it is possible to have
-  complex preload code composed with multiple modules by using a tool like
-  webpack or browserify. An example of using browserify is below.
-
-To create a browserify bundle and use it as a preload script, something like
-the following should be used:
-
-```sh
-  browserify preload/index.js \
-    -x electron \
-    --insert-global-vars=__filename,__dirname -o preload.js
-```
-
-The `-x` flag should be used with any required module that is already exposed in
-the preload scope, and tells browserify to use the enclosing `require` function
-for it. `--insert-global-vars` will ensure that `process`, `Buffer` and
-`setImmediate` are also taken from the enclosing scope(normally browserify
-injects code for those).
-
-Currently the `require` function provided in the preload scope exposes the
-following modules:
-
-- `electron`
-  - `crashReporter`
-  - `desktopCapturer`
-  - `ipcRenderer`
-  - `nativeImage`
-  - `webFrame`
-- `events`
-- `timers`
-- `url`
-
-More may be added as needed to expose more Electron APIs in the sandbox.
-
-## Rendering untrusted content
-
-Rendering untrusted content in Electron is still somewhat uncharted territory,
-though some apps are finding success (e.g. Beaker Browser). Our goal is to get
-as close to Chrome as we can in terms of the security of sandboxed content, but
-ultimately we will always be behind due to a few fundamental issues:
-
-1. We do not have the dedicated resources or expertise that Chromium has to
-   apply to the security of its product. We do our best to make use of what we
-   have, to inherit everything we can from Chromium, and to respond quickly to
-   security issues, but Electron cannot be as secure as Chromium without the
-   resources that Chromium is able to dedicate.
-2. Some security features in Chrome (such as Safe Browsing and Certificate
-   Transparency) require a centralized authority and dedicated servers, both of
-   which run counter to the goals of the Electron project. As such, we disable
-   those features in Electron, at the cost of the associated security they
-   would otherwise bring.
-3. There is only one Chromium, whereas there are many thousands of apps built
-   on Electron, all of which behave slightly differently. Accounting for those
-   differences can yield a huge possibility space, and make it challenging to
-   ensure the security of the platform in unusual use cases.
-4. We can't push security updates to users directly, so we rely on app vendors
-   to upgrade the version of Electron underlying their app in order for
-   security updates to reach users.
-
-Here are some things to consider before rendering untrusted content:
-
-- A preload script can accidentally leak privileged APIs to untrusted code,
-  unless [`contextIsolation`](../tutorial/security.md#3-enable-context-isolation-for-remote-content)
-  is also enabled.
-- Some bug in the V8 engine may allow malicious code to access the renderer
-  preload APIs, effectively granting full access to the system through the
-  `remote` module. Therefore, it is highly recommended to [disable the `remote`
-  module](../tutorial/security.md#15-disable-the-remote-module).
-  If disabling is not feasible, you should selectively [filter the `remote`
-  module](../tutorial/security.md#16-filter-the-remote-module).
-- While we make our best effort to backport Chromium security fixes to older
-  versions of Electron, we do not make a guarantee that every fix will be
-  backported. Your best chance at staying secure is to be on the latest stable
-  version of Electron.

docs/api/session.md

@@ -822,6 +822,11 @@ Returns `Extension[]` - A list of all loaded extensions.
 **Note:** This API cannot be called before the `ready` event of the `app` module
 is emitted.
 
+#### `ses.getStoragePath()`
+
+A `String | null` indicating the absolute file system path where data for this
+session is persisted on disk.  For in memory sessions this returns `null`.
+
 ### Instance Properties
 
 The following properties are available on instances of `Session`:
@@ -835,6 +840,11 @@ code to the `setSpellCheckerLanguages` API that isn't in this array will result
 
 A `Boolean` indicating whether builtin spell checker is enabled.
 
+#### `ses.storagePath` _Readonly_
+
+A `String | null` indicating the absolute file system path where data for this
+session is persisted on disk.  For in memory sessions this returns `null`.
+
 #### `ses.cookies` _Readonly_
 
 A [`Cookies`](cookies.md) object for this session.

docs/api/share-menu.md

@@ -1,8 +1,4 @@
-## Class: ShareMenu
-
-> Create share menu on macOS.
-
-Process: [Main](../glossary.md#main-process)
+# ShareMenu
 
 The `ShareMenu` class creates [Share Menu][share-menu] on macOS, which can be
 used to share information from the current context to apps, social media
@@ -11,6 +7,12 @@ accounts, and other services.
 For including the share menu as a submenu of other menus, please use the
 `shareMenu` role of [`MenuItem`](menu-item.md).
 
+## Class: ShareMenu
+
+> Create share menu on macOS.
+
+Process: [Main](../glossary.md#main-process)
+
 ### `new ShareMenu(sharingItem)`
 
 * `sharingItem` SharingItem - The item to share.

docs/api/structures/jump-list-category.md

@@ -19,3 +19,7 @@
 property set then its `type` is assumed to be `tasks`. If the `name` property
 is set but the `type` property is omitted then the `type` is assumed to be
 `custom`.
+
+**Note:** The maximum length of a Jump List item's `description` property is
+260 characters. Beyond this limit, the item will not be added to the Jump
+List, nor will it be displayed.

docs/api/structures/jump-list-item.md

@@ -17,7 +17,7 @@
 * `title` String (optional) - The text to be displayed for the item in the Jump List.
   Should only be set if `type` is `task`.
 * `description` String (optional) - Description of the task (displayed in a tooltip).
-  Should only be set if `type` is `task`.
+  Should only be set if `type` is `task`. Maximum length 260 characters.
 * `iconPath` String (optional) - The absolute path to an icon to be displayed in a
   Jump List, which can be an arbitrary resource file that contains an icon
   (e.g. `.ico`, `.exe`, `.dll`). You can usually specify `process.execPath` to

docs/api/structures/upload-file.md

@@ -1,6 +1,6 @@
 # UploadFile Object
 
-* `type` String - `file`.
+* `type` 'file' - `file`.
 * `filePath` String - Path of file to be uploaded.
 * `offset` Integer - Defaults to `0`.
 * `length` Integer - Number of bytes to read from `offset`.

docs/api/structures/upload-raw-data.md

@@ -1,4 +1,4 @@
 # UploadRawData Object
 
-* `type` String - `rawData`.
+* `type` 'rawData' - `rawData`.
 * `bytes` Buffer - Data to be uploaded.

docs/api/system-preferences.md

@@ -130,6 +130,8 @@ This is necessary for events such as `NSUserDefaultsDidChangeNotification`.
   * `userInfo` Record<String, unknown>
   * `object` String
 
+Returns `Number` - The ID of this subscription
+
 Same as `subscribeNotification`, but uses `NSWorkspace.sharedWorkspace.notificationCenter`.
 This is necessary for events such as `NSWorkspaceDidActivateApplicationNotification`.
 

docs/api/touch-bar.md

@@ -1,3 +1,5 @@
+# TouchBar
+
 ## Class: TouchBar
 
 > Create TouchBar layouts for native macOS applications

docs/api/tray.md

@@ -1,3 +1,5 @@
+# Tray
+
 ## Class: Tray
 
 > Add icons and context menus to the system's notification area.

docs/api/web-contents.md

@@ -1184,6 +1184,7 @@ Ignore application menu shortcuts while this web contents is focused.
     * `url` String - The _resolved_ version of the URL passed to `window.open()`. e.g. opening a window with `window.open('foo')` will yield something like `https://the-origin/the/current/path/foo`.
     * `frameName` String - Name of the window provided in `window.open()`
     * `features` String - Comma separated list of window features provided to `window.open()`.
+
   Returns `{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}` - `deny` cancels the creation of the new
   window. `allow` will allow the new window to be created. Specifying `overrideBrowserWindowOptions` allows customization of the created window.
   Returning an unrecognized value such as a null, undefined, or an object
@@ -1320,8 +1321,7 @@ Inserts `text` to the focused element.
 * `text` String - Content to be searched, must not be empty.
 * `options` Object (optional)
   * `forward` Boolean (optional) - Whether to search forward or backward, defaults to `true`.
-  * `findNext` Boolean (optional) - Whether the operation is first request or a follow up,
-    defaults to `false`.
+  * `findNext` Boolean (optional) - Whether to begin a new text finding session with this request. Should be `true` for initial requests, and `false` for follow-up requests. Defaults to `false`.
   * `matchCase` Boolean (optional) - Whether search should be case-sensitive,
     defaults to `false`.
 
@@ -1363,19 +1363,21 @@ Captures a snapshot of the page within `rect`. Omitting `rect` will capture the
 Returns `Boolean` - Whether this page is being captured. It returns true when the capturer count
 is large then 0.
 
-#### `contents.incrementCapturerCount([size, stayHidden])`
+#### `contents.incrementCapturerCount([size, stayHidden, stayAwake])`
 
 * `size` [Size](structures/size.md) (optional) - The preferred size for the capturer.
 * `stayHidden` Boolean (optional) -  Keep the page hidden instead of visible.
+* `stayAwake` Boolean (optional) -  Keep the system awake instead of allowing it to sleep.
 
 Increase the capturer count by one. The page is considered visible when its browser window is
 hidden and the capturer count is non-zero. If you would like the page to stay hidden, you should ensure that `stayHidden` is set to true.
 
 This also affects the Page Visibility API.
 
-#### `contents.decrementCapturerCount([stayHidden])`
+#### `contents.decrementCapturerCount([stayHidden, stayAwake])`
 
 * `stayHidden` Boolean (optional) -  Keep the page in hidden state instead of visible.
+* `stayAwake` Boolean (optional) -  Keep the system awake instead of allowing it to sleep.
 
 Decrease the capturer count by one. The page will be set to hidden or occluded state when its
 browser window is hidden or occluded and the capturer count reaches zero. If you want to

docs/api/webview-tag.md

@@ -5,7 +5,7 @@
 Electron's `webview` tag is based on [Chromium's `webview`][chrome-webview], which
 is undergoing dramatic architectural changes. This impacts the stability of `webviews`,
 including rendering, navigation, and event routing. We currently recommend to not
-use the `webview` tag and to consider alternatives, like `iframe`, Electron's `BrowserView`,
+use the `webview` tag and to consider alternatives, like `iframe`, [Electron's `BrowserView`](browser-view.md),
 or an architecture that avoids embedded content altogether.
 
 ## Enabling
@@ -515,8 +515,7 @@ Inserts `text` to the focused element.
 * `text` String - Content to be searched, must not be empty.
 * `options` Object (optional)
   * `forward` Boolean (optional) - Whether to search forward or backward, defaults to `true`.
-  * `findNext` Boolean (optional) - Whether the operation is first request or a follow up,
-    defaults to `false`.
+  * `findNext` Boolean (optional) - Whether to begin a new text finding session with this request. Should be `true` for initial requests, and `false` for follow-up requests. Defaults to `false`.
   * `matchCase` Boolean (optional) - Whether search should be case-sensitive,
     defaults to `false`.
 

docs/api/window-open.md

@@ -83,9 +83,9 @@ const mainWindow = new BrowserWindow()
 
 mainWindow.webContents.setWindowOpenHandler(({ url }) => {
   if (url.startsWith('https://github.com/')) {
-    return true
+    return { action: 'allow' }
   }
-  return false
+  return { action: 'deny' }
 })
 
 mainWindow.webContents.on('did-create-window', (childWindow) => {

docs/breaking-changes.md

@@ -136,6 +136,22 @@ systemPreferences.isHighContrastColorScheme()
 nativeTheme.shouldUseHighContrastColors
 ```
 
+### Deprecated: WebContents `new-window` event
+
+The `new-window` event of WebContents has been deprecated. It is replaced by [`webContents.setWindowOpenHandler()`](api/web-contents.md#contentssetwindowopenhandlerhandler).
+
+```js
+// Deprecated in Electron 13
+webContents.on('new-window', (event) => {
+  event.preventDefault()
+})
+
+// Replace with
+webContents.setWindowOpenHandler((details) => {
+  return { action: 'deny' }
+})
+```
+
 ## Planned Breaking API Changes (12.0)
 
 ### Removed: Pepper Flash support
@@ -160,6 +176,9 @@ the previous behavior, `contextIsolation: false` must be specified in WebPrefere
 
 We [recommend having contextIsolation enabled](https://github.com/electron/electron/blob/master/docs/tutorial/security.md#3-enable-context-isolation-for-remote-content) for the security of your application.
 
+Another implication is that `require()` cannot be used in the renderer process unless
+`nodeIntegration` is `true` and `contextIsolation` is `false`.
+
 For more details see: https://github.com/electron/electron/issues/23506
 
 ### Removed: `crashReporter.getCrashesDirectory()`

docs/development/build-instructions-gn.md

@@ -1,6 +1,8 @@
 # Build Instructions
 
-Follow the guidelines below for building Electron.
+Follow the guidelines below for building **Electron itself**, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the [application distribution][application-distribution] guide.
+
+[application-distribution]: ../tutorial/application-distribution.md
 
 ## Platform prerequisites
 

docs/development/build-instructions-linux.md

@@ -1,6 +1,8 @@
 # Build Instructions (Linux)
 
-Follow the guidelines below for building Electron on Linux.
+Follow the guidelines below for building **Electron itself** on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the [application distribution][application-distribution] guide.
+
+[application-distribution]: ../tutorial/application-distribution.md
 
 ## Prerequisites
 

docs/development/build-instructions-macos.md

@@ -1,6 +1,8 @@
 # Build Instructions (macOS)
 
-Follow the guidelines below for building Electron on macOS.
+Follow the guidelines below for building **Electron itself** on macOS, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the [application distribution][application-distribution] guide.
+
+[application-distribution]: ../tutorial/application-distribution.md
 
 ## Prerequisites
 

docs/development/build-instructions-windows.md

@@ -1,6 +1,8 @@
 # Build Instructions (Windows)
 
-Follow the guidelines below for building Electron on Windows.
+Follow the guidelines below for building **Electron itself** on Windows, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the [application distribution][application-distribution] guide.
+
+[application-distribution]: ../tutorial/application-distribution.md
 
 ## Prerequisites
 

docs/development/issues.md

@@ -33,8 +33,7 @@ contributing, and more. Please use the issue tracker for bugs only!
 To submit a bug report:
 
 When opening a new issue in the [`electron/electron` issue tracker](https://github.com/electron/electron/issues/new/choose), users
-will be presented with [a template](https://github.com/electron/electron/blob/master/.github/ISSUE_TEMPLATE/Bug_report.md)
-that should be filled in.
+will be presented with a template that should be filled in.
 
 If you believe that you have found a bug in Electron, please fill out the template
 to the best of your ability.

docs/development/source-code-directory-structure.md

@@ -100,7 +100,5 @@ script/ - The set of all scripts Electron runs for a variety of purposes.
     └── uploaders/ - Uploads various release-related files during release.
 ```
 
-* **tools** - Helper scripts used by GN files.
-  * Scripts put here should never be invoked by users directly, unlike those in `script`.
 * **typings** - TypeScript typings for Electron's internal code.
 * **vendor** - Source code for some third party dependencies.

docs/fiddles/features/drag-and-drop/index.html

@@ -7,12 +7,9 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
-    <a href="#" id="drag">Drag me</a>
+    <p>Drag the boxes below to somewhere in your OS (Finder/Explorer, Desktop, etc.) to copy an example markdown file.</p>
+    <div style="border:2px solid black;border-radius:3px;padding:5px;display:inline-block" draggable="true" id="drag1">Drag me - File 1</div>
+    <div style="border:2px solid black;border-radius:3px;padding:5px;display:inline-block" draggable="true" id="drag2">Drag me - File 2</div>
     <script src="renderer.js"></script>
 </body>
 </html>

docs/fiddles/features/drag-and-drop/main.js

@@ -1,21 +1,28 @@
 const { app, BrowserWindow, ipcMain, nativeImage, NativeImage } = require('electron')
-const fs = require('fs');
-const http = require('http');
+const path = require('path')
+const fs = require('fs')
+const https = require('https')
 
-function createWindow () {
+function createWindow() {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
     webPreferences: {
-      nodeIntegration: true
+      preload: path.join(__dirname, 'preload.js')
     }
   })
 
   win.loadFile('index.html')
 }
-const iconName = 'iconForDragAndDrop.png';
-const icon = fs.createWriteStream(`${process.cwd()}/${iconName}`);
-http.get('http://img.icons8.com/ios/452/drag-and-drop.png', (response) => {
+
+const iconName = path.join(__dirname, 'iconForDragAndDrop.png');
+const icon = fs.createWriteStream(iconName);
+
+// Create a new file to copy - you can also copy existing files.
+fs.writeFileSync(path.join(__dirname, 'drag-and-drop-1.md'), '# First file to test drag and drop')
+fs.writeFileSync(path.join(__dirname, 'drag-and-drop-2.md'), '# Second file to test drag and drop')
+
+https.get('https://img.icons8.com/ios/452/drag-and-drop.png', (response) => {
   response.pipe(icon);
 });
 
@@ -23,8 +30,8 @@ app.whenReady().then(createWindow)
 
 ipcMain.on('ondragstart', (event, filePath) => {
   event.sender.startDrag({
-    file: filePath,
-    icon: `${process.cwd()}/${iconName}`
+    file: path.join(__dirname, filePath),
+    icon: iconName,
   })
 })
 

docs/fiddles/features/drag-and-drop/preload.js

@@ -0,0 +1,8 @@
+const { contextBridge, ipcRenderer } = require('electron')
+const path = require('path')
+
+contextBridge.exposeInMainWorld('electron', {
+  startDrag: (fileName) => {
+    ipcRenderer.send('ondragstart', fileName)
+  }
+})

docs/fiddles/features/drag-and-drop/renderer.js

@@ -1,9 +1,9 @@
-const { ipcRenderer } = require('electron')
-const fs = require('fs')
-
-document.getElementById('drag').ondragstart = (event) => {
-  const fileName = 'drag-and-drop.md'
-  fs.writeFileSync(fileName, '# Test drag and drop');
+document.getElementById('drag1').ondragstart = (event) => {
   event.preventDefault()
-  ipcRenderer.send('ondragstart', process.cwd() + `/${fileName}`)
+  window.electron.startDrag('drag-and-drop-1.md')
+}
+
+document.getElementById('drag2').ondragstart = (event) => {
+  event.preventDefault()
+  window.electron.startDrag('drag-and-drop-2.md')
 }

docs/fiddles/features/macos-dark-mode/main.js

@@ -1,11 +1,12 @@
 const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')
+const path = require('path')
 
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
     webPreferences: {
-      nodeIntegration: true
+      preload: path.join(__dirname, 'preload.js')
     }
   })
 
@@ -25,16 +26,18 @@ function createWindow () {
   })
 }
 
-app.whenReady().then(createWindow)
+app.whenReady().then(() => {
+  createWindow()
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow()
+    }
+  })
+})
 
 app.on('window-all-closed', () => {
   if (process.platform !== 'darwin') {
     app.quit()
   }
 })
-
-app.on('activate', () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})

docs/fiddles/features/macos-dark-mode/preload.js

@@ -0,0 +1,6 @@
+const { contextBridge, ipcRenderer } = require('electron')
+
+contextBridge.exposeInMainWorld('darkMode', {
+  toggle: () => ipcRenderer.invoke('dark-mode:toggle'),
+  system: () => ipcRenderer.invoke('dark-mode:system')
+})

docs/fiddles/features/macos-dark-mode/renderer.js

@@ -1,11 +1,9 @@
-const { ipcRenderer } = require('electron')
-
 document.getElementById('toggle-dark-mode').addEventListener('click', async () => {
-  const isDarkMode = await ipcRenderer.invoke('dark-mode:toggle')
+  const isDarkMode = await window.darkMode.toggle()
   document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'
 })
 
 document.getElementById('reset-to-system').addEventListener('click', async () => {
-  await ipcRenderer.invoke('dark-mode:system')
+  await window.darkMode.system()
   document.getElementById('theme-source').innerHTML = 'System'
 })

docs/fiddles/features/macos-dock-menu/index.html

@@ -7,10 +7,6 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
+    <p>Right click the dock icon to see the custom menu options.</p>
 </body>
 </html>

docs/fiddles/features/macos-dock-menu/main.js

@@ -4,9 +4,6 @@ function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
   })
 
   win.loadFile('index.html')
@@ -27,7 +24,9 @@ const dockMenu = Menu.buildFromTemplate([
 ])
 
 app.whenReady().then(() => {
-  app.dock.setMenu(dockMenu)
+  if (process.platform === 'darwin') {
+    app.dock.setMenu(dockMenu)
+  }
 }).then(createWindow)
 
 app.on('window-all-closed', () => {

docs/fiddles/quick-start/index.html

@@ -8,9 +8,9 @@
 <body>
     <h1>Hello World!</h1>
     <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
+        We are using Node.js <span id="node-version"></span>,
+        Chromium <span id="chrome-version"></span>,
+        and Electron <span id="electron-version"></span>.
     </p>
 </body>
 </html>

docs/fiddles/quick-start/main.js

@@ -1,18 +1,27 @@
 const { app, BrowserWindow } = require('electron')
+const path = require('path')
 
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
     webPreferences: {
-      nodeIntegration: true
+      preload: path.join(__dirname, 'preload.js')
     }
   })
 
   win.loadFile('index.html')
 }
 
-app.whenReady().then(createWindow)
+app.whenReady().then(() => {
+  createWindow()
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow()
+    }
+  })
+})
 
 app.on('window-all-closed', () => {
   if (process.platform !== 'darwin') {
@@ -20,8 +29,3 @@ app.on('window-all-closed', () => {
   }
 })
 
-app.on('activate', () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})

docs/fiddles/quick-start/preload.js

@@ -0,0 +1,11 @@
+window.addEventListener('DOMContentLoaded', () => {
+  const replaceText = (selector, text) => {
+    const element = document.getElementById(selector)
+    if (element) element.innerText = text
+  }
+
+  for (const type of ['chrome', 'node', 'electron']) {
+    replaceText(`${type}-version`, process.versions[type])
+  }
+})
+

docs/styleguide.md

@@ -2,15 +2,14 @@
 
 These are the guidelines for writing Electron documentation.
 
-## Titles
+## Headings
 
 * Each page must have a single `#`-level title at the top.
-* Chapters in the same page must have `##`-level titles.
-* Sub-chapters need to increase the number of `#` in the title according to
+* Chapters in the same page must have `##`-level headings.
+* Sub-chapters need to increase the number of `#` in the heading according to
   their nesting depth.
-* All words in the page's title must be capitalized, except for conjunctions
-  like "of" and "and" .
-* Only the first word of a chapter title must be capitalized.
+* The page's title must follow [APA title case][title-case].
+* All chapters must follow [APA sentence case][sentence-case].
 
 Using `Quick Start` as example:
 
@@ -44,12 +43,20 @@ For API references, there are exceptions to this rule.
 
 ## Markdown rules
 
+This repository uses the [`markdownlint`][markdownlint] package to enforce consistent
+Markdown styling. For the exact rules, see the `.markdownlint.json` file in the root
+folder.
+
+There are a few style guidelines that aren't covered by the linter rules:
+
+<!--TODO(erickzhao): make sure this matches with the lint:markdownlint task-->
 * Use `sh` instead of `cmd` in code blocks (due to the syntax highlighter).
-* Lines should be wrapped at 80 columns.
+* Keep line lengths between 80 and 100 characters if possible for readability
+  purposes.
 * No nesting lists more than 2 levels (due to the markdown renderer).
 * All `js` and `javascript` code blocks are linted with
 [standard-markdown](https://www.npmjs.com/package/standard-markdown).
-* For unordered lists, use asterisks instead of dashes
+* For unordered lists, use asterisks instead of dashes.
 
 ## Picking words
 
@@ -60,14 +67,15 @@ For API references, there are exceptions to this rule.
 
 The following rules only apply to the documentation of APIs.
 
-### Page title
+### Title and description
 
-Each page must use the actual object name returned by `require('electron')`
-as the title, such as `BrowserWindow`, `autoUpdater`, and `session`.
+Each module's API doc must use the actual object name returned by `require('electron')`
+as its title (such as `BrowserWindow`, `autoUpdater`, and `session`).
 
-Under the page title must be a one-line description starting with `>`.
+Directly under the page title, add a one-line description of the module
+as a markdown quote (beginning with `>`).
 
-Using `session` as example:
+Using the `session` module as an example:
 
 ```markdown
 # session
@@ -99,14 +107,19 @@ Using `autoUpdater` as an example:
 * API classes or classes that are part of modules must be listed under a
   `## Class: TheClassName` chapter.
 * One page can have multiple classes.
-* Constructors must be listed with `###`-level titles.
-* [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static) must be listed under a `### Static Methods` chapter.
-* [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods) must be listed under an `### Instance Methods` chapter.
-* All methods that have a return value must start their description with "Returns `[TYPE]` - Return description"
-  * If the method returns an `Object`, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.
+* Constructors must be listed with `###`-level headings.
+* [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static)
+  must be listed under a `### Static Methods` chapter.
+* [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods)
+  must be listed under an `### Instance Methods` chapter.
+* All methods that have a return value must start their description with
+  "Returns `[TYPE]` - [Return description]"
+  * If the method returns an `Object`, its structure can be specified using a colon
+    followed by a newline then an unordered list of properties in the same style as
+    function parameters.
 * Instance Events must be listed under an `### Instance Events` chapter.
 * Instance Properties must be listed under an `### Instance Properties` chapter.
-  * Instance properties must start with "A [Property Type] ..."
+  * Instance Properties must start with "A [Property Type] ..."
 
 Using the `Session` and `Cookies` classes as an example:
 
@@ -142,7 +155,7 @@ Using the `Session` and `Cookies` classes as an example:
 #### `cookies.get(filter, callback)`
 ```
 
-### Methods
+### Methods and their arguments
 
 The methods chapter must be in the following form:
 
@@ -155,8 +168,12 @@ The methods chapter must be in the following form:
 ...
 ```
 
-The title can be `###` or `####`-levels depending on whether it is a method of
-a module or a class.
+#### Heading level
+
+The heading can be `###` or `####`-levels depending on whether the method
+belongs to a module or a class.
+
+#### Function signature
 
 For modules, the `objectName` is the module's name. For classes, it must be the
 name of the instance of the class, and must not be the same as the module's
@@ -165,23 +182,33 @@ name.
 For example, the methods of the `Session` class under the `session` module must
 use `ses` as the `objectName`.
 
-The optional arguments are notated by square brackets `[]` surrounding the optional argument
-as well as the comma required if this optional argument follows another
+Optional arguments are notated by square brackets `[]` surrounding the optional
+argument as well as the comma required if this optional argument follows another
 argument:
 
-```sh
+```markdown
 required[, optional]
 ```
 
-Below the method is more detailed information on each of the arguments. The type
-of argument is notated by either the common types:
+#### Argument descriptions
 
-* [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
-* [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)
-* [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
-* [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
-* [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
-* Or a custom type like Electron's [`WebContent`](api/web-contents.md)
+More detailed information on each of the arguments is noted in an unordered list
+below the method. The type of argument is notated by either JavaScript primitives
+(e.g. `String`, `Promise`, or `Object`), a custom API structure like Electron's
+[`Cookie`](api/structures/cookie.md), or the wildcard `any`.
+
+If the argument is of type `Array`, use `[]` shorthand with the type of value
+inside the array (for example,`any[]` or `String[]`).
+
+If the argument is of type `Promise`, parametrize the type with what the promise
+resolves to (for example, `Promise<void>` or `Promise<String>`).
+
+If an argument can be of multiple types, separate the types with `|`.
+
+The description for `Function` type arguments should make it clear how it may be
+called and list the types of the parameters that will be passed to it.
+
+#### Platform-specific functionality
 
 If an argument or a method is unique to certain platforms, those platforms are
 denoted using a space-delimited italicized list following the datatype. Values
@@ -191,12 +218,6 @@ can be `macOS`, `Windows` or `Linux`.
 * `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.
 ```
 
-`Array` type arguments must specify what elements the array may include in
-the description below.
-
-The description for `Function` type arguments should make it clear how it may be
-called and list the types of the parameters that will be passed to it.
-
 ### Events
 
 The events chapter must be in following form:
@@ -211,8 +232,8 @@ Returns:
 ...
 ```
 
-The title can be `###` or `####`-levels depending on whether it is an event of
-a module or a class.
+The heading can be `###` or `####`-levels depending on whether the event
+belongs to a module or a class.
 
 The arguments of an event follow the same rules as methods.
 
@@ -226,9 +247,13 @@ The properties chapter must be in following form:
 ...
 ```
 
-The title can be `###` or `####`-levels depending on whether it is a property of
-a module or a class.
+The heading can be `###` or `####`-levels depending on whether the property
+belongs to a module or a class.
 
-## Documentation Translations
+## Documentation translations
 
 See [electron/i18n](https://github.com/electron/i18n#readme)
+
+[title-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case
+[sentence-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case
+[markdownlint]: https://github.com/DavidAnson/markdownlint

docs/tutorial/dark-mode.md

@@ -47,18 +47,18 @@ of this theming, due to the use of the macOS 10.14 SDK.
 
 ## Example
 
-We'll start with a working application from the
-[Quick Start Guide](quick-start.md) and add functionality gradually.
+This example demonstrates an Electron application that derives its theme colors from the
+`nativeTheme`. Additionally, it provides theme toggle and reset controls using IPC channels.
 
-First, let's edit our interface so users can toggle between light and dark
-modes.  This basic UI contains buttons to change the `nativeTheme.themeSource`
-setting and a text element indicating which `themeSource` value is selected.
-By default, Electron follows the system's dark mode preference, so we
-will hardcode the theme source as "System".
+```javascript fiddle='docs/fiddles/features/macos-dark-mode'
 
-Add the following lines to the `index.html` file:
+```
 
-```html
+### How does this work?
+
+Starting with the `index.html` file:
+
+```html title='index.html'
 <!DOCTYPE html>
 <html>
 <head>
@@ -80,65 +80,70 @@ Add the following lines to the `index.html` file:
 </html>
 ```
 
-Next, add [event listeners](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
-that listen for `click` events on the toggle buttons. Because the `nativeTheme`
-module only exposed in the Main process, you need to set up each listener's
-callback to use IPC to send messages to and handle responses from the Main
-process:
+And the `style.css` file:
 
-* when the "Toggle Dark Mode" button is clicked, we send the
-`dark-mode:toggle` message (event) to tell the Main process to trigger a theme
-change, and update the "Current Theme Source" label in the UI based on the
-response from the Main process.
-* when the "Reset to System Theme" button is clicked, we send the
-`dark-mode:system` message (event) to tell the Main process to use the system
-color scheme, and update the "Current Theme Source" label to `System`.
+```css title='style.css'
+@media (prefers-color-scheme: dark) {
+  body { background: #333; color: white; }
+}
 
-To add listeners and handlers, add the following lines to the `renderer.js` file:
+@media (prefers-color-scheme: light) {
+  body { background: #ddd; color: black; }
+}
+```
 
-```javascript
-const { ipcRenderer } = require('electron')
+The example renders an HTML page with a couple elements. The `<strong id="theme-source">`
+ element shows which theme is currently selected, and the two `<button>` elements are the
+ controls. The CSS file uses the [`prefers-color-scheme`][prefers-color-scheme] media query
+ to set the `<body>` element background and text colors.
 
+The `preload.js` script adds a new API to the `window` object called `darkMode`. This API
+ exposes two IPC channels to the renderer process, `'dark-mode:toggle'` and `'dark-mode:system'`.
+ It also assigns two methods, `toggle` and `system`, which pass messages from the renderer to the
+ main process.
+
+```js title='preload.js'
+const { contextBridge, ipcRenderer } = require('electron')
+
+contextBridge.exposeInMainWorld('darkMode', {
+  toggle: () => ipcRenderer.invoke('dark-mode:toggle'),
+  system: () => ipcRenderer.invoke('dark-mode:system')
+})
+```
+
+Now the renderer process can communicate with the main process securely and perform the necessary
+ mutations to the `nativeTheme` object.
+
+The `renderer.js` file is responsible for controlling the `<button>` functionality.
+
+```js title='renderer.js'
 document.getElementById('toggle-dark-mode').addEventListener('click', async () => {
-  const isDarkMode = await ipcRenderer.invoke('dark-mode:toggle')
+  const isDarkMode = await window.darkMode.toggle()
   document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'
 })
 
 document.getElementById('reset-to-system').addEventListener('click', async () => {
-  await ipcRenderer.invoke('dark-mode:system')
+  await window.darkMode.system()
   document.getElementById('theme-source').innerHTML = 'System'
 })
 ```
 
-If you run your code at this point, you'll see that your buttons don't do
-anything just yet, and your Main process will output an error like this when
-you click on your buttons:
-`Error occurred in handler for 'dark-mode:toggle': No handler registered for 'dark-mode:toggle'`
-This is expected — we haven't actually touched any `nativeTheme` code yet.
+Using `addEventListener`, the `renderer.js` file adds `'click'` [event listeners][event-listeners]
+ to each button element. Each event listener handler makes calls to the respective `window.darkMode`
+ API methods.
 
-Now that we're done wiring the IPC from the Renderer's side, the next step
-is to update the `main.js` file to handle events from the Renderer process.
+Finally, the `main.js` file represents the main process and contains the actual `nativeTheme` API.
 
-Depending on the received event, we update the
-[`nativeTheme.themeSource`](../api/native-theme.md#nativethemethemesource)
-property to apply the desired theme on the system's native UI elements
-(e.g. context menus) and propagate the preferred color scheme to the Renderer
-process:
-
-* Upon receiving `dark-mode:toggle`, we check if the dark theme is currently
-active using the `nativeTheme.shouldUseDarkColors` property, and set the
-`themeSource` to the opposite theme.
-* Upon receiving `dark-mode:system`, we reset the `themeSource` to `system`.
-
-```javascript
+```js
 const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')
+const path = require('path')
 
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
     webPreferences: {
-      nodeIntegration: true
+      preload: path.join(__dirname, 'preload.js')
     }
   })
 
@@ -154,44 +159,41 @@ function createWindow () {
   })
 
   ipcMain.handle('dark-mode:system', () => {
-    nativeTheme.themeSource = 'system'
+    nativeTheme.themeSouce = 'system'
   })
 }
 
-app.whenReady().then(createWindow)
+app.whenReady().then(() => {
+  createWindow()
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow()
+    }
+  })
+})
 
 app.on('window-all-closed', () => {
   if (process.platform !== 'darwin') {
     app.quit()
   }
 })
-
-app.on('activate', () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})
 ```
 
-The final step is to add a bit of styling to enable dark mode for the web parts
-of the UI by leveraging the [`prefers-color-scheme`][prefer-color-scheme] CSS
-attribute. The value of `prefers-color-scheme` will follow your
-`nativeTheme.themeSource` setting.
+The `ipcMain.handle` methods are how the main process responds to the click events from the buttons
+ on the HTML page.
 
-Create a `styles.css` file and add the following lines:
+The `'dark-mode:toggle'` IPC channel handler method checks the `shouldUseDarkColors` boolean property,
+ sets the corresponding `themeSource`, and then returns the current `shouldUseDarkColors` property.
+ Looking back on the renderer process event listener for this IPC channel, the return value from this
+ handler is utilized to assign the correct text to the `<strong id='theme-source'>` element.
 
-```css fiddle='docs/fiddles/features/macos-dark-mode'
-@media (prefers-color-scheme: dark) {
-  body { background:  #333; color: white; }
-}
+The `'dark-mode:system'` IPC channel handler method assigns the string `'system'` to the `themeSource`
+ and returns nothing. This also corresponds with the relative renderer process event listener as the
+ method is awaited with no return value expected.
 
-@media (prefers-color-scheme: light) {
-  body { background:  #ddd; color: black; }
-}
-```
-
-After launching the Electron application, you can change modes or reset the
-theme to system default by clicking corresponding buttons:
+Run the example using Electron Fiddle and then click the "Toggle Dark Mode" button; the app should
+ start alternating between a light and dark background color.
 
 ![Dark Mode](../images/dark_mode.gif)
 
@@ -199,4 +201,5 @@ theme to system default by clicking corresponding buttons:
 [electron-forge]: https://www.electronforge.io/
 [electron-packager]: https://github.com/electron/electron-packager
 [packager-darwindarkmode-api]: https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#darwindarkmodesupport
-[prefer-color-scheme]: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
+[prefers-color-scheme]: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
+[event-listeners]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

docs/tutorial/installation.md

@@ -11,14 +11,19 @@ npm install electron --save-dev
 See the [Electron versioning doc][versioning] for info on how to
 manage Electron versions in your apps.
 
-## Global Installation
+## Running Electron ad-hoc
 
-You can also install the `electron` command globally in your `$PATH`:
+If you're in a pinch and would prefer to not use `npm install` in your local
+project, you can also run Electron ad-hoc using the [`npx`][npx] command runner
+bundled with `npm`:
 
 ```sh
-npm install electron -g
+npx electron .
 ```
 
+The above command will run the current working directory with Electron. Note that
+any dependencies in your app will not be installed.
+
 ## Customization
 
 If you want to change the architecture that is downloaded (e.g., `ia32` on an
@@ -178,6 +183,7 @@ If you need to force a re-download of the asset and the SHASUM file set the
 
 [npm]: https://docs.npmjs.com
 [versioning]: ./electron-versioning.md
+[npx]: https://docs.npmjs.com/cli/v7/commands/npx
 [releases]: https://github.com/electron/electron/releases
 [proxy-env-10]: https://github.com/gajus/global-agent/blob/v2.1.5/README.md#environment-variables
 [proxy-env]: https://github.com/np-maintain/global-tunnel/blob/v2.7.1/README.md#auto-config

docs/tutorial/mac-app-store-submission-guide.md

@@ -1,53 +1,111 @@
 # Mac App Store Submission Guide
 
-Since v0.34.0, Electron allows submitting packaged apps to the Mac App Store
-(MAS). This guide provides information on: how to submit your app and the
-limitations of the MAS build.
+This guide provides information on:
 
-**Note:** Submitting an app to Mac App Store requires enrolling in the [Apple Developer
-Program][developer-program], which costs money.
+* How to sign Electron apps on macOS;
+* How to submit Electron apps to Mac App Store (MAS);
+* The limitations of the MAS build.
 
-## How to Submit Your App
+## Requirements
 
-The following steps introduce a simple way to submit your app to Mac App Store.
-However, these steps do not ensure your app will be approved by Apple; you
-still need to read Apple's [Submitting Your App][submitting-your-app] guide on
-how to meet the Mac App Store requirements.
+To sign Electron apps, the following tools must be installed first:
 
-### Get Certificate
+* Xcode 11 or above.
+* The [electron-osx-sign][electron-osx-sign] npm module.
 
-To submit your app to the Mac App Store, you first must get a certificate from
-Apple. You can follow these [existing guides][nwjs-guide] on web.
+You also have to register an Apple Developer account and join the
+[Apple Developer Program][developer-program].
 
-### Get Team ID
+## Sign Electron apps
 
-Before signing your app, you need to know the Team ID of your account. To locate
-your Team ID, Sign in to [Apple Developer Center](https://developer.apple.com/account/),
-and click Membership in the sidebar. Your Team ID appears in the Membership
-Information section under the team name.
+Electron apps can be distributed through Mac App Store or outside it. Each way
+requires different ways of signing and testing. This guide focuses on
+distribution via Mac App Store, but will also mention other methods.
 
-### Sign Your App
+The following steps describe how to get the certificates from Apple, how to sign
+Electron apps, and how to test them.
 
-After finishing the preparation work, you can package your app by following
-[Application Distribution](application-distribution.md), and then proceed to
-signing your app.
+### Get certificates
 
-First, you have to add a `ElectronTeamID` key to your app's `Info.plist`, which
-has your Team ID as its value:
+The simplest way to get signing certificates is to use Xcode:
 
-```xml
-<plist version="1.0">
-<dict>
-  ...
-  <key>ElectronTeamID</key>
-  <string>TEAM_ID</string>
-</dict>
-</plist>
-```
+1. Open Xcode and open "Accounts" preferences;
+2. Sign in with your Apple account;
+3. Select a team and click "Manage Certificates";
+4. In the lower-left corner of the signing certificates sheet, click the Add
+   button (+), and add following certificates:
+   * "Apple Development"
+   * "Apple Distribution"
 
-Then, you need to prepare three entitlements files.
+The "Apple Development" certificate is used to sign apps for development and
+testing, on machines that have been registered on Apple Developer website. The
+method of registration will be described in
+[Prepare provisioning profile](#prepare-provisioning-profile).
 
-`child.plist`:
+Apps signed with the "Apple Development" certificate cannot be submitted to Mac
+App Store. For that purpose, apps must be signed with the "Apple Distribution"
+certificate instead. But note that apps signed with the "Apple Distribution"
+certificate cannot run directly, they must be re-signed by Apple to be able to
+run, which will only be possible after being downloaded from the Mac App Store.
+
+#### Other certificates
+
+You may notice that there are also other kinds of certificates.
+
+The "Developer ID Application" certificate is used to sign apps before
+distributing them outside the Mac App Store.
+
+The "Developer ID Installer" and "Mac Installer Distribution" certificates are
+used to sign the Mac Installer Package instead of the app itself. Most Electron
+apps do not use Mac Installer Package so they are generally not needed.
+
+The full list of certificate types can be found
+[here](https://help.apple.com/xcode/mac/current/#/dev80c6204ec).
+
+Apps signed with "Apple Development" and "Apple Distribution" certificates can
+only run under [App Sandbox][app-sandboxing], so they must use the MAS build of
+Electron. However, the "Developer ID Application" certificate does not have this
+restrictions, so apps signed with it can use either the normal build or the MAS
+build of Electron.
+
+#### Legacy certificate names
+
+Apple has been changing the names of certificates during past years, you might
+encounter them when reading old documentations, and some utilities are still
+using one of the old names.
+
+* The "Apple Distribution" certificate was also named as "3rd Party Mac
+  Developer Application" and "Mac App Distribution".
+* The "Apple Development" certificate was also named as "Mac Developer" and
+  "Development".
+
+### Prepare provisioning profile
+
+If you want to test your app on your local machine before submitting your app to
+the Mac App Store, you have to sign the app with the "Apple Development"
+certificate with the provisioning profile embedded in the app bundle.
+
+To [create a provisioning profile](https://help.apple.com/developer-account/#/devf2eb157f8),
+you can follow the below steps:
+
+1. Open the "Certificates, Identifiers & Profiles" page on the
+   [Apple Developer](https://developer.apple.com/account) website.
+2. Add a new App ID for your app in the "Identifiers" page.
+3. Register your local machine in the "Devices" page. You can find your
+   machine's "Device ID" in the "Hardware" page of the "System Information" app.
+4. Register a new Provisioning Profile in the "Profiles" page, and download it
+   to `/path/to/yourapp.provisionprofile`.
+
+### Enable Apple's App Sandbox
+
+Apps submitted to the Mac App Store must run under Apple's
+[App Sandbox][app-sandboxing], and only the MAS build of Electron can run with
+the App Sandbox. The standard darwin build of Electron will fail to launch
+when run under App Sandbox.
+
+When signing the app with `electron-osx-sign`, it will automatically add the
+necessary entitlements to your app's entitlements, but if you are using custom
+entitlements, you must ensure App Sandbox capacity is added:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -56,13 +114,14 @@ Then, you need to prepare three entitlements files.
   <dict>
     <key>com.apple.security.app-sandbox</key>
     <true/>
-    <key>com.apple.security.inherit</key>
-    <true/>
   </dict>
 </plist>
 ```
 
-`parent.plist`:
+#### Extra steps without `electron-osx-sign`
+
+If you are signing your app without using `electron-osx-sign`, you must ensure
+the app bundle's entitlements have at least following keys:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -79,7 +138,11 @@ Then, you need to prepare three entitlements files.
 </plist>
 ```
 
-`loginhelper.plist`:
+The `TEAM_ID` should be replaced with your Apple Developer account's Team ID,
+and the `your.bundle.id` should be replaced with the App ID of the app.
+
+And the following entitlements must be added to the binaries and helpers in
+the app's bundle:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -88,80 +151,97 @@ Then, you need to prepare three entitlements files.
   <dict>
     <key>com.apple.security.app-sandbox</key>
     <true/>
+    <key>com.apple.security.inherit</key>
+    <true/>
   </dict>
 </plist>
 ```
 
-You have to replace `TEAM_ID` with your Team ID, and replace `your.bundle.id`
-with the Bundle ID of your app.
+And the app bundle's `Info.plist` must include `ElectronTeamID` key, which has
+your Apple Developer account's Team ID as its value:
 
-And then sign your app with the following script:
-
-```sh
-#!/bin/bash
-
-# Name of your app.
-APP="YourApp"
-# The path of your app to sign.
-APP_PATH="/path/to/YourApp.app"
-# The path to the location you want to put the signed package.
-RESULT_PATH="~/Desktop/$APP.pkg"
-# The name of certificates you requested.
-APP_KEY="3rd Party Mac Developer Application: Company Name (APPIDENTITY)"
-INSTALLER_KEY="3rd Party Mac Developer Installer: Company Name (APPIDENTITY)"
-# The path of your plist files.
-CHILD_PLIST="/path/to/child.plist"
-PARENT_PLIST="/path/to/parent.plist"
-LOGINHELPER_PLIST="/path/to/loginhelper.plist"
-
-FRAMEWORKS_PATH="$APP_PATH/Contents/Frameworks"
-
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework/Versions/A/Electron Framework"
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework/Versions/A/Libraries/libffmpeg.dylib"
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework/Versions/A/Libraries/libnode.dylib"
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/Electron Framework.framework"
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/$APP Helper.app/Contents/MacOS/$APP Helper"
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$FRAMEWORKS_PATH/$APP Helper.app/"
-codesign -s "$APP_KEY" -f --entitlements "$LOGINHELPER_PLIST" "$APP_PATH/Contents/Library/LoginItems/$APP Login Helper.app/Contents/MacOS/$APP Login Helper"
-codesign -s "$APP_KEY" -f --entitlements "$LOGINHELPER_PLIST" "$APP_PATH/Contents/Library/LoginItems/$APP Login Helper.app/"
-codesign -s "$APP_KEY" -f --entitlements "$CHILD_PLIST" "$APP_PATH/Contents/MacOS/$APP"
-codesign -s "$APP_KEY" -f --entitlements "$PARENT_PLIST" "$APP_PATH"
-
-productbuild --component "$APP_PATH" /Applications --sign "$INSTALLER_KEY" "$RESULT_PATH"
+```xml
+<plist version="1.0">
+<dict>
+  ...
+  <key>ElectronTeamID</key>
+  <string>TEAM_ID</string>
+</dict>
+</plist>
 ```
 
-If you are new to app sandboxing under macOS, you should also read through
-Apple's [Enabling App Sandbox][enable-app-sandbox] to have a basic idea, then
-add keys for the permissions needed by your app to the entitlements files.
+When using `electron-osx-sign` the `ElectronTeamID` key will be added
+automatically by extracting the Team ID from the certificate's name. You may
+need to manually add this key if `electron-osx-sign` could not find the correct
+Team ID.
 
-Apart from manually signing your app, you can also choose to use the
-[electron-osx-sign][electron-osx-sign] module to do the job.
+### Sign apps for development
 
-#### Sign Native Modules
+To sign an app that can run on your development machine, you must sign it with
+the "Apple Development" certificate and pass the provisioning profile to
+`electron-osx-sign`.
 
-Native modules used in your app also need to be signed. If using
-electron-osx-sign, be sure to include the path to the built binaries in the
-argument list:
-
-```sh
-electron-osx-sign YourApp.app YourApp.app/Contents/Resources/app/node_modules/nativemodule/build/release/nativemodule
+```bash
+electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile
 ```
 
-Also note that native modules may have intermediate files produced which should
-not be included (as they would also need to be signed). If you use
-[electron-packager][electron-packager] before version 8.1.0, add
-`--ignore=.+\.o$` to your build step to ignore these files. Versions 8.1.0 and
-later ignore those files by default.
+If you are signing without `electron-osx-sign`, you must place the provisioning
+profile to `YourApp.app/Contents/embedded.provisionprofile`.
 
-### Upload Your App
+The signed app can only run on the machines that registered by the provisioning
+profile, and this is the only way to test the signed app before submitting to
+Mac App Store.
 
-After signing your app, you can use Application Loader to upload it to iTunes
+### Sign apps for submitting to the Mac App Store
+
+To sign an app that will be submitted to Mac App Store, you must sign it with
+the "Apple Distribution" certificate. Note that apps signed with this
+certificate will not run anywhere, unless it is downloaded from Mac App Store.
+
+```bash
+electron-osx-sign YourApp.app --identity='Apple Distribution'
+```
+
+### Sign apps for distribution outside the Mac App Store
+
+If you don't plan to submit the app to Mac App Store, you can sign it the
+"Developer ID Application" certificate. In this way there is no requirement on
+App Sandbox, and you should use the normal darwin build of Electron if you don't
+use App Sandbox.
+
+```bash
+electron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess
+```
+
+By passing `--no-gatekeeper-assess`, the `electron-osx-sign` will skip the macOS
+GateKeeper check as your app usually has not been notarized yet by this step.
+
+<!-- TODO(zcbenz): Add a chapter about App Notarization -->
+This guide does not cover [App Notarization][app-notarization], but you might
+want to do it otherwise Apple may prevent users from using your app outside Mac
+App Store.
+
+## Submit Apps to the Mac App Store
+
+After signing the app with the "Apple Distribution" certificate, you can
+continue to submit it to Mac App Store.
+
+However, this guide do not ensure your app will be approved by Apple; you
+still need to read Apple's [Submitting Your App][submitting-your-app] guide on
+how to meet the Mac App Store requirements.
+
+### Upload
+
+The Application Loader should be used to upload the signed app to iTunes
 Connect for processing, making sure you have [created a record][create-record]
 before uploading.
 
-### Submit Your App for Review
+If you are seeing errors like private APIs uses, you should check if the app is
+using the MAS build of Electron.
 
-After these steps, you can [submit your app for review][submit-for-review].
+### Submit for review
+
+After uploading, you should [submit your app for review][submit-for-review].
 
 ## Limitations of MAS Build
 
@@ -181,13 +261,13 @@ Also, due to the usage of app sandboxing, the resources which can be accessed by
 the app are strictly limited; you can read [App Sandboxing][app-sandboxing] for
 more information.
 
-### Additional Entitlements
+### Additional entitlements
 
 Depending on which Electron APIs your app uses, you may need to add additional
-entitlements to your `parent.plist` file to be able to use these APIs from your
-app's Mac App Store build.
+entitlements to your app's entitlements file. Otherwise, the App Sandbox may
+prevent you from using them.
 
-#### Network Access
+#### Network access
 
 Enable outgoing network connections to allow your app to connect to a server:
 
@@ -261,15 +341,12 @@ Electron uses following cryptographic algorithms:
 * RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004)
 
 [developer-program]: https://developer.apple.com/support/compare-memberships/
-[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html
-[nwjs-guide]: https://github.com/nwjs/nw.js/wiki/Mac-App-Store-%28MAS%29-Submission-Guideline#first-steps
-[enable-app-sandbox]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html
-[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html
-[electron-osx-sign]: https://github.com/electron-userland/electron-osx-sign
-[electron-packager]: https://github.com/electron/electron-packager
-[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html
+[electron-osx-sign]: https://github.com/electron/electron-osx-sign
 [app-sandboxing]: https://developer.apple.com/app-sandboxing/
+[app-notarization]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution
+[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html
+[create-record]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/CreatingiTunesConnectRecord.html
+[submit-for-review]: https://developer.apple.com/library/ios/documentation/LanguagesUtilities/Conceptual/iTunesConnect_Guide/Chapters/SubmittingTheApp.html
 [export-compliance]: https://help.apple.com/app-store-connect/#/devc3f64248f
-[temporary-exception]: https://developer.apple.com/library/mac/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/AppSandboxTemporaryExceptionEntitlements.html
 [user-selected]: https://developer.apple.com/library/mac/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW6
 [network-access]: https://developer.apple.com/library/ios/documentation/Miscellaneous/Reference/EntitlementKeyReference/Chapters/EnablingAppSandbox.html#//apple_ref/doc/uid/TP40011195-CH4-SW9

docs/tutorial/macos-dock.md

@@ -1,6 +1,4 @@
-# macOS Dock
-
-## Overview
+# Configuring the macOS Dock
 
 Electron has APIs to configure the app's icon in the macOS Dock. A macOS-only
 API exists to create a custom dock menu, but Electron also uses the app dock
@@ -25,7 +23,16 @@ Starting with a working application from the
  following lines:
 
 ```javascript fiddle='docs/fiddles/features/macos-dock-menu'
-const { app, Menu } = require('electron')
+const { app, BrowserWindow, Menu } = require('electron')
+
+function createWindow () {
+  const win = new BrowserWindow({
+    width: 800,
+    height: 600,
+  })
+
+  win.loadFile('index.html')
+}
 
 const dockMenu = Menu.buildFromTemplate([
   {
@@ -42,8 +49,23 @@ const dockMenu = Menu.buildFromTemplate([
 ])
 
 app.whenReady().then(() => {
-  app.dock.setMenu(dockMenu)
+  if (process.platform === 'darwin') {
+    app.dock.setMenu(dockMenu)
+  }
+}).then(createWindow)
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit()
+  }
 })
+
+app.on('activate', () => {
+  if (BrowserWindow.getAllWindows().length === 0) {
+    createWindow()
+  }
+})
+
 ```
 
 After launching the Electron application, right click the application icon.

docs/tutorial/native-file-drag-drop.md

@@ -14,30 +14,46 @@ API in response to the `ondragstart` event.
 
 ## Example
 
-Starting with a working application from the
-[Quick Start Guide](quick-start.md), add the following lines to the
-`index.html` file:
+An example demonstrating how you can create a file on the fly to be dragged out of the window.
+
+### Preload.js
+
+In `preload.js` use the [`contextBridge`] to inject a method `window.electron.startDrag(...)` that will send an IPC message to the main process.
+
+```js
+const { contextBridge, ipcRenderer } = require('electron')
+const path = require('path')
+
+contextBridge.exposeInMainWorld('electron', {
+  startDrag: (fileName) => {
+    ipcRenderer.send('ondragstart', path.join(process.cwd(), fileName))
+  }
+})
+```
+
+### Index.html
+
+Add a draggable element to `index.html`, and reference your renderer script:
 
 ```html
-<a href="#" id="drag">Drag me</a>
+<div style="border:2px solid black;border-radius:3px;padding:5px;display:inline-block" draggable="true" id="drag">Drag me</div>
 <script src="renderer.js"></script>
 ```
 
-and add the following lines to the `renderer.js` file:
+### Renderer.js
+
+In `renderer.js` set up the renderer process to handle drag events by calling the method you added via the [`contextBridge`] above.
 
 ```javascript
-const { ipcRenderer } = require('electron')
-
 document.getElementById('drag').ondragstart = (event) => {
   event.preventDefault()
-  ipcRenderer.send('ondragstart', '/absolute/path/to/the/item')
+  window.electron.startDrag('drag-and-drop.md')
 }
 ```
 
-The code above instructs the Renderer process to handle the `ondragstart` event
-and forward the information to the Main process.
+### Main.js
 
-In the Main process(`main.js` file), expand the received event with a path to the file that is
+In the Main process (`main.js` file), expand the received event with a path to the file that is
 being dragged and an icon:
 
 ```javascript fiddle='docs/fiddles/features/drag-and-drop'
@@ -56,3 +72,5 @@ the item from the BrowserWindow onto your desktop. In this guide,
 the item is a Markdown file located in the root of the project:
 
 ![Drag and drop](../images/drag-and-drop.gif)
+
+[`contextBridge`]: ../api/context-bridge.md

docs/tutorial/quick-start.md

@@ -32,6 +32,7 @@ From a development perspective, an Electron application is essentially a Node.js
 my-electron-app/
 ├── package.json
 ├── main.js
+├── preload.js
 └── index.html
 ```
 
@@ -55,45 +56,49 @@ The main script may look as follows:
 
 ```javascript fiddle='docs/fiddles/quick-start'
 const { app, BrowserWindow } = require('electron')
+const path = require('path')
 
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
     webPreferences: {
-      nodeIntegration: true
+      preload: path.join(__dirname, 'preload.js')
     }
   })
 
   win.loadFile('index.html')
 }
 
-app.whenReady().then(createWindow)
+app.whenReady().then(() => {
+  createWindow()
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow()
+    }
+  })
+})
 
 app.on('window-all-closed', () => {
   if (process.platform !== 'darwin') {
     app.quit()
   }
 })
-
-app.on('activate', () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})
 ```
 
 ##### What is going on above?
 
 1. Line 1: First, you import the `app` and `BrowserWindow` modules of the `electron` package to be able to manage your application's lifecycle events, as well as create and control browser windows.
-2. Line 3: After that, you define a function that creates a [new browser window](../api/browser-window.md#new-browserwindowoptions) with node integration enabled, loads `index.html` file into this window (line 12, we will discuss the file later).
-3. Line 15: You create a new browser window by invoking the `createWindow` function once the Electron application [is initialized](../api/app.md#appwhenready).
-4. Line 17: You add a new listener that tries to quit the application when it no longer has any open windows. This listener is a no-op on macOS due to the operating system's [window management behavior](https://support.apple.com/en-ca/guide/mac-help/mchlp2469/mac).
-5. Line 23: You add a new listener that creates a new browser window only if when the application has no visible windows after being activated. For example, after launching the application for the first time, or re-launching the already running application.
+2. Line 2: Second, you import the `path` package which provides utility functions for file paths.
+3. Line 4: After that, you define a function that creates a [new browser window](../api/browser-window.md#new-browserwindowoptions) with a preload script, loads `index.html` file into this window (line 13, we will discuss the file later).
+4. Line 16: You create a new browser window by invoking the `createWindow` function once the Electron application [is initialized](../api/app.md#appwhenready).
+5. Line 18: You add a new listener that creates a new browser window only if when the application has no visible windows after being activated. For example, after launching the application for the first time, or re-launching the already running application.
+6. Line 25: You add a new listener that tries to quit the application when it no longer has any open windows. This listener is a no-op on macOS due to the operating system's [window management behavior](https://support.apple.com/en-ca/guide/mac-help/mchlp2469/mac).
 
 #### Create a web page
 
-This is the web page you want to display once the application is initialized. This web page represents the Renderer process. You can create multiple browser windows, where each window uses its own independent Renderer. Each window can optionally be granted with full access to Node.js API through the `nodeIntegration` preference.
+This is the web page you want to display once the application is initialized. This web page represents the Renderer process. You can create multiple browser windows, where each window uses its own independent Renderer. You can optionally grant access to additional Node.js APIs by exposing them from your preload script.
 
 The `index.html` page looks as follows:
 
@@ -108,14 +113,38 @@ The `index.html` page looks as follows:
 <body style="background: white;">
     <h1>Hello World!</h1>
     <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
+        We are using Node.js <span id="node-version"></span>,
+        Chromium <span id="chrome-version"></span>,
+        and Electron <span id="electron-version"></span>.
     </p>
 </body>
 </html>
 ```
 
+#### Define a preload script
+
+Your preload script (in our case, the `preload.js` file) acts as a bridge between Node.js and your web page. It allows you to expose specific APIs and behaviors to your web page rather than insecurely exposing the entire Node.js API. In this example we will use the preload script to read version information from the `process` object and update the web page with that info.
+
+```javascript fiddle='docs/fiddles/quick-start'
+window.addEventListener('DOMContentLoaded', () => {
+  const replaceText = (selector, text) => {
+    const element = document.getElementById(selector)
+    if (element) element.innerText = text
+  }
+
+  for (const type of ['chrome', 'node', 'electron']) {
+    replaceText(`${type}-version`, process.versions[type])
+  }
+})
+```
+
+##### What's going on above?
+
+1. On line 1: First you define an event listener that tells you when the web page has loaded
+2. On line 2: Second you define a utility function used to set the text of the placeholders in the `index.html`
+3. On line 7: Next you loop through the list of components whose version you want to display
+4. On line 8: Finally, you call `replaceText` to look up the version placeholders in `index.html` and set their text value to the values from `process.versions`
+
 #### Modify your package.json file
 
 Your Electron application uses the `package.json` file as the main entry point (as any other Node.js application). The main script of your application is `main.js`, so modify the `package.json` file accordingly:
@@ -167,7 +196,8 @@ The simplest and the fastest way to distribute your newly created app is using
 1. Import Electron Forge to your app folder:
 
     ```sh
-    npx @electron-forge/cli import
+    npm install --save-dev @electron-forge/cli
+    npx electron-forge import
 
     ✔ Checking your system
     ✔ Initializing Git Repository
@@ -282,7 +312,7 @@ ipcRenderer.invoke('perform-action', ...args)
 
 ##### Node.js API
 
-> NOTE: To access the Node.js API from the Renderer process, you need to set the `nodeIntegration` preference to `true`.
+> NOTE: To access the Node.js API from the Renderer process, you need to set the `nodeIntegration` preference to `true` and the `contextIsolation` preference to `false`.  Please note that access to the Node.js API in any renderer that loads remote content is not recommended for [security reasons](../tutorial/security.md#2-do-not-enable-nodejs-integration-for-remote-content).
 
 Electron exposes full access to Node.js API and its modules both in the Main and the Renderer processes. For example, you can read all the files from the root directory:
 

docs/tutorial/recent-documents.md

@@ -83,6 +83,22 @@ following code snippet to your menu template:
 }
 ```
 
+Make sure the application menu is added after the [`'ready'`](../api/app.md#event-ready)
+event and not before, or the menu item will be disabled:
+
+```javascript
+const { app, Menu } = require('electron')
+
+const template = [
+  // Menu template here
+]
+const menu = Menu.buildFromTemplate(template)
+
+app.whenReady().then(() => {
+  Menu.setApplicationMenu(menu)
+})
+```
+
 ![macOS Recent Documents menu item][menu-item-image]
 
 When a file is requested from the recent documents menu, the `open-file` event

docs/tutorial/repl.md

@@ -1,27 +1,23 @@
 # REPL
 
-Read-Eval-Print-Loop (REPL) is a simple, interactive computer programming
-environment that takes single user inputs (i.e. single expressions), evaluates
-them, and returns the result to the user.
+[Read-Eval-Print-Loop](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) (REPL)
+is a simple, interactive computer programming environment that takes single user
+inputs (i.e. single expressions), evaluates them, and returns the result to the user.
 
-The `repl` module provides a REPL implementation that can be accessed using:
+## Main process
 
-* Assuming you have `electron` or `electron-prebuilt` installed as a local
-  project dependency:
+Electron exposes the [Node.js `repl` module](https://nodejs.org/dist/latest/docs/api/repl.html)
+through the `--interactive` CLI flag. Assuming you have `electron` installed as a local project
+dependency, you should be able to access the REPL with the following command:
 
   ```sh
   ./node_modules/.bin/electron --interactive
   ```
 
-* Assuming you have `electron` or `electron-prebuilt` installed globally:
+**Note:** `electron --interactive` is not available on Windows
+(see [electron/electron#5776](https://github.com/electron/electron/pull/5776) for more details).
 
-  ```sh
-  electron --interactive
-  ```
+## Renderer process
 
-This only creates a REPL for the main process. You can use the Console
-tab of the Dev Tools to get a REPL for the renderer processes.
-
-**Note:** `electron --interactive` is not available on Windows.
-
-More information can be found in the [Node.js REPL docs](https://nodejs.org/dist/latest/docs/api/repl.html).
+You can use the DevTools Console tab to get a REPL for any renderer process.
+To learn more, read [the Chrome documentation](https://developer.chrome.com/docs/devtools/console/).

docs/tutorial/sandbox.md

@@ -0,0 +1,169 @@
+# Process Sandboxing
+
+One key security feature in Chromium is that processes can be executed within a sandbox.
+The sandbox limits the harm that malicious code can cause by limiting access to most
+system resources — sandboxed processes can only freely use CPU cycles and memory.
+In order to perform operations requiring additional privilege, sandboxed processes
+use dedicated communication channels to delegate tasks to more privileged processes.
+
+In Chromium, sandboxing is applied to most processes other than the main process.
+This includes renderer processes, as well as utility processes such as the audio service,
+the GPU service and the network service.
+
+See Chromium's [Sandbox design document][sandbox] for more information.
+
+## Electron's sandboxing policies
+
+Electron comes with a mixed sandbox environment, meaning sandboxed processes can run
+alongside privileged ones. By default, renderer processes are not sandboxed, but
+utility processes are. Note that as in Chromium, the main (browser) process is
+privileged and cannot be sandboxed.
+
+Historically, this mixed sandbox approach was established because having Node.js available
+in the renderer is an extremely powerful tool for app developers. Unfortunately, this
+feature is also an equally massive security vulnerability.
+
+Theoretically, unsandboxed renderers are not a problem for desktop applications that
+only display trusted code, but they make Electron less secure than Chromium for
+displaying untrusted web content. However, even purportedly trusted code may be
+dangerous — there are countless attack vectors that malicious actors can use, from
+cross-site scripting to content injection to man-in-the-middle attacks on remotely loaded
+websites, just to name a few. For this reason, we recommend enabling renderer sandboxing
+for the vast majority of cases under an abundance of caution.
+
+<!--TODO: update this guide when #28466 is either solved or closed -->
+Note that there is an active discussion in the issue tracker to enable renderer sandboxing
+by default. See [#28466][issue-28466]) for details.
+
+## Sandbox behaviour in Electron
+
+Sandboxed processes in Electron behave _mostly_ in the same way as Chromium's do, but
+Electron has a few additional concepts to consider because it interfaces with Node.js.
+
+### Renderer processes
+
+When renderer processes in Electron are sandboxed, they behave in the same way as a
+regular Chrome renderer would. A sandboxed renderer won't have a Node.js
+environment initialized.
+
+<!-- TODO(erickzhao): when we have a solid guide for IPC, link it here -->
+Therefore, when the sandbox is enabled, renderer processes can only perform privileged
+tasks (such as interacting with the filesystem, making changes to the system, or spawning
+subprocesses) by delegating these tasks to the main process via inter-process
+communication (IPC).
+
+### Preload scripts
+
+In order to allow renderer processes to communicate with the main process, preload
+scripts attached to sandboxed renderers will still have a polyfilled subset of Node.js
+APIs available. A `require` function similar to Node's `require` module is exposed,
+but can only import a subset of Electron and Node's built-in modules:
+
+* `electron` (only renderer process modules)
+* [`events`](https://nodejs.org/api/events.html)
+* [`timers`](https://nodejs.org/api/timers.html)
+* [`url`](https://nodejs.org/api/url.html)
+
+In addition, the preload script also polyfills certain Node.js primitives as globals:
+
+* [`Buffer`](https://nodejs.org/api/Buffer.html)
+* [`process`](../api/process.md)
+* [`clearImmediate`](https://nodejs.org/api/timers.html#timers_clearimmediate_immediate)
+* [`setImmediate`](https://nodejs.org/api/timers.html#timers_setimmediate_callback_args)
+
+Because the `require` function is a polyfill with limited functionality, you will not be
+able to use [CommonJS modules][commonjs] to separate your preload script into multiple
+files. If you need to split your preload code, use a bundler such as [webpack][webpack]
+or [Parcel][parcel].
+
+Note that because the environment presented to the `preload` script is substantially
+more privileged than that of a sandboxed renderer, it is still possible to leak
+privileged APIs to untrusted code running in the renderer process unless
+[`contextIsolation`][contextIsolation] is enabled.
+
+## Configuring the sandbox
+
+### Enabling the sandbox for a single process
+
+In Electron, renderer sandboxing can be enabled on a per-process basis with
+the `sandbox: true` preference in the [`BrowserWindow`][browser-window] constructor.
+
+```js
+// main.js
+app.whenReady().then(() => {
+  const win = new BrowserWindow({
+    webPreferences: {
+      sandbox: true
+    }
+  })
+  win.loadURL('https://google.com')
+})
+```
+
+### Enabling the sandbox globally
+
+If you want to force sandboxing for all renderers, you can also use the
+[`app.enableSandbox`][enable-sandbox] API. Note that this API has to be called before the
+app's `ready` event.
+
+```js
+// main.js
+app.enableSandbox()
+app.whenReady().then(() => {
+  // no need to pass `sandbox: true` since `app.enableSandbox()` was called.
+  const win = new BrowserWindow()
+  win.loadURL('https://google.com')
+})
+```
+
+### Disabling Chromium's sandbox (testing only)
+
+You can also disable Chromium's sandbox entirely with the [`--no-sandbox`][no-sandbox]
+CLI flag, which will disable the sandbox for all processes (including utility processes).
+We highly recommend that you only use this flag for testing purposes, and **never**
+in production.
+
+Note that the `sandbox: true` option will still disable the renderer's Node.js
+environment.
+
+## A note on rendering untrusted content
+
+Rendering untrusted content in Electron is still somewhat uncharted territory,
+though some apps are finding success (e.g. [Beaker Browser][beaker]).
+Our goal is to get as close to Chrome as we can in terms of the security of
+sandboxed content, but ultimately we will always be behind due to a few fundamental
+issues:
+
+1. We do not have the dedicated resources or expertise that Chromium has to
+   apply to the security of its product. We do our best to make use of what we
+   have, to inherit everything we can from Chromium, and to respond quickly to
+   security issues, but Electron cannot be as secure as Chromium without the
+   resources that Chromium is able to dedicate.
+2. Some security features in Chrome (such as Safe Browsing and Certificate
+   Transparency) require a centralized authority and dedicated servers, both of
+   which run counter to the goals of the Electron project. As such, we disable
+   those features in Electron, at the cost of the associated security they
+   would otherwise bring.
+3. There is only one Chromium, whereas there are many thousands of apps built
+   on Electron, all of which behave slightly differently. Accounting for those
+   differences can yield a huge possibility space, and make it challenging to
+   ensure the security of the platform in unusual use cases.
+4. We can't push security updates to users directly, so we rely on app vendors
+   to upgrade the version of Electron underlying their app in order for
+   security updates to reach users.
+
+While we make our best effort to backport Chromium security fixes to older
+versions of Electron, we do not make a guarantee that every fix will be
+backported. Your best chance at staying secure is to be on the latest stable
+version of Electron.
+
+[sandbox]: https://chromium.googlesource.com/chromium/src/+/master/docs/design/sandbox.md
+[issue-28466]: https://github.com/electron/electron/issues/28466
+[browser-window]: ../api/browser-window.md
+[enable-sandbox]: ../api/app.md#appenablesandbox
+[no-sandbox]: ../api/command-line-switches.md#--no-sandbox
+[commonjs]: https://nodejs.org/api/modules.html#modules_modules_commonjs_modules
+[webpack]: https://webpack.js.org/
+[parcel]: https://parceljs.org/
+[context-isolation]: ./context-isolation.md
+[beaker]: https://github.com/beakerbrowser/beaker

docs/tutorial/security.md

@@ -44,7 +44,7 @@ Chromium shared library and Node.js. Vulnerabilities affecting these components
 may impact the security of your application. By updating Electron to the latest
 version, you ensure that critical vulnerabilities (such as *nodeIntegration bypasses*)
 are already patched and cannot be exploited in your application. For more information,
-see "[Use a current version of Electron](#17-use-a-current-version-of-electron)".
+see "[Use a current version of Electron](#15-use-a-current-version-of-electron)".
 
 * **Evaluate your dependencies.** While NPM provides half a million reusable packages,
 it is your responsibility to choose trusted 3rd-party libraries. If you use outdated
@@ -99,9 +99,7 @@ You should at least follow these steps to improve the security of your applicati
 12. [Disable or limit navigation](#12-disable-or-limit-navigation)
 13. [Disable or limit creation of new windows](#13-disable-or-limit-creation-of-new-windows)
 14. [Do not use `openExternal` with untrusted content](#14-do-not-use-openexternal-with-untrusted-content)
-15. [Disable the `remote` module](#15-disable-the-remote-module)
-16. [Filter the `remote` module](#16-filter-the-remote-module)
-17. [Use a current version of Electron](#17-use-a-current-version-of-electron)
+15. [Use a current version of Electron](#15-use-a-current-version-of-electron)
 
 To automate the detection of misconfigurations and insecure patterns, it is
 possible to use
@@ -665,134 +663,7 @@ const { shell } = require('electron')
 shell.openExternal('https://example.com/index.html')
 ```
 
-## 15) Disable the `remote` module
-
-The `remote` module provides a way for the renderer processes to
-access APIs normally only available in the main process. Using it, a
-renderer can invoke methods of a main process object without explicitly sending
-inter-process messages. If your desktop application does not run untrusted
-content, this can be a useful way to have your renderer processes access and
-work with modules that are only available to the main process, such as
-GUI-related modules (dialogs, menus, etc.).
-
-However, if your app can run untrusted content and even if you
-[sandbox][sandbox] your renderer processes accordingly, the `remote` module
-makes it easy for malicious code to escape the sandbox and have access to
-system resources via the higher privileges of the main process. Therefore,
-it should be disabled in such circumstances.
-
-### Why?
-
-`remote` uses an internal IPC channel to communicate with the main process.
-"Prototype pollution" attacks can grant malicious code access to the internal
-IPC channel, which can then be used to escape the sandbox by mimicking `remote`
-IPC messages and getting access to main process modules running with higher
-privileges.
-
-Additionally, it's possible for preload scripts to accidentally leak modules to a
-sandboxed renderer. Leaking `remote` arms malicious code with a multitude
-of main process modules with which to perform an attack.
-
-Disabling the `remote` module eliminates these attack vectors. Enabling
-context isolation also prevents the "prototype pollution" attacks from
-succeeding.
-
-### How?
-
-```js
-// Bad if the renderer can run untrusted content
-const mainWindow = new BrowserWindow({
-  webPreferences: {
-    enableRemoteModule: true
-  }
-})
-```
-
-```js
-// Good
-const mainWindow = new BrowserWindow({
-  webPreferences: {
-    enableRemoteModule: false
-  }
-})
-```
-
-```html
-<!-- Bad if the renderer can run untrusted content  -->
-<webview enableremotemodule="true" src="page.html"></webview>
-
-<!-- Good -->
-<webview enableremotemodule="false" src="page.html"></webview>
-```
-
-> **Note:** The default value of `enableRemoteModule` is `false` starting
-> from Electron 10. For prior versions, you need to explicitly disable
-> the `remote` module by the means above.
-
-## 16) Filter the `remote` module
-
-If you cannot disable the `remote` module, you should filter the globals,
-Node, and Electron modules (so-called built-ins) accessible via `remote`
-that your application does not require. This can be done by blocking
-certain modules entirely and by replacing others with proxies that
-expose only the functionality that your app needs.
-
-### Why?
-
-Due to the system access privileges of the main process, functionality
-provided by the main process modules may be dangerous in the hands of
-malicious code running in a compromised renderer process. By limiting
-the set of accessible modules to the minimum that your app needs and
-filtering out the others, you reduce the toolset that malicious code
-can use to attack the system.
-
-Note that the safest option is to
-[fully disable the remote module](#15-disable-the-remote-module). If
-you choose to filter access rather than completely disable the module,
-you must be very careful to ensure that no escalation of privilege is
-possible through the modules you allow past the filter.
-
-### How?
-
-```js
-const readOnlyFsProxy = require(/* ... */) // exposes only file read functionality
-
-const allowedModules = new Set(['crypto'])
-const proxiedModules = new Map([['fs', readOnlyFsProxy]])
-const allowedElectronModules = new Set(['shell'])
-const allowedGlobals = new Set()
-
-app.on('remote-require', (event, webContents, moduleName) => {
-  if (proxiedModules.has(moduleName)) {
-    event.returnValue = proxiedModules.get(moduleName)
-  }
-  if (!allowedModules.has(moduleName)) {
-    event.preventDefault()
-  }
-})
-
-app.on('remote-get-builtin', (event, webContents, moduleName) => {
-  if (!allowedElectronModules.has(moduleName)) {
-    event.preventDefault()
-  }
-})
-
-app.on('remote-get-global', (event, webContents, globalName) => {
-  if (!allowedGlobals.has(globalName)) {
-    event.preventDefault()
-  }
-})
-
-app.on('remote-get-current-window', (event, webContents) => {
-  event.preventDefault()
-})
-
-app.on('remote-get-current-web-contents', (event, webContents) => {
-  event.preventDefault()
-})
-```
-
-## 17) Use a current version of Electron
+## 15) Use a current version of Electron
 
 You should strive for always using the latest available version of Electron.
 Whenever a new major version is released, you should attempt to update your
@@ -821,5 +692,5 @@ which potential security issues are not as widely known.
 [window-open-handler]: ../api/web-contents.md#contentssetwindowopenhandlerhandler
 [will-navigate]: ../api/web-contents.md#event-will-navigate
 [open-external]: ../api/shell.md#shellopenexternalurl-options
-[sandbox]: ../api/sandbox-option.md
+[sandbox]: ../tutorial/sandbox.md
 [responsible-disclosure]: https://en.wikipedia.org/wiki/Responsible_disclosure

docs/tutorial/support.md

@@ -94,7 +94,7 @@ Following platforms are supported by Electron:
 ### macOS
 
 Only 64bit binaries are provided for macOS, and the minimum macOS version
-supported is macOS 10.10 (Yosemite).
+supported is macOS 10.11 (El Capitan).
 
 Native support for Apple Silicon (`arm64`) devices was added in Electron 11.0.0.
 

docs/tutorial/using-selenium-and-webdriver.md

@@ -86,12 +86,12 @@ const driver = new webdriver.Builder()
   // The "9515" is the port opened by chrome driver.
   .usingServer('http://localhost:9515')
   .withCapabilities({
-    chromeOptions: {
+    'goog:chromeOptions': {
       // Here is the path to your Electron binary.
       binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'
     }
   })
-  .forBrowser('electron')
+  .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0
   .build()
 
 driver.get('http://www.google.com')

electron_paks.gni

@@ -73,7 +73,7 @@ template("electron_extra_paks") {
       "//components/resources",
       "//content:content_resources",
       "//content:dev_ui_content_resources",
-      "//content/browser/resources/media:media_internals_resources",
+      "//content/browser/resources/media:resources",
       "//content/browser/tracing:resources",
       "//content/browser/webrtc/resources",
       "//electron:resources",

electron_strings.grdp

@@ -51,6 +51,21 @@
   <message name="IDS_PICTURE_IN_PICTURE_SKIP_AD_CONTROL_TEXT" desc="Text label of the skip ad control button. The button appears when the user hovers over the Picture-in-Picture window.">
     Skip Ad
   </message>
+  <message name="IDS_PICTURE_IN_PICTURE_MUTE_MICROPHONE_TEXT" desc="Text label of the mute microphone control button. The button appears when the user hovers over the Picture-in-Picture window.">
+    Mute microphone
+  </message>
+  <message name="IDS_PICTURE_IN_PICTURE_UNMUTE_MICROPHONE_TEXT" desc="Text label of the unmute microphone control button. The button appears when the user hovers over the Picture-in-Picture window.">
+    Unmute microphone
+  </message>
+  <message name="IDS_PICTURE_IN_PICTURE_TURN_ON_CAMERA_TEXT" desc="Text label of the turn on camera control button. The button appears when the user hovers over the Picture-in-Picture window.">
+    Turn on camera
+  </message>
+  <message name="IDS_PICTURE_IN_PICTURE_TURN_OFF_CAMERA_TEXT" desc="Text label of the turn off camera control button. The button appears when the user hovers over the Picture-in-Picture window.">
+    Turn off camera
+  </message>
+  <message name="IDS_PICTURE_IN_PICTURE_HANG_UP_TEXT" desc="Text label of the hang up control button. The button appears when the user hovers over the Picture-in-Picture window.">
+    Hang up
+  </message>
   <message name="IDS_PICTURE_IN_PICTURE_CLOSE_CONTROL_TEXT" desc="Text label of the close control button. The button appears when the user hovers over the Picture-in-Picture window.">
     Close
   </message>

filenames.auto.gni

@@ -29,7 +29,6 @@ auto_filenames = {
     "docs/api/incoming-message.md",
     "docs/api/ipc-main.md",
     "docs/api/ipc-renderer.md",
-    "docs/api/locales.md",
     "docs/api/menu-item.md",
     "docs/api/menu.md",
     "docs/api/message-channel-main.md",
@@ -44,7 +43,6 @@ auto_filenames = {
     "docs/api/process.md",
     "docs/api/protocol.md",
     "docs/api/remote.md",
-    "docs/api/sandbox-option.md",
     "docs/api/screen.md",
     "docs/api/service-workers.md",
     "docs/api/session.md",

filenames.gni

@@ -404,6 +404,8 @@ filenames = {
     "shell/browser/native_window_observer.h",
     "shell/browser/net/asar/asar_url_loader.cc",
     "shell/browser/net/asar/asar_url_loader.h",
+    "shell/browser/net/asar/asar_url_loader_factory.cc",
+    "shell/browser/net/asar/asar_url_loader_factory.h",
     "shell/browser/net/cert_verifier_client.cc",
     "shell/browser/net/cert_verifier_client.h",
     "shell/browser/net/electron_url_loader_factory.cc",

lib/asar/fs-wrapper.ts

@@ -532,15 +532,17 @@ export const wrapFsWithAsar = (fs: Record<string, any>) => {
       return fs.readFile(realPath, options, callback);
     }
 
+    const buffer = Buffer.alloc(info.size);
+    const fd = archive.getFd();
+    if (!(fd >= 0)) {
+      const error = createError(AsarError.NOT_FOUND, { asarPath, filePath });
+      nextTick(callback, [error]);
+      return;
+    }
+
     logASARAccess(asarPath, filePath, info.offset);
-    archive.read(info.offset, info.size).then((buf) => {
-      const buffer = Buffer.from(buf);
-      callback(null, encoding ? buffer.toString(encoding) : buffer);
-    }, (err) => {
-      const error: AsarErrorObject = new Error(`EINVAL, ${err.message} while reading ${filePath} in ${asarPath}`);
-      error.code = 'EINVAL';
-      error.errno = -22;
-      callback(error);
+    fs.read(fd, buffer, 0, info.size, info.offset, (error: Error) => {
+      callback(error, encoding ? buffer.toString(encoding) : buffer);
     });
   };
 
@@ -573,19 +575,13 @@ export const wrapFsWithAsar = (fs: Record<string, any>) => {
     }
 
     const { encoding } = options;
+    const buffer = Buffer.alloc(info.size);
+    const fd = archive.getFd();
+    if (!(fd >= 0)) throw createError(AsarError.NOT_FOUND, { asarPath, filePath });
 
     logASARAccess(asarPath, filePath, info.offset);
-    let arrayBuffer: ArrayBuffer;
-    try {
-      arrayBuffer = archive.readSync(info.offset, info.size);
-    } catch (err) {
-      const error: AsarErrorObject = new Error(`EINVAL, ${err.message} while reading ${filePath} in ${asarPath}`);
-      error.code = 'EINVAL';
-      error.errno = -22;
-      throw error;
-    }
-    const buffer = Buffer.from(arrayBuffer);
-    return encoding ? buffer.toString(encoding) : buffer;
+    fs.readSync(fd, buffer, 0, info.size, info.offset);
+    return (encoding) ? buffer.toString(encoding) : buffer;
   };
 
   const { readdir } = fs;
@@ -697,17 +693,12 @@ export const wrapFsWithAsar = (fs: Record<string, any>) => {
       return [str, str.length > 0];
     }
 
+    const buffer = Buffer.alloc(info.size);
+    const fd = archive.getFd();
+    if (!(fd >= 0)) return [];
+
     logASARAccess(asarPath, filePath, info.offset);
-    let arrayBuffer: ArrayBuffer;
-    try {
-      arrayBuffer = archive.readSync(info.offset, info.size);
-    } catch (err) {
-      const error: AsarErrorObject = new Error(`EINVAL, ${err.message} while reading ${filePath} in ${asarPath}`);
-      error.code = 'EINVAL';
-      error.errno = -22;
-      throw error;
-    }
-    const buffer = Buffer.from(arrayBuffer);
+    fs.readSync(fd, buffer, 0, info.size, info.offset);
     const str = buffer.toString('utf8');
     return [str, str.length > 0];
   };

lib/browser/api/app.ts

@@ -63,6 +63,9 @@ Object.defineProperty(app, 'applicationMenu', {
   return execFile !== 'electron';
 })();
 
+// The native implementation is not provided on non-windows platforms
+app.setAppUserModelId = app.setAppUserModelId || (() => {});
+
 app._setDefaultAppPaths = (packagePath) => {
   // Set the user path according to application's name.
   app.setPath('userData', path.join(app.getPath('appData'), app.name!));

lib/browser/api/crash-reporter.ts

@@ -10,13 +10,13 @@ class CrashReporter {
       extra = {},
       globalExtra = {},
       ignoreSystemCrashHandler = false,
-      submitURL,
+      submitURL = '',
       uploadToServer = true,
       rateLimit = false,
       compress = true
     } = options || {};
 
-    if (submitURL == null) throw new Error('submitURL is a required option to crashReporter.start');
+    if (uploadToServer && !submitURL) throw new Error('submitURL must be specified when uploadToServer is true');
 
     if (!compress) {
       deprecate.log('Sending uncompressed crash reports is deprecated and will be removed in a future version of Electron. Set { compress: true } to opt-in to the new behavior. Crash reports will be uploaded gzipped, which most crash reporting servers support.');

lib/browser/api/dialog.ts

@@ -2,10 +2,10 @@ import { app, BrowserWindow } from 'electron/main';
 import type { OpenDialogOptions, OpenDialogReturnValue, MessageBoxOptions, SaveDialogOptions, SaveDialogReturnValue, MessageBoxReturnValue, CertificateTrustDialogOptions } from 'electron/main';
 const dialogBinding = process._linkedBinding('electron_browser_dialog');
 
-const DialogType = {
-  OPEN: 'OPEN' as 'OPEN',
-  SAVE: 'SAVE' as 'SAVE'
-};
+enum DialogType {
+  OPEN = 'OPEN',
+  SAVE = 'SAVE'
+}
 
 enum SaveFileDialogProperties {
   createDirectory = 1 << 0,
@@ -72,7 +72,7 @@ const setupSaveDialogProperties = (properties: (keyof typeof SaveFileDialogPrope
   return dialogProperties;
 };
 
-const setupDialogProperties = (type: keyof typeof DialogType, properties: string[]): number => {
+const setupDialogProperties = (type: DialogType, properties: string[]): number => {
   if (type === DialogType.OPEN) {
     return setupOpenDialogProperties(properties as (keyof typeof OpenFileDialogProperties)[]);
   } else if (type === DialogType.SAVE) {

lib/browser/api/menu.ts

@@ -177,7 +177,7 @@ Menu.setApplicationMenu = function (menu: MenuType) {
     bindings.setApplicationMenu(menu);
   } else {
     const windows = BaseWindow.getAllWindows();
-    return windows.map(w => w.setMenu(menu));
+    windows.map(w => w.setMenu(menu));
   }
 };
 

lib/browser/api/net.ts

@@ -188,6 +188,11 @@ class ChunkedBodyStream extends Writable {
     this._downstream = pipe;
     if (this._pendingChunk) {
       const doneWriting = (maybeError: Error | void) => {
+        // If the underlying request has been aborted, we honeslty don't care about the error
+        // all work should cease as soon as we abort anyway, this error is probably a
+        // "mojo pipe disconnected" error (code=9)
+        if (this._clientRequest._aborted) return;
+
         const cb = this._pendingCallback!;
         delete this._pendingCallback;
         delete this._pendingChunk;

lib/browser/api/web-contents.ts

@@ -1,5 +1,5 @@
 import { app, ipcMain, session, deprecate, webFrameMain } from 'electron/main';
-import type { BrowserWindowConstructorOptions, MenuItem, MenuItemConstructorOptions, LoadURLOptions } from 'electron/main';
+import type { BrowserWindowConstructorOptions, LoadURLOptions } from 'electron/main';
 
 import * as url from 'url';
 import * as path from 'path';
@@ -61,7 +61,7 @@ const PDFPageSizes: Record<string, ElectronInternal.MediaSize> = {
     width_microns: 279400,
     custom_display_name: 'Tabloid'
   }
-};
+} as const;
 
 // The minimum micron size Chromium accepts is that where:
 // Per printing/units.h:
@@ -94,6 +94,7 @@ const defaultPrintingSetting = {
   pagesPerSheet: 1,
   isFirstRequest: false,
   previewUIID: 0,
+  // True, if the document source is modifiable. e.g. HTML and not PDF.
   previewModifiable: true,
   printToPDF: true,
   deviceName: 'Save as PDF',
@@ -109,7 +110,7 @@ const defaultPrintingSetting = {
   printerType: 2,
   title: undefined as string | undefined,
   url: undefined as string | undefined
-};
+} as const;
 
 // JavaScript implementations of WebContents.
 const binding = process._linkedBinding('electron_browser_web_contents');
@@ -191,7 +192,7 @@ WebContents.prototype.executeJavaScriptInIsolatedWorld = async function (worldId
 
 let pendingPromise: Promise<any> | undefined;
 WebContents.prototype.printToPDF = async function (options) {
-  const printSettings = {
+  const printSettings: Record<string, any> = {
     ...defaultPrintingSetting,
     requestID: getNextId()
   };
@@ -432,7 +433,11 @@ WebContents.prototype._callWindowOpenHandler = function (event: Electron.Event,
     event.preventDefault();
     return null;
   } else if (response.action === 'allow') {
-    if (typeof response.overrideBrowserWindowOptions === 'object' && response.overrideBrowserWindowOptions !== null) { return response.overrideBrowserWindowOptions; } else { return {}; }
+    if (typeof response.overrideBrowserWindowOptions === 'object' && response.overrideBrowserWindowOptions !== null) {
+      return response.overrideBrowserWindowOptions;
+    } else {
+      return {};
+    }
   } else {
     event.preventDefault();
     console.error('The window open handler response must be an object with an \'action\' property of \'allow\' or \'deny\'.');
@@ -546,18 +551,6 @@ WebContents.prototype._init = function () {
     ipcMain.emit(channel, event, message);
   });
 
-  // Handle context menu action request from pepper plugin.
-  this.on('pepper-context-menu' as any, function (event: ElectronInternal.Event, params: {x: number, y: number, menu: Array<(MenuItemConstructorOptions) | (MenuItem)>}, callback: () => void) {
-    // Access Menu via electron.Menu to prevent circular require.
-    const menu = require('electron').Menu.buildFromTemplate(params.menu);
-    menu.popup({
-      window: event.sender.getOwnerBrowserWindow(),
-      x: params.x,
-      y: params.y,
-      callback
-    });
-  });
-
   this.on('crashed', (event, ...args) => {
     app.emit('renderer-process-crashed', event, this, ...args);
   });
@@ -580,19 +573,22 @@ WebContents.prototype._init = function () {
     // Make new windows requested by links behave like "window.open".
     this.on('-new-window' as any, (event: ElectronInternal.Event, url: string, frameName: string, disposition: string,
       rawFeatures: string, referrer: Electron.Referrer, postData: PostData) => {
-      openGuestWindow({
-        event,
-        embedder: event.sender,
-        disposition,
-        referrer,
-        postData,
-        overrideBrowserWindowOptions: {},
-        windowOpenArgs: {
-          url,
-          frameName,
-          features: rawFeatures
-        }
-      });
+      const options = this._callWindowOpenHandler(event, url, frameName, rawFeatures);
+      if (!event.defaultPrevented) {
+        openGuestWindow({
+          event,
+          embedder: event.sender,
+          disposition,
+          referrer,
+          postData,
+          overrideBrowserWindowOptions: options || {},
+          windowOpenArgs: {
+            url,
+            frameName,
+            features: rawFeatures
+          }
+        });
+      }
     });
 
     let windowOpenOverriddenOptions: BrowserWindowConstructorOptions | null = null;
@@ -604,6 +600,7 @@ WebContents.prototype._init = function () {
           // it's technically a BrowserWindowConstructorOptions option because
           // we need to access it in the renderer at init time.
           backgroundColor: windowOpenOverriddenOptions.backgroundColor,
+          transparent: windowOpenOverriddenOptions.transparent,
           ...windowOpenOverriddenOptions.webPreferences
         } : undefined;
         this._setNextChildWebPreferences(

lib/browser/default-menu.ts

@@ -27,7 +27,7 @@ export const setDefaultApplicationMenu = () => {
       {
         label: 'Community Discussions',
         click: async () => {
-          await shell.openExternal('https://discuss.atom.io/c/electron');
+          await shell.openExternal('https://discord.gg/electron');
         }
       },
       {

lib/browser/guest-window-manager.ts

@@ -42,7 +42,6 @@ export function openGuestWindow ({ event, embedder, guest, referrer, disposition
   windowOpenArgs: WindowOpenArgs,
 }): BrowserWindow | undefined {
   const { url, frameName, features } = windowOpenArgs;
-  const isNativeWindowOpen = !!guest;
   const { options: browserWindowOptions, additionalFeatures } = makeBrowserWindowOptions({
     embedder,
     features,
@@ -57,6 +56,7 @@ export function openGuestWindow ({ event, embedder, guest, referrer, disposition
     windowOpenArgs,
     additionalFeatures,
     disposition,
+    postData,
     referrer
   });
   if (didCancelEvent) return;
@@ -74,11 +74,14 @@ export function openGuestWindow ({ event, embedder, guest, referrer, disposition
     webContents: guest,
     ...browserWindowOptions
   });
-  if (!isNativeWindowOpen) {
+  if (!guest) {
     // We should only call `loadURL` if the webContents was constructed by us in
     // the case of BrowserWindowProxy (non-sandboxed, nativeWindowOpen: false),
     // as navigating to the url when creating the window from an existing
     // webContents is not necessary (it will navigate there anyway).
+    // This can also happen if we enter this function from OpenURLFromTab, in
+    // which case the browser process is responsible for initiating navigation
+    // in the new window.
     window.loadURL(url, {
       httpReferrer: referrer,
       ...(postData && {
@@ -146,7 +149,7 @@ function emitDeprecatedNewWindowEvent ({ event, embedder, guest, windowOpenArgs,
   const isWebViewWithPopupsDisabled = embedder.getType() === 'webview' && embedder.getLastWebPreferences().disablePopups;
   const postBody = postData ? {
     data: postData,
-    headers: formatPostDataHeaders(postData as Electron.UploadRawData[])
+    ...parseContentTypeFormat(postData)
   } : null;
 
   embedder.emit(
@@ -276,22 +279,40 @@ function getDeprecatedInheritedOptions (embedder: WebContents) {
   return inheritableOptions;
 }
 
-function formatPostDataHeaders (postData: Electron.UploadRawData[]) {
+function formatPostDataHeaders (postData: PostData) {
   if (!postData) return;
 
-  let extraHeaders = 'content-type: application/x-www-form-urlencoded';
+  const { contentType, boundary } = parseContentTypeFormat(postData);
+  if (boundary != null) { return `content-type: ${contentType}; boundary=${boundary}`; }
 
-  if (postData.length > 0) {
-    const postDataFront = postData[0].bytes.toString();
-    const boundary = /^--.*[^-\r\n]/.exec(
-      postDataFront
-    );
-    if (boundary != null) {
-      extraHeaders = `content-type: multipart/form-data; boundary=${boundary[0].substr(
-        2
-      )}`;
+  return `content-type: ${contentType}`;
+}
+
+const MULTIPART_CONTENT_TYPE = 'multipart/form-data';
+const URL_ENCODED_CONTENT_TYPE = 'application/x-www-form-urlencoded';
+
+// Figure out appropriate headers for post data.
+const parseContentTypeFormat = function (postData: Exclude<PostData, undefined>) {
+  if (postData.length) {
+    if (postData[0].type === 'rawData') {
+      // For multipart forms, the first element will start with the boundary
+      // notice, which looks something like `------WebKitFormBoundary12345678`
+      // Note, this regex would fail when submitting a urlencoded form with an
+      // input attribute of name="--theKey", but, uhh, don't do that?
+      const postDataFront = postData[0].bytes.toString();
+      const boundary = /^--.*[^-\r\n]/.exec(postDataFront);
+      if (boundary) {
+        return {
+          boundary: boundary[0].substr(2),
+          contentType: MULTIPART_CONTENT_TYPE
+        };
+      }
     }
   }
-
-  return extraHeaders;
-}
+  // Either the form submission didn't contain any inputs (the postData array
+  // was empty), or we couldn't find the boundary and thus we can assume this is
+  // a key=value style form.
+  return {
+    contentType: URL_ENCODED_CONTENT_TYPE
+  };
+};

lib/common/parse-features-string.ts

@@ -62,7 +62,7 @@ export function parseCommaSeparatedKeyValue (source: string, useSoonToBeDeprecat
   for (const keyValuePair of source.split(',')) {
     const [key, value] = keyValuePair.split('=').map(str => str.trim());
     if (useSoonToBeDeprecatedBehaviorForBareKeys && value === undefined) {
-      bareKeys.push(key);
+      if (key) { bareKeys.push(key); }
       continue;
     }
     parsed[key] = coerce(key, value);

lib/common/web-view-events.ts

@@ -1,4 +1,4 @@
-export const webViewEvents: Record<string, string[]> = {
+export const webViewEvents: Record<string, readonly string[]> = {
   'load-commit': ['url', 'isMainFrame'],
   'did-attach': [],
   'did-finish-load': [],
@@ -33,4 +33,4 @@ export const webViewEvents: Record<string, string[]> = {
   'found-in-page': ['result'],
   'did-change-theme-color': ['themeColor'],
   'update-target-url': ['url']
-};
+} as const;

lib/renderer/init.ts

@@ -39,6 +39,10 @@ require('@electron/internal/common/init');
 // The global variable will be used by ipc for event dispatching
 const v8Util = process._linkedBinding('electron_common_v8_util');
 
+// Expose process.contextId
+const contextId = v8Util.getHiddenValue<string>(global, 'contextId');
+Object.defineProperty(process, 'contextId', { enumerable: true, value: contextId });
+
 const { ipcRendererInternal } = require('@electron/internal/renderer/ipc-renderer-internal');
 const ipcRenderer = require('@electron/internal/renderer/api/ipc-renderer').default;
 

lib/renderer/web-view/guest-view-internal.ts

@@ -8,7 +8,7 @@ import { IPC_MESSAGES } from '@electron/internal/common/ipc-messages';
 
 const DEPRECATED_EVENTS: Record<string, string> = {
   'page-title-updated': 'page-title-set'
-};
+} as const;
 
 const dispatchEvent = function (
   webView: WebViewImpl, eventName: string, eventKey: string, ...args: Array<any>

lib/renderer/web-view/web-view-impl.ts

@@ -162,7 +162,7 @@ export class WebViewImpl {
 
   // Emits focus/blur events.
   onFocusChange () {
-    const hasFocus = document.activeElement === this.webviewNode;
+    const hasFocus = this.webviewNode.ownerDocument.activeElement === this.webviewNode;
     if (hasFocus !== this.hasFocus) {
       this.hasFocus = hasFocus;
       this.dispatchEvent(hasFocus ? 'focus' : 'blur');

lib/sandboxed_renderer/init.ts

@@ -89,6 +89,10 @@ Object.defineProperty(preloadProcess, 'noDeprecation', {
   }
 });
 
+// Expose process.contextId
+const contextId = v8Util.getHiddenValue<string>(global, 'contextId');
+Object.defineProperty(preloadProcess, 'contextId', { enumerable: true, value: contextId });
+
 process.on('loaded', () => (preloadProcess as events.EventEmitter).emit('loaded'));
 process.on('exit', () => (preloadProcess as events.EventEmitter).emit('exit'));
 (process as events.EventEmitter).on('document-start', () => (preloadProcess as events.EventEmitter).emit('document-start'));

package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron",
-  "version": "13.0.0-nightly.20210303",
+  "version": "13.0.0-beta.28",
   "repository": "https://github.com/electron/electron",
   "description": "Build cross platform desktop apps with JavaScript, HTML, and CSS",
   "devDependencies": {
@@ -64,7 +64,6 @@
     "shx": "^0.3.2",
     "standard-markdown": "^6.0.0",
     "stream-json": "^1.7.1",
-    "sumchecker": "^2.0.2",
     "tap-xunit": "^2.4.1",
     "temp": "^0.8.3",
     "timers-browserify": "1.4.2",

patches/boringssl/expose_aes-cfb.patch

@@ -57,7 +57,7 @@ index 53cb9d2dc8f1962a70dc12b648d27c32be8aca4b..84af06fc56e4aa72d4d48801d7c037ad
    callback(EVP_aes_192_ctr(), "aes-192-ctr", NULL, arg);
    callback(EVP_aes_256_ctr(), "aes-256-ctr", NULL, arg);
 diff --git a/include/openssl/cipher.h b/include/openssl/cipher.h
-index c6bec489b51ca2e71b7f81e64a8e59b534e2e91a..512a9003164e65bd4ab896ef75b173dab3a8d1db 100644
+index badd496293fb9748adacff10478ea702d1155c5f..8565934bac9a810281b04946cb9f38d7623320f7 100644
 --- a/include/openssl/cipher.h
 +++ b/include/openssl/cipher.h
 @@ -430,6 +430,7 @@ OPENSSL_EXPORT const EVP_CIPHER *EVP_des_ede3_ecb(void);