Bump v15.3.6

Co-authored-by: John Kleinschmidt <jkleinsc@electronjs.org>

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -8,9 +8,9 @@ body:
     label: Preflight Checklist
     description: Please ensure you've completed all of the following.
     options:
-      - label: I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/master/CONTRIBUTING.md) for this project.
+      - label: I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/main/CONTRIBUTING.md) for this project.
         required: true
-      - label: I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/master/CODE_OF_CONDUCT.md) that this project adheres to.
+      - label: I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md) that this project adheres to.
         required: true
       - label: I have searched the [issue tracker](https://www.github.com/electron/electron/issues) for a feature request that matches the one I want to file, without success.
         required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -8,9 +8,9 @@ body:
     label: Preflight Checklist
     description: Please ensure you've completed all of the following.
     options:
-      - label: I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/master/CONTRIBUTING.md) for this project.
+      - label: I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/main/CONTRIBUTING.md) for this project.
         required: true
-      - label: I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/master/CODE_OF_CONDUCT.md) that this project adheres to.
+      - label: I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md) that this project adheres to.
         required: true
       - label: I have searched the [issue tracker](https://www.github.com/electron/electron/issues) for a feature request that matches the one I want to file, without success.
         required: true

.github/ISSUE_TEMPLATE/mac_app_store_private_api_rejection.yml

@@ -7,9 +7,9 @@ body:
     label: Preflight Checklist
     description: Please ensure you've completed all of the following.
     options:
-      - label: I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/master/CONTRIBUTING.md) for this project.
+      - label: I have read the [Contributing Guidelines](https://github.com/electron/electron/blob/main/CONTRIBUTING.md) for this project.
         required: true
-      - label: I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/master/CODE_OF_CONDUCT.md) that this project adheres to.
+      - label: I agree to follow the [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md) that this project adheres to.
         required: true
 - type: input
   attributes:

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,7 +3,7 @@
 Thank you for your Pull Request. Please provide a description above and review
 the requirements below.
 
-Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTING.md
+Contributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md
 -->
 
 #### Checklist
@@ -11,7 +11,7 @@ Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTIN
 
 - [ ] PR description included and stakeholders cc'd
 - [ ] `npm test` passes
-- [ ] tests are [changed or added](https://github.com/electron/electron/blob/master/docs/development/testing.md)
+- [ ] tests are [changed or added](https://github.com/electron/electron/blob/main/docs/development/testing.md)
 - [ ] relevant documentation is changed or added
 - [ ] [PR release notes](https://github.com/electron/clerk/blob/master/README.md) describe the change in a way relevant to app developers, and are [capitalized, punctuated, and past tense](https://github.com/electron/clerk/blob/master/README.md#examples).
 

.github/config.yml

@@ -2,7 +2,7 @@
 newPRWelcomeComment: |
   💖 Thanks for opening this pull request! 💖
 
-  We use [semantic commit messages](https://github.com/electron/electron/blob/master/docs/development/pull-requests.md#commit-message-guidelines) to streamline the release process. Before your pull request can be merged, you should **update your pull request title** to start with a semantic prefix.
+  We use [semantic commit messages](https://github.com/electron/electron/blob/main/docs/development/pull-requests.md#commit-message-guidelines) to streamline the release process. Before your pull request can be merged, you should **update your pull request title** to start with a semantic prefix.
 
   Examples of commit messages with semantic prefixes:
 
@@ -12,9 +12,9 @@ newPRWelcomeComment: |
 
   Things that will help get your PR across the finish line:
 
-  - Follow the JavaScript, C++, and Python [coding style](https://github.com/electron/electron/blob/master/docs/development/coding-style.md).
+  - Follow the JavaScript, C++, and Python [coding style](https://github.com/electron/electron/blob/main/docs/development/coding-style.md).
   - Run `npm run lint` locally to catch formatting errors earlier.
-  - Document any user-facing changes you've made following the [documentation styleguide](https://github.com/electron/electron/blob/master/docs/styleguide.md).
+  - Document any user-facing changes you've made following the [documentation styleguide](https://github.com/electron/electron/blob/main/docs/styleguide.md).
   - Include tests when adding/changing behavior.
   - Include screenshots and animated GIFs whenever possible.
 

.gitignore

@@ -26,6 +26,7 @@ compile_commands.json
 # npm package
 /npm/dist
 /npm/path.txt
+/npm/checksums.json
 
 .npmrc
 

BUILD.gn

@@ -187,6 +187,12 @@ action("electron_js2c") {
          rebase_path(sources, root_build_dir)
 }
 
+action("generate_config_gypi") {
+  outputs = [ "$root_gen_dir/config.gypi" ]
+  script = "script/generate-config-gypi.py"
+  args = rebase_path(outputs) + [ target_cpu ]
+}
+
 target_gen_default_app_js = "$target_gen_dir/js/default_app"
 
 typescript_build("default_app_js") {
@@ -361,6 +367,7 @@ source_set("electron_lib") {
     "//ppapi/shared_impl",
     "//printing/buildflags",
     "//services/device/public/cpp/geolocation",
+    "//services/device/public/cpp/hid",
     "//services/device/public/mojom",
     "//services/proxy_resolver:lib",
     "//services/video_capture/public/mojom:constants",
@@ -1006,6 +1013,12 @@ if (is_mac) {
     outputs = [ "{{bundle_resources_dir}}/{{source_file_part}}" ]
   }
 
+  asar_hashed_info_plist("electron_app_plist") {
+    keys = [ "DEFAULT_APP_ASAR_HEADER_SHA" ]
+    hash_targets = [ ":default_app_asar_header_hash" ]
+    plist_file = "shell/browser/resources/mac/Info.plist"
+  }
+
   mac_app_bundle("electron_app") {
     output_name = electron_product_name
     sources = filenames.app_sources
@@ -1013,6 +1026,7 @@ if (is_mac) {
     include_dirs = [ "." ]
     deps = [
       ":electron_app_framework_bundle_data",
+      ":electron_app_plist",
       ":electron_app_resources",
       ":electron_fuses",
       "//base",
@@ -1021,7 +1035,7 @@ if (is_mac) {
     if (is_mas_build) {
       deps += [ ":electron_login_helper_app" ]
     }
-    info_plist = "shell/browser/resources/mac/Info.plist"
+    info_plist_target = ":electron_app_plist"
     extra_substitutions = [
       "ELECTRON_BUNDLE_ID=$electron_mac_bundle_id",
       "ELECTRON_VERSION=$electron_version",
@@ -1131,6 +1145,7 @@ if (is_mac) {
     ]
 
     data = []
+    data_deps = []
 
     data += [ "$root_out_dir/resources.pak" ]
     data += [ "$root_out_dir/chrome_100_percent.pak" ]
@@ -1149,6 +1164,10 @@ if (is_mac) {
       public_deps = [ "//tools/v8_context_snapshot:v8_context_snapshot" ]
     }
 
+    if (is_linux) {
+      data_deps += [ "//components/crash/core/app:chrome_crashpad_handler" ]
+    }
+
     if (is_win) {
       sources += [
         # TODO: we should be generating our .rc files more like how chrome does
@@ -1404,7 +1423,8 @@ dist_zip("hunspell_dictionaries_zip") {
 }
 
 copy("libcxx_headers") {
-  sources = libcxx_headers + libcxx_licenses
+  sources = libcxx_headers + libcxx_licenses +
+            [ "//buildtools/third_party/libc++/__config_site" ]
   outputs = [ "$target_gen_dir/electron_libcxx_include/{{source_root_relative_dir}}/{{source_file_part}}" ]
 }
 

CONTRIBUTING.md

@@ -22,7 +22,7 @@ Issues are created [here](https://github.com/electron/electron/issues/new).
 
 ### Issue Closure
 
-Bug reports will be closed if the issue has been inactive and the latest affected version no longer receives support. At the moment, Electron maintains its three latest major versions, with a new major version being released every 12 weeks. (For more information on Electron's release cadence, see [this blog post](https://electronjs.org/blog/12-week-cadence).)
+Bug reports will be closed if the issue has been inactive and the latest affected version no longer receives support. At the moment, Electron maintains its three latest major versions, with a new major version being released every 8 weeks. (For more information on Electron's release cadence, see [this blog post](https://electronjs.org/blog/8-week-cadence).)
 
 _If an issue has been closed and you still feel it's relevant, feel free to ping a maintainer or add a comment!_
 
@@ -36,7 +36,7 @@ Having the original text _as well as_ the translation can help mitigate translat
 
 Responses to posted issues may or may not be in the original language.
 
-**Please note** that using non-English as an attempt to circumvent our [Code of Conduct](https://github.com/electron/electron/blob/master/CODE_OF_CONDUCT.md) will be an immediate, and possibly indefinite, ban from the project.
+**Please note** that using non-English as an attempt to circumvent our [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md) will be an immediate, and possibly indefinite, ban from the project.
 
 ## [Pull Requests](https://electronjs.org/docs/development/pull-requests)
 

DEPS

@@ -15,9 +15,9 @@ gclient_gn_args = [
 
 vars = {
   'chromium_version':
-    '93.0.4550.0',
+    '94.0.4606.81',
   'node_version':
-    'v16.2.0',
+    'v16.5.0',
   'nan_version':
     # The following commit hash of NAN is v2.14.2 with *only* changes to the
     # test suite. This should be updated to a specific tag when one becomes

ELECTRON_VERSION

@@ -1 +1 @@
-15.0.0-nightly.20210624
+15.3.6

README.md

@@ -1,7 +1,7 @@
 [![Electron Logo](https://electronjs.org/images/electron-logo.svg)](https://electronjs.org)
 
-[![CircleCI Build Status](https://circleci.com/gh/electron/electron/tree/master.svg?style=shield)](https://circleci.com/gh/electron/electron/tree/master)
-[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/4lggi9dpjc1qob7k/branch/master?svg=true)](https://ci.appveyor.com/project/electron-bot/electron-ljo26/branch/master)
+[![CircleCI Build Status](https://circleci.com/gh/electron/electron/tree/main.svg?style=shield)](https://circleci.com/gh/electron/electron/tree/main)
+[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/4lggi9dpjc1qob7k/branch/main?svg=true)](https://ci.appveyor.com/project/electron-bot/electron-ljo26/branch/main)
 [![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: 🇨🇳 🇧🇷 🇪🇸 🇯🇵 🇷🇺 🇫🇷 🇺🇸 🇩🇪.
@@ -16,7 +16,7 @@ Follow [@ElectronJS](https://twitter.com/electronjs) on Twitter for important
 announcements.
 
 This project adheres to the Contributor Covenant
-[code of conduct](https://github.com/electron/electron/tree/master/CODE_OF_CONDUCT.md).
+[code of conduct](https://github.com/electron/electron/tree/main/CODE_OF_CONDUCT.md).
 By participating, you are expected to uphold this code. Please report unacceptable
 behavior to [coc@electronjs.org](mailto:coc@electronjs.org).
 
@@ -98,6 +98,6 @@ and more can be found in the [support document](docs/tutorial/support.md#finding
 
 ## License
 
-[MIT](https://github.com/electron/electron/blob/master/LICENSE)
+[MIT](https://github.com/electron/electron/blob/main/LICENSE)
 
 When using the Electron or other GitHub logos, be sure to follow the [GitHub logo guidelines](https://github.com/logos).

SECURITY.md

@@ -10,7 +10,7 @@ Report security bugs in third-party modules to the person or team maintaining th
 
 ## The Electron Security Notification Process
 
-For context on Electron's security notification process, please see the [Notifications](https://github.com/electron/governance/blob/master/wg-security/membership-and-notifications.md#notifications) section of the Security WG's [Membership and Notifications](https://github.com/electron/governance/blob/master/wg-security/membership-and-notifications.md) Governance document.
+For context on Electron's security notification process, please see the [Notifications](https://github.com/electron/governance/blob/main/wg-security/membership-and-notifications.md#notifications) section of the Security WG's [Membership and Notifications](https://github.com/electron/governance/blob/main/wg-security/membership-and-notifications.md) Governance document.
 
 ## Learning More About Security
 

azure-pipelines-woa.yml

@@ -53,6 +53,22 @@ steps:
   env:
     APPVEYOR_TOKEN: $(APPVEYOR_TOKEN)
 
+- powershell: |
+    try {
+      $localArtifactPath = "$pwd\src\pdb.zip"
+      $serverArtifactPath = "$env:APPVEYOR_URL/buildjobs/$env:APPVEYOR_JOB_ID/artifacts/pdb.zip"
+      Invoke-RestMethod -Method Get -Uri $serverArtifactPath -OutFile $localArtifactPath -Headers @{ "Authorization" = "Bearer $env:APPVEYOR_TOKEN" }
+      cd src
+      & "${env:ProgramFiles(x86)}\7-Zip\7z.exe" x -y pdb.zip
+    } catch {
+      Write-Host "There was an exception encountered while downloading pdb files:" $_.Exception.Message
+    } finally {
+      $global:LASTEXITCODE = 0
+    }
+  displayName: 'Download pdb files for detailed stacktraces'
+  env:
+    APPVEYOR_TOKEN: $(APPVEYOR_TOKEN)
+
 - powershell: |
     New-Item src\out\Default\gen\node_headers\Release -Type directory
     Copy-Item -path src\out\Default\electron.lib -destination src\out\Default\gen\node_headers\Release\node.lib
@@ -63,15 +79,30 @@ steps:
     set npm_config_nodedir=%cd%\out\Default\gen\node_headers
     set npm_config_arch=arm64
     cd electron
-    # CalculateNativeWinOcclusion is disabled due to https://bugs.chromium.org/p/chromium/issues/detail?id=1139022
-    node script/yarn test -- --enable-logging --verbose --disable-features=CalculateNativeWinOcclusion
-  displayName: 'Run Electron tests'
+    node script/yarn test --runners=main --runTestFilesSeperately --enable-logging --disable-features=CalculateNativeWinOcclusion
+  displayName: 'Run Electron Main process tests'
+  env:
+    ELECTRON_ENABLE_STACK_DUMPING: true
+    ELECTRON_OUT_DIR: Default
+    IGNORE_YARN_INSTALL_ERROR: 1
+    ELECTRON_TEST_RESULTS_DIR: junit
+    MOCHA_MULTI_REPORTERS: 'mocha-junit-reporter, tap'
+    MOCHA_REPORTER: mocha-multi-reporters
+
+- script: |
+    cd src
+    set npm_config_nodedir=%cd%\out\Default\gen\node_headers
+    set npm_config_arch=arm64
+    cd electron
+    node script/yarn test --runners=remote --enable-logging --disable-features=CalculateNativeWinOcclusion
+  displayName: 'Run Electron Remote based tests'
   env:
     ELECTRON_OUT_DIR: Default
     IGNORE_YARN_INSTALL_ERROR: 1
     ELECTRON_TEST_RESULTS_DIR: junit
     MOCHA_MULTI_REPORTERS: 'mocha-junit-reporter, tap'
     MOCHA_REPORTER: mocha-multi-reporters
+  condition: always()    
 
 - task: PublishTestResults@2
   displayName: 'Publish Test Results'

build/args/all.gn

@@ -2,7 +2,7 @@ is_electron_build = true
 root_extra_deps = [ "//electron" ]
 
 # Registry of NMVs --> https://github.com/nodejs/node/blob/master/doc/abi_version_registry.json
-node_module_version = 89
+node_module_version = 98
 
 v8_promise_internal_field_count = 1
 v8_typed_array_max_size_in_heap = 0

build/asar.gni

@@ -57,4 +57,42 @@ template("asar") {
              rebase_path(outputs[0]),
            ]
   }
+
+  node_action(target_name + "_header_hash") {
+    invoker_out = invoker.outputs
+
+    deps = [ ":" + invoker.target_name ]
+    sources = invoker.outputs
+
+    script = "//electron/script/gn-asar-hash.js"
+    outputs = [ "$target_gen_dir/asar_hashes/$target_name.hash" ]
+
+    args = [
+      rebase_path(invoker_out[0]),
+      rebase_path(outputs[0]),
+    ]
+  }
+}
+
+template("asar_hashed_info_plist") {
+  node_action(target_name) {
+    assert(defined(invoker.plist_file),
+           "Need plist_file to add hashed assets to")
+    assert(defined(invoker.keys), "Need keys to replace with asset hash")
+    assert(defined(invoker.hash_targets), "Need hash_targets to read hash from")
+
+    deps = invoker.hash_targets
+
+    script = "//electron/script/gn-plist-but-with-hashes.js"
+    inputs = [ invoker.plist_file ]
+    outputs = [ "$target_gen_dir/hashed_plists/$target_name.plist" ]
+    hash_files = []
+    foreach(hash_target, invoker.hash_targets) {
+      hash_files += get_target_outputs(hash_target)
+    }
+    args = [
+             rebase_path(invoker.plist_file),
+             rebase_path(outputs[0]),
+           ] + invoker.keys + rebase_path(hash_files)
+  }
 }

build/fuses/fuses.json5

@@ -3,5 +3,9 @@
   "_schema": "0 == off, 1 == on, r == removed fuse",
   "_version": 1,
   "run_as_node": "1",
-  "cookie_encryption": "0"
+  "cookie_encryption": "0",
+  "node_options": "1",
+  "node_cli_inspect": "1",
+  "embedded_asar_integrity_validation": "0",
+  "only_load_app_from_asar": "0"
 }

build/npm-run.py

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

build/zip.py

@@ -31,12 +31,6 @@ PATHS_TO_SKIP = [
   # //chrome/browser/resources/ssl/ssl_error_assistant, but we don't need to
   # ship it.
   'pyproto',
-  # On Windows, this binary doesn't exist (the crashpad handler is built-in).
-  # On MacOS, the binary is called 'chrome_crashpad_handler' and is inside the
-  # app bundle.
-  # On Linux, we don't use crashpad, but this binary is still built for some
-  # reason. Exclude it from the zip.
-  './crashpad_handler',
   # Skip because these are outputs that we don't need.
   'resources/inspector',
   'gen/third_party/devtools-frontend/src',

chromium_src/BUILD.gn

@@ -21,6 +21,8 @@ static_library("chrome") {
     "//chrome/browser/devtools/devtools_contents_resizing_strategy.h",
     "//chrome/browser/devtools/devtools_embedder_message_dispatcher.cc",
     "//chrome/browser/devtools/devtools_embedder_message_dispatcher.h",
+    "//chrome/browser/devtools/devtools_eye_dropper.cc",
+    "//chrome/browser/devtools/devtools_eye_dropper.h",
     "//chrome/browser/devtools/devtools_file_system_indexer.cc",
     "//chrome/browser/devtools/devtools_file_system_indexer.h",
     "//chrome/browser/extensions/global_shortcut_listener.cc",
@@ -35,6 +37,8 @@ static_library("chrome") {
     "//chrome/browser/net/proxy_config_monitor.h",
     "//chrome/browser/net/proxy_service_factory.cc",
     "//chrome/browser/net/proxy_service_factory.h",
+    "//chrome/browser/platform_util.cc",
+    "//chrome/browser/platform_util.h",
     "//chrome/browser/predictors/preconnect_manager.cc",
     "//chrome/browser/predictors/preconnect_manager.h",
     "//chrome/browser/predictors/predictors_features.cc",
@@ -45,6 +49,10 @@ static_library("chrome") {
     "//chrome/browser/predictors/resolve_host_client_impl.h",
     "//chrome/browser/ui/views/autofill/autofill_popup_view_utils.cc",
     "//chrome/browser/ui/views/autofill/autofill_popup_view_utils.h",
+    "//chrome/browser/ui/views/eye_dropper/eye_dropper.cc",
+    "//chrome/browser/ui/views/eye_dropper/eye_dropper.h",
+    "//chrome/browser/ui/views/eye_dropper/eye_dropper_view.cc",
+    "//chrome/browser/ui/views/eye_dropper/eye_dropper_view.h",
     "//extensions/browser/app_window/size_constraints.cc",
     "//extensions/browser/app_window/size_constraints.h",
   ]
@@ -56,6 +64,9 @@ static_library("chrome") {
       "//chrome/browser/icon_loader_mac.mm",
       "//chrome/browser/media/webrtc/system_media_capture_permissions_mac.h",
       "//chrome/browser/media/webrtc/system_media_capture_permissions_mac.mm",
+      "//chrome/browser/media/webrtc/window_icon_util_mac.mm",
+      "//chrome/browser/ui/views/eye_dropper/eye_dropper_view_mac.h",
+      "//chrome/browser/ui/views/eye_dropper/eye_dropper_view_mac.mm",
     ]
   }
 
@@ -64,13 +75,28 @@ static_library("chrome") {
       "//chrome/browser/extensions/global_shortcut_listener_win.cc",
       "//chrome/browser/extensions/global_shortcut_listener_win.h",
       "//chrome/browser/icon_loader_win.cc",
+      "//chrome/browser/media/webrtc/window_icon_util_win.cc",
+      "//chrome/browser/ui/frame/window_frame_util.h",
+      "//chrome/browser/ui/view_ids.h",
       "//chrome/browser/win/chrome_process_finder.cc",
       "//chrome/browser/win/chrome_process_finder.h",
+      "//chrome/browser/win/titlebar_config.h",
       "//chrome/child/v8_crashpad_support_win.cc",
       "//chrome/child/v8_crashpad_support_win.h",
     ]
   }
 
+  if (is_linux) {
+    sources += [ "//chrome/browser/media/webrtc/window_icon_util_linux.cc" ]
+  }
+
+  if (use_aura) {
+    sources += [
+      "//chrome/browser/platform_util_aura.cc",
+      "//chrome/browser/ui/views/eye_dropper/eye_dropper_view_aura.cc",
+    ]
+  }
+
   public_deps = [
     "//chrome/browser:dev_ui_browser_resources",
     "//chrome/common",
@@ -144,64 +170,6 @@ static_library("chrome") {
     deps += [ "//ui/snapshot" ]
   }
 
-  if (enable_color_chooser) {
-    sources += [
-      "//chrome/browser/devtools/devtools_eye_dropper.cc",
-      "//chrome/browser/devtools/devtools_eye_dropper.h",
-      "//chrome/browser/platform_util.cc",
-      "//chrome/browser/platform_util.h",
-      "//chrome/browser/ui/browser_dialogs.h",
-      "//chrome/browser/ui/color_chooser.h",
-      "//chrome/browser/ui/views/eye_dropper/eye_dropper.cc",
-      "//chrome/browser/ui/views/eye_dropper/eye_dropper.h",
-      "//chrome/browser/ui/views/eye_dropper/eye_dropper_view.cc",
-      "//chrome/browser/ui/views/eye_dropper/eye_dropper_view.h",
-    ]
-
-    if (use_aura) {
-      sources += [
-        "//chrome/browser/platform_util_aura.cc",
-        "//chrome/browser/ui/views/eye_dropper/eye_dropper_view_aura.cc",
-      ]
-
-      if (!is_win) {
-        sources += [
-          "//chrome/browser/ui/views/color_chooser_aura.cc",
-          "//chrome/browser/ui/views/color_chooser_aura.h",
-        ]
-      }
-
-      deps += [ "//components/feature_engagement" ]
-    }
-
-    if (is_mac) {
-      sources += [
-        "//chrome/browser/media/webrtc/window_icon_util_mac.mm",
-        "//chrome/browser/ui/cocoa/color_chooser_mac.h",
-        "//chrome/browser/ui/cocoa/color_chooser_mac.mm",
-        "//chrome/browser/ui/views/eye_dropper/eye_dropper_view_mac.h",
-        "//chrome/browser/ui/views/eye_dropper/eye_dropper_view_mac.mm",
-      ]
-      deps += [
-        "//components/remote_cocoa/app_shim",
-        "//components/remote_cocoa/browser",
-      ]
-    }
-
-    if (is_win) {
-      sources += [
-        "//chrome/browser/media/webrtc/window_icon_util_win.cc",
-        "//chrome/browser/ui/views/color_chooser_dialog.cc",
-        "//chrome/browser/ui/views/color_chooser_dialog.h",
-        "//chrome/browser/ui/views/color_chooser_win.cc",
-      ]
-    }
-
-    if (is_linux) {
-      sources += [ "//chrome/browser/media/webrtc/window_icon_util_linux.cc" ]
-    }
-  }
-
   if (enable_widevine) {
     sources += [
       "//chrome/renderer/media/chrome_key_systems.cc",
@@ -346,17 +314,13 @@ source_set("plugins") {
   sources += [
     "//chrome/renderer/pepper/chrome_renderer_pepper_host_factory.cc",
     "//chrome/renderer/pepper/chrome_renderer_pepper_host_factory.h",
+    "//chrome/renderer/pepper/pepper_flash_font_file_host.cc",
+    "//chrome/renderer/pepper/pepper_flash_font_file_host.h",
     "//chrome/renderer/pepper/pepper_shared_memory_message_filter.cc",
     "//chrome/renderer/pepper/pepper_shared_memory_message_filter.h",
   ]
   if (enable_pdf_viewer) {
-    sources += [
-      "//chrome/renderer/pepper/pepper_flash_font_file_host.cc",
-      "//chrome/renderer/pepper/pepper_flash_font_file_host.h",
-    ]
-    if (enable_pdf_viewer) {
-      deps += [ "//components/pdf/renderer" ]
-    }
+    deps += [ "//components/pdf/renderer" ]
   }
   deps += [
     "//components/strings",

chromium_src/chrome/browser/process_singleton_win.cc

@@ -4,6 +4,7 @@
 
 #include "chrome/browser/process_singleton.h"
 
+#include <windows.h>
 #include <shellapi.h>
 
 #include "base/base_paths.h"

docs/README.md

@@ -59,10 +59,9 @@ an issue:
 * [Testing and Debugging](tutorial/application-debugging.md)
   * [Debugging the Main Process](tutorial/debugging-main-process.md)
   * [Debugging with Visual Studio Code](tutorial/debugging-vscode.md)
-  * [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
   * [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)
+  * [Automated Testing](tutorial/automated-testing.md)
   * [REPL](tutorial/repl.md)
 * [Distribution](tutorial/application-distribution.md)
   * [Supported Platforms](tutorial/support.md#supported-platforms)

docs/api/app.md

@@ -36,10 +36,10 @@ Returns:
 * `launchInfo` Record<string, any> | [NotificationResponse](structures/notification-response.md) _macOS_
 
 Emitted once, when Electron has finished initializing. On macOS, `launchInfo`
-holds the `userInfo` of the `NSUserNotification` or information from
-[`UNNotificationResponse`](structures/notification-response.md) that was used to open the
-application, if it was launched from Notification Center. You can also call
-`app.isReady()` to check if this event has already fired and `app.whenReady()`
+holds the `userInfo` of the [`NSUserNotification`](https://developer.apple.com/documentation/foundation/nsusernotification)
+or information from [`UNNotificationResponse`](https://developer.apple.com/documentation/usernotifications/unnotificationresponse)
+that was used to open the application, if it was launched from Notification Center.
+You can also call `app.isReady()` to check if this event has already fired and `app.whenReady()`
 to get a Promise that is fulfilled when Electron is initialized.
 
 ### Event: 'window-all-closed'
@@ -161,6 +161,8 @@ Returns:
   [`NSUserActivity.activityType`][activity-type].
 * `userInfo` unknown - Contains app-specific state stored by the activity on
   another device.
+* `details` Object
+  * `webpageURL` String (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.
 
 Emitted during [Handoff][handoff] when an activity from a different device wants
 to be resumed. You should call `event.preventDefault()` if you want to handle
@@ -275,6 +277,7 @@ Returns:
 * `certificate` [Certificate](structures/certificate.md)
 * `callback` Function
   * `isTrusted` Boolean - Whether to consider the certificate as trusted
+* `isMainFrame` Boolean
 
 Emitted when failed to verify the `certificate` for `url`, to trust the
 certificate you should prevent the default behavior with
@@ -1059,6 +1062,61 @@ Imports the certificate in pkcs12 format into the platform certificate store.
 `callback` is called with the `result` of import operation, a value of `0`
 indicates success while any other value indicates failure according to Chromium [net_error_list](https://source.chromium.org/chromium/chromium/src/+/master:net/base/net_error_list.h).
 
+### `app.configureHostResolver(options)`
+
+* `options` Object
+  * `enableBuiltInResolver` Boolean (optional) - Whether the built-in host
+    resolver is used in preference to getaddrinfo. When enabled, the built-in
+    resolver will attempt to use the system's DNS settings to do DNS lookups
+    itself. Enabled by default on macOS, disabled by default on Windows and
+    Linux.
+  * `secureDnsMode` String (optional) - Can be "off", "automatic" or "secure".
+    Configures the DNS-over-HTTP mode. When "off", no DoH lookups will be
+    performed. When "automatic", DoH lookups will be performed first if DoH is
+    available, and insecure DNS lookups will be performed as a fallback. When
+    "secure", only DoH lookups will be performed. Defaults to "automatic".
+  * `secureDnsServers` String[]&#32;(optional) - A list of DNS-over-HTTP
+    server templates. See [RFC8484 § 3][] for details on the template format.
+    Most servers support the POST method; the template for such servers is
+    simply a URI. Note that for [some DNS providers][doh-providers], the
+    resolver will automatically upgrade to DoH unless DoH is explicitly
+    disabled, even if there are no DoH servers provided in this list.
+  * `enableAdditionalDnsQueryTypes` Boolean (optional) - Controls whether additional DNS
+    query types, e.g. HTTPS (DNS type 65) will be allowed besides the
+    traditional A and AAAA queries when a request is being made via insecure
+    DNS. Has no effect on Secure DNS which always allows additional types.
+    Defaults to true.
+
+Configures host resolution (DNS and DNS-over-HTTPS). By default, the following
+resolvers will be used, in order:
+
+1. DNS-over-HTTPS, if the [DNS provider supports it][doh-providers], then
+2. the built-in resolver (enabled on macOS only by default), then
+3. the system's resolver (e.g. `getaddrinfo`).
+
+This can be configured to either restrict usage of non-encrypted DNS
+(`secureDnsMode: "secure"`), or disable DNS-over-HTTPS (`secureDnsMode:
+"off"`). It is also possible to enable or disable the built-in resolver.
+
+To disable insecure DNS, you can specify a `secureDnsMode` of `"secure"`. If you do
+so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in
+case the user's DNS configuration does not include a provider that supports
+DoH.
+
+```js
+app.configureHostResolver({
+  secureDnsMode: 'secure',
+  secureDnsServers: [
+    'https://cloudflare-dns.com/dns-query'
+  ]
+})
+```
+
+This API must be called after the `ready` event is emitted.
+
+[doh-providers]: https://source.chromium.org/chromium/chromium/src/+/main:net/dns/public/doh_provider_entry.cc;l=31?q=%22DohProviderEntry::GetList()%22&ss=chromium%2Fchromium%2Fsrc
+[RFC8484 § 3]: https://datatracker.ietf.org/doc/html/rfc8484#section-3
+
 ### `app.disableHardwareAcceleration()`
 
 Disables hardware acceleration for current app.
@@ -1135,8 +1193,8 @@ badge.
 
 On macOS, it shows on the dock icon. On Linux, it only works for Unity launcher.
 
-**Note:** Unity launcher requires the existence of a `.desktop` file to work,
-for more information please read [Desktop Environment Integration][unity-requirement].
+**Note:** Unity launcher requires a `.desktop` file to work. For more information,
+please read the [Unity integration documentation][unity-requirement].
 
 ### `app.getBadgeCount()` _Linux_ _macOS_
 
@@ -1374,8 +1432,8 @@ An `Integer` property that returns the badge count for current app. Setting the
 
 On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.
 
-**Note:** Unity launcher requires the existence of a `.desktop` file to work,
-for more information please read [Desktop Environment Integration][unity-requirement].
+**Note:** Unity launcher requires a `.desktop` file to work. For more information,
+please read the [Unity integration documentation][unity-requirement].
 
 **Note:** On macOS, you need to ensure that your application has the permission
 to display notifications for this property to take effect.
@@ -1403,7 +1461,7 @@ A `Boolean` property that returns  `true` if the app is packaged, `false` otherw
 [LSCopyDefaultHandlerForURLScheme]: https://developer.apple.com/library/mac/documentation/Carbon/Reference/LaunchServicesReference/#//apple_ref/c/func/LSCopyDefaultHandlerForURLScheme
 [handoff]: https://developer.apple.com/library/ios/documentation/UserExperience/Conceptual/Handoff/HandoffFundamentals/HandoffFundamentals.html
 [activity-type]: https://developer.apple.com/library/ios/documentation/Foundation/Reference/NSUserActivity_Class/index.html#//apple_ref/occ/instp/NSUserActivity/activityType
-[unity-requirement]: ../tutorial/desktop-environment-integration.md#unity-launcher
+[unity-requirement]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher
 [mas-builds]: ../tutorial/mac-app-store-submission-guide.md
 [Squirrel-Windows]: https://github.com/Squirrel/Squirrel.Windows
 [JumpListBeginListMSDN]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378398(v=vs.85).aspx

docs/api/auto-updater.md

@@ -43,7 +43,7 @@ The installer generated with Squirrel will create a shortcut icon with an
 same ID for your app with `app.setAppUserModelId` API, otherwise Windows will
 not be able to pin your app properly in task bar.
 
-Unlike Squirrel.Mac, Windows can host updates on S3 or any other static file host.
+Like Squirrel.Mac, Windows can host updates on S3 or any other static file host.
 You can read the documents of [Squirrel.Windows][squirrel-windows] to get more details
 about how Squirrel.Windows works.
 

docs/api/browser-window.md

@@ -17,17 +17,19 @@ win.loadURL('https://github.com')
 win.loadFile('index.html')
 ```
 
-## Frameless window
+## Window customization
 
-To create a window without chrome, or a transparent window in arbitrary shape,
-you can use the [Frameless Window](frameless-window.md) API.
+The `BrowserWindow` class exposes various ways to modify the look and behavior of
+your app's windows. For more details, see the [Window Customization](../tutorial/window-customization.md)
+tutorial.
 
-## Showing window gracefully
+## Showing the window gracefully
 
-When loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display
-without visual flash, there are two solutions for different situations.
+When loading a page in the window directly, users may see the page load incrementally,
+which is not a good experience for a native app. To make the window display
+without a visual flash, there are two solutions for different situations.
 
-## Using `ready-to-show` event
+### Using the `ready-to-show` event
 
 While loading the page, the `ready-to-show` event will be emitted when the renderer
 process has rendered the page for the first time if the window has not been shown yet. Showing
@@ -48,7 +50,7 @@ event.
 Please note that using this event implies that the renderer will be considered "visible" and
 paint even though `show` is false.  This event will never fire if you use `paintWhenInitiallyHidden: false`
 
-## Setting `backgroundColor`
+### Setting the `backgroundColor` property
 
 For a complex app, the `ready-to-show` event could be emitted too late, making
 the app feel slow. In this case, it is recommended to show the window
@@ -183,13 +185,13 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     `true`.
   * `paintWhenInitiallyHidden` Boolean (optional) - Whether the renderer should be active when `show` is `false` and it has just been created.  In order for `document.visibilityState` to work correctly on first load with `show: false` you should set this to `false`.  Setting this to `false` will cause the `ready-to-show` event to not fire.  Default is `true`.
   * `frame` Boolean (optional) - Specify `false` to create a
-    [Frameless Window](frameless-window.md). Default is `true`.
+    [frameless window](../tutorial/window-customization.md#create-frameless-windows). Default is `true`.
   * `parent` BrowserWindow (optional) - Specify parent window. Default is `null`.
   * `modal` Boolean (optional) - Whether this is a modal window. This only works when the
     window is a child window. Default is `false`.
-  * `acceptFirstMouse` Boolean (optional) - Whether the web view accepts a single
-    mouse-down event that simultaneously activates the window. Default is
-    `false`.
+  * `acceptFirstMouse` Boolean (optional) - Whether clicking an inactive window will also
+  click through to the web contents. Default is `false` on macOS. This option is not
+  configurable on other platforms.
   * `disableAutoHideCursor` Boolean (optional) - Whether to hide cursor when typing.
     Default is `false`.
   * `autoHideMenuBar` Boolean (optional) - Auto hide the menu bar unless the `Alt`
@@ -205,7 +207,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     transparent) and 1.0 (fully opaque). This is only implemented on Windows and macOS.
   * `darkTheme` Boolean (optional) - Forces using dark theme for the window, only works on
     some GTK+3 desktop environments. Default is `false`.
-  * `transparent` Boolean (optional) - Makes the window [transparent](frameless-window.md#transparent-window).
+  * `transparent` Boolean (optional) - Makes the window [transparent](../tutorial/window-customization.md#create-transparent-windows).
     Default is `false`. On Windows, does not work unless the window is frameless.
   * `type` String (optional) - The type of window, default is normal window. See more about
     this below.
@@ -213,16 +215,13 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     * `followWindow` - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.
     * `active` - The backdrop should always appear active.
     * `inactive` - The backdrop should always appear inactive.
-  * `titleBarStyle` String (optional) - The style of window title bar.
+  * `titleBarStyle` String (optional) _macOS_ _Windows_ - The style of window title bar.
     Default is `default`. Possible values are:
-    * `default` - Results in the standard gray opaque Mac title
-      bar.
-    * `hidden` - Results in a hidden title bar and a full size content window, yet
-      the title bar still has the standard window controls ("traffic lights") in
-      the top left.
-    * `hiddenInset` - Results in a hidden title bar with an alternative look
+    * `default` - Results in the standard title bar for macOS or Windows respectively.
+    * `hidden` - Results in a hidden title bar and a full size content window. On macOS, the window still has the standard window controls (“traffic lights”) in the top left. On Windows, when combined with `titleBarOverlay: true` it will activate the Window Controls Overlay (see `titleBarOverlay` for more information), otherwise no window controls will be shown.
+    * `hiddenInset` - Only on macOS, results in a hidden title bar with an alternative look
       where the traffic light buttons are slightly more inset from the window edge.
-    * `customButtonsOnHover` - Results in a hidden title bar and a full size
+    * `customButtonsOnHover` - Only on macOS, results in a hidden title bar and a full size
       content window, the traffic light buttons will display when being hovered
       over in the top left of the window.  **Note:** This option is currently
       experimental.
@@ -392,6 +391,9 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       contain the layout of the document—without requiring scrolling. Enabling
       this will cause the `preferred-size-changed` event to be emitted on the
       `WebContents` when the preferred size changes. Default is `false`.
+  * `titleBarOverlay` Object | Boolean (optional) -  When using a frameless window in conjuction with `win.setWindowButtonVisibility(true)` on macOS or using a `titleBarStyle` so that the standard window controls ("traffic lights" on macOS) are visible, this property enables the Window Controls Overlay [JavaScript APIs][overlay-javascript-apis] and [CSS Environment Variables][overlay-css-env-vars]. Specifying `true` will result in an overlay with default system colors. Default is `false`.
+    * `color` String (optional) _Windows_ - The CSS color of the Window Controls Overlay when enabled. Default is the system color.
+    * `symbolColor` String (optional) _Windows_ - The CSS color of the symbols on the Window Controls Overlay when enabled. Default is the system color.
 
 When setting minimum or maximum window size with `minWidth`/`maxWidth`/
 `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from
@@ -987,7 +989,7 @@ the player itself we would call this function with arguments of 16/9 and
 are within the content view--only that they exist. Sum any extra width and
 height areas you have within the overall content view.
 
-The aspect ratio is not respected when window is resized programmingly with
+The aspect ratio is not respected when window is resized programmatically with
 APIs like `win.setSize`.
 
 #### `win.setBackgroundColor(backgroundColor)`
@@ -997,7 +999,7 @@ APIs like `win.setSize`.
   is `true`). Default is `#FFF` (white).
 
 Sets the background color of the window. See [Setting
-`backgroundColor`](#setting-backgroundcolor).
+`backgroundColor`](#setting-the-backgroundcolor-property).
 
 #### `win.previewFile(path[, displayName])` _macOS_
 
@@ -1042,7 +1044,7 @@ Returns [`Rectangle`](structures/rectangle.md) - The `bounds` of the window as `
 #### `win.getBackgroundColor()`
 
 Returns `String` - Gets the background color of the window. See [Setting
-`backgroundColor`](#setting-backgroundcolor).
+`backgroundColor`](#setting-the-backgroundcolor-property).
 
 #### `win.setContentBounds(bounds[, animate])`
 
@@ -1695,7 +1697,7 @@ current window into a top-level window.
 
 #### `win.getParentWindow()`
 
-Returns `BrowserWindow` - The parent window.
+Returns `BrowserWindow | null` - The parent window or `null` if there is no parent.
 
 #### `win.getChildWindows()`
 
@@ -1815,3 +1817,5 @@ removed in future Electron releases.
 [window-levels]: https://developer.apple.com/documentation/appkit/nswindow/level
 [chrome-content-scripts]: https://developer.chrome.com/extensions/content_scripts#execution-environment
 [event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
+[overlay-javascript-apis]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md#javascript-apis
+[overlay-css-env-vars]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md#css-environment-variables

docs/api/clipboard.md

@@ -197,9 +197,9 @@ Returns `Boolean` - Whether the clipboard supports the specified `format`.
 ```js
 const { clipboard } = require('electron')
 
-const hasFormat = clipboard.has('<p>selection</p>')
+const hasFormat = clipboard.has('public/utf8-plain-text')
 console.log(hasFormat)
-// 'true' or 'false
+// 'true' or 'false'
 ```
 
 ### `clipboard.read(format)` _Experimental_
@@ -208,6 +208,10 @@ console.log(hasFormat)
 
 Returns `String` - Reads `format` type from the clipboard.
 
+`format` should contain valid ASCII characters and have `/` separator.
+`a/c`, `a/bc` are valid formats while `/abc`, `abc/`, `a/`, `/a`, `a`
+are not valid.
+
 ### `clipboard.readBuffer(format)` _Experimental_
 
 * `format` String
@@ -218,9 +222,9 @@ Returns `Buffer` - Reads `format` type from the clipboard.
 const { clipboard } = require('electron')
 
 const buffer = Buffer.from('this is binary', 'utf8')
-clipboard.writeBuffer('public.utf8-plain-text', buffer)
+clipboard.writeBuffer('public/utf8-plain-text', buffer)
 
-const ret = clipboard.readBuffer('public.utf8-plain-text')
+const ret = clipboard.readBuffer('public/utf8-plain-text')
 
 console.log(buffer.equals(out))
 // true
@@ -238,7 +242,7 @@ Writes the `buffer` into the clipboard as `format`.
 const { clipboard } = require('electron')
 
 const buffer = Buffer.from('writeBuffer', 'utf8')
-clipboard.writeBuffer('public.utf8-plain-text', buffer)
+clipboard.writeBuffer('public/utf8-plain-text', buffer)
 ```
 
 ### `clipboard.write(data[, type])`

docs/api/command-line.md

@@ -53,3 +53,12 @@ Returns `Boolean` - Whether the command-line switch is present.
 Returns `String` - The command-line switch value.
 
 **Note:** When the switch is not present or has no value, it returns empty string.
+
+#### `commandLine.removeSwitch(switch)`
+
+* `switch` String - A command-line switch
+
+Removes the specified switch from Chromium's command line.
+
+**Note:** This will not affect `process.argv`. The intended usage of this function is to
+control Chromium's behavior.

docs/api/context-bridge.md

@@ -41,7 +41,7 @@ When `contextIsolation` is enabled in your `webPreferences` (this is the default
 
 The `contextBridge` module has the following methods:
 
-### `contextBridge.exposeInMainWorld(apiKey, api)` _Experimental_
+### `contextBridge.exposeInMainWorld(apiKey, api)`
 
 * `apiKey` String - The key to inject the API onto `window` with.  The API will be accessible on `window[apiKey]`.
 * `api` any - Your API, more information on what this API can be and how it works is available below.
@@ -50,7 +50,7 @@ The `contextBridge` module has the following methods:
 
 ### API
 
-The `api` provided to [`exposeInMainWorld`](#contextbridgeexposeinmainworldapikey-api-experimental) must be a `Function`, `String`, `Number`, `Array`, `Boolean`, or an object
+The `api` provided to [`exposeInMainWorld`](#contextbridgeexposeinmainworldapikey-api) must be a `Function`, `String`, `Number`, `Array`, `Boolean`, or an object
 whose keys are strings and values are a `Function`, `String`, `Number`, `Array`, `Boolean`, or another nested object that meets the same conditions.
 
 `Function` values are proxied to the other context and all other values are **copied** and **frozen**. Any data / primitives sent in

docs/api/cookies.md

@@ -93,7 +93,7 @@ the response.
   * `domain` String (optional) - The domain of the cookie; this will be normalized with a preceding dot so that it's also valid for subdomains. Empty by default if omitted.
   * `path` String (optional) - The path of the cookie. Empty by default if omitted.
   * `secure` Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to
-    false.
+    false unless [Same Site=None](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite#samesitenone_requires_secure) attribute is used.
   * `httpOnly` Boolean (optional) - Whether the cookie should be marked as HTTP only.
     Defaults to false.
   * `expirationDate` Double (optional) - The expiration date of the cookie as the number of

docs/api/dialog.md

@@ -234,6 +234,7 @@ expanding and collapsing the dialog.
   * `title` String (optional) - Title of the message box, some platforms will not show it.
   * `detail` String (optional) - Extra information of the message.
   * `icon` ([NativeImage](native-image.md) | String) (optional)
+  * `textWidth` Integer (optional) _macOS_ - Custom width of the text in the message box.
   * `cancelId` Integer (optional) - The index of the button to be used to cancel the dialog, via
     the `Esc` key. By default this is assigned to the first button with "cancel" or "no" as the
     label. If no such labeled buttons exist and this option is not set, `0` will be used as the
@@ -273,6 +274,11 @@ If `browserWindow` is not shown dialog will not be attached to it. In such case
     will result in one button labeled "OK".
   * `defaultId` Integer (optional) - Index of the button in the buttons array which will
     be selected by default when the message box opens.
+  * `signal` AbortSignal (optional) - Pass an instance of [AbortSignal][] to
+    optionally close the message box, the message box will behave as if it was
+    cancelled by the user. On macOS, `signal` does not work with message boxes
+    that do not have a parent window, since those message boxes run
+    synchronously due to platform limitations.
   * `title` String (optional) - Title of the message box, some platforms will not show it.
   * `detail` String (optional) - Extra information of the message.
   * `checkboxLabel` String (optional) - If provided, the message box will
@@ -280,6 +286,7 @@ If `browserWindow` is not shown dialog will not be attached to it. In such case
   * `checkboxChecked` Boolean (optional) - Initial checked state of the
     checkbox. `false` by default.
   * `icon` [NativeImage](native-image.md) (optional)
+  * `textWidth` Integer (optional) _macOS_ - Custom width of the text in the message box.
   * `cancelId` Integer (optional) - The index of the button to be used to cancel the dialog, via
     the `Esc` key. By default this is assigned to the first button with "cancel" or "no" as the
     label. If no such labeled buttons exist and this option is not set, `0` will be used as the
@@ -360,3 +367,5 @@ window is provided.
 
 You can call `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` to change
 the offset from the window frame where sheets are attached.
+
+[AbortSignal]: https://nodejs.org/api/globals.html#globals_class_abortsignal

docs/api/environment-variables.md

@@ -122,7 +122,7 @@ Prints Chromium's internal logging to the console.
 
 Setting this variable is the same as passing `--enable-logging`
 on the command line. For more info, see `--enable-logging` in [command-line
-switches](./command-line-switches.md#enable-loggingfile).
+switches](./command-line-switches.md#--enable-loggingfile).
 
 ### `ELECTRON_LOG_FILE`
 
@@ -130,7 +130,7 @@ Sets the file destination for Chromium's internal logging.
 
 Setting this variable is the same as passing `--log-file`
 on the command line. For more info, see `--log-file` in [command-line
-switches](./command-line-switches.md#log-filepath).
+switches](./command-line-switches.md#--log-filepath).
 
 ### `ELECTRON_DEBUG_DRAG_REGIONS`
 

docs/api/extensions.md

@@ -78,6 +78,7 @@ The following methods of `chrome.runtime` are supported:
 - `chrome.runtime.getURL`
 - `chrome.runtime.connect`
 - `chrome.runtime.sendMessage`
+- `chrome.runtime.reload`
 
 The following events of `chrome.runtime` are supported:
 

docs/api/frameless-window.md

@@ -1,188 +0,0 @@
-# Frameless Window
-
-> Open a window without toolbars, borders, or other graphical "chrome".
-
-A frameless window is a window that has no
-[chrome](https://developer.mozilla.org/en-US/docs/Glossary/Chrome), the parts of
-the window, like toolbars, that are not a part of the web page. These are
-options on the [`BrowserWindow`](browser-window.md) class.
-
-## Create a frameless window
-
-To create a frameless window, you need to set `frame` to `false` in
-[BrowserWindow](browser-window.md)'s `options`:
-
-```javascript
-const { BrowserWindow } = require('electron')
-const win = new BrowserWindow({ width: 800, height: 600, frame: false })
-win.show()
-```
-
-### Alternatives on macOS
-
-There's an alternative way to specify a chromeless window.
-Instead of setting `frame` to `false` which disables both the titlebar and window controls,
-you may want to have the title bar hidden and your content extend to the full window size,
-yet still preserve the window controls ("traffic lights") for standard window actions.
-You can do so by specifying the `titleBarStyle` option:
-
-#### `hidden`
-
-Results in a hidden title bar and a full size content window, yet the title bar still has the standard window controls (“traffic lights”) in the top left.
-
-```javascript
-const { BrowserWindow } = require('electron')
-const win = new BrowserWindow({ titleBarStyle: 'hidden' })
-win.show()
-```
-
-#### `hiddenInset`
-
-Results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.
-
-```javascript
-const { BrowserWindow } = require('electron')
-const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })
-win.show()
-```
-
-#### `customButtonsOnHover`
-
-Uses custom drawn close, and miniaturize buttons that display
-when hovering in the top left of the window. The fullscreen button
-is not available due to restrictions of frameless windows as they
-interface with Apple's macOS window masks. These custom buttons prevent
-issues with mouse events that occur with the standard window toolbar buttons.
-This option is only applicable for frameless windows.
-
-```javascript
-const { BrowserWindow } = require('electron')
-const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover', frame: false })
-win.show()
-```
-
-## Transparent window
-
-By setting the `transparent` option to `true`, you can also make the frameless
-window transparent:
-
-```javascript
-const { BrowserWindow } = require('electron')
-const win = new BrowserWindow({ transparent: true, frame: false })
-win.show()
-```
-
-### Limitations
-
-* You can not click through the transparent area. We are going to introduce an
-  API to set window shape to solve this, see
-  [our issue](https://github.com/electron/electron/issues/1335) for details.
-* Transparent windows are not resizable. Setting `resizable` to `true` may make
-  a transparent window stop working on some platforms.
-* The `blur` filter only applies to the web page, so there is no way to apply
-  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
-  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
-  NVidia drivers](https://bugs.chromium.org/p/chromium/issues/detail?id=369209) on
-  Linux.
-* On Mac, the native window shadow will not be shown on a transparent window.
-
-## Click-through window
-
-To create a click-through window, i.e. making the window ignore all mouse
-events, you can call the [win.setIgnoreMouseEvents(ignore)][ignore-mouse-events]
-API:
-
-```javascript
-const { BrowserWindow } = require('electron')
-const win = new BrowserWindow()
-win.setIgnoreMouseEvents(true)
-```
-
-### Forwarding
-
-Ignoring mouse messages makes the web page oblivious to mouse movement, meaning
-that mouse movement events will not be emitted. On Windows operating systems an
-optional parameter can be used to forward mouse move messages to the web page,
-allowing events such as `mouseleave` to be emitted:
-
-```javascript
-const { ipcRenderer } = require('electron')
-const el = document.getElementById('clickThroughElement')
-el.addEventListener('mouseenter', () => {
-  ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })
-})
-el.addEventListener('mouseleave', () => {
-  ipcRenderer.send('set-ignore-mouse-events', false)
-})
-
-// Main process
-const { ipcMain } = require('electron')
-ipcMain.on('set-ignore-mouse-events', (event, ...args) => {
-  BrowserWindow.fromWebContents(event.sender).setIgnoreMouseEvents(...args)
-})
-```
-
-This makes the web page click-through when over `el`, and returns to normal
-outside it.
-
-## Draggable region
-
-By default, the frameless window is non-draggable. Apps need to specify
-`-webkit-app-region: drag` in CSS to tell Electron which regions are draggable
-(like the OS's standard titlebar), and apps can also use
-`-webkit-app-region: no-drag` to exclude the non-draggable area from the
- draggable region. Note that only rectangular shapes are currently supported.
-
-Note: `-webkit-app-region: drag` is known to have problems while the developer tools are open. See this [GitHub issue](https://github.com/electron/electron/issues/3647) for more information including a workaround.
-
-To make the whole window draggable, you can add `-webkit-app-region: drag` as
-`body`'s style:
-
-```html
-<body style="-webkit-app-region: drag">
-</body>
-```
-
-And note that if you have made the whole window draggable, you must also mark
-buttons as non-draggable, otherwise it would be impossible for users to click on
-them:
-
-```css
-button {
-  -webkit-app-region: no-drag;
-}
-```
-
-If you're only setting a custom titlebar as draggable, you also need to make all
-buttons in titlebar non-draggable.
-
-## Text selection
-
-In a frameless window the dragging behavior may conflict with selecting text.
-For example, when you drag the titlebar you may accidentally select the text on
-the titlebar. To prevent this, you need to disable text selection within a
-draggable area like this:
-
-```css
-.titlebar {
-  -webkit-user-select: none;
-  -webkit-app-region: drag;
-}
-```
-
-## Context menu
-
-On some platforms, the draggable area will be treated as a non-client frame, so
-when you right click on it a system menu will pop up. To make the context menu
-behave correctly on all platforms you should never use a custom context menu on
-draggable areas.
-
-[ignore-mouse-events]: browser-window.md#winsetignoremouseeventsignore-options

docs/api/ipc-main.md

@@ -40,6 +40,8 @@ ipcMain.on('synchronous-message', (event, arg) => {
 
 ```javascript
 // In renderer process (web page).
+// NB. Electron APIs are only accessible from preload, unless contextIsolation is disabled.
+// See https://www.electronjs.org/docs/tutorial/process-model#preload-scripts for more details.
 const { ipcRenderer } = require('electron')
 console.log(ipcRenderer.sendSync('synchronous-message', 'ping')) // prints "pong"
 

docs/api/menu-item.md

@@ -14,7 +14,7 @@ See [`Menu`](menu.md) for examples.
     * `menuItem` MenuItem
     * `browserWindow` [BrowserWindow](browser-window.md) | undefined - This will not be defined if no window is open.
     * `event` [KeyboardEvent](structures/keyboard-event.md)
-  * `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
+  * `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `toggleSpellChecker`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
     `click` property will be ignored. See [roles](#roles).
   * `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
     `radio`.
@@ -155,11 +155,17 @@ A `String` indicating the type of the item. Can be `normal`, `separator`, `subme
 
 #### `menuItem.role`
 
-A `String` (optional) indicating the item's role, if set. Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu`
+A `String` (optional) indicating the item's role, if set. Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `toggleSpellChecker`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu`
 
 #### `menuItem.accelerator`
 
-A `Accelerator` (optional) indicating the item's accelerator, if set.
+An `Accelerator` (optional) indicating the item's accelerator, if set.
+
+#### `menuItem.userAccelerator` _Readonly_ _macOS_
+
+An `Accelerator | null` indicating the item's [user-assigned accelerator](https://developer.apple.com/documentation/appkit/nsmenuitem/1514850-userkeyequivalent?language=objc) for the menu item.
+
+**Note:** This property is only initialized after the `MenuItem` has been added to a `Menu`. Either via `Menu.buildFromTemplate` or via `Menu.append()/insert()`.  Accessing before initialization will just return `null`.
 
 #### `menuItem.icon`
 

docs/api/menu.md

@@ -162,7 +162,7 @@ const template = [
       { role: 'services' },
       { type: 'separator' },
       { role: 'hide' },
-      { role: 'hideothers' },
+      { role: 'hideOthers' },
       { role: 'unhide' },
       { type: 'separator' },
       { role: 'quit' }

docs/api/safe-storage.md

@@ -0,0 +1,40 @@
+# safeStorage
+
+> Allows access to simple encryption and decryption of strings for storage on the local machine.
+
+Process: [Main](../glossary.md#main-process)
+
+This module protects data stored on disk from being accessed by other applications or users with full disk access.
+
+Note that on Mac, access to the system Keychain is required and
+these calls can block the current thread to collect user input.
+The same is true for Linux, if a password management tool is available.
+
+## Methods
+
+The `safeStorage` module has the following methods:
+
+### `safeStorage.isEncryptionAvailable()`
+
+Returns `Boolean` - Whether encryption is available.
+
+On Linux, returns true if the secret key is
+available. On MacOS, returns true if Keychain is available.
+On Windows, returns true with no other preconditions.
+
+### `safeStorage.encryptString(plainText)`
+
+* `plainText` String
+
+Returns `Buffer` -  An array of bytes representing the encrypted string.
+
+This function will throw an error if encryption fails.
+
+### `safeStorage.decryptString(encrypted)`
+
+* `encrypted` Buffer
+
+Returns `String` - the decrypted string. Decrypts the encrypted buffer
+obtained  with `safeStorage.encryptString` back into a string.
+
+This function will throw an error if decryption fails.

docs/api/session.md

@@ -86,8 +86,8 @@ available from next tick of the process.
 const { session } = require('electron')
 session.defaultSession.on('will-download', (event, item, webContents) => {
   event.preventDefault()
-  require('request')(item.getURL(), (data) => {
-    require('fs').writeFileSync('/somewhere', data)
+  require('got')(item.getURL()).then((response) => {
+    require('fs').writeFileSync('/somewhere', response.body)
   })
 })
 ```
@@ -180,7 +180,97 @@ Emitted when a hunspell dictionary file download fails.  For details
 on the failure you should collect a netlog and inspect the download
 request.
 
-#### Event: 'select-serial-port' _Experimental_
+#### Event: 'select-hid-device'
+
+Returns:
+
+* `event` Event
+* `details` Object
+  * `deviceList` [HIDDevice[]](structures/hid-device.md)
+  * `frame` [WebFrameMain](web-frame-main.md)
+* `callback` Function
+  * `deviceId` String | null (optional)
+
+Emitted when a HID device needs to be selected when a call to
+`navigator.hid.requestDevice` is made. `callback` should be called with
+`deviceId` to be selected; passing no arguments to `callback` will
+cancel the request.  Additionally, permissioning on `navigator.hid` can
+be further managed by using [ses.setPermissionCheckHandler(handler)](#sessetpermissioncheckhandlerhandler)
+and [ses.setDevicePermissionHandler(handler)`](#sessetdevicepermissionhandlerhandler).
+
+```javascript
+const { app, BrowserWindow } = require('electron')
+
+let win = null
+
+app.whenReady().then(() => {
+  win = new BrowserWindow()
+
+  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
+    if (permission === 'hid') {
+      // Add logic here to determine if permission should be given to allow HID selection
+      return true
+    }
+    return false
+  })
+
+  // Optionally, retrieve previously persisted devices from a persistent store
+  const grantedDevices = fetchGrantedDevices()
+
+  win.webContents.session.setDevicePermissionHandler((details) => {
+    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
+      if (details.device.vendorId === 123 && details.device.productId === 345) {
+        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
+        return true
+      }
+
+      // Search through the list of devices that have previously been granted permission
+      return grantedDevices.some((grantedDevice) => {
+        return grantedDevice.vendorId === details.device.vendorId &&
+              grantedDevice.productId === details.device.productId &&
+              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
+      })
+    }
+    return false
+  })
+
+  win.webContents.session.on('select-hid-device', (event, details, callback) => {
+    event.preventDefault()
+    const selectedDevice = details.deviceList.find((device) => {
+      return device.vendorId === '9025' && device.productId === '67'
+    })
+    callback(selectedPort?.deviceId)
+  })
+})
+```
+
+#### Event: 'hid-device-added'
+
+Returns:
+
+* `event` Event
+* `details` Object
+  * `device` [HIDDevice[]](structures/hid-device.md)
+  * `frame` [WebFrameMain](web-frame-main.md)
+
+Emitted when a new HID device becomes available. For example, when a new USB device is plugged in.
+
+This event will only be emitted after `navigator.hid.requestDevice` has been called and `select-hid-device` has fired.
+
+#### Event: 'hid-device-removed'
+
+Returns:
+
+* `event` Event
+* `details` Object
+  * `device` [HIDDevice[]](structures/hid-device.md)
+  * `frame` [WebFrameMain](web-frame-main.md)
+
+Emitted when a HID device has been removed.  For example, this event will fire when a USB device is unplugged.
+
+This event will only be emitted after `navigator.hid.requestDevice` has been called and `select-hid-device` has fired.
+
+#### Event: 'select-serial-port'
 
 Returns:
 
@@ -197,20 +287,45 @@ cancel the request.  Additionally, permissioning on `navigator.serial` can
 be managed by using [ses.setPermissionCheckHandler(handler)](#sessetpermissioncheckhandlerhandler)
 with the `serial` permission.
 
-Because this is an experimental feature it is disabled by default.  To enable this feature, you
-will need to use the `--enable-features=ElectronSerialChooser` command line switch.
-
 ```javascript
 const { app, BrowserWindow } = require('electron')
 
 let win = null
-app.commandLine.appendSwitch('enable-features', 'ElectronSerialChooser')
 
 app.whenReady().then(() => {
   win = new BrowserWindow({
     width: 800,
     height: 600
   })
+
+  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
+    if (permission === 'serial') {
+      // Add logic here to determine if permission should be given to allow serial selection
+      return true
+    }
+    return false
+  })
+
+  // Optionally, retrieve previously persisted devices from a persistent store
+  const grantedDevices = fetchGrantedDevices()
+
+  win.webContents.session.setDevicePermissionHandler((details) => {
+    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'serial') {
+      if (details.device.vendorId === 123 && details.device.productId === 345) {
+        // Always allow this type of device (this allows skipping the call to `navigator.serial.requestPort` first)
+        return true
+      }
+
+      // Search through the list of devices that have previously been granted permission
+      return grantedDevices.some((grantedDevice) => {
+        return grantedDevice.vendorId === details.device.vendorId &&
+              grantedDevice.productId === details.device.productId &&
+              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
+      })
+    }
+    return false
+  })
+
   win.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
     event.preventDefault()
     const selectedPort = portList.find((device) => {
@@ -225,7 +340,7 @@ app.whenReady().then(() => {
 })
 ```
 
-#### Event: 'serial-port-added' _Experimental_
+#### Event: 'serial-port-added'
 
 Returns:
 
@@ -235,7 +350,7 @@ Returns:
 
 Emitted after `navigator.serial.requestPort` has been called and `select-serial-port` has fired if a new serial port becomes available.  For example, this event will fire when a new USB device is plugged in.
 
-#### Event: 'serial-port-removed' _Experimental_
+#### Event: 'serial-port-removed'
 
 Returns:
 
@@ -502,6 +617,7 @@ win.webContents.session.setCertificateVerifyProc((request, callback) => {
     * `permissionGranted` Boolean - Allow or deny the permission.
   * `details` Object - Some properties are only available on certain permission types.
     * `externalURL` String (optional) - The url of the `openExternal` request.
+    * `securityOrigin` String (optional) - The security origin of the `media` request.
     * `mediaTypes` String[] (optional) - The types of media access being requested, elements can be `video`
       or `audio`
     * `requestingUrl` String - The last URL the requesting frame loaded
@@ -527,8 +643,8 @@ session.fromPartition('some-partition').setPermissionRequestHandler((webContents
 #### `ses.setPermissionCheckHandler(handler)`
 
 * `handler` Function\<Boolean> | null
-  * `webContents` ([WebContents](web-contents.md) | null) - WebContents checking the permission.  Please note that if the request comes from a subframe you should use `requestingUrl` to check the request origin.  Cross origin sub frames making permission checks will pass a `null` webContents to this handler.  You should use `embeddingOrigin` and `requestingOrigin` to determine what origin the owning frame and the requesting frame are on respectively.
-  * `permission` String - Type of permission check.  Valid values are `midiSysex`, `notifications`, `geolocation`, `media`,`mediaKeySystem`,`midi`, `pointerLock`, `fullscreen`, `openExternal`, or `serial`.
+  * `webContents` ([WebContents](web-contents.md) | null) - WebContents checking the permission.  Please note that if the request comes from a subframe you should use `requestingUrl` to check the request origin.  All cross origin sub frames making permission checks will pass a `null` webContents to this handler, while certain other permission checks such as `notifications` checks will always pass `null`.  You should use `embeddingOrigin` and `requestingOrigin` to determine what origin the owning frame and the requesting frame are on respectively.
+  * `permission` String - Type of permission check.  Valid values are `midiSysex`, `notifications`, `geolocation`, `media`,`mediaKeySystem`,`midi`, `pointerLock`, `fullscreen`, `openExternal`, `hid`, or `serial`.
   * `requestingOrigin` String - The origin URL of the permission check
   * `details` Object - Some properties are only available on certain permission types.
     * `embeddingOrigin` String (optional) - The origin of the frame embedding the frame that made the permission check.  Only set for cross-origin sub frames making permission checks.
@@ -556,6 +672,78 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents,
 })
 ```
 
+#### `ses.setDevicePermissionHandler(handler)`
+
+* `handler` Function\<Boolean> | null
+  * `details` Object
+    * `deviceType` String - The type of device that permission is being requested on, can be `hid` or `serial`.
+    * `origin` String - The origin URL of the device permission check.
+    * `device` [HIDDevice](structures/hid-device.md) | [SerialPort](structures/serial-port.md)- the device that permission is being requested for.
+    * `frame` [WebFrameMain](web-frame-main.md) - WebFrameMain checking the device permission.
+
+Sets the handler which can be used to respond to device permission checks for the `session`.
+Returning `true` will allow the device to be permitted and `false` will reject it.
+To clear the handler, call `setDevicePermissionHandler(null)`.
+This handler can be used to provide default permissioning to devices without first calling for permission
+to devices (eg via `navigator.hid.requestDevice`).  If this handler is not defined, the default device
+permissions as granted through device selection (eg via `navigator.hid.requestDevice`) will be used.
+Additionally, the default behavior of Electron is to store granted device permision through the lifetime
+of the corresponding WebContents.  If longer term storage is needed, a developer can store granted device
+permissions (eg when handling the `select-hid-device` event) and then read from that storage with `setDevicePermissionHandler`.
+
+```javascript
+const { app, BrowserWindow } = require('electron')
+
+let win = null
+
+app.whenReady().then(() => {
+  win = new BrowserWindow()
+
+  win.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
+    if (permission === 'hid') {
+      // Add logic here to determine if permission should be given to allow HID selection
+      return true
+    } else if (permission === 'serial') {
+      // Add logic here to determine if permission should be given to allow serial port selection
+    }
+    return false
+  })
+
+  // Optionally, retrieve previously persisted devices from a persistent store
+  const grantedDevices = fetchGrantedDevices()
+
+  win.webContents.session.setDevicePermissionHandler((details) => {
+    if (new URL(details.origin).hostname === 'some-host' && details.deviceType === 'hid') {
+      if (details.device.vendorId === 123 && details.device.productId === 345) {
+        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
+        return true
+      }
+
+      // Search through the list of devices that have previously been granted permission
+      return grantedDevices.some((grantedDevice) => {
+        return grantedDevice.vendorId === details.device.vendorId &&
+              grantedDevice.productId === details.device.productId &&
+              grantedDevice.serialNumber && grantedDevice.serialNumber === details.device.serialNumber
+      })
+    } else if (details.deviceType === 'serial') {
+      if (details.device.vendorId === 123 && details.device.productId === 345) {
+        // Always allow this type of device (this allows skipping the call to `navigator.hid.requestDevice` first)
+        return true
+      }
+    }
+    return false
+  })
+
+  win.webContents.session.on('select-hid-device', (event, details, callback) => {
+    event.preventDefault()
+    const selectedDevice = details.deviceList.find((device) => {
+      return device.vendorId === '9025' && device.productId === '67'
+    })
+    callback(selectedPort?.deviceId)
+  })
+})
+```
+
 #### `ses.clearHostResolverCache()`
 
 Returns `Promise<void>` - Resolves when the operation is complete.

docs/api/structures/hid-device.md

@@ -0,0 +1,8 @@
+# HIDDevice Object
+
+* `deviceId` String - Unique identifier for the device.
+* `name` String - Name of the device.
+* `vendorId` Integer - The USB vendor ID.
+* `productId` Integer - The USB product ID.
+* `serialNumber` String (optional) - The USB device serial number.
+* `guid` String (optional) - Unique identifier for the HID interface.  A device may have multiple HID interfaces.

docs/api/structures/web-request-filter.md

@@ -0,0 +1,3 @@
+# WebRequestFilter Object
+
+* `urls` String[] - Array of URL patterns that will be used to filter out the requests that do not match the URL patterns.

docs/api/touch-bar-scrubber.md

@@ -15,7 +15,7 @@ _This class is not exported from the `'electron'` module. It is only available a
     * `highlightedIndex` Integer - The index of the item the user touched.
   * `selectedStyle` String (optional) - Selected item style. Can be `background`, `outline` or `none`. Defaults to `none`.
   * `overlayStyle` String (optional) - Selected overlay item style. Can be `background`, `outline` or `none`. Defaults to `none`.
-  * `showArrowButtons` Boolean (optional) - Defaults to `false`.
+  * `showArrowButtons` Boolean (optional) - Whether to show arrow buttons. Defaults to `false` and is only shown if `items` is non-empty.
   * `mode` String (optional) - Can be `fixed` or `free`. The default is `free`.
   * `continuous` Boolean (optional) - Defaults to `true`.
 

docs/api/web-contents.md

@@ -45,6 +45,26 @@ returns `null`.
 Returns `WebContents` | undefined - A WebContents instance with the given ID, or
 `undefined` if there is no WebContents associated with the given ID.
 
+### `webContents.fromDevToolsTargetId(targetId)`
+
+* `targetId` String - The Chrome DevTools Protocol [TargetID](https://chromedevtools.github.io/devtools-protocol/tot/Target/#type-TargetID) associated with the WebContents instance.
+
+Returns `WebContents` | undefined - A WebContents instance with the given TargetID, or
+`undefined` if there is no WebContents associated with the given TargetID.
+
+When communicating with the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/),
+it can be useful to lookup a WebContents instance based on its assigned TargetID.
+
+```js
+async function lookupTargetId (browserWindow) {
+  const wc = browserWindow.webContents
+  await wc.debugger.attach('1.3')
+  const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
+  const { targetId } = targetInfo
+  const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
+}
+```
+
 ## Class: WebContents
 
 > Render and control the contents of a BrowserWindow instance.
@@ -114,7 +134,7 @@ Returns:
 
 * `event` Event
 
-Emitted when the document in the given frame is loaded.
+Emitted when the document in the top-level frame is loaded.
 
 #### Event: 'page-title-updated'
 
@@ -449,6 +469,8 @@ Returns:
   * `control` Boolean - Equivalent to [KeyboardEvent.controlKey][keyboardevent].
   * `alt` Boolean - Equivalent to [KeyboardEvent.altKey][keyboardevent].
   * `meta` Boolean - Equivalent to [KeyboardEvent.metaKey][keyboardevent].
+  * `location` Number - Equivalent to [KeyboardEvent.location][keyboardevent].
+  * `modifiers` String[] - See [InputEvent.modifiers](structures/input-event.md).
 
 Emitted before dispatching the `keydown` and `keyup` events in the page.
 Calling `event.preventDefault` will prevent the page `keydown`/`keyup` events
@@ -508,6 +530,7 @@ Returns:
 * `certificate` [Certificate](structures/certificate.md)
 * `callback` Function
   * `isTrusted` Boolean - Indicates whether the certificate can be considered trusted.
+* `isMainFrame` Boolean
 
 Emitted when failed to verify the `certificate` for `url`.
 
@@ -628,6 +651,7 @@ Returns:
 * `params` Object
   * `x` Integer - x coordinate.
   * `y` Integer - y coordinate.
+  * `frame` WebFrameMain - Frame from which the context menu was invoked.
   * `linkURL` String - URL of the link that encloses the node the context menu
     was invoked on.
   * `linkText` String - Text associated with the link. May be an empty
@@ -712,6 +736,8 @@ first available device will be selected. `callback` should be called with
 `deviceId` to be selected, passing empty string to `callback` will
 cancel the request.
 
+If no event listener is added for this event, all bluetooth requests will be cancelled.
+
 ```javascript
 const { app, BrowserWindow } = require('electron')
 
@@ -854,6 +880,16 @@ Emitted when the `WebContents` preferred size has changed.
 This event will only be emitted when `enablePreferredSizeMode` is set to `true`
 in `webPreferences`.
 
+#### Event: 'frame-created'
+
+Returns:
+
+* `event` Event
+* `details` Object
+  * `frame` WebFrameMain
+
+Emitted when the [mainFrame](web-contents.md#contentsmainframe-readonly), an `<iframe>`, or a nested `<iframe>` is loaded within the page.
+
 ### Instance Methods
 
 #### `contents.loadURL(url[, options])`
@@ -1460,8 +1496,8 @@ win.loadURL('http://github.com')
 
 win.webContents.on('did-finish-load', () => {
   // Use default printing options
+  const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
   win.webContents.printToPDF({}).then(data => {
-    const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
     fs.writeFile(pdfPath, data, (error) => {
       if (error) throw error
       console.log(`Wrote PDF successfully to ${pdfPath}`)
@@ -1576,7 +1612,7 @@ app.whenReady().then(() => {
 
 * `options` Object (optional)
   * `mode` String - Opens the devtools with specified dock state, can be
-    `right`, `bottom`, `undocked`, `detach`. Defaults to last used dock state.
+    `left`, `right`, `bottom`, `undocked`, `detach`. Defaults to last used dock state.
     In `undocked` mode it's possible to dock back. In `detach` mode it's not.
   * `activate` Boolean (optional) - Whether to bring the opened devtools window
     to the foreground. The default is `true`.
@@ -1793,7 +1829,8 @@ End subscribing for frame presentation events.
 #### `contents.startDrag(item)`
 
 * `item` Object
-  * `file` String[] | String - The path(s) to the file(s) being dragged.
+  * `file` String - The path to the file being dragged.
+  * `files` String[] (optional) - The paths to the files being dragged. (`files` will override `file` field)
   * `icon` [NativeImage](native-image.md) | String - The image must be
     non-empty on macOS.
 
@@ -1990,11 +2027,6 @@ when the DevTools has been closed.
 
 A [`Debugger`](debugger.md) instance for this webContents.
 
-[keyboardevent]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent
-[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
-[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
-[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage
-
 #### `contents.backgroundThrottling`
 
 A `Boolean` property that determines whether or not this WebContents will throttle animations and timers
@@ -2003,3 +2035,8 @@ when the page becomes backgrounded. This also affects the Page Visibility API.
 #### `contents.mainFrame` _Readonly_
 
 A [`WebFrameMain`](web-frame-main.md) property that represents the top frame of the page's frame hierarchy.
+
+[keyboardevent]: https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent
+[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter
+[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
+[`postMessage`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage

docs/api/web-frame-main.md

@@ -71,6 +71,12 @@ or `undefined` if there is no WebFrameMain associated with the given IDs.
 Process: [Main](../glossary.md#main-process)<br />
 _This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
 
+### Instance Events
+
+#### Event: 'dom-ready'
+
+Emitted when the document is loaded.
+
 ### Instance Methods
 
 #### `frame.executeJavaScript(code[, userGesture])`

docs/api/web-request.md

@@ -43,9 +43,7 @@ The following methods are available on instances of `WebRequest`:
 
 #### `webRequest.onBeforeRequest([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -54,7 +52,7 @@ The following methods are available on instances of `WebRequest`:
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `uploadData` [UploadData[]](structures/upload-data.md)
@@ -88,9 +86,7 @@ Some examples of valid `urls`:
 
 #### `webRequest.onBeforeSendHeaders([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -99,7 +95,7 @@ Some examples of valid `urls`:
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `requestHeaders` Record<string, string>
@@ -117,9 +113,7 @@ The `callback` has to be called with a `response` object.
 
 #### `webRequest.onSendHeaders([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -128,7 +122,7 @@ The `callback` has to be called with a `response` object.
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `requestHeaders` Record<string, string>
@@ -139,9 +133,7 @@ response are visible by the time this listener is fired.
 
 #### `webRequest.onHeadersReceived([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -150,12 +142,11 @@ response are visible by the time this listener is fired.
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `statusLine` String
     * `statusCode` Integer
-    * `requestHeaders` Record<string, string>
     * `responseHeaders` Record<string, string[]> (optional)
   * `callback` Function
     * `headersReceivedResponse` Object
@@ -173,9 +164,7 @@ The `callback` has to be called with a `response` object.
 
 #### `webRequest.onResponseStarted([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -184,7 +173,7 @@ The `callback` has to be called with a `response` object.
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `responseHeaders` Record<string, string[]> (optional)
@@ -199,9 +188,7 @@ and response headers are available.
 
 #### `webRequest.onBeforeRedirect([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -210,7 +197,7 @@ and response headers are available.
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `redirectURL` String
@@ -226,9 +213,7 @@ redirect is about to occur.
 
 #### `webRequest.onCompleted([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -237,7 +222,7 @@ redirect is about to occur.
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `responseHeaders` Record<string, string[]> (optional)
@@ -251,9 +236,7 @@ completed.
 
 #### `webRequest.onErrorOccurred([filter, ]listener)`
 
-* `filter` Object (optional)
-  * `urls` String[] - Array of URL patterns that will be used to filter out the
-        requests that do not match the URL patterns.
+* `filter` [WebRequestFilter](structures/web-request-filter.md) (optional)
 * `listener` Function | null
   * `details` Object
     * `id` Integer
@@ -262,7 +245,7 @@ completed.
     * `webContentsId` Integer (optional)
     * `webContents` WebContents (optional)
     * `frame` WebFrameMain (optional)
-    * `resourceType` String
+    * `resourceType` String - Can be `mainFrame`, `subFrame`, `stylesheet`, `script`, `image`, `font`, `object`, `xhr`, `ping`, `cspReport`, `media`, `webSocket` or `other`.
     * `referrer` String
     * `timestamp` Double
     * `fromCache` Boolean

docs/api/webview-tag.md

@@ -143,12 +143,16 @@ browser plugins. Plugins are disabled by default.
 ### `preload`
 
 ```html
+<!-- from a file -->
 <webview src="https://www.github.com/" preload="./test.js"></webview>
+<!-- or if you want to load from an asar archive -->
+<webview src="https://www.github.com/" preload="./app.asar/test.js"></webview>
 ```
 
 A `String` that specifies a script that will be loaded before other scripts run in the guest
-page. The protocol of script's URL must be either `file:` or `asar:`, because it
-will be loaded by `require` in guest page under the hood.
+page. The protocol of script's URL must be `file:` (even when using `asar:` archives) because
+it will be loaded by Node's `require` under the hood, which treats `asar:` archives as virtual
+directories.
 
 When the guest page doesn't have node integration this script will still have
 access to all Node APIs, but global objects injected by Node will be deleted
@@ -606,6 +610,21 @@ listening to the `channel` event with the [`ipcRenderer`](ipc-renderer.md) modul
 See [webContents.send](web-contents.md#contentssendchannel-args) for
 examples.
 
+### `<webview>.sendToFrame(frameId, channel, ...args)`
+
+* `frameId` [number, number] - `[processId, frameId]`
+* `channel` String
+* `...args` any[]
+
+Returns `Promise<void>`
+
+Send an asynchronous message to renderer process via `channel`, you can also
+send arbitrary arguments. The renderer process can handle the message by
+listening to the `channel` event with the [`ipcRenderer`](ipc-renderer.md) module.
+
+See [webContents.sendToFrame](web-contents.md#contentssendtoframeframeid-channel-args) for
+examples.
+
 ### `<webview>.sendInputEvent(event)`
 
 * `event`  [MouseInputEvent](structures/mouse-input-event.md) | [MouseWheelInputEvent](structures/mouse-wheel-input-event.md) | [KeyboardInputEvent](structures/keyboard-input-event.md)
@@ -710,6 +729,10 @@ Corresponds to the points in time when the spinner of the tab starts spinning.
 
 Corresponds to the points in time when the spinner of the tab stops spinning.
 
+### Event: 'did-attach'
+
+Fired when attached to the embedder web contents.
+
 ### Event: 'dom-ready'
 
 Fired when document in the given frame is loaded.
@@ -830,6 +853,32 @@ this purpose.
 
 Calling `event.preventDefault()` does __NOT__ have any effect.
 
+### Event: 'did-start-navigation'
+
+Returns:
+
+* `url` String
+* `isInPlace` Boolean
+* `isMainFrame` Boolean
+* `frameProcessId` Integer
+* `frameRoutingId` Integer
+
+Emitted when any frame (including main) starts navigating. `isInPlace` will be
+`true` for in-page navigations.
+
+### Event: 'did-redirect-navigation'
+
+Returns:
+
+* `url` String
+* `isInPlace` Boolean
+* `isMainFrame` Boolean
+* `frameProcessId` Integer
+* `frameRoutingId` Integer
+
+Emitted after a server side redirect occurs during navigation. For example a 302
+redirect.
+
 ### Event: 'did-navigate'
 
 Returns:
@@ -842,6 +891,23 @@ This event is not emitted for in-page navigations, such as clicking anchor links
 or updating the `window.location.hash`. Use `did-navigate-in-page` event for
 this purpose.
 
+### Event: 'did-frame-navigate'
+
+Returns:
+
+* `url` String
+* `httpResponseCode` Integer - -1 for non HTTP navigations
+* `httpStatusText` String - empty for non HTTP navigations,
+* `isMainFrame` Boolean
+* `frameProcessId` Integer
+* `frameRoutingId` Integer
+
+Emitted when any frame navigation is done.
+
+This event is not emitted for in-page navigations, such as clicking anchor links
+or updating the `window.location.hash`. Use `did-navigate-in-page` event for
+this purpose.
+
 ### Event: 'did-navigate-in-page'
 
 Returns:
@@ -873,6 +939,7 @@ webview.addEventListener('close', () => {
 
 Returns:
 
+* `frameId` [number, number] - pair of `[processId, frameId]`.
 * `channel` String
 * `args` any[]
 
@@ -958,3 +1025,78 @@ Emitted when DevTools is focused / opened.
 
 [runtime-enabled-features]: https://cs.chromium.org/chromium/src/third_party/blink/renderer/platform/runtime_enabled_features.json5?l=70
 [chrome-webview]: https://developer.chrome.com/docs/extensions/reference/webviewTag/
+
+### Event: 'context-menu'
+
+Returns:
+
+* `params` Object
+  * `x` Integer - x coordinate.
+  * `y` Integer - y coordinate.
+  * `linkURL` String - URL of the link that encloses the node the context menu
+    was invoked on.
+  * `linkText` String - Text associated with the link. May be an empty
+    string if the contents of the link are an image.
+  * `pageURL` String - URL of the top level page that the context menu was
+    invoked on.
+  * `frameURL` String - URL of the subframe that the context menu was invoked
+    on.
+  * `srcURL` String - Source URL for the element that the context menu
+    was invoked on. Elements with source URLs are images, audio and video.
+  * `mediaType` String - Type of the node the context menu was invoked on. Can
+    be `none`, `image`, `audio`, `video`, `canvas`, `file` or `plugin`.
+  * `hasImageContents` Boolean - Whether the context menu was invoked on an image
+    which has non-empty contents.
+  * `isEditable` Boolean - Whether the context is editable.
+  * `selectionText` String - Text of the selection that the context menu was
+    invoked on.
+  * `titleText` String - Title text of the selection that the context menu was
+    invoked on.
+  * `altText` String - Alt text of the selection that the context menu was
+    invoked on.
+  * `suggestedFilename` String - Suggested filename to be used when saving file through 'Save
+    Link As' option of context menu.
+  * `selectionRect` [Rectangle](structures/rectangle.md) - Rect representing the coordinates in the document space of the selection.
+  * `selectionStartOffset` Number - Start position of the selection text.
+  * `referrerPolicy` [Referrer](structures/referrer.md) - The referrer policy of the frame on which the menu is invoked.
+  * `misspelledWord` String - The misspelled word under the cursor, if any.
+  * `dictionarySuggestions` String[] - An array of suggested words to show the
+    user to replace the `misspelledWord`.  Only available if there is a misspelled
+    word and spellchecker is enabled.
+  * `frameCharset` String - The character encoding of the frame on which the
+    menu was invoked.
+  * `inputFieldType` String - If the context menu was invoked on an input
+    field, the type of that field. Possible values are `none`, `plainText`,
+    `password`, `other`.
+  * `spellcheckEnabled` Boolean - If the context is editable, whether or not spellchecking is enabled.
+  * `menuSourceType` String - Input source that invoked the context menu.
+    Can be `none`, `mouse`, `keyboard`, `touch`, `touchMenu`, `longPress`, `longTap`, `touchHandle`, `stylus`, `adjustSelection`, or `adjustSelectionReset`.
+  * `mediaFlags` Object - The flags for the media element the context menu was
+    invoked on.
+    * `inError` Boolean - Whether the media element has crashed.
+    * `isPaused` Boolean - Whether the media element is paused.
+    * `isMuted` Boolean - Whether the media element is muted.
+    * `hasAudio` Boolean - Whether the media element has audio.
+    * `isLooping` Boolean - Whether the media element is looping.
+    * `isControlsVisible` Boolean - Whether the media element's controls are
+      visible.
+    * `canToggleControls` Boolean - Whether the media element's controls are
+      toggleable.
+    * `canPrint` Boolean - Whether the media element can be printed.
+    * `canSave` Boolean - Whether or not the media element can be downloaded.
+    * `canShowPictureInPicture` Boolean - Whether the media element can show picture-in-picture.
+    * `isShowingPictureInPicture` Boolean - Whether the media element is currently showing picture-in-picture.
+    * `canRotate` Boolean - Whether the media element can be rotated.
+    * `canLoop` Boolean - Whether the media element can be looped.
+  * `editFlags` Object - These flags indicate whether the renderer believes it
+    is able to perform the corresponding action.
+    * `canUndo` Boolean - Whether the renderer believes it can undo.
+    * `canRedo` Boolean - Whether the renderer believes it can redo.
+    * `canCut` Boolean - Whether the renderer believes it can cut.
+    * `canCopy` Boolean - Whether the renderer believes it can copy.
+    * `canPaste` Boolean - Whether the renderer believes it can paste.
+    * `canDelete` Boolean - Whether the renderer believes it can delete.
+    * `canSelectAll` Boolean - Whether the renderer believes it can select all.
+    * `canEditRichly` Boolean - Whether the renderer believes it can edit text richly.
+
+Emitted when there is a new context menu that needs to be handled.

docs/api/window-open.md

@@ -64,6 +64,9 @@ window.open('https://github.com', '_blank', 'top=500,left=200,frame=false,nodeIn
   `features` will be passed to any registered `webContents`'s
   `did-create-window` event handler in the `options` argument.
 * `frameName` follows the specification of `windowName` located in the [native documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#parameters).
+* When opening `about:blank`, the child window's `WebPreferences` will be copied
+  from the parent window, and there is no way to override it because Chromium
+  skips browser side navigation in this case.
 
 To customize or cancel the creation of the window, you can optionally set an
 override handler with `webContents.setWindowOpenHandler()` from the main

docs/breaking-changes.md

@@ -12,8 +12,39 @@ This document uses the following convention to categorize breaking changes:
 * **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
 * **Removed:** An API or feature was removed, and is no longer supported by Electron.
 
+## Planned Breaking API Changes (15.0)
+
+### Default Changed: `nativeWindowOpen` defaults to `true`
+
+Prior to Electron 15, `window.open` was by default shimmed to use
+`BrowserWindowProxy`. This meant that `window.open('about:blank')` did not work
+to open synchronously scriptable child windows, among other incompatibilities.
+`nativeWindowOpen` is no longer experimental, and is now the default.
+
+See the documentation for [window.open in Electron](api/window-open.md)
+for more details.
+
 ## Planned Breaking API Changes (14.0)
 
+### Removed: `remote` module
+
+The `remote` module was deprecated in Electron 12, and will be removed in
+Electron 14. It is replaced by the
+[`@electron/remote`](https://github.com/electron/remote) module.
+
+```js
+// Deprecated in Electron 12:
+const { BrowserWindow } = require('electron').remote
+```
+
+```js
+// Replace with:
+const { BrowserWindow } = require('@electron/remote')
+
+// In the main process:
+require('@electron/remote/main').initialize()
+```
+
 ### Removed: `app.allowRendererProcessReuse`
 
 The `app.allowRendererProcessReuse` property will be removed as part of our plan to
@@ -43,16 +74,6 @@ ensure your code works with this property enabled.  It has been enabled by defau
 
 You will be affected by this change if you use either `webFrame.executeJavaScript` or `webFrame.executeJavaScriptInIsolatedWorld`. You will need to ensure that values returned by either of those methods are supported by the [Context Bridge API](api/context-bridge.md#parameter--error--return-type-support) as these methods use the same value passing semantics.
 
-### Default Changed: `nativeWindowOpen` defaults to `true`
-
-Prior to Electron 14, `window.open` was by default shimmed to use
-`BrowserWindowProxy`. This meant that `window.open('about:blank')` did not work
-to open synchronously scriptable child windows, among other incompatibilities.
-`nativeWindowOpen` is no longer experimental, and is now the default.
-
-See the documentation for [window.open in Electron](api/window-open.md)
-for more details.
-
 ### Removed: BrowserWindowConstructorOptions inheriting from parent windows
 
 Prior to Electron 14, windows opened with `window.open` would inherit
@@ -556,7 +577,7 @@ error.
 ### API Changed: `shell.openItem` is now `shell.openPath`
 
 The `shell.openItem` API has been replaced with an asynchronous `shell.openPath` API.
-You can see the original API proposal and reasoning [here](https://github.com/electron/governance/blob/master/wg-api/spec-documents/shell-openitem.md).
+You can see the original API proposal and reasoning [here](https://github.com/electron/governance/blob/main/wg-api/spec-documents/shell-openitem.md).
 
 ## Planned Breaking API Changes (8.0)
 

docs/development/README.md

@@ -4,8 +4,8 @@ These guides are intended for people working on the Electron project itself.
 For guides on Electron app development, see
 [/docs/README.md](../README.md#guides-and-tutorials).
 
-* [Code of Conduct](https://github.com/electron/electron/blob/master/CODE_OF_CONDUCT.md)
-* [Contributing to Electron](https://github.com/electron/electron/blob/master/CONTRIBUTING.md)
+* [Code of Conduct](https://github.com/electron/electron/blob/main/CODE_OF_CONDUCT.md)
+* [Contributing to Electron](https://github.com/electron/electron/blob/main/CONTRIBUTING.md)
 * [Issues](issues.md)
 * [Pull Requests](pull-requests.md)
 * [Documentation Styleguide](coding-style.md#documentation)

docs/development/azure-vm-setup.md

@@ -8,7 +8,7 @@ Example Use Case:
     * We need `VS15.9` and we have `VS15.7` installed; this would require us to update an Azure image.
 
 1. Identify the image you wish to modify.
-    * In [appveyor.yml](https://github.com/electron/electron/blob/master/appveyor.yml), the image is identified by the property *image*.
+    * In [appveyor.yml](https://github.com/electron/electron/blob/main/appveyor.yml), the image is identified by the property *image*.
         * The names used correspond to the *"images"* defined for a build cloud, eg the [libcc-20 cloud](https://windows-ci.electronjs.org/build-clouds/8).
     * Find the image you wish to modify in the build cloud and make note of the **VHD Blob Path** for that image, which is the value for that corresponding key.
         * You will need this URI path to copy into a new image.

docs/development/build-instructions-gn.md

@@ -65,8 +65,8 @@ origin URLs.
 $ cd src/electron
 $ git remote remove origin
 $ git remote add origin https://github.com/electron/electron
-$ git checkout master
-$ git branch --set-upstream-to=origin/master
+$ git checkout main
+$ git branch --set-upstream-to=origin/main
 $ cd -
 ```
 

docs/development/debugging-instructions-macos.md

@@ -26,7 +26,9 @@ you prefer a graphical interface.
 * **.lldbinit**: Create or edit `~/.lldbinit` to allow Chromium code to be properly source-mapped.
 
    ```text
-   command script import ~/electron/src/tools/lldb/lldbinit.py
+   # e.g: ['~/electron/src/tools/lldb']
+   script sys.path[:0] = ['<...path/to/electron/src/tools/lldb>']
+   script import lldbinit
    ```
 
 ## Attaching to and Debugging Electron

docs/development/electron-vs-nwjs.md

@@ -72,4 +72,4 @@ to try NW.js.
 
 [nwjs]: https://nwjs.io/
 [electron-modules]: https://www.npmjs.com/search?q=electron
-[node-bindings]: https://github.com/electron/electron/tree/master/lib/common
+[node-bindings]: https://github.com/electron/electron/tree/main/lib/common

docs/development/pull-requests.md

@@ -45,10 +45,10 @@ Once you've built the project locally, you're ready to start making changes!
 ### Step 3: Branch
 
 To keep your development environment organized, create local branches to
-hold your work. These should be branched directly off of the `master` branch.
+hold your work. These should be branched directly off of the `main` branch.
 
 ```sh
-$ git checkout -b my-branch -t upstream/master
+$ git checkout -b my-branch -t upstream/main
 ```
 
 ## Making Changes
@@ -134,11 +134,11 @@ Once you have committed your changes, it is a good idea to use `git rebase`
 
 ```sh
 $ git fetch upstream
-$ git rebase upstream/master
+$ git rebase upstream/main
 ```
 
 This ensures that your working branch has the latest changes from `electron/electron`
-master.
+main.
 
 ### Step 7: Test
 
@@ -189,7 +189,7 @@ the requirements below.
 
 Bug fixes and new features should include tests and possibly benchmarks.
 
-Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTING.md
+Contributors guide: https://github.com/electron/electron/blob/main/CONTRIBUTING.md
 -->
 ```
 
@@ -222,7 +222,7 @@ seem unfamiliar, refer to this
 #### Approval and Request Changes Workflow
 
 All pull requests require approval from a
-[Code Owner](https://github.com/electron/electron/blob/master/.github/CODEOWNERS)
+[Code Owner](https://github.com/electron/electron/blob/main/.github/CODEOWNERS)
 of the area you modified in order to land. Whenever a maintainer reviews a pull
 request they may request changes. These may be small, such as fixing a typo, or
 may involve substantive changes. Such requests are intended to be helpful, but

docs/development/setting-up-symbol-server.md

@@ -43,8 +43,9 @@ SRV*c:\code\symbols\*https://msdl.microsoft.com/download/symbols;SRV*c:\code\sym
 
 ## Using the symbol server in Visual Studio
 
-![Tools -> Options](https://mdn.mozillademos.org/files/733/symbol-server-vc8express-menu.jpg)
-![Symbols Settings](https://mdn.mozillademos.org/files/2497/2005_options.gif)
+![Tools -> Options](../images/vs-tools-options.png)
+
+![Symbols Settings](../images/vs-options-debugging-symbols.png)
 
 ## Troubleshooting: Symbols will not load
 

docs/fiddles/features/web-bluetooth/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
+    <title>Web Bluetooth API</title>
+  </head>
+  <body>
+    <h1>Web Bluetooth API</h1>
+
+    <button id="clickme">Test Bluetooth</button>
+
+    <p>Currently selected bluetooth device: <strong id="device-name""></strong></p>
+
+    <script src="./renderer.js"></script>
+  </body>
+</html>

docs/fiddles/features/web-bluetooth/main.js

@@ -0,0 +1,30 @@
+const {app, BrowserWindow} = require('electron')
+const path = require('path')
+
+function createWindow () {
+  const mainWindow = new BrowserWindow({
+    width: 800,
+    height: 600
+  })
+
+  mainWindow.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
+    event.preventDefault()
+    if (deviceList && deviceList.length > 0) {
+      callback(deviceList[0].deviceId)
+    } 
+  })
+
+  mainWindow.loadFile('index.html')
+}
+
+app.whenReady().then(() => {
+  createWindow()
+  
+  app.on('activate', function () {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow()
+  })
+})
+
+app.on('window-all-closed', function () {
+  if (process.platform !== 'darwin') app.quit()
+})

docs/fiddles/features/web-bluetooth/renderer.js

@@ -0,0 +1,8 @@
+async function testIt() {
+  const device = await navigator.bluetooth.requestDevice({
+    acceptAllDevices: true
+  })
+  document.getElementById('device-name').innerHTML = device.name || `ID: ${device.id}`
+}
+
+document.getElementById('clickme').addEventListener('click',testIt)

docs/fiddles/features/web-hid/index.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
+    <title>WebHID API</title>
+  </head>
+  <body>
+    <h1>WebHID API</h1>
+
+    <button id="clickme">Test WebHID</button>
+
+    <h3>HID devices automatically granted access via <i>setDevicePermissionHandler</i></h3>
+    <div id="granted-devices"></div>
+    
+    <h3>HID devices automatically granted access via <i>select-hid-device</i></h3>
+    <div id="granted-devices2"></div>
+
+    <script src="./renderer.js"></script>
+  </body>
+</html>

docs/fiddles/features/web-hid/main.js

@@ -0,0 +1,50 @@
+const {app, BrowserWindow} = require('electron')
+const path = require('path')
+
+function createWindow () {
+  const mainWindow = new BrowserWindow({
+    width: 800,
+    height: 600
+  })
+  
+  mainWindow.webContents.session.on('select-hid-device', (event, details, callback) => {
+    event.preventDefault()
+    if (details.deviceList && details.deviceList.length > 0) {
+      callback(details.deviceList[0].deviceId)
+    }
+  })
+
+  mainWindow.webContents.session.on('hid-device-added', (event, device) => {    
+    console.log('hid-device-added FIRED WITH', device)
+  })
+
+  mainWindow.webContents.session.on('hid-device-removed', (event, device) => {    
+    console.log('hid-device-removed FIRED WITH', device)
+  })
+
+  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
+    if (permission === 'hid' && details.securityOrigin === 'file:///') {
+      return true
+    }
+  })
+
+  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
+    if (details.deviceType === 'hid' && details.origin === 'file://') {
+      return true
+    }
+  })
+  
+  mainWindow.loadFile('index.html')
+}
+
+app.whenReady().then(() => {
+  createWindow()
+  
+  app.on('activate', function () {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow()
+  })
+})
+
+app.on('window-all-closed', function () {
+  if (process.platform !== 'darwin') app.quit()
+})

docs/fiddles/features/web-hid/renderer.js

@@ -0,0 +1,19 @@
+async function testIt() {
+  const grantedDevices = await navigator.hid.getDevices()
+  let grantedDeviceList = ''
+  grantedDevices.forEach(device => {
+    grantedDeviceList += `<hr>${device.productName}</hr>`
+  })
+  document.getElementById('granted-devices').innerHTML = grantedDeviceList
+  const grantedDevices2 = await navigator.hid.requestDevice({
+    filters: []
+  })
+
+  grantedDeviceList = ''
+   grantedDevices2.forEach(device => {
+    grantedDeviceList += `<hr>${device.productName}</hr>`
+  })
+  document.getElementById('granted-devices2').innerHTML = grantedDeviceList
+}
+
+document.getElementById('clickme').addEventListener('click',testIt)

docs/fiddles/features/web-serial/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
+    <title>Web Serial API</title>
+  <body>
+    <h1>Web Serial API</h1>
+
+    <button id="clickme">Test Web Serial API</button>
+
+    <p>Matching Arduino Uno device: <strong id="device-name""></strong></p>
+
+    <script src="./renderer.js"></script>
+  </body>
+</html>

docs/fiddles/features/web-serial/main.js

@@ -0,0 +1,54 @@
+const {app, BrowserWindow} = require('electron')
+const path = require('path')
+
+function createWindow () {
+  const mainWindow = new BrowserWindow({
+    width: 800,
+    height: 600
+  })
+  
+  mainWindow.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
+    event.preventDefault()
+    if (portList && portList.length > 0) {
+      callback(portList[0].portId)
+    } else {
+      callback('') //Could not find any matching devices
+    }
+  })
+
+  mainWindow.webContents.session.on('serial-port-added', (event, port) => {
+    console.log('serial-port-added FIRED WITH', port)
+  })
+
+  mainWindow.webContents.session.on('serial-port-removed', (event, port) => {
+    console.log('serial-port-removed FIRED WITH', port)
+  })
+
+  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
+    if (permission === 'serial' && details.securityOrigin === 'file:///') {
+      return true
+    }
+  })
+
+  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
+    if (details.deviceType === 'serial' && details.origin === 'file://') {
+      return true
+    }
+  })
+  
+  mainWindow.loadFile('index.html')
+
+  mainWindow.webContents.openDevTools()
+}
+
+app.whenReady().then(() => {
+  createWindow()
+  
+  app.on('activate', function () {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow()
+  })
+})
+
+app.on('window-all-closed', function () {
+  if (process.platform !== 'darwin') app.quit()
+})

docs/fiddles/features/web-serial/renderer.js

@@ -0,0 +1,19 @@
+async function testIt() {
+  const filters = [
+    { usbVendorId: 0x2341, usbProductId: 0x0043 },
+    { usbVendorId: 0x2341, usbProductId: 0x0001 }
+  ];
+  try {
+    const port = await navigator.serial.requestPort({filters});
+    const portInfo = port.getInfo();
+    document.getElementById('device-name').innerHTML = `vendorId: ${portInfo.usbVendorId} | productId: ${portInfo.usbProductId} `
+  } catch (ex) {
+    if (ex.name === 'NotFoundError') {
+      document.getElementById('device-name').innerHTML = 'Device NOT found'
+    } else {
+      document.getElementById('device-name').innerHTML = ex
+    }
+  }
+}
+
+document.getElementById('clickme').addEventListener('click',testIt)

docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/index.html

@@ -1,92 +1,81 @@
 <!DOCTYPE html>
 <html>
-  <head>
-    <meta charset="UTF-8">
-    <title>Hello World!</title>
-  </head>
+
+<head>
+  <meta charset="UTF-8">
+  <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
+  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
+  <meta http-equiv="X-Content-Security-Policy" content="default-src 'self'; script-src 'self'">
+  <title>app.setAsDefaultProtocol Demo</title>
+</head>
+
 <body>
-  <section>
-    <header>
-        <h1>
-          Protocol Handler
-        </h1>
-        <h3>The <code>app</code> module provides methods for handling protocols.</h3>
-        <p>These methods allow you to set and unset the protocols your app should be the default app for. Similar to when a browser asks to be your default for viewing web pages.</p>
+  <h1>App Default Protocol Demo</h1>
 
-        <p>Open the <a href="https://electronjs.org/docs/api/app">full app API documentation<span class="u-visible-to-screen-reader">(opens in new window)</span></a> in your browser.</p>
-    </header>
+  <p>The protocol API allows us to register a custom protocol and intercept existing protocol requests.</p>
+  <p>These methods allow you to set and unset the protocols your app should be the default app for. Similar to when a
+    browser asks to be your default for viewing web pages.</p>
 
-    <div >
-        <button id="open-in-browser" class="js-container-target demo-toggle-button">Launch current page in browser
-          <div class="demo-meta u-avoid-clicks">Supports: Win, macOS <span class="demo-meta-divider">|</span> Process: Main</div>
-        </button>
-        <section id='open-app-link'>
-          <a href="electron-api-demos://open">Now... launch the app from a web link</a>
-        </section>
-        <div >
-          <p>You can set your app as the default app to open for a specific protocol. For instance, in this demo we set this app as the default for <code>electron-api-demos://</code>. The demo button above will launch a page in your default browser with a link. Click that link and it will re-launch this app.</p>
-          <h5>Packaging</h5>
-          <p>This feature will only work on macOS when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS <code>plist</code> for the app is updated to include the new protocol handler. If you're using <code>electron-packager</code> then you can add the flag <code>--extend-info</code> with a path to the <code>plist</code> you've created. The one for this app is below.</p>
-          <h5>Renderer Process</h5>
-          <pre><code>
-            const {shell} = require('electron')
-            const path = require('path')
-            const protocolHandlerBtn = document.getElementById('protocol-handler')
-            protocolHandlerBtn.addEventListener('click', () => {
-                const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
-                const pagePath = path.join('file://', pageDirectory, '../../sections/system/protocol-link.html')
-                shell.openExternal(pagePath)
-            })
-          </code></pre>
-          <h5>Main Process</h5>
-          <pre><code>
-            const {app, dialog} = require('electron')
-            const path = require('path')
+  <p>Open the <a href="https://www.electronjs.org/docs/api/protocol">full protocol API documentation</a> in your
+    browser.</p>
 
-            if (process.defaultApp) {
-                if (process.argv.length >= 2) {
-                    app.setAsDefaultProtocolClient('electron-api-demos', process.execPath, [path.resolve(process.argv[1])])
-                }
-            } else {
-                app.setAsDefaultProtocolClient('electron-api-demos')
-            }
+  -----
 
-            app.on('open-url', (event, url) => {
-                dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
-            })
+  <h3>Demo</h3>
+  <p>
+    First: Launch current page in browser
+    <button id="open-in-browser" class="js-container-target demo-toggle-button">
+        Click to Launch Browser
+      </button>
+  </p>
 
-          </code></pre>
-          <h5>macOS plist</h5>
-          <pre><code>
-            <?xml version="1.0" encoding="UTF-8"?>
-                <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-                    <plist version="1.0">
-                        <dict>
-                            <key>CFBundleURLTypes</key>
-                            <array>
-                                <dict>
-                                    <key>CFBundleURLSchemes</key>
-                                    <array>
-                                        <string>electron-api-demos</string>
-                                    </array>
-                                    <key>CFBundleURLName</key>
-                                    <string>Electron API Demos Protocol</string>
-                                </dict>
-                            </array>
-                            <key>ElectronTeamID</key>
-                            <string>VEKTX9H2N7</string>
-                        </dict>
-                    </plist>
-                </code>
-            </pre>
-        </div>
-    </div>
-    <script type="text/javascript">
-        require('./renderer.js')
-    </script>
-</section>
+  <p>
+    Then: Launch the app from a web link!
+    <a href="electron-fiddle://open">Click here to launch the app</a>
+  </p>
+
+  ----
+
+  <p>You can set your app as the default app to open for a specific protocol. For instance, in this demo we set this app
+    as the default for <code>electron-fiddle://</code>. The demo button above will launch a page in your default
+    browser with a link. Click that link and it will re-launch this app.</p>
+
+
+  <h3>Packaging</h3>
+  <p>This feature will only work on macOS when your app is packaged. It will not work when you're launching it in
+    development from the command-line. When you package your app you'll need to make sure the macOS <code>plist</code>
+    for the app is updated to include the new protocol handler. If you're using <code>electron-packager</code> then you
+    can add the flag <code>--extend-info</code> with a path to the <code>plist</code> you've created. The one for this
+    app is below:</p>
+
+  <p>
+  <h5>macOS plist</h5>
+  <pre><code>
+    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
+    &lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"&gt;
+            &lt;plist version="1.0"&gt;
+                &lt;dict&gt;
+                    &lt;key&gt;CFBundleURLTypes&lt;/key&gt;
+                    &lt;array&gt;
+                        &lt;dict&gt;
+                            &lt;key&gt;CFBundleURLSchemes&lt;/key&gt;
+                            &lt;array&gt;
+                                &lt;string&gt;electron-api-demos&lt;/string&gt;
+                            &lt;/array&gt;
+                            &lt;key&gt;CFBundleURLName&lt;/key&gt;
+                            &lt;string&gt;Electron API Demos Protocol&lt;/string&gt;
+                        &lt;/dict&gt;
+                    &lt;/array&gt;
+                    &lt;key&gt;ElectronTeamID&lt;/key&gt;
+                    &lt;string&gt;VEKTX9H2N7&lt;/string&gt;
+                &lt;/dict&gt;
+            &lt;/plist&gt;
+        </code>
+    </pre>
+  <p>
+
+    <!-- You can also require other files to run in this process -->
+    <script src="./renderer.js"></script>
 </body>
-</html>
 
-  </body>
-</html>
+</html>

docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/main.js

@@ -1,10 +1,39 @@
 // Modules to control application life and create native browser window
-const { app, BrowserWindow, dialog } = require('electron')
+const { app, BrowserWindow, ipcMain, shell, dialog } = require('electron')
 const path = require('path')
 
-// Keep a global reference of the window object, if you don't, the window will
-// be closed automatically when the JavaScript object is garbage collected.
-let mainWindow
+let mainWindow;
+
+if (process.defaultApp) {
+  if (process.argv.length >= 2) {
+    app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
+  }
+} else {
+    app.setAsDefaultProtocolClient('electron-fiddle')
+}
+
+const gotTheLock = app.requestSingleInstanceLock()
+
+if (!gotTheLock) {
+  app.quit()
+} else {
+  app.on('second-instance', (event, commandLine, workingDirectory) => {
+    // Someone tried to run a second instance, we should focus our window.
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore()
+      mainWindow.focus()
+    }
+  })
+
+  // Create mainWindow, load the rest of the app, etc...
+  app.whenReady().then(() => {
+    createWindow()
+  })
+  
+  app.on('open-url', (event, url) => {
+    dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
+  })
+}
 
 function createWindow () {
   // Create the browser window.
@@ -12,58 +41,23 @@ function createWindow () {
     width: 800,
     height: 600,
     webPreferences: {
-      nodeIntegration: true
+      preload: path.join(__dirname, 'preload.js'),
     }
   })
 
-  // and load the index.html of the app.
   mainWindow.loadFile('index.html')
-
-  // Open the DevTools.
-  mainWindow.webContents.openDevTools()
-
-  // Emitted when the window is closed.
-  mainWindow.on('closed', function () {
-    // Dereference the window object, usually you would store windows
-    // in an array if your app supports multi windows, this is the time
-    // when you should delete the corresponding element.
-    mainWindow = null
-  })
 }
 
-// This method will be called when Electron has finished
-// initialization and is ready to create browser windows.
-// Some APIs can only be used after this event occurs.
-app.whenReady().then(createWindow)
-
-// Quit when all windows are closed.
+// Quit when all windows are closed, except on macOS. There, it's common
+// for applications and their menu bar to stay active until the user quits
+// explicitly with Cmd + Q.
 app.on('window-all-closed', function () {
-  // On macOS it is common for applications and their menu bar
-  // to stay active until the user quits explicitly with Cmd + Q
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
+  if (process.platform !== 'darwin') app.quit()
 })
 
-app.on('activate', function () {
-  // On macOS it is common to re-create a window in the app when the
-  // dock icon is clicked and there are no other windows open.
-  if (mainWindow === null) {
-    createWindow()
-  }
-})
-
-// In this file you can include the rest of your app's specific main process
-// code. You can also put them in separate files and require them here.
-
-if (process.defaultApp) {
-  if (process.argv.length >= 2) {
-    app.setAsDefaultProtocolClient('electron-api-demos', process.execPath, [path.resolve(process.argv[1])])
-  }
-} else {
-  app.setAsDefaultProtocolClient('electron-api-demos')
-}
-
-app.on('open-url', (event, url) => {
-  dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
+// Handle window controls via IPC
+ipcMain.on('shell:open', () => {
+  const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
+  const pagePath = path.join('file://', pageDirectory, 'index.html')
+  shell.openExternal(pagePath)
 })

docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/preload.js

@@ -0,0 +1,11 @@
+// All of the Node.js APIs are available in the preload process.
+// It has the same sandbox as a Chrome extension.
+const { contextBridge, ipcRenderer } = require('electron')
+
+// Set up context bridge between the renderer process and the main process
+contextBridge.exposeInMainWorld(
+  'shell',
+  {
+    open: () => ipcRenderer.send('shell:open'),
+  }
+)

docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/renderer.js

@@ -1,14 +1,8 @@
-const { shell } = require('electron')
-const path = require('path')
+// This file is required by the index.html file and will
+// be executed in the renderer process for that window.
+// All APIs exposed by the context bridge are available here.
 
-const openInBrowserButton = document.getElementById('open-in-browser')
-const openAppLink = document.getElementById('open-app-link')
-// Hides openAppLink when loaded inside Electron
-openAppLink.style.display = 'none'
-
-openInBrowserButton.addEventListener('click', () => {
-  console.log('clicked')
-  const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
-  const pagePath = path.join('file://', pageDirectory, 'index.html')
-  shell.openExternal(pagePath)
-})
+// Binds the buttons to the context bridge API.
+document.getElementById('open-in-browser').addEventListener('click', () => {
+  shell.open();
+});

docs/fiddles/windows/manage-windows/frameless-window/index.html

@@ -59,8 +59,9 @@
 
           <p>
             For more details, see the
-            <a href="https://electronjs.org/docs/api/frameless-window/">
-              Frameless Window
+            <a href="https://electronjs.org/docs/tutorial/window-customization/">
+              Window Customization
+
             </a>
             documentation.
           </p>

docs/glossary.md

@@ -4,15 +4,39 @@ This page defines some terminology that is commonly used in Electron development
 
 ### ASAR
 
-ASAR stands for Atom Shell Archive Format. An [asar][asar] archive is a simple
+ASAR stands for Atom Shell Archive Format. An [asar] archive is a simple
 `tar`-like format that concatenates files into a single file. Electron can read
 arbitrary files from it without unpacking the whole file.
 
-The ASAR format was created primarily to improve performance on Windows... TODO
+The ASAR format was created primarily to improve performance on Windows when
+reading large quantities of small files (e.g. when loading your app's JavaScript
+dependency tree from `node_modules`).
+
+### code signing
+
+Code signing is a process where an app developer digitally signs their code to
+ensure that it hasn't been tampered with after packaging. Both Windows and
+macOS implement their own version of code signing. As a desktop app developer,
+it's important that you sign your code if you plan on distributing it to the
+general public.
+
+For more information, read the [Code Signing] tutorial.
+
+### context isolation
+
+Context isolation is a security measure in Electron that ensures that your
+preload script cannot leak privileged Electron or Node.js APIs to the web
+contents in your renderer process. With context isolation enabled, the
+only way to expose APIs from your preload script is through the
+`contextBridge` API.
+
+For more information, read the [Context Isolation] tutorial.
+
+See also: [preload script](#preload-script), [renderer process](#renderer-process)
 
 ### CRT
 
-The C Run-time Library (CRT) is the part of the C++ Standard Library that
+The C Runtime Library (CRT) is the part of the C++ Standard Library that
 incorporates the ISO C99 standard library. The Visual C++ libraries that
 implement the CRT support native code development, and both mixed native and
 managed code, and pure managed code for .NET development.
@@ -20,8 +44,7 @@ managed code, and pure managed code for .NET development.
 ### DMG
 
 An Apple Disk Image is a packaging format used by macOS. DMG files are
-commonly used for distributing application "installers". [electron-builder]
-supports `dmg` as a build target.
+commonly used for distributing application "installers".
 
 ### IME
 
@@ -31,19 +54,15 @@ keyboards to input Chinese, Japanese, Korean and Indic characters.
 
 ### IDL
 
-Interface description language. Write function signatures and data types in a format that can be used to generate interfaces in Java, C++, JavaScript, etc.
+Interface description language. Write function signatures and data types in a
+format that can be used to generate interfaces in Java, C++, JavaScript, etc.
 
 ### IPC
 
-IPC stands for Inter-Process Communication. Electron uses IPC to send
-serialized JSON messages between the [main] and [renderer] processes.
+IPC stands for inter-process communication. Electron uses IPC to send
+serialized JSON messages between the main and renderer processes.
 
-### libchromiumcontent
-
-A shared library that includes the [Chromium Content module] and all its
-dependencies (e.g., Blink, [V8], etc.). Also referred to as "libcc".
-
-- [github.com/electron/libchromiumcontent](https://github.com/electron/libchromiumcontent)
+see also: [main process](#main-process), [renderer process](#renderer-process)
 
 ### main process
 
@@ -68,10 +87,22 @@ MAS, see the [Mac App Store Submission Guide].
 
 ### Mojo
 
-An IPC system for communicating intra- or inter-process, and that's important because Chrome is keen on being able to split its work into separate processes or not, depending on memory pressures etc.
+An IPC system for communicating intra- or inter-process, and that's important
+because Chrome is keen on being able to split its work into separate processes
+or not, depending on memory pressures etc.
 
 See https://chromium.googlesource.com/chromium/src/+/master/mojo/README.md
 
+See also: [IPC](#ipc)
+
+### MSI
+
+On Windows, MSI packages are used by the Windows Installer
+(also known as Microsoft Installer) service to install and configure
+applications.
+
+More information can be found in [Microsoft's documentation][msi].
+
 ### native modules
 
 Native modules (also called [addons] in
@@ -85,22 +116,33 @@ likely to use a different V8 version from the Node binary installed in your
 system, you have to manually specify the location of Electron’s headers when
 building native modules.
 
-See also [Using Native Node Modules].
+For more information, read the [Native Node Modules] tutorial.
 
-### NSIS
+### notarization
 
-Nullsoft Scriptable Install System is a script-driven Installer
-authoring tool for Microsoft Windows. It is released under a combination of
-free software licenses, and is a widely-used alternative to commercial
-proprietary products like InstallShield. [electron-builder] supports NSIS
-as a build target.
+Notarization is a macOS-specific process where a developer can send a
+code-signed app to Apple servers to get verified for malicious
+components through an automated service.
+
+See also: [code signing](#code-signing)
 
 ### OSR
 
-OSR (Off-screen rendering) can be used for loading heavy page in
+OSR (offscreen rendering) can be used for loading heavy page in
 background and then displaying it after (it will be much faster).
 It allows you to render page without showing it on screen.
 
+For more information, read the [Offscreen Rendering][osr] tutorial.
+
+### preload script
+
+Preload scripts contain code that executes in a renderer process
+before its web contents begin loading. These scripts run within
+the renderer context, but are granted more privileges by having
+access to Node.js APIs.
+
+See also: [renderer process](#renderer-process), [context isolation](#context-isolation)
+
 ### process
 
 A process is an instance of a computer program that is being executed. Electron
@@ -120,13 +162,17 @@ The renderer process is a browser window in your app. Unlike the main process,
 there can be multiple of these and each is run in a separate process.
 They can also be hidden.
 
-In normal browsers, web pages usually run in a sandboxed environment and are not
-allowed access to native resources. Electron users, however, have the power to
-use Node.js APIs in web pages allowing lower level operating system
-interactions.
-
 See also: [process](#process), [main process](#main-process)
 
+### sandbox
+
+The sandbox is a security feature inherited from Chromium that restricts
+your renderer processes to a limited set of permissions.
+
+For more information, read the [Process Sandboxing] tutorial.
+
+See also: [process](#process)
+
 ### Squirrel
 
 Squirrel is an open-source framework that enables Electron apps to update
@@ -174,13 +220,15 @@ embedded content.
 
 [addons]: https://nodejs.org/api/addons.html
 [asar]: https://github.com/electron/asar
-[autoUpdater]: api/auto-updater.md
-[Chromium Content module]: https://www.chromium.org/developers/content-module
-[electron-builder]: https://github.com/electron-userland/electron-builder
-[libchromiumcontent]: #libchromiumcontent
-[Mac App Store Submission Guide]: tutorial/mac-app-store-submission-guide.md
+[autoupdater]: api/auto-updater.md
+[code signing]: tutorial/code-signing.md
+[context isolation]: tutorial/context-isolation.md
+[mac app store submission guide]: tutorial/mac-app-store-submission-guide.md
 [main]: #main-process
+[msi]: https://docs.microsoft.com/en-us/windows/win32/msi/windows-installer-portal
+[offscreen rendering]: tutorial/offscreen-rendering.md
+[process sandboxing]: tutorial/sandbox.md
 [renderer]: #renderer-process
 [userland]: #userland
-[Using Native Node Modules]: tutorial/using-native-node-modules.md
-[V8]: #v8
+[using native node modules]: tutorial/using-native-node-modules.md
+[v8]: #v8

docs/tutorial/accessibility.md

@@ -1,48 +1,7 @@
 # Accessibility
 
-Making accessible applications is important and we're happy to provide
-functionality to [Devtron][devtron] and [Spectron][spectron] that gives
-developers the opportunity to make their apps better for everyone.
-
----
-
 Accessibility concerns in Electron applications are similar to those of
-websites because they're both ultimately HTML. With Electron apps, however,
-you can't use the online resources for accessibility audits because your app
-doesn't have a URL to point the auditor to.
-
-These features bring those auditing tools to your Electron app. You can
-choose to add audits to your tests with Spectron or use them within DevTools
-with Devtron. Read on for a summary of the tools.
-
-## Spectron
-
-In the testing framework Spectron, you can now audit each window and `<webview>`
-tag in your application. For example:
-
-```javascript
-app.client.auditAccessibility().then(function (audit) {
-  if (audit.failed) {
-    console.error(audit.message)
-  }
-})
-```
-
-You can read more about this feature in [Spectron's documentation][spectron-a11y].
-
-## Devtron
-
-In Devtron, there is an accessibility tab which will allow you to audit a
-page in your app, sort and filter the results.
-
-![devtron screenshot][devtron-screenshot]
-
-Both of these tools are using the [Accessibility Developer Tools][a11y-devtools]
-library built by Google for Chrome. You can learn more about the accessibility
-audit rules this library uses on that [repository's wiki][a11y-devtools-wiki].
-
-If you know of other great accessibility tools for Electron, add them to the
-accessibility documentation with a pull request.
+websites because they're both ultimately HTML.
 
 ## Manually enabling accessibility features
 
@@ -84,10 +43,6 @@ CFStringRef kAXManualAccessibility = CFSTR("AXManualAccessibility");
 }
 ```
 
-[devtron]: https://electronjs.org/devtron
-[devtron-screenshot]: https://cloud.githubusercontent.com/assets/1305617/17156618/9f9bcd72-533f-11e6-880d-389115f40a2a.png
-[spectron]: https://electronjs.org/spectron
-[spectron-a11y]: https://github.com/electron/spectron#accessibility-testing
 [a11y-docs]: https://www.chromium.org/developers/design-documents/accessibility#TOC-How-Chrome-detects-the-presence-of-Assistive-Technology
 [a11y-devtools]: https://github.com/GoogleChrome/accessibility-developer-tools
 [a11y-devtools-wiki]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules

docs/tutorial/application-distribution.md

@@ -56,7 +56,7 @@ will then be your distribution to deliver to users.
 
 ### With an app source code archive
 
-Instead of from shipping your app by copying all of its source files, you can
+Instead of shipping your app by copying all of its source files, you can
 package your app into an [asar] archive to improve the performance of reading
 files on platforms like Windows, if you are not already using a bundler such
 as Parcel or Webpack.

docs/tutorial/automated-testing-with-a-custom-driver.md

@@ -1,135 +0,0 @@
-# Automated Testing with a Custom Driver
-
-To write automated tests for your Electron app, you will need a way to "drive" your application. [Spectron](https://electronjs.org/spectron) is a commonly-used solution which lets you emulate user actions via [WebDriver](https://webdriver.io/). However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.
-
-To create a custom driver, we'll use Node.js' [child_process](https://nodejs.org/api/child_process.html) API. The test suite will spawn the Electron process, then establish a simple messaging protocol:
-
-```js
-const childProcess = require('child_process')
-const electronPath = require('electron')
-
-// spawn the process
-const env = { /* ... */ }
-const stdio = ['inherit', 'inherit', 'inherit', 'ipc']
-const appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })
-
-// listen for IPC messages from the app
-appProcess.on('message', (msg) => {
-  // ...
-})
-
-// send an IPC message to the app
-appProcess.send({ my: 'message' })
-```
-
-From within the Electron app, you can listen for messages and send replies using the Node.js [process](https://nodejs.org/api/process.html) API:
-
-```js
-// listen for IPC messages from the test suite
-process.on('message', (msg) => {
-  // ...
-})
-
-// send an IPC message to the test suite
-process.send({ my: 'message' })
-```
-
-We can now communicate from the test suite to the Electron app using the `appProcess` object.
-
-For convenience, you may want to wrap `appProcess` in a driver object that provides more high-level functions. Here is an example of how you can do this:
-
-```js
-class TestDriver {
-  constructor ({ path, args, env }) {
-    this.rpcCalls = []
-
-    // start child process
-    env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages
-    this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })
-
-    // handle rpc responses
-    this.process.on('message', (message) => {
-      // pop the handler
-      const rpcCall = this.rpcCalls[message.msgId]
-      if (!rpcCall) return
-      this.rpcCalls[message.msgId] = null
-      // reject/resolve
-      if (message.reject) rpcCall.reject(message.reject)
-      else rpcCall.resolve(message.resolve)
-    })
-
-    // wait for ready
-    this.isReady = this.rpc('isReady').catch((err) => {
-      console.error('Application failed to start', err)
-      this.stop()
-      process.exit(1)
-    })
-  }
-
-  // simple RPC call
-  // to use: driver.rpc('method', 1, 2, 3).then(...)
-  async rpc (cmd, ...args) {
-    // send rpc request
-    const msgId = this.rpcCalls.length
-    this.process.send({ msgId, cmd, args })
-    return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))
-  }
-
-  stop () {
-    this.process.kill()
-  }
-}
-```
-
-In the app, you'd need to write a simple handler for the RPC calls:
-
-```js
-if (process.env.APP_TEST_DRIVER) {
-  process.on('message', onMessage)
-}
-
-async function onMessage ({ msgId, cmd, args }) {
-  let method = METHODS[cmd]
-  if (!method) method = () => new Error('Invalid method: ' + cmd)
-  try {
-    const resolve = await method(...args)
-    process.send({ msgId, resolve })
-  } catch (err) {
-    const reject = {
-      message: err.message,
-      stack: err.stack,
-      name: err.name
-    }
-    process.send({ msgId, reject })
-  }
-}
-
-const METHODS = {
-  isReady () {
-    // do any setup needed
-    return true
-  }
-  // define your RPC-able methods here
-}
-```
-
-Then, in your test suite, you can use your test-driver as follows:
-
-```js
-const test = require('ava')
-const electronPath = require('electron')
-
-const app = new TestDriver({
-  path: electronPath,
-  args: ['./app'],
-  env: {
-    NODE_ENV: 'test'
-  }
-})
-test.before(async t => {
-  await app.isReady
-})
-test.after.always('cleanup', async t => {
-  await app.stop()
-})
-```

docs/tutorial/automated-testing.md

@@ -0,0 +1,265 @@
+# Automated Testing
+
+Test automation is an efficient way of validating that your application code works as intended.
+While Electron doesn't actively maintain its own testing solution, this guide will go over a couple
+ways you can run end-to-end automated tests on your Electron app.
+
+## Using the WebDriver interface
+
+From [ChromeDriver - WebDriver for Chrome][chrome-driver]:
+
+> WebDriver is an open source tool for automated testing of web apps across many
+> browsers. It provides capabilities for navigating to web pages, user input,
+> JavaScript execution, and more. ChromeDriver is a standalone server which
+> implements WebDriver's wire protocol for Chromium. It is being developed by
+> members of the Chromium and WebDriver teams.
+
+There are a few ways that you can set up testing using WebDriver.
+
+### With WebdriverIO
+
+[WebdriverIO](https://webdriver.io/) (WDIO) is a test automation framework that provides a
+Node.js package for testing with WebDriver. Its ecosystem also includes various plugins
+(e.g. reporter and services) that can help you put together your test setup.
+
+#### Install the testrunner
+
+First you need to run the WebdriverIO starter toolkit in your project root directory:
+
+```sh npm2yarn
+npx wdio . --yes
+```
+
+This installs all necessary packages for you and generates a `wdio.conf.js` configuration file.
+
+#### Connect WDIO to your Electron app
+
+Update the capabilities in your configuration file to point to your Electron app binary:
+
+```javascript title='wdio.conf.js'
+export.config = {
+  // ...
+  capabilities: [{
+    browserName: 'chrome',
+    'goog:chromeOptions': {
+      binary: '/path/to/your/electron/binary', // Path to your Electron binary.
+      args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/
+    }
+  }]
+  // ...
+}
+```
+
+#### Run your tests
+
+To run your tests:
+
+```sh
+$ npx wdio run wdio.conf.js
+```
+
+[chrome-driver]: https://sites.google.com/chromium.org/driver/
+
+### With Selenium
+
+[Selenium](https://www.selenium.dev/) is a web automation framework that
+exposes bindings to WebDriver APIs in many languages. Their Node.js bindings
+are available under the `selenium-webdriver` package on NPM.
+
+#### Run a ChromeDriver server
+
+In order to use Selenium with Electron, you need to download the `electron-chromedriver`
+binary, and run it:
+
+```sh npm2yarn
+npm install --save-dev electron-chromedriver
+./node_modules/.bin/chromedriver
+Starting ChromeDriver (v2.10.291558) on port 9515
+Only local connections are allowed.
+```
+
+Remember the port number `9515`, which will be used later.
+
+#### Connect Selenium to ChromeDriver
+
+Next, install Selenium into your project:
+
+```sh npm2yarn
+npm install --save-dev selenium-webdriver
+```
+
+Usage of `selenium-webdriver` with Electron is the same as with
+normal websites, except that you have to manually specify how to connect
+ChromeDriver and where to find the binary of your Electron app:
+
+```js title='test.js'
+const webdriver = require('selenium-webdriver')
+const driver = new webdriver.Builder()
+  // The "9515" is the port opened by ChromeDriver.
+  .usingServer('http://localhost:9515')
+  .withCapabilities({
+    'goog:chromeOptions': {
+      // Here is the path to your Electron binary.
+      binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'
+    }
+  })
+  .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0
+  .build()
+driver.get('http://www.google.com')
+driver.findElement(webdriver.By.name('q')).sendKeys('webdriver')
+driver.findElement(webdriver.By.name('btnG')).click()
+driver.wait(() => {
+  return driver.getTitle().then((title) => {
+    return title === 'webdriver - Google Search'
+  })
+}, 1000)
+driver.quit()
+```
+
+## Using a custom test driver
+
+It's also possible to write your own custom driver using Node.js' built-in IPC-over-STDIO.
+Custom test drivers require you to write additional app code, but have lower overhead and let you
+expose custom methods to your test suite.
+
+To create a custom driver, we'll use Node.js' [`child_process`](https://nodejs.org/api/child_process.html) API.
+The test suite will spawn the Electron process, then establish a simple messaging protocol:
+
+```js title='testDriver.js'
+const childProcess = require('child_process')
+const electronPath = require('electron')
+
+// spawn the process
+const env = { /* ... */ }
+const stdio = ['inherit', 'inherit', 'inherit', 'ipc']
+const appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })
+
+// listen for IPC messages from the app
+appProcess.on('message', (msg) => {
+  // ...
+})
+
+// send an IPC message to the app
+appProcess.send({ my: 'message' })
+```
+
+From within the Electron app, you can listen for messages and send replies using the Node.js
+[`process`](https://nodejs.org/api/process.html) API:
+
+```js title='main.js'
+// listen for messages from the test suite
+process.on('message', (msg) => {
+  // ...
+})
+
+// send a message to the test suite
+process.send({ my: 'message' })
+```
+
+We can now communicate from the test suite to the Electron app using the `appProcess` object.
+
+For convenience, you may want to wrap `appProcess` in a driver object that provides more
+high-level functions. Here is an example of how you can do this. Let's start by creating
+a `TestDriver` class:
+
+```js title='testDriver.js'
+class TestDriver {
+  constructor ({ path, args, env }) {
+    this.rpcCalls = []
+
+    // start child process
+    env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages
+    this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })
+
+    // handle rpc responses
+    this.process.on('message', (message) => {
+      // pop the handler
+      const rpcCall = this.rpcCalls[message.msgId]
+      if (!rpcCall) return
+      this.rpcCalls[message.msgId] = null
+      // reject/resolve
+      if (message.reject) rpcCall.reject(message.reject)
+      else rpcCall.resolve(message.resolve)
+    })
+
+    // wait for ready
+    this.isReady = this.rpc('isReady').catch((err) => {
+      console.error('Application failed to start', err)
+      this.stop()
+      process.exit(1)
+    })
+  }
+
+  // simple RPC call
+  // to use: driver.rpc('method', 1, 2, 3).then(...)
+  async rpc (cmd, ...args) {
+    // send rpc request
+    const msgId = this.rpcCalls.length
+    this.process.send({ msgId, cmd, args })
+    return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))
+  }
+
+  stop () {
+    this.process.kill()
+  }
+}
+
+module.exports = { TestDriver };
+```
+
+In your app code, can then write a simple handler to receive RPC calls:
+
+```js title='main.js'
+const METHODS = {
+  isReady () {
+    // do any setup needed
+    return true
+  }
+  // define your RPC-able methods here
+}
+
+const onMessage = async ({ msgId, cmd, args }) => {
+  let method = METHODS[cmd]
+  if (!method) method = () => new Error('Invalid method: ' + cmd)
+  try {
+    const resolve = await method(...args)
+    process.send({ msgId, resolve })
+  } catch (err) {
+    const reject = {
+      message: err.message,
+      stack: err.stack,
+      name: err.name
+    }
+    process.send({ msgId, reject })
+  }
+}
+
+if (process.env.APP_TEST_DRIVER) {
+  process.on('message', onMessage)
+}
+```
+
+Then, in your test suite, you can use your `TestDriver` class with the test automation
+framework of your choosing. The following example uses
+[`ava`](https://www.npmjs.com/package/ava), but other popular choices like Jest
+or Mocha would work as well:
+
+```js title='test.js'
+const test = require('ava')
+const electronPath = require('electron')
+const { TestDriver } = require('./testDriver')
+
+const app = new TestDriver({
+  path: electronPath,
+  args: ['./app'],
+  env: {
+    NODE_ENV: 'test'
+  }
+})
+test.before(async t => {
+  await app.isReady
+})
+test.after.always('cleanup', async t => {
+  await app.stop()
+})
+```

docs/tutorial/code-signing.md

@@ -88,14 +88,15 @@ without meaning any harm:
   <dict>
     <key>com.apple.security.cs.allow-jit</key>
     <true/>
-    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
-    <true/>
     <key>com.apple.security.cs.debugger</key>
     <true/>
   </dict>
 </plist>
 ```
 
+Note that up until Electron 12, the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement was required
+as well. However, it should not be used anymore if it can be avoided.
+
 To see all of this in action, check out Electron Fiddle's source code,
 [especially its `electron-forge` configuration
 file](https://github.com/electron/fiddle/blob/master/forge.config.js).
@@ -133,7 +134,7 @@ are likely using [`electron-packager`], which includes [`electron-osx-sign`] and
 
 If you're using Packager's API, you can pass [in configuration that both signs
 and notarizes your
-application](https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html).
+application](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html).
 
 ```js
 const packager = require('electron-packager')
@@ -165,14 +166,15 @@ without meaning any harm:
   <dict>
     <key>com.apple.security.cs.allow-jit</key>
     <true/>
-    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
-    <true/>
     <key>com.apple.security.cs.debugger</key>
     <true/>
   </dict>
 </plist>
 ```
 
+Up until Electron 12, the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement was required
+as well. However, it should not be used anymore if it can be avoided.
+
 ## Mac App Store
 
 See the [Mac App Store Guide].

docs/tutorial/context-isolation.md

@@ -4,39 +4,38 @@
 
 Context Isolation is a feature that ensures that both your `preload` scripts and Electron's internal logic run in a separate context to the website you load in a [`webContents`](../api/web-contents.md).  This is important for security purposes as it helps prevent the website from accessing Electron internals or the powerful APIs your preload script has access to.
 
-This means that the `window` object that your preload script has access to is actually a **different** object than the website would have access to.  For example, if you set `window.hello = 'wave'` in your preload script and context isolation is enabled `window.hello` will be undefined if the website tries to access it.
+This means that the `window` object that your preload script has access to is actually a **different** object than the website would have access to.  For example, if you set `window.hello = 'wave'` in your preload script and context isolation is enabled, `window.hello` will be undefined if the website tries to access it.
 
-Every single application should have context isolation enabled and from Electron 12 it will be enabled by default.
-
-## How do I enable it?
-
-From Electron 12, it will be enabled by default. For lower versions it is an option in the `webPreferences` option when constructing `new BrowserWindow`'s.
-
-```javascript
-const mainWindow = new BrowserWindow({
-  webPreferences: {
-    contextIsolation: true
-  }
-})
-```
+Context isolation has been enabled by default since Electron 12, and it is a recommended security setting for _all applications_.
 
 ## Migration
 
-> I used to provide APIs from my preload script using `window.X = apiObject` now what?
+> Without context isolation, I used to provide APIs from my preload script using `window.X = apiObject`. Now what?
 
-Exposing APIs from your preload script to the loaded website is a common usecase and there is a dedicated module in Electron to help you do this in a painless way.
+### Before: context isolation disabled
 
-**Before: With context isolation disabled**
+Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global `window` object with the renderer. You could then attach arbitrary properties to a preload script:
 
-```javascript
+```javascript title='preload.js'
+// preload with contextIsolation disabled
 window.myAPI = {
   doAThing: () => {}
 }
 ```
 
-**After: With context isolation enabled**
+The `doAThing()` function could then be used directly in the renderer process:
 
-```javascript
+```javascript title='renderer.js'
+// use the exposed API in the renderer
+window.myAPI.doAThing()
+```
+
+### After: context isolation enabled
+
+There is a dedicated module in Electron to help you do this in a painless way. The [`contextBridge`](../api/context-bridge.md) module can be used to **safely** expose APIs from your preload script's isolated context to the context the website is running in. The API will also be accessible from the website on `window.myAPI` just like it was before.
+
+```javascript title='preload.js'
+// preload with contextIsolation enabled
 const { contextBridge } = require('electron')
 
 contextBridge.exposeInMainWorld('myAPI', {
@@ -44,26 +43,63 @@ contextBridge.exposeInMainWorld('myAPI', {
 })
 ```
 
-The [`contextBridge`](../api/context-bridge.md) module can be used to **safely** expose APIs from the isolated context your preload script runs in to the context the website is running in. The API will also be accessible from the website on `window.myAPI` just like it was before.
+```javascript title='renderer.js'
+// use the exposed API in the renderer
+window.myAPI.doAThing()
+```
 
-You should read the `contextBridge` documentation linked above to fully understand its limitations.  For instance you can't send custom prototypes or symbols over the bridge.
+Please read the `contextBridge` documentation linked above to fully understand its limitations. For instance, you can't send custom prototypes or symbols over the bridge.
 
-## Security Considerations
+## Security considerations
 
-Just enabling `contextIsolation` and using `contextBridge` does not automatically mean that everything you do is safe.  For instance this code is **unsafe**.
+Just enabling `contextIsolation` and using `contextBridge` does not automatically mean that everything you do is safe. For instance, this code is **unsafe**.
 
-```javascript
+```javascript title='preload.js'
 // ❌ Bad code
 contextBridge.exposeInMainWorld('myAPI', {
   send: ipcRenderer.send
 })
 ```
 
-It directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
+It directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible. The correct way to expose IPC-based APIs would instead be to provide one method per IPC message.
 
-```javascript
+```javascript title='preload.js'
 // ✅ Good code
 contextBridge.exposeInMainWorld('myAPI', {
   loadPreferences: () => ipcRenderer.invoke('load-prefs')
 })
 ```
+
+## Usage with TypeScript
+
+If you're building your Electron app with TypeScript, you'll want to add types to your APIs exposed over the context bridge. The renderer's `window` object won't have the correct typings unless you extend the types with a [declaration file].
+
+For example, given this `preload.ts` script:
+
+```typescript title='preload.ts'
+contextBridge.exposeInMainWorld('electronAPI', {
+  loadPreferences: () => ipcRenderer.invoke('load-prefs')
+})
+```
+
+You can create a `renderer.d.ts` declaration file and globally augment the `Window` interface:
+
+```typescript title='renderer.d.ts'
+export interface IElectronAPI {
+  loadPreferences: () => Promise<void>,
+}
+
+declare global {
+  interface Window {
+    electronAPI: IElectronAPI
+  }
+}
+```
+
+Doing so will ensure that the TypeScript compiler will know about the `electronAPI` property on your global `window` object when writing scripts in your renderer process:
+
+```typescript title='renderer.ts'
+window.electronAPI.loadPreferences()
+```
+
+[declaration file]: https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html

docs/tutorial/dark-mode.md

@@ -80,9 +80,9 @@ Starting with the `index.html` file:
 </html>
 ```
 
-And the `style.css` file:
+And the `styles.css` file:
 
-```css title='style.css'
+```css title='styles.css'
 @media (prefers-color-scheme: dark) {
   body { background: #333; color: white; }
 }
@@ -200,6 +200,6 @@ Run the example using Electron Fiddle and then click the "Toggle Dark Mode" butt
 [system-wide-dark-mode]: https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/dark-mode/
 [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
+[packager-darwindarkmode-api]: https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html#darwindarkmodesupport
 [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/desktop-environment-integration.md

@@ -1,35 +0,0 @@
-# Desktop Environment Integration
-
-Different operating systems provide different features for integrating desktop
-applications into their desktop environments. For example, on Windows,
-applications can put shortcuts in the JumpList of task bar, and on Mac,
-applications can put a custom menu in the dock menu.
-
-This guide explains how to integrate your application into those desktop
-environments with Electron APIs.
-
-## Notifications
-
-See the [Notifications documentation](notifications.md).
-
-## Recent Documents
-
-See [Recent Documents documentation](recent-documents.md).
-
-## Progress Bar
-
-See the [Progress Bar documentation](progress-bar.md).
-
-## Unity Launcher
-
-See the [Unity Launcher documentation][unity-launcher].
-
-## Represented File for macOS Window
-
-See the [Represented File documentation](represented-file.md).
-
-## Dragging files out of the window
-
-See the [Native File Drag & Drop documentation](native-file-drag-drop.md).
-
-[unity-launcher]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher

docs/tutorial/devices.md

@@ -0,0 +1,108 @@
+# Device Access
+
+Like Chromium based browsers, Electron provides access to device hardware
+through web APIs.  For the most part these APIs work like they do in a browser,
+but there are some differences that need to be taken into account.  The primary
+difference between Electron and browsers is what happens when device access is
+requested.  In a browser, users are presented with a popup where they can grant
+access to an individual device.  In Electron APIs are provided which can be
+used by a developer to either automatically pick a device or prompt users to
+pick a device via a developer created interface.
+
+## Web Bluetooth API
+
+The [Web Bluetooth API](https://web.dev/bluetooth/) can be used to communicate
+with bluetooth devices. In order to use this API in Electron, developers will
+need to handle the [`select-bluetooth-device` event on the webContents](../api/web-contents.md#event-select-bluetooth-device)
+associated with the device request.
+
+### Example
+
+This example demonstrates an Electron application that automatically selects
+the first available bluetooth device when the `Test Bluetooth` button is
+clicked.
+
+```javascript fiddle='docs/fiddles/features/web-bluetooth'
+
+```
+
+## WebHID API
+
+The [WebHID API](https://web.dev/hid/) can be used to access HID devices such
+as keyboards and gamepads.  Electron provides several APIs for working with
+the WebHID API:
+
+* The [`select-hid-device` event on the Session](../api/session.md#event-select-hid-device)
+  can be used to select a HID device when a call to
+  `navigator.hid.requestDevice` is made.  Additionally the [`hid-device-added`](../api/session.md#event-hid-device-added)
+  and [`hid-device-removed`](../api/session.md#event-hid-device-removed) events
+  on the Session can be used to handle devices being plugged in or unplugged during the
+  `navigator.hid.requestDevice` process.
+* [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler)
+  can be used to provide default permissioning to devices without first calling
+  for permission to devices via `navigator.hid.requestDevice`.  Additionally,
+  the default behavior of Electron is to store granted device permision through
+  the lifetime of the corresponding WebContents.  If longer term storage is
+  needed, a developer can store granted device permissions (eg when handling
+  the `select-hid-device` event) and then read from that storage with
+  `setDevicePermissionHandler`.
+* [`ses.setPermissionCheckHandler(handler)`](../api/session.md#sessetpermissioncheckhandlerhandler)
+  can be used to disable HID access for specific origins.
+
+### Blocklist
+
+By default Electron employs the same [blocklist](https://github.com/WICG/webhid/blob/main/blocklist.txt)
+used by Chromium.  If you wish to override this behavior, you can do so by
+setting the `disable-hid-blocklist` flag:
+
+```javascript
+app.commandLine.appendSwitch('disable-hid-blocklist')
+```
+
+### Example
+
+This example demonstrates an Electron application that automatically selects
+HID devices through [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler)
+and through [`select-hid-device` event on the Session](../api/session.md#event-select-hid-device)
+when the `Test WebHID` button is clicked.
+
+```javascript fiddle='docs/fiddles/features/web-hid'
+
+```
+
+## Web Serial API
+
+The [Web Serial API](https://web.dev/serial/) can be used to access serial
+devices that are connected via serial port, USB, or Bluetooth.  In order to use
+this API in Electron, developers will need to handle the
+[`select-serial-port` event on the Session](../api/session.md#event-select-serial-port)
+associated with the serial port request.
+
+There are several additional APIs for working with the Web Serial API:
+
+* The [`serial-port-added`](../api/session.md#event-serial-port-added)
+  and [`serial-port-removed`](../api/session.md#event-serial-port-removed) events
+  on the Session can be used to handle devices being plugged in or unplugged during the
+  `navigator.serial.requestPort` process.
+* [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler)
+  can be used to provide default permissioning to devices without first calling
+  for permission to devices via `navigator.serial.requestPort`.  Additionally,
+  the default behavior of Electron is to store granted device permision through
+  the lifetime of the corresponding WebContents.  If longer term storage is
+  needed, a developer can store granted device permissions (eg when handling
+  the `select-serial-port` event) and then read from that storage with
+  `setDevicePermissionHandler`.
+* [`ses.setPermissionCheckHandler(handler)`](../api/session.md#sessetpermissioncheckhandlerhandler)
+  can be used to disable serial access for specific origins.
+
+### Example
+
+This example demonstrates an Electron application that automatically selects
+serial devices through [`ses.setDevicePermissionHandler(handler)`](../api/session.md#sessetdevicepermissionhandlerhandler)
+as well as demonstrating selecting the first available Arduino Uno serial device (if connected) through
+[`select-serial-port` event on the Session](../api/session.md#event-select-serial-port)
+when the `Test Web Serial` button is clicked.
+
+```javascript fiddle='docs/fiddles/features/web-serial'
+
+```

docs/tutorial/electron-timelines.md

@@ -1,23 +1,28 @@
 # Electron Release Timelines
 
+Special notes:
+
 * The `-beta.1` and `stable` dates are our solid release dates.
 * We strive for weekly beta releases, however we often release more betas than scheduled.
 * All dates are our goals but there may be reasons for adjusting the stable deadline, such as security bugs.
 * Take a look at the [5.0.0 Timeline blog post](https://electronjs.org/blog/electron-5-0-timeline) for info about publicizing our release dates.
 * Since Electron 6.0, we've been targeting every other Chromium version and releasing our stable on the same day as Chrome stable. You can reference Chromium's release schedule [here](https://chromiumdash.appspot.com/schedule). See [Electron's new release cadence blog post](https://www.electronjs.org/blog/12-week-cadence) for more details on our release schedule.
+* Electron 15.0 only will include a special Alpha release. Starting in Electron 16.0, we will release on an 8-week cadence. See [Electron's new 8-week cadence blog post](https://www.electronjs.org/blog/8-week-cadence) for more details.
 
-| Version | -beta.1 | Stable | Chrome | Node |
-| ------- | ------- | ------ | ------ | ---- |
-| 2.0.0 | 2018-02-21 | 2018-05-01 | M61 | v8.9 |
-| 3.0.0 | 2018-06-21 | 2018-09-18 | M66 | v10.2 |
-| 4.0.0 | 2018-10-11 | 2018-12-20 | M69 | v10.11 |
-| 5.0.0 | 2019-01-22 | 2019-04-24 | M73 | v12.0 |
-| 6.0.0 | 2019-05-01 | 2019-07-30 | M76 | v12.4 |
-| 7.0.0 | 2019-08-01 | 2019-10-22 | M78 | v12.8 |
-| 8.0.0 | 2019-10-24 | 2020-02-04 | M80 | v12.13 |
-| 9.0.0 | 2020-02-06 | 2020-05-19 | M83 | v12.14 |
-| 10.0.0 | 2020-05-21 | 2020-08-25 | M85 | v12.16 |
-| 11.0.0 | 2020-08-27 | 2020-11-17 | M87 | v12.18 |
-| 12.0.0 | 2020-11-19 | 2021-03-02 | M89 | v14.16 |
-| 13.0.0 | 2021-03-04 | 2021-05-25 | M91 | v14.16 |
-| 14.0.0 | 2021-05-27 | 2021-08-31 | M93 | TBD |
+| Electron | Alpha | Beta | Stable | Chrome | Node |
+| ------- | ----- | ------- | ------ | ------ | ---- |
+| 2.0.0 | -- | 2018-Feb-21 | 2018-May-01 | M61 | v8.9 |
+| 3.0.0 | -- | 2018-Jun-21 | 2018-Sep-18 | M66 | v10.2 |
+| 4.0.0 | -- | 2018-Oct-11 | 2018-Dec-20 | M69 | v10.11 |
+| 5.0.0 | -- | 2019-Jan-22 | 2019-Apr-24 | M73 | v12.0 |
+| 6.0.0 | -- | 2019-May-01 | 2019-Jul-30 | M76 | v12.4 |
+| 7.0.0 | -- | 2019-Aug-01 | 2019-Oct-22 | M78 | v12.8 |
+| 8.0.0 | -- | 2019-Oct-24 | 2020-Feb-04 | M80 | v12.13 |
+| 9.0.0 | -- | 2020-Feb-06 | 2020-May-19 | M83 | v12.14 |
+| 10.0.0 | -- | 2020-May-21 | 2020-Aug-25 | M85 | v12.16 |
+| 11.0.0 | -- | 2020-Aug-27 | 2020-Nov-17 | M87 | v12.18 |
+| 12.0.0 | -- | 2020-Nov-19 | 2021-Mar-02 | M89 | v14.16 |
+| 13.0.0 | -- | 2021-Mar-04 | 2021-May-25 | M91 | v14.16 |
+| 14.0.0 | -- | 2021-May-27 | 2021-Aug-31 | M93 | v14.17 |
+| 15.0.0 | 2021-Jul-20 | 2021-Sep-01 | 2021-Sep-21 | M94 | v16.5 |
+| 16.0.0 | -- | 2021-Sep-23 | 2021-Nov-16 | M96 | TBD |

docs/tutorial/electron-versioning.md

@@ -2,43 +2,31 @@
 
 > A detailed look at our versioning policy and implementation.
 
-As of version 2.0.0, Electron follows [SemVer](#semver). The following command will install the most recent stable build of Electron:
+As of version 2.0.0, Electron follows the [SemVer](#semver) spec. The following command will install the most recent stable build of Electron:
 
-```sh
+```sh npm2yarn
 npm install --save-dev electron
 ```
 
 To update an existing project to use the latest stable version:
 
-```sh
+```sh npm2yarn
 npm install --save-dev electron@latest
 ```
 
-## Version 1.x
-
-Electron versions *< 2.0* did not conform to the [SemVer](https://semver.org) spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
-
-Here is an example of the 1.x strategy:
-
-![1.x Versioning](../images/versioning-sketch-0.png)
-
-An app developed with `1.8.1` cannot take the `1.8.3` bug fix without either absorbing the `1.8.2` feature, or by backporting the fix and maintaining a new release line.
-
-## Version 2.0 and Beyond
+## Versioning scheme
 
 There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.
 
-1. Strict use of SemVer
+1. Strict use of the [SemVer](#semver) spec
 2. Introduction of semver-compliant `-beta` tags
 3. Introduction of [conventional commit messages](https://conventionalcommits.org/)
 4. Well-defined stabilization branches
-5. The `master` branch is versionless; only stabilization branches contain version information
+5. The `main` branch is versionless; only stabilization branches contain version information
 
 We will cover in detail how git branching works, how npm tagging works, what developers should expect to see, and how one can backport changes.
 
-# SemVer
-
-From 2.0 onward, Electron will follow SemVer.
+## SemVer
 
 Below is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
 
@@ -48,22 +36,25 @@ Below is a table explicitly mapping types of changes to their corresponding cate
 | Node.js major version updates   | Node.js minor version updates      | Node.js patch version updates |
 | Chromium version updates        |                                    | fix-related chromium patches  |
 
+For more information, see the [Semantic Versioning 2.0.0](https://semver.org/) spec.
+
 Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
 
-# Stabilization Branches
+## Stabilization branches
 
-Stabilization branches are branches that run parallel to master, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to master.
+Stabilization branches are branches that run parallel to `main`, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to `main`.
 
 ![Stabilization Branches](../images/versioning-sketch-1.png)
 
-Since Electron 8, stabilization branches are always **major** version lines, and named against the following template `$MAJOR-x-y` e.g. `8-x-y`.  Prior to that we used **minor** version lines and named them as `$MAJOR-$MINOR-x` e.g. `2-0-x`
+Since Electron 8, stabilization branches are always **major** version lines, and named against the following template `$MAJOR-x-y` e.g. `8-x-y`.  Prior to that we used **minor** version lines and named them as `$MAJOR-$MINOR-x` e.g. `2-0-x`.
+
+We allow for multiple stabilization branches to exist simultaneously, one for each supported version. For more details on which versions are supported, see our [Electron Release Timelines](./electron-timelines.md) doc.
 
-We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.
 ![Multiple Stability Branches](../images/versioning-sketch-2.png)
 
-Older lines will not be supported by GitHub, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
+Older lines will not be supported by the Electron project, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.
 
-# Beta Releases and Bug Fixes
+## Beta releases and bug fixes
 
 Developers want to know which releases are _safe_ to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in `package.json` :
 
@@ -116,15 +107,7 @@ A few examples of how various SemVer ranges will pick up new releases:
 
 ![Semvers and Releases](../images/versioning-sketch-7.png)
 
-# Missing Features: Alphas
-
-Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.
-
-As a future consideration, we may introduce one or both of the following:
-
-* alpha releases that have looser stability constraints to betas; for example it would be allowable to admit new features while a stability channel is in _alpha_
-
-# Feature Flags
+## Feature flags
 
 Feature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or **soft branch** must have the following properties:
 
@@ -132,20 +115,29 @@ Feature flags are a common practice in Chromium, and are well-established in the
 * it completely segments new and old code paths; refactoring old code to support a new feature _violates_ the feature-flag contract
 * feature flags are eventually removed after the feature is released
 
-# Semantic Commits
+## Semantic commits
 
-We seek to increase clarity at all levels of the update and releases process. Starting with `2.0.0` we will require pull requests adhere to the [Conventional Commits](https://conventionalcommits.org/) spec, which can be summarized as follows:
+All pull requests must adhere to the [Conventional Commits](https://conventionalcommits.org/) spec, which can be summarized as follows:
 
 * Commits that would result in a SemVer **major** bump must start their body with `BREAKING CHANGE:`.
 * Commits that would result in a SemVer **minor** bump must start with `feat:`.
 * Commits that would result in a SemVer **patch** bump must start with `fix:`.
 
-* We allow squashing of commits, provided that the squashed message adheres to the above message format.
-* It is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
+The `electron/electron` repository also enforces squash merging, so you only need to make sure that your pull request has the correct title prefix.
 
-# Versioned `master`
+## Versioned `main` branch
 
-* The `master` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json`
-* Release branches are never merged back to master
-* Release branches _do_ contain the correct version in their `package.json`
-* As soon as a release branch is cut for a major, master must be bumped to the next major.  I.e. `master` is always versioned as the next theoretical release branch
+* The `main` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json`.
+* Release branches are never merged back to `main`.
+* Release branches _do_ contain the correct version in their `package.json`.
+* As soon as a release branch is cut for a major, `main` must be bumped to the next major (i.e. `main` is always versioned as the next theoretical release branch).
+
+## Historical versioning (Electron 1.X)
+
+Electron versions *< 2.0* did not conform to the [SemVer](https://semver.org) spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Teams, Skype, VS Code, and GitHub Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
+
+Here is an example of the 1.x strategy:
+
+![1.x Versioning](../images/versioning-sketch-0.png)
+
+An app developed with `1.8.1` cannot take the `1.8.3` bug fix without either absorbing the `1.8.2` feature, or by backporting the fix and maintaining a new release line.

docs/tutorial/fuses.md

@@ -51,4 +51,4 @@ Somewhere in the Electron binary there will be a sequence of bytes that look lik
 
 To flip a fuse you find its position in the fuse wire and change it to "0" or "1" depending on the state you'd like.
 
-You can view the current schema [here](https://github.com/electron/electron/blob/master/build/fuses/fuses.json5).
+You can view the current schema [here](https://github.com/electron/electron/blob/main/build/fuses/fuses.json5).

docs/tutorial/in-app-purchases.md

@@ -1,4 +1,4 @@
-# In-App Purchase (macOS)
+# In-App Purchases (macOS)
 
 ## Preparing
 

docs/tutorial/installation.md

@@ -1,4 +1,4 @@
-# Installation
+# Advanced Installation Instructions
 
 To install prebuilt Electron binaries, use [`npm`][npm].
 The preferred method is to install Electron as a development dependency in your
@@ -90,6 +90,11 @@ ELECTRON_CUSTOM_DIR="{{ version }}"
 The above configuration will download from URLs such as
 `https://npm.taobao.org/mirrors/electron/8.0.0/electron-v8.0.0-linux-x64.zip`.
 
+If your mirror serves artifacts with different checksums to the official
+Electron release you may have to set `electron_use_remote_checksums=1` to
+force Electron to use the remote `SHASUMS256.txt` file to verify the checksum
+instead of the embedded checksums.
+
 #### Cache
 
 Alternatively, you can override the local cache. `@electron/get` will cache

docs/tutorial/launch-app-from-url-in-another-app.md

@@ -0,0 +1,214 @@
+---
+title: Launching Your Electron App From a URL In Another App
+description: This guide will take you through the process of setting your electron app as the default handler for a specific protocol.
+slug: launch-app-from-url-in-another-app
+hide_title: true
+---
+
+# Launching Your Electron App From A URL In Another App
+
+## Overview
+
+<!-- ✍ Update this section if you want to provide more details -->
+
+This guide will take you through the process of setting your Electron app as the default
+handler for a specific [protocol](https://www.electronjs.org/docs/api/protocol).
+
+By the end of this tutorial, we will have set our app to intercept and handle
+any clicked URLs that start with a specific protocol. In this guide, the protocol
+we will use will be "`electron-fiddle://`".
+
+## Examples
+
+### Main Process (main.js)
+
+First, we will import the required modules from `electron`. These modules help
+control our application lifecycle and create a native browser window.
+
+```javascript
+const { app, BrowserWindow, shell } = require('electron')
+const path = require('path')
+```
+
+Next, we will proceed to register our application to handle all "`electron-fiddle://`" protocols.
+
+```javascript
+if (process.defaultApp) {
+  if (process.argv.length >= 2) {
+    app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
+  }
+} else {
+  app.setAsDefaultProtocolClient('electron-fiddle')
+}
+```
+
+We will now define the function in charge of creating our browser window and load our application's `index.html` file.
+
+```javascript
+const createWindow = () => {
+  // Create the browser window.
+  mainWindow = new BrowserWindow({
+    width: 800,
+    height: 600,
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js')
+    }
+  })
+
+  mainWindow.loadFile('index.html')
+}
+```
+
+In this next step, we will create our  `BrowserWindow` and tell our application how to handle an event in which an external protocol is clicked.
+
+This code will be different in Windows compared to MacOS and Linux. This is due to Windows requiring additional code in order to open the contents of the protocol link within the same Electron instance. Read more about this [here](https://www.electronjs.org/docs/api/app#apprequestsingleinstancelock).
+
+#### Windows code:
+
+```javascript
+const gotTheLock = app.requestSingleInstanceLock()
+
+if (!gotTheLock) {
+  app.quit()
+} else {
+  app.on('second-instance', (event, commandLine, workingDirectory) => {
+    // Someone tried to run a second instance, we should focus our window.
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) mainWindow.restore()
+      mainWindow.focus()
+    }
+  })
+
+  // Create mainWindow, load the rest of the app, etc...
+  app.whenReady().then(() => {
+    createWindow()
+  })
+
+  // Handle the protocol. In this case, we choose to show an Error Box.
+  app.on('open-url', (event, url) => {
+    dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
+  })
+}
+```
+
+#### MacOS and Linux code:
+
+```javascript
+// This method will be called when Electron has finished
+// initialization and is ready to create browser windows.
+// Some APIs can only be used after this event occurs.
+app.whenReady().then(() => {
+  createWindow()
+})
+
+// Handle the protocol. In this case, we choose to show an Error Box.
+app.on('open-url', (event, url) => {
+  dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
+})
+```
+
+Finally, we will add some additional code to handle when someone closes our application.
+
+```javascript
+// Quit when all windows are closed, except on macOS. There, it's common
+// for applications and their menu bar to stay active until the user quits
+// explicitly with Cmd + Q.
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit()
+})
+```
+
+## Important notes
+
+### Packaging
+
+On macOS and Linux, this feature will only work when your app is packaged. It will not work when
+you're launching it in development from the command-line. When you package your app you'll need to
+make sure the macOS `Info.plist` and the Linux `.desktop` files for the app are updated to include
+the new protocol handler. Some of the Electron tools for bundling and distributing apps handle
+this for you.
+
+#### [Electron Forge](https://electronforge.io)
+
+If you're using Electron Forge, adjust `packagerConfig` for macOS support, and the configuration for
+the appropriate Linux makers for Linux support, in your [Forge
+configuration](https://www.electronforge.io/configuration) _(please note the following example only
+shows the bare minimum needed to add the configuration changes)_:
+
+```json
+{
+  "config": {
+    "forge": {
+      "packagerConfig": {
+        "protocols": [
+          {
+            "name": "Electron Fiddle",
+            "schemes": ["electron-fiddle"]
+          }
+        ]
+      },
+      "makers": [
+        {
+          "name": "@electron-forge/maker-deb",
+          "config": {
+            "mimeType": ["x-scheme-handler/electron-fiddle"]
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+#### [Electron Packager](https://github.com/electron/electron-packager)
+
+For macOS support:
+
+If you're using Electron Packager's API, adding support for protocol handlers is similar to how
+Electron Forge is handled, except
+`protocols` is part of the Packager options passed to the `packager` function.
+
+```javascript
+const packager = require('electron-packager')
+
+packager({
+  // ...other options...
+  protocols: [
+    {
+      name: 'Electron Fiddle',
+      schemes: ['electron-fiddle']
+    }
+  ]
+
+}).then(paths => console.log(`SUCCESS: Created ${paths.join(', ')}`))
+  .catch(err => console.error(`ERROR: ${err.message}`))
+```
+
+If you're using Electron Packager's CLI, use the `--protocol` and `--protocol-name` flags. For
+example:
+
+```shell
+npx electron-packager . --protocol=electron-fiddle --protocol-name="Electron Fiddle"
+```
+
+## Conclusion
+
+After you start your Electron app, you can enter in a URL in your browser that contains the custom
+protocol, for example `"electron-fiddle://open"` and observe that the application will respond and
+show an error dialog box.
+
+<!--
+    Because Electron examples usually require multiple files (HTML, CSS, JS
+    for the main and renderer process, etc.), we use this custom code block
+    for Fiddle (https://www.electronjs.org/fiddle).
+    Please modify any of the files in the referenced folder to fit your
+    example.
+    The content in this codeblock will not be rendered in the website so you
+    can leave it empty.
+-->
+
+```fiddle docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app
+
+```
+
+<!-- ✍ Explanation of the code below -->

docs/tutorial/linux-desktop-actions.md

@@ -1,4 +1,4 @@
-# Custom Linux Desktop Launcher Actions
+# Desktop Launcher Actions (Linux)
 
 ## Overview
 

docs/tutorial/macos-dock.md

@@ -1,4 +1,4 @@
-# Configuring the macOS Dock
+# Dock (macOS)
 
 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

docs/tutorial/notifications.md

@@ -1,4 +1,4 @@
-# Notifications (Windows, Linux, macOS)
+# Notifications
 
 ## Overview
 
@@ -130,14 +130,6 @@ if you exceed that limit.
 
 [apple-notification-guidelines]: https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/
 
-#### Advanced Notifications
-
-Later versions of macOS allow for notifications with an input field, allowing the user
-to quickly reply to a notification. In order to send notifications with an input field,
-use the userland module [node-mac-notifier][node-mac-notifier].
-
-[node-mac-notifier]: https://github.com/CharlieHess/node-mac-notifier
-
 #### Do not disturb / Session State
 
 To detect whether or not you're allowed to send a notification, use the userland module

docs/tutorial/offscreen-rendering.md

@@ -17,7 +17,7 @@ the dirty area is passed to the `paint` event to be more efficient.
 losses with no benefits.
 * When nothing is happening on a webpage, no frames are generated.
 * An offscreen window is always created as a
-[Frameless Window](../api/frameless-window.md).
+[Frameless Window](../tutorial/window-customization.md)..
 
 ### Rendering Modes
 

docs/tutorial/performance.md

@@ -120,9 +120,9 @@ file in the directory you executed it in. Both files can be analyzed using
 the Chrome Developer Tools, using the `Performance` and `Memory` tabs
 respectively.
 
-![Performance CPU Profile][performance-cpu-prof]
+![Performance CPU Profile](../images/performance-cpu-prof.png)
 
-![Performance Heap Memory Profile][performance-heap-prof]
+![Performance Heap Memory Profile](../images/performance-heap-prof.png)
 
 In this example, on the author's machine, we saw that loading `request` took
 almost half a second, whereas `node-fetch` took dramatically less memory
@@ -412,8 +412,6 @@ As of writing this article, the popular choices include [Webpack][webpack],
 [Parcel][parcel], and [rollup.js][rollup].
 
 [security]: ./security.md
-[performance-cpu-prof]: ../images/performance-cpu-prof.png
-[performance-heap-prof]: ../images/performance-heap-prof.png
 [chrome-devtools-tutorial]: https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/
 [worker-threads]: https://nodejs.org/api/worker_threads.html
 [web-workers]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers

docs/tutorial/process-model.md

@@ -83,7 +83,7 @@ As a practical example, the app shown in the [quick start guide][quick-start-lif
 uses `app` APIs to create a more native application window experience.
 
 ```js title='main.js'
-// quitting the app when no windows are open on macOS
+// quitting the app when no windows are open on non-macOS platforms
 app.on('window-all-closed', function () {
   if (process.platform !== 'darwin') app.quit()
 })
@@ -148,7 +148,9 @@ A preload script can be attached to the main process in the `BrowserWindow` cons
 const { BrowserWindow } = require('electron')
 //...
 const win = new BrowserWindow({
-  preload: 'path/to/preload.js'
+  webPreferences: {
+    preload: 'path/to/preload.js'
+  }
 })
 //...
 ```

docs/tutorial/progress-bar.md

@@ -1,4 +1,4 @@
-# Progress Bar in Taskbar (Windows, macOS, Unity)
+# Taskbar Progress Bar (Windows & macOS)
 
 ## Overview
 
@@ -7,16 +7,16 @@ without the need of switching to the window itself.
 
 On Windows, you can use a taskbar button to display a progress bar.
 
-![Windows Progress Bar][windows-progress-bar]
+![Windows Progress Bar](../images/windows-progress-bar.png)
 
 On macOS, the progress bar will be displayed as a part of the dock icon.
 
-![macOS Progress Bar][macos-progress-bar]
+![macOS Progress Bar](../images/macos-progress-bar.png)
 
 On Linux, the Unity graphical interface also has a similar feature that allows
 you to specify the progress bar in the launcher.
 
-![Linux Progress Bar][linux-progress-bar]
+![Linux Progress Bar](../images/linux-progress-bar.png)
 
 > NOTE: on Windows, each window can have its own progress bar, whereas on macOS
 and Linux (Unity) there can be only one progress bar for the application.
@@ -102,8 +102,4 @@ For macOS, the progress bar will also be indicated for your application
 when using [Mission Control](https://support.apple.com/en-us/HT204100):
 
 ![Mission Control Progress Bar](../images/mission-control-progress-bar.png)
-
-[windows-progress-bar]: https://cloud.githubusercontent.com/assets/639601/5081682/16691fda-6f0e-11e4-9676-49b6418f1264.png
-[macos-progress-bar]: ../images/macos-progress-bar.png
-[linux-progress-bar]: ../images/linux-progress-bar.png
 [setprogressbar]: ../api/browser-window.md#winsetprogressbarprogress-options

docs/tutorial/quick-start.md

@@ -223,7 +223,7 @@ app.on('window-all-closed', function () {
 
 [node-platform]: https://nodejs.org/api/process.html#process_process_platform
 [window-all-closed]: ../api/app.md#event-window-all-closed
-[window-all-closed]: ../api/app.md#appquit
+[app-quit]: ../api/app.md#appquit
 
 #### Open a window if none are open (macOS)
 

docs/tutorial/represented-file.md

@@ -1,4 +1,4 @@
-# Represented File for macOS BrowserWindows
+# Representing Files in a BrowserWindow (macOS)
 
 ## Overview
 

docs/tutorial/sandbox.md

@@ -79,7 +79,7 @@ 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.
+[`contextIsolation`][context-isolation] is enabled.
 
 ## Configuring the sandbox
 

docs/tutorial/security.md

@@ -23,7 +23,7 @@ your responsibility to ensure that the code is not malicious.
 ## Reporting Security Issues
 
 For information on how to properly disclose an Electron vulnerability,
-see [SECURITY.md](https://github.com/electron/electron/tree/master/SECURITY.md)
+see [SECURITY.md](https://github.com/electron/electron/tree/main/SECURITY.md)
 
 ## Chromium Security Issues and Upgrades
 
@@ -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](#15-use-a-current-version-of-electron)".
+see "[Use a current version of Electron](#16-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
@@ -88,18 +88,19 @@ You should at least follow these steps to improve the security of your applicati
 1. [Only load secure content](#1-only-load-secure-content)
 2. [Disable the Node.js integration in all renderers that display remote content](#2-do-not-enable-nodejs-integration-for-remote-content)
 3. [Enable context isolation in all renderers that display remote content](#3-enable-context-isolation-for-remote-content)
-4. [Use `ses.setPermissionRequestHandler()` in all sessions that load remote content](#4-handle-session-permission-requests-from-remote-content)
-5. [Do not disable `webSecurity`](#5-do-not-disable-websecurity)
-6. [Define a `Content-Security-Policy`](#6-define-a-content-security-policy) and use restrictive rules (i.e. `script-src 'self'`)
-7. [Do not set `allowRunningInsecureContent` to `true`](#7-do-not-set-allowrunninginsecurecontent-to-true)
-8. [Do not enable experimental features](#8-do-not-enable-experimental-features)
-9. [Do not use `enableBlinkFeatures`](#9-do-not-use-enableblinkfeatures)
-10. [`<webview>`: Do not use `allowpopups`](#10-do-not-use-allowpopups)
-11. [`<webview>`: Verify options and params](#11-verify-webview-options-before-creation)
-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. [Use a current version of Electron](#15-use-a-current-version-of-electron)
+4. [Enable sandboxing](#4-enable-sandboxing)
+5. [Use `ses.setPermissionRequestHandler()` in all sessions that load remote content](#5-handle-session-permission-requests-from-remote-content)
+6. [Do not disable `webSecurity`](#6-do-not-disable-websecurity)
+7. [Define a `Content-Security-Policy`](#7-define-a-content-security-policy) and use restrictive rules (i.e. `script-src 'self'`)
+8. [Do not set `allowRunningInsecureContent` to `true`](#8-do-not-set-allowrunninginsecurecontent-to-true)
+9. [Do not enable experimental features](#9-do-not-enable-experimental-features)
+10. [Do not use `enableBlinkFeatures`](#10-do-not-use-enableblinkfeatures)
+11. [`<webview>`: Do not use `allowpopups`](#11-do-not-use-allowpopups)
+12. [`<webview>`: Verify options and params](#12-verify-webview-options-before-creation)
+13. [Disable or limit navigation](#13-disable-or-limit-navigation)
+14. [Disable or limit creation of new windows](#14-disable-or-limit-creation-of-new-windows)
+15. [Do not use `openExternal` with untrusted content](#15-do-not-use-openexternal-with-untrusted-content)
+16. [Use a current version of Electron](#16-use-a-current-version-of-electron)
 
 To automate the detection of misconfigurations and insecure patterns, it is
 possible to use
@@ -239,7 +240,26 @@ and prevent the use of Node primitives `contextIsolation` **must** also be used.
 For more information on what `contextIsolation` is and how to enable it please
 see our dedicated [Context Isolation](context-isolation.md) document.
 
-## 4) Handle Session Permission Requests From Remote Content
+## 4) Enable Sandboxing
+
+[Sandboxing](sandbox.md) is a Chromium feature that uses the operating system to
+significantly limit what renderer processes have access to. You should enable
+the sandbox in all renderers. Loading, reading or processing any untrusted
+content in an unsandboxed process, including the main process, is not advised.
+
+### How?
+
+When creating a window, pass the `sandbox: true` option in `webPreferences`:
+
+```js
+const win = new BrowserWindow({
+  webPreferences: {
+    sandbox: true
+  }
+})
+```
+
+## 5) Handle Session Permission Requests From Remote Content
 
 You may have seen permission requests while using Chrome: They pop up whenever
 the website attempts to use a feature that the user has to manually approve (
@@ -277,7 +297,7 @@ session
   })
 ```
 
-## 5) Do Not Disable WebSecurity
+## 6) Do Not Disable WebSecurity
 
 _Recommendation is Electron's default_
 
@@ -318,7 +338,7 @@ const mainWindow = new BrowserWindow()
 <webview src="page.html"></webview>
 ```
 
-## 6) Define a Content Security Policy
+## 7) Define a Content Security Policy
 
 A Content Security Policy (CSP) is an additional layer of protection against
 cross-site-scripting attacks and data injection attacks. We recommend that they
@@ -374,7 +394,7 @@ on a page directly in the markup using a `<meta>` tag:
 <meta http-equiv="Content-Security-Policy" content="default-src 'none'">
 ```
 
-## 7) Do Not Set `allowRunningInsecureContent` to `true`
+## 8) Do Not Set `allowRunningInsecureContent` to `true`
 
 _Recommendation is Electron's default_
 
@@ -407,7 +427,7 @@ const mainWindow = new BrowserWindow({
 const mainWindow = new BrowserWindow({})
 ```
 
-## 8) Do Not Enable Experimental Features
+## 9) Do Not Enable Experimental Features
 
 _Recommendation is Electron's default_
 
@@ -439,7 +459,7 @@ const mainWindow = new BrowserWindow({
 const mainWindow = new BrowserWindow({})
 ```
 
-## 9) Do Not Use `enableBlinkFeatures`
+## 10) Do Not Use `enableBlinkFeatures`
 
 _Recommendation is Electron's default_
 
@@ -471,7 +491,7 @@ const mainWindow = new BrowserWindow({
 const mainWindow = new BrowserWindow()
 ```
 
-## 10) Do Not Use `allowpopups`
+## 11) Do Not Use `allowpopups`
 
 _Recommendation is Electron's default_
 
@@ -498,7 +518,7 @@ you know it needs that feature.
 <webview src="page.html"></webview>
 ```
 
-## 11) Verify WebView Options Before Creation
+## 12) Verify WebView Options Before Creation
 
 A WebView created in a renderer process that does not have Node.js integration
 enabled will not be able to enable integration itself. However, a WebView will
@@ -545,7 +565,7 @@ app.on('web-contents-created', (event, contents) => {
 Again, this list merely minimizes the risk, it does not remove it. If your goal
 is to display a website, a browser will be a more secure option.
 
-## 12) Disable or limit navigation
+## 13) Disable or limit navigation
 
 If your app has no need to navigate or only needs to navigate to known pages,
 it is a good idea to limit navigation outright to that known scope, disallowing
@@ -589,7 +609,7 @@ app.on('web-contents-created', (event, contents) => {
 })
 ```
 
-## 13) Disable or limit creation of new windows
+## 14) Disable or limit creation of new windows
 
 If you have a known set of windows, it's a good idea to limit the creation of
 additional windows in your app.
@@ -636,7 +656,7 @@ app.on('web-contents-created', (event, contents) => {
 })
 ```
 
-## 14) Do not use `openExternal` with untrusted content
+## 15) Do not use `openExternal` with untrusted content
 
 Shell's [`openExternal`][open-external] allows opening a given protocol URI with
 the desktop's native utilities. On macOS, for instance, this function is similar
@@ -663,7 +683,7 @@ const { shell } = require('electron')
 shell.openExternal('https://example.com/index.html')
 ```
 
-## 15) Use a current version of Electron
+## 16) 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

docs/tutorial/snapcraft.md

@@ -1,4 +1,4 @@
-# Snapcraft Guide (Ubuntu Software Center & More)
+# Snapcraft Guide (Linux)
 
 This guide provides information on how to package your Electron application
 for any Snapcraft environment, including the Ubuntu Software Center.