Bump v12.2.1

* fix: Enable X509_V_FLAG_TRUSTED_FIRST flag in BoringSSL

Fixes: https://github.com/electron/electron/issues/31212
Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

* Update .patches

* chore: update patches

Co-authored-by: Juan Cruz Viotti <jv@jviotti.com>
Co-authored-by: Samuel Attard <sam@electronjs.org>
Co-authored-by: PatchUp <73610968+patchup[bot]@users.noreply.github.com>

.circleci/config.yml

@@ -57,6 +57,16 @@ parameters:
     type: boolean
     default: false
 
+# Executors
+executors:
+  linux-arm:
+    resource_class: electronjs/linux-arm
+    machine: true
+
+  linux-arm64:
+    resource_class: electronjs/linux-arm64
+    machine: true
+
 # The config expects the following environment variables to be set:
 #  - "SLACK_WEBHOOK" Slack hook URL to send notifications.
 #
@@ -69,7 +79,7 @@ parameters:
 # Build machines configs.
 docker-image: &docker-image
   docker:
-    - image: electron.azurecr.io/build:4cec2c5ab66765caa724e37bae2bffb9b29722a5
+    - image: electron.azurecr.io/build:d818f06a9b1540c7fd38f75ad5a2c493dd6843b6
 
 machine-linux-medium: &machine-linux-medium
   <<: *docker-image
@@ -225,6 +235,25 @@ step-maybe-notify-slack-success: &step-maybe-notify-slack-success
       fi
     when: on_success
 
+step-maybe-cleanup-arm: &step-maybe-cleanup-arm
+  run:
+    name: Cleanup after testing
+    command: |
+      if  [ "$TARGET_ARCH" == "arm64" ] &&[ "`uname`" == "Darwin" ]; then
+        killall Electron || echo "No Electron processes left running"
+        killall Safari || echo "No Safari processes left running"
+        rm -rf ~/Library/Application\ Support/Electron*
+        rm -rf ~/Library/Application\ Support/electron*
+      elif [ "$TARGET_ARCH" == "arm" ] || [ "$TARGET_ARCH" == "arm64" ]; then
+        XVFB=/usr/bin/Xvfb
+        /sbin/start-stop-daemon --stop --exec $XVFB || echo "Xvfb not running"
+        pkill electron || echo "electron not running"
+        rm -rf ~/.config/Electron*
+        rm -rf ~/.config/electron*
+      fi
+
+    when: always
+
 step-checkout-electron: &step-checkout-electron
   checkout:
     path: src/electron
@@ -261,7 +290,7 @@ step-gclient-sync: &step-gclient-sync
           if ! git diff-index --quiet HEAD --; then
             # There are changes to the patches. Make a git commit with the updated patches
             git add patches
-            GIT_COMMITTER_NAME="Electron Bot" GIT_COMMITTER_EMAIL="electron@github.com" git commit -m "update patches" --author="Electron Bot <electron@github.com>"
+            GIT_COMMITTER_NAME="PatchUp" GIT_COMMITTER_EMAIL="73610968+patchup[bot]@users.noreply.github.com" git commit -m "chore: update patches" --author="PatchUp <73610968+patchup[bot]@users.noreply.github.com>"
             # Export it
             mkdir -p ../../patches
             git format-patch -1 --stdout --keep-subject --no-stat --full-index > ../../patches/update-patches.patch
@@ -308,9 +337,11 @@ step-setup-goma-for-build: &step-setup-goma-for-build
       npm install
       mkdir third_party
       node -e "require('./src/utils/goma.js').downloadAndPrepare({ gomaOneForAll: true })"
+      export GOMA_FALLBACK_ON_AUTH_FAILURE=true
       third_party/goma/goma_ctl.py ensure_start
       echo 'export GN_GOMA_FILE='`node -e "console.log(require('./src/utils/goma.js').gnFilePath)"` >> $BASH_ENV
       echo 'export LOCAL_GOMA_DIR='`node -e "console.log(require('./src/utils/goma.js').dir)"` >> $BASH_ENV
+      echo 'export GOMA_FALLBACK_ON_AUTH_FAILURE=true' >> $BASH_ENV
       cd ..
 
 step-restore-brew-cache: &step-restore-brew-cache
@@ -512,6 +543,7 @@ step-electron-build: &step-electron-build
         ninja -C out/Default electron:electron_mksnapshot_zip -j $NUMBER_OF_NINJA_PROCESSES
         ninja -C out/Default tools/v8_context_snapshot -j $NUMBER_OF_NINJA_PROCESSES
         gn desc out/Default v8:run_mksnapshot_default args > out/Default/mksnapshot_args
+        (cd out/Default; zip mksnapshot.zip mksnapshot_args clang_x64_v8_arm64/gen/v8/embedded.S)
         rm -rf out/Default/clang_x64_v8_arm64/obj
 
         # Regenerate because we just deleted some ninja files 
@@ -666,6 +698,7 @@ step-persist-data-for-tests: &step-persist-data-for-tests
       - src/electron
       - src/third_party/electron_node
       - src/third_party/nan
+      - src/cross-arch-snapshots
 
 step-electron-dist-unzip: &step-electron-dist-unzip
   run:
@@ -728,7 +761,11 @@ step-verify-mksnapshot: &step-verify-mksnapshot
     name: Verify mksnapshot
     command: |
       cd src
-      python electron/script/verify-mksnapshot.py --source-root "$PWD" --build-dir out/Default
+      if [ "$TARGET_ARCH" == "arm" ] || [ "$TARGET_ARCH" == "arm64" ]; then
+        python electron/script/verify-mksnapshot.py --source-root "$PWD" --build-dir out/Default --snapshot-files-dir $PWD/cross-arch-snapshots
+      else
+        python electron/script/verify-mksnapshot.py --source-root "$PWD" --build-dir out/Default
+      fi
 
 step-verify-chromedriver: &step-verify-chromedriver
   run:
@@ -855,23 +892,6 @@ step-maybe-cross-arch-snapshot-store: &step-maybe-cross-arch-snapshot-store
     path: src/cross-arch-snapshots
     destination: cross-arch-snapshots
 
-step-maybe-trigger-arm-test: &step-maybe-trigger-arm-test
-  run:
-    name: Trigger an arm test on VSTS if applicable
-    command: |
-      cd src
-      # Only run for non-fork prs
-      if [ "$TRIGGER_ARM_TEST" == "true" ] && [ -z "$CIRCLE_PR_NUMBER" ]; then
-        #Trigger VSTS job, passing along CircleCI job number and branch to build
-        if [ "`uname`" == "Darwin" ]; then
-          echo "Triggering electron-arm2-testing build on Azure DevOps"  
-          node electron/script/release/ci-release-build.js --job=electron-arm2-testing --ci=DevOps --armTest --circleBuildNum=$CIRCLE_BUILD_NUM $CIRCLE_BRANCH
-        else
-          echo "Triggering electron-$TARGET_ARCH-testing build on VSTS"  
-          node electron/script/release/ci-release-build.js --job=electron-$TARGET_ARCH-testing --ci=VSTS --armTest --circleBuildNum=$CIRCLE_BUILD_NUM $CIRCLE_BRANCH
-        fi
-      fi
-
 step-maybe-generate-typescript-defs: &step-maybe-generate-typescript-defs
   run:
     name: Generate type declarations
@@ -1286,8 +1306,14 @@ steps-tests: &steps-tests
           ELECTRON_DISABLE_SECURITY_WARNINGS: 1
         command: |
           cd src
-          (cd electron && node script/yarn test --runners=main --trace-uncaught --enable-logging --files $(circleci tests glob spec-main/*-spec.ts | circleci tests split))
-          (cd electron && node script/yarn test --runners=remote --trace-uncaught --enable-logging --files $(circleci tests glob spec/*-spec.js | circleci tests split))
+          if [ "$TARGET_ARCH" == "arm" ] || [ "$TARGET_ARCH" == "arm64" ]; then
+            export ELECTRON_SKIP_NATIVE_MODULE_TESTS=true
+            (cd electron && node script/yarn test --runners=main --trace-uncaught --enable-logging)
+            (cd electron && node script/yarn test --runners=remote --trace-uncaught --enable-logging)
+          else
+            (cd electron && node script/yarn test --runners=main --trace-uncaught --enable-logging --files $(circleci tests glob spec-main/*-spec.ts | circleci tests split))
+            (cd electron && node script/yarn test --runners=remote --trace-uncaught --enable-logging --files $(circleci tests glob spec/*-spec.js | circleci tests split))
+          fi
     - run:
         name: Check test results existence
         command: |
@@ -1308,6 +1334,8 @@ steps-tests: &steps-tests
 
     - *step-maybe-notify-slack-failure
 
+    - *step-maybe-cleanup-arm
+
 steps-test-nan: &steps-test-nan
   steps:
     - attach_workspace:
@@ -1580,9 +1608,6 @@ commands:
                 steps:
                   - *step-save-out-cache
 
-            # Trigger tests on arm hardware if needed
-            - *step-maybe-trigger-arm-test
-
             - *step-maybe-notify-slack-failure
 
   electron-publish:
@@ -1910,7 +1935,7 @@ jobs:
       GCLIENT_EXTRA_ARGS: '--custom-var=checkout_arm=True --custom-var=checkout_arm64=True'
     steps:
       - electron-build:
-          persist: false
+          persist: true
           checkout: true
           use-out-cache: false
 
@@ -1968,7 +1993,7 @@ jobs:
       GCLIENT_EXTRA_ARGS: '--custom-var=checkout_arm=True --custom-var=checkout_arm64=True'
     steps:
       - electron-build:
-          persist: false
+          persist: true
           checkout: true
           use-out-cache: false
 
@@ -2356,6 +2381,24 @@ jobs:
       <<: *env-send-slack-notifications
     <<: *steps-verify-ffmpeg
 
+  linux-arm-testing-tests:
+    executor: linux-arm
+    environment:
+      <<: *env-arm
+      <<: *env-global
+      <<: *env-headless-testing
+      <<: *env-stack-dumping
+    <<: *steps-tests
+
+  linux-arm64-testing-tests:
+    executor: linux-arm64
+    environment:
+      <<: *env-arm64
+      <<: *env-global
+      <<: *env-headless-testing
+      <<: *env-stack-dumping
+    <<: *steps-tests
+
   osx-testing-x64-tests:
     <<: *machine-mac-large
     environment:
@@ -2536,15 +2579,19 @@ workflows:
     - osx-publish-x64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
     - mas-publish-x64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
     - osx-publish-arm64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
     - mas-publish-arm64-skip-checkout:
         requires:
           - mac-checkout
+        context: release-env
 
   lint:
     when: << pipeline.parameters.run-lint >>
@@ -2584,8 +2631,23 @@ workflows:
             - linux-ia32-testing
 
       - linux-arm-testing
+      - linux-arm-testing-tests:
+          filters:
+            branches:
+              # Do not run this on forked pull requests
+              ignore: /pull\/[0-9]+/        
+          requires:
+            - linux-arm-testing      
 
       - linux-arm64-testing
+      - linux-arm64-testing-tests:
+          filters:
+            branches:
+              # Do not run this on forked pull requests
+              ignore: /pull\/[0-9]+/        
+          requires:
+            - linux-arm64-testing
+
       - linux-arm64-testing-gn-check:
           requires:
             - linux-checkout-fast

.env.example

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

.gitignore

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

DEPS

@@ -14,7 +14,7 @@ gclient_gn_args = [
 
 vars = {
   'chromium_version':
-    '89.0.4389.90',
+    '89.0.4389.128',
   'node_version':
     'v14.16.0',
   'nan_version':

ELECTRON_VERSION

@@ -1 +1 @@
-12.0.2
+12.2.1

README.md

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

appveyor.yml

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

build/npm-run.py

@@ -21,6 +21,6 @@ except subprocess.CalledProcessError as e:
         + "' failed with code '"
         + str(e.returncode)
         + "':\n"
-        + e.output
+        + e.output.decode('utf8')
     )
     sys.exit(e.returncode)

build/webpack/webpack.config.base.js

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

build/webpack/webpack.gni

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

chromium_src/BUILD.gn

@@ -139,6 +139,8 @@ static_library("chrome") {
 
   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",

default_app/default_app.ts

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

docs/README.md

@@ -18,20 +18,14 @@ an issue:
 
 ## Guides and Tutorials
 
-### Quickstart
+### Getting started
 
-* [Quick Start Guide](tutorial/quick-start.md)
-  * [Prerequisites](tutorial/quick-start.md#prerequisites)
-  * [Create a basic application](tutorial/quick-start.md#create-a-basic-application)
-  * [Run your application](tutorial/quick-start.md#run-your-application)
-  * [Package and distribute the application](tutorial/quick-start.md#package-and-distribute-the-application)
+* [Introduction](tutorial/introduction.md)
+* [Quick Start](tutorial/quick-start.md)
+* [Process Model](tutorial/process-model.md)
 
 ### Learning the basics
 
-* [Electron's Process Model](tutorial/quick-start.md#application-architecture)
-  * [Main and Renderer Processes](tutorial/quick-start.md#main-and-renderer-processes)
-  * [Electron API](tutorial/quick-start.md#electron-api)
-  * [Node.js API](tutorial/quick-start.md#nodejs-api)
 * Adding Features to Your App
   * [Notifications](tutorial/notifications.md)
   * [Recent Documents](tutorial/recent-documents.md)
@@ -59,6 +53,7 @@ an issue:
   * [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
   * [Performance Strategies](tutorial/performance.md)
   * [Security Strategies](tutorial/security.md)
+  * [Process Sandboxing](tutorial/sandbox.md)
 * [Accessibility](tutorial/accessibility.md)
   * [Manually Enabling Accessibility Features](tutorial/accessibility.md#manually-enabling-accessibility-features)
 * [Testing and Debugging](tutorial/application-debugging.md)
@@ -68,6 +63,7 @@ an issue:
   * [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
   * [DevTools Extension](tutorial/devtools-extension.md)
   * [Automated Testing with a Custom Driver](tutorial/automated-testing-with-a-custom-driver.md)
+  * [REPL](tutorial/repl.md)
 * [Distribution](tutorial/application-distribution.md)
   * [Supported Platforms](tutorial/support.md#supported-platforms)
   * [Code Signing](tutorial/code-signing.md)
@@ -91,11 +87,6 @@ These individual tutorials expand on topics discussed in the guide above.
 * Electron Releases & Developer Feedback
   * [Versioning Policy](tutorial/electron-versioning.md)
   * [Release Timelines](tutorial/electron-timelines.md)
-* [Packaging App Source Code with asar](tutorial/application-packaging.md)
-  * [Generating asar Archives](tutorial/application-packaging.md#generating-asar-archives)
-  * [Using asar Archives](tutorial/application-packaging.md#using-asar-archives)
-  * [Limitations](tutorial/application-packaging.md#limitations-of-the-node-api)
-  * [Adding Unpacked Files to asar Archives](tutorial/application-packaging.md#adding-unpacked-files-to-asar-archives)
 * [Testing Widevine CDM](tutorial/testing-widevine-cdm.md)
 
 ---
@@ -131,6 +122,8 @@ These individual tutorials expand on topics discussed in the guide above.
 * [ipcMain](api/ipc-main.md)
 * [Menu](api/menu.md)
 * [MenuItem](api/menu-item.md)
+* [MessageChannelMain](api/message-channel-main.md)
+* [MessagePortMain](api/message-port-main.md)
 * [net](api/net.md)
 * [netLog](api/net-log.md)
 * [nativeTheme](api/native-theme.md)
@@ -140,6 +133,7 @@ These individual tutorials expand on topics discussed in the guide above.
 * [protocol](api/protocol.md)
 * [screen](api/screen.md)
 * [session](api/session.md)
+* [ShareMenu](api/share-menu.md)
 * [systemPreferences](api/system-preferences.md)
 * [TouchBar](api/touch-bar.md)
 * [Tray](api/tray.md)
@@ -149,15 +143,14 @@ These individual tutorials expand on topics discussed in the guide above.
 ### Modules for the Renderer Process (Web Page):
 
 * [contextBridge](api/context-bridge.md)
-* [desktopCapturer](api/desktop-capturer.md)
 * [ipcRenderer](api/ipc-renderer.md)
-* [remote](api/remote.md)
 * [webFrame](api/web-frame.md)
 
 ### Modules for Both Processes:
 
 * [clipboard](api/clipboard.md)
 * [crashReporter](api/crash-reporter.md)
+* [desktopCapturer](api/desktop-capturer.md)
 * [nativeImage](api/native-image.md)
 * [shell](api/shell.md)
 

docs/api/accelerator.md

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

docs/api/app.md

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

docs/api/browser-view.md

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

docs/api/browser-window.md

@@ -265,12 +265,12 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       be the absolute file path to the script.
       When node integration is turned off, the preload script can reintroduce
       Node global symbols back to the global scope. See example
-      [here](process.md#event-loaded).
+      [here](context-bridge.md#exposing-node-global-symbols).
     * `sandbox` Boolean (optional) - If set, this will sandbox the renderer
       associated with the window, making it compatible with the Chromium
       OS-level sandbox and disabling the Node.js engine. This is not the same as
       the `nodeIntegration` option and the APIs available to the preload script
-      are more limited. Read more about the option [here](sandbox-option.md).
+      are more limited. Read more about the option [here](../tutorial/sandbox.md).
     * `enableRemoteModule` Boolean (optional) - Whether to enable the [`remote`](remote.md) module.
       Default is `false`.
     * `session` [Session](session.md#class-session) (optional) - Sets the session used by the
@@ -1386,7 +1386,7 @@ can be be used to listen to changes to tablet mode.
 
 #### `win.getMediaSourceId()`
 
-Returns `String` - Window id in the format of DesktopCapturerSource's id. For example "window:1234:0".
+Returns `String` - Window id in the format of DesktopCapturerSource's id. For example "window:1324:0".
 
 More precisely the format is `window:id:other_id` where `id` is `HWND` on
 Windows, `CGWindowID` (`uint64_t`) on macOS and `Window` (`unsigned long`) on

docs/api/client-request.md

@@ -71,7 +71,7 @@ const request = net.request({
 
 Returns:
 
-* `response` IncomingMessage - An object representing the HTTP response message.
+* `response` [IncomingMessage](incoming-message.md) - An object representing the HTTP response message.
 
 #### Event: 'login'
 

docs/api/command-line-switches.md

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

docs/api/context-bridge.md

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

docs/api/dialog.md

@@ -24,7 +24,7 @@ The `dialog` module has the following methods:
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
     left empty the default label will be used.
   * `filters` [FileFilter[]](structures/file-filter.md) (optional)
-  * `properties` String[] (optional) - Contains which features the dialog should
+  * `properties` String[] (optional) - Contains which features the dialog should
     use. The following values are supported:
     * `openFile` - Allow files to be selected.
     * `openDirectory` - Allow directories to be selected.
@@ -87,7 +87,7 @@ dialog.showOpenDialogSync(mainWindow, {
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
     left empty the default label will be used.
   * `filters` [FileFilter[]](structures/file-filter.md) (optional)
-  * `properties` String[] (optional) - Contains which features the dialog should
+  * `properties` String[] (optional) - Contains which features the dialog should
     use. The following values are supported:
     * `openFile` - Allow files to be selected.
     * `openDirectory` - Allow directories to be selected.
@@ -112,7 +112,7 @@ Returns `Promise<Object>` - Resolve with an object containing the following:
 
 * `canceled` Boolean - whether or not the dialog was canceled.
 * `filePaths` String[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.
-* `bookmarks` String[] (optional) _macOS_ _mas_ - An array matching the `filePaths` array of base64 encoded strings which contains security scoped bookmark data. `securityScopedBookmarks` must be enabled for this to be populated. (For return values, see [table here](#bookmarks-array).)
+* `bookmarks` String[]&#32;(optional) _macOS_ _mas_ - An array matching the `filePaths` array of base64 encoded strings which contains security scoped bookmark data. `securityScopedBookmarks` must be enabled for this to be populated. (For return values, see [table here](#bookmarks-array).)
 
 The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
 
@@ -154,7 +154,7 @@ dialog.showOpenDialog(mainWindow, {
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)
 * `options` Object
-  * `title` String (optional)
+  * `title` String (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
   * `defaultPath` String (optional) - Absolute directory path, absolute file
     path, or file name to use by default.
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
@@ -165,7 +165,7 @@ dialog.showOpenDialog(mainWindow, {
     displayed in front of the filename text field.
   * `showsTagField` Boolean (optional) _macOS_ - Show the tags input box,
     defaults to `true`.
-  * `properties` String[] (optional)
+  * `properties` String[]&#32;(optional)
     * `showHiddenFiles` - Show hidden files in dialog.
     * `createDirectory` _macOS_ - Allow creating new directories from dialog.
     * `treatPackageAsDirectory` _macOS_ - Treat packages, such as `.app` folders,
@@ -185,7 +185,7 @@ The `filters` specifies an array of file types that can be displayed, see
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)
 * `options` Object
-  * `title` String (optional)
+  * `title` String (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
   * `defaultPath` String (optional) - Absolute directory path, absolute file
     path, or file name to use by default.
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
@@ -195,7 +195,7 @@ The `filters` specifies an array of file types that can be displayed, see
   * `nameFieldLabel` String (optional) _macOS_ - Custom label for the text
     displayed in front of the filename text field.
   * `showsTagField` Boolean (optional) _macOS_ - Show the tags input box, defaults to `true`.
-  * `properties` String[] (optional)
+  * `properties` String[]&#32;(optional)
     * `showHiddenFiles` - Show hidden files in dialog.
     * `createDirectory` _macOS_ - Allow creating new directories from dialog.
     * `treatPackageAsDirectory` _macOS_ - Treat packages, such as `.app` folders,
@@ -227,7 +227,7 @@ expanding and collapsing the dialog.
   `"warning"`. On Windows, `"question"` displays the same icon as `"info"`, unless
   you set an icon using the `"icon"` option. On macOS, both `"warning"` and
   `"error"` display the same warning icon.
-  * `buttons` String[] (optional) - Array of texts for buttons. On Windows, an empty array
+  * `buttons` String[]&#32;(optional) - Array of texts for buttons. On Windows, an empty array
     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.
@@ -273,7 +273,7 @@ If `browserWindow` is not shown dialog will not be attached to it. In such case
   `"warning"`. On Windows, `"question"` displays the same icon as `"info"`, unless
   you set an icon using the `"icon"` option. On macOS, both `"warning"` and
   `"error"` display the same warning icon.
-  * `buttons` String[] (optional) - Array of texts for buttons. On Windows, an empty array
+  * `buttons` String[]&#32;(optional) - Array of texts for buttons. On Windows, an empty array
     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.

docs/api/frameless-window.md

@@ -82,8 +82,11 @@ win.show()
 * 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).
-* On Windows operating systems, transparent windows will not work when DWM is
+* 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

docs/api/locales.md

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

docs/api/menu.md

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

docs/api/message-channel-main.md

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

docs/api/message-port-main.md

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

docs/api/process.md

@@ -42,19 +42,6 @@ In sandboxed renderers the `process` object contains only a subset of the APIs:
 Emitted when Electron has loaded its internal initialization script and is
 beginning to load the web page or the main script.
 
-It can be used by the preload script to add removed Node global symbols back to
-the global scope when node integration is turned off:
-
-```javascript
-// preload.js
-const _setImmediate = setImmediate
-const _clearImmediate = clearImmediate
-process.once('loaded', () => {
-  global.setImmediate = _setImmediate
-  global.clearImmediate = _clearImmediate
-})
-```
-
 ## Properties
 
 ### `process.defaultApp` _Readonly_

docs/api/sandbox-option.md

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

docs/api/share-menu.md

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

docs/api/structures/display.md

@@ -11,9 +11,9 @@
 * `colorDepth` Number - The number of bits per pixel.
 * `depthPerComponent` Number - The number of bits per color component.
 * `displayFrequency` Number - The display refresh rate.
-* `bounds` [Rectangle](rectangle.md)
+* `bounds` [Rectangle](rectangle.md) - the bounds of the display in DIP points.
 * `size` [Size](size.md)
-* `workArea` [Rectangle](rectangle.md)
+* `workArea` [Rectangle](rectangle.md) - the work area of the display in DIP points.
 * `workAreaSize` [Size](size.md)
 * `internal` Boolean - `true` for an internal display and `false` for an external display
 

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

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

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

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

docs/api/structures/upload-file.md

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

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

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

docs/api/synopsis.md

@@ -13,7 +13,7 @@ either process type.
 
 The basic rule is: if a module is [GUI][gui] or low-level system related, then
 it should be only available in the main process. You need to be familiar with
-the concept of [main process vs. renderer process](../tutorial/quick-start.md#main-and-renderer-processes)
+the concept of main process vs. renderer process
 scripts to be able to use those modules.
 
 The main process script is like a normal Node.js script:
@@ -43,8 +43,6 @@ extra ability to use node modules if `nodeIntegration` is enabled:
 </html>
 ```
 
-To run your app, read [Run your app](../tutorial/quick-start.md#run-your-application).
-
 ## Destructuring assignment
 
 As of 0.37, you can use

docs/api/system-preferences.md

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

docs/api/touch-bar.md

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

docs/api/tray.md

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

docs/api/web-contents.md

@@ -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.
@@ -1169,6 +1189,7 @@ Ignore application menu shortcuts while this web contents is focused.
     * `url` String - The _resolved_ version of the URL passed to `window.open()`. e.g. opening a window with `window.open('foo')` will yield something like `https://the-origin/the/current/path/foo`.
     * `frameName` String - Name of the window provided in `window.open()`
     * `features` String - Comma separated list of window features provided to `window.open()`.
+
   Returns `{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}` - `deny` cancels the creation of the new
   window. `allow` will allow the new window to be created. Specifying `overrideBrowserWindowOptions` allows customization of the created window.
   Returning an unrecognized value such as a null, undefined, or an object
@@ -1305,8 +1326,7 @@ Inserts `text` to the focused element.
 * `text` String - Content to be searched, must not be empty.
 * `options` Object (optional)
   * `forward` Boolean (optional) - Whether to search forward or backward, defaults to `true`.
-  * `findNext` Boolean (optional) - Whether the operation is first request or a follow up,
-    defaults to `false`.
+  * `findNext` Boolean (optional) - Whether to begin a new text finding session with this request. Should be `true` for initial requests, and `false` for follow-up requests. Defaults to `false`.
   * `matchCase` Boolean (optional) - Whether search should be case-sensitive,
     defaults to `false`.
 

docs/api/web-request.md

@@ -154,7 +154,6 @@ response are visible by the time this listener is fired.
     * `timestamp` Double
     * `statusLine` String
     * `statusCode` Integer
-    * `requestHeaders` Record<string, string>
     * `responseHeaders` Record<string, string[]> (optional)
   * `callback` Function
     * `headersReceivedResponse` Object

docs/api/webview-tag.md

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

docs/api/window-open.md

@@ -117,15 +117,18 @@ const mainWindow = new BrowserWindow({
 mainWindow.webContents.setWindowOpenHandler(({ url }) => {
   if (url === 'about:blank') {
     return {
-      frame: false,
-      fullscreenable: false,
-      backgroundColor: 'black',
-      webPreferences: {
-        preload: 'my-child-window-preload-script.js'
+      action: 'allow',
+      overrideBrowserWindowOptions: {
+        frame: false,
+        fullscreenable: false,
+        backgroundColor: 'black',
+        webPreferences: {
+          preload: 'my-child-window-preload-script.js'
+        }
       }
     }
   }
-  return false
+  return { action: 'deny' }
 })
 ```
 

docs/breaking-changes.md

@@ -6,14 +6,20 @@ Breaking changes will be documented here, and deprecation warnings added to JS c
 
 This document uses the following convention to categorize breaking changes:
 
-- **API Changed:** An API was changed in such a way that code that has not been updated is guaranteed to throw an exception.
-- **Behavior Changed:** The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown.
-- **Default Changed:** Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value.
-- **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.
+* **API Changed:** An API was changed in such a way that code that has not been updated is guaranteed to throw an exception.
+* **Behavior Changed:** The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown.
+* **Default Changed:** Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value.
+* **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 (14.0)
 
+### API Changed: `window.(open)`
+
+The optional parameter `frameName` will no longer set the title of the window. This now follows the specification described by the [native documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#parameters) under the corresponding parameter `windowName`.
+
+If you were using this parameter to set the title of a window, you can instead use [win.setTitle(title)](https://www.electronjs.org/docs/api/browser-window#winsettitletitle).
+
 ### Removed: `worldSafeExecuteJavaScript`
 
 In Electron 14, `worldSafeExecuteJavaScript` will be removed.  There is no alternative, please
@@ -24,6 +30,28 @@ You will be affected by this change if you use either `webFrame.executeJavaScrip
 
 ## Planned Breaking API Changes (13.0)
 
+### API Changed: `session.setPermissionCheckHandler(handler)`
+
+The `handler` methods first parameter was previously always a `webContents`, it can now sometimes be `null`.  You should use the `requestingOrigin`, `embeddingOrigin` and `securityOrigin` properties to respond to the permission check correctly.  As the `webContents` can be `null` it can no longer be relied on.
+
+```js
+// Old code
+session.setPermissionCheckHandler((webContents, permission) => {
+  if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
+    return true
+  }
+  return false
+})
+
+// Replace with
+session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
+  if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
+    return true
+  }
+  return false
+})
+```
+
 ### Removed: `shell.moveItemToTrash()`
 
 The deprecated synchronous `shell.moveItemToTrash()` API has been removed. Use
@@ -36,6 +64,78 @@ shell.moveItemToTrash(path)
 shell.trashItem(path).then(/* ... */)
 ```
 
+### Removed: `BrowserWindow` extension APIs
+
+The deprecated extension APIs have been removed:
+
+* `BrowserWindow.addExtension(path)`
+* `BrowserWindow.addDevToolsExtension(path)`
+* `BrowserWindow.removeExtension(name)`
+* `BrowserWindow.removeDevToolsExtension(name)`
+* `BrowserWindow.getExtensions()`
+* `BrowserWindow.getDevToolsExtensions()`
+
+Use the session APIs instead:
+
+* `ses.loadExtension(path)`
+* `ses.removeExtension(extension_id)`
+* `ses.getAllExtensions()`
+
+```js
+// Removed in Electron 13
+BrowserWindow.addExtension(path)
+BrowserWindow.addDevToolsExtension(path)
+// Replace with
+session.defaultSession.loadExtension(path)
+```
+
+```js
+// Removed in Electron 13
+BrowserWindow.removeExtension(name)
+BrowserWindow.removeDevToolsExtension(name)
+// Replace with
+session.defaultSession.removeExtension(extension_id)
+```
+
+```js
+// Removed in Electron 13
+BrowserWindow.getExtensions()
+BrowserWindow.getDevToolsExtensions()
+// Replace with
+session.defaultSession.getAllExtensions()
+```
+
+### Removed: methods in `systemPreferences`
+
+The following `systemPreferences` methods have been deprecated:
+
+* `systemPreferences.isDarkMode()`
+* `systemPreferences.isInvertedColorScheme()`
+* `systemPreferences.isHighContrastColorScheme()`
+
+Use the following `nativeTheme` properties instead:
+
+* `nativeTheme.shouldUseDarkColors`
+* `nativeTheme.shouldUseInvertedColorScheme`
+* `nativeTheme.shouldUseHighContrastColors`
+
+```js
+// Removed in Electron 13
+systemPreferences.isDarkMode()
+// Replace with
+nativeTheme.shouldUseDarkColors
+
+// Removed in Electron 13
+systemPreferences.isInvertedColorScheme()
+// Replace with
+nativeTheme.shouldUseInvertedColorScheme
+
+// Removed in Electron 13
+systemPreferences.isHighContrastColorScheme()
+// Replace with
+nativeTheme.shouldUseHighContrastColors
+```
+
 ## Planned Breaking API Changes (12.0)
 
 ### Removed: Pepper Flash support
@@ -60,6 +160,9 @@ the previous behavior, `contextIsolation: false` must be specified in WebPrefere
 
 We [recommend having contextIsolation enabled](https://github.com/electron/electron/blob/master/docs/tutorial/security.md#3-enable-context-isolation-for-remote-content) for the security of your application.
 
+Another implication is that `require()` cannot be used in the renderer process unless
+`nodeIntegration` is `true` and `contextIsolation` is `false`.
+
 For more details see: https://github.com/electron/electron/issues/23506
 
 ### Removed: `crashReporter.getCrashesDirectory()`
@@ -79,12 +182,12 @@ app.getPath('crashDumps')
 The following `crashReporter` methods are no longer available in the renderer
 process:
 
-- `crashReporter.start`
-- `crashReporter.getLastCrashReport`
-- `crashReporter.getUploadedReports`
-- `crashReporter.getUploadToServer`
-- `crashReporter.setUploadToServer`
-- `crashReporter.getCrashesDirectory`
+* `crashReporter.start`
+* `crashReporter.getLastCrashReport`
+* `crashReporter.getUploadedReports`
+* `crashReporter.getUploadToServer`
+* `crashReporter.setUploadToServer`
+* `crashReporter.getCrashesDirectory`
 
 They should be called only from the main process.
 
@@ -135,6 +238,7 @@ shell.trashItem(path).then(/* ... */)
 ## Planned Breaking API Changes (11.0)
 
 ### Removed: `BrowserView.{destroy, fromId, fromWebContents, getAllViews}` and `id` property of `BrowserView`
+
 The experimental APIs `BrowserView.{destroy, fromId, fromWebContents, getAllViews}`
 have now been removed. Additionally, the `id` property of `BrowserView`
 has also been removed.
@@ -174,12 +278,12 @@ app.getPath('crashDumps')
 Calling the following `crashReporter` methods from the renderer process is
 deprecated:
 
-- `crashReporter.start`
-- `crashReporter.getLastCrashReport`
-- `crashReporter.getUploadedReports`
-- `crashReporter.getUploadToServer`
-- `crashReporter.setUploadToServer`
-- `crashReporter.getCrashesDirectory`
+* `crashReporter.start`
+* `crashReporter.getLastCrashReport`
+* `crashReporter.getUploadedReports`
+* `crashReporter.getUploadToServer`
+* `crashReporter.setUploadToServer`
+* `crashReporter.getCrashesDirectory`
 
 The only non-deprecated methods remaining in the `crashReporter` module in the
 renderer are `addExtraParameter`, `removeExtraParameter` and `getParameters`.
@@ -221,6 +325,7 @@ We [recommend moving away from the remote
 module](https://medium.com/@nornagon/electrons-remote-module-considered-harmful-70d69500f31).
 
 ### `protocol.unregisterProtocol`
+
 ### `protocol.uninterceptProtocol`
 
 The APIs are now synchronous and the optional callback is no longer needed.
@@ -233,14 +338,23 @@ protocol.unregisterProtocol(scheme)
 ```
 
 ### `protocol.registerFileProtocol`
+
 ### `protocol.registerBufferProtocol`
+
 ### `protocol.registerStringProtocol`
+
 ### `protocol.registerHttpProtocol`
+
 ### `protocol.registerStreamProtocol`
+
 ### `protocol.interceptFileProtocol`
+
 ### `protocol.interceptStringProtocol`
+
 ### `protocol.interceptBufferProtocol`
+
 ### `protocol.interceptHttpProtocol`
+
 ### `protocol.interceptStreamProtocol`
 
 The APIs are now synchronous and the optional callback is no longer needed.
@@ -285,6 +399,7 @@ For more detailed information see [#18397](https://github.com/electron/electron/
 ### Deprecated: `BrowserWindow` extension APIs
 
 The following extension APIs have been deprecated:
+
 * `BrowserWindow.addExtension(path)`
 * `BrowserWindow.addDevToolsExtension(path)`
 * `BrowserWindow.removeExtension(name)`
@@ -293,6 +408,7 @@ The following extension APIs have been deprecated:
 * `BrowserWindow.getDevToolsExtensions()`
 
 Use the session APIs instead:
+
 * `ses.loadExtension(path)`
 * `ses.removeExtension(extension_id)`
 * `ses.getAllExtensions()`
@@ -373,7 +489,7 @@ Clone Algorithm][SCA], the same algorithm used to serialize messages for
 `postMessage`. This brings about a 2x performance improvement for large
 messages, but also brings some breaking changes in behavior.
 
-- Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any
+* Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any
   such values, over IPC will now throw an exception, instead of silently
   converting the functions to `undefined`.
 
@@ -387,21 +503,21 @@ ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
 // => throws Error("() => {} could not be cloned.")
 ```
 
-- `NaN`, `Infinity` and `-Infinity` will now be correctly serialized, instead
+* `NaN`, `Infinity` and `-Infinity` will now be correctly serialized, instead
   of being converted to `null`.
-- Objects containing cyclic references will now be correctly serialized,
+* Objects containing cyclic references will now be correctly serialized,
   instead of being converted to `null`.
-- `Set`, `Map`, `Error` and `RegExp` values will be correctly serialized,
+* `Set`, `Map`, `Error` and `RegExp` values will be correctly serialized,
   instead of being converted to `{}`.
-- `BigInt` values will be correctly serialized, instead of being converted to
+* `BigInt` values will be correctly serialized, instead of being converted to
   `null`.
-- Sparse arrays will be serialized as such, instead of being converted to dense
+* Sparse arrays will be serialized as such, instead of being converted to dense
   arrays with `null`s.
-- `Date` objects will be transferred as `Date` objects, instead of being
+* `Date` objects will be transferred as `Date` objects, instead of being
   converted to their ISO string representation.
-- Typed Arrays (such as `Uint8Array`, `Uint16Array`, `Uint32Array` and so on)
+* Typed Arrays (such as `Uint8Array`, `Uint16Array`, `Uint32Array` and so on)
   will be transferred as such, instead of being converted to Node.js `Buffer`.
-- Node.js `Buffer` objects will be transferred as `Uint8Array`s. You can
+* Node.js `Buffer` objects will be transferred as `Uint8Array`s. You can
   convert a `Uint8Array` back to a Node.js `Buffer` by wrapping the underlying
   `ArrayBuffer`:
 
@@ -470,6 +586,7 @@ limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined
 ### Deprecated events in `systemPreferences`
 
 The following `systemPreferences` events have been deprecated:
+
 * `inverted-color-scheme-changed`
 * `high-contrast-color-scheme-changed`
 
@@ -487,11 +604,13 @@ nativeTheme.on('updated', () => { /* ... */ })
 ### Deprecated: methods in `systemPreferences`
 
 The following `systemPreferences` methods have been deprecated:
+
 * `systemPreferences.isDarkMode()`
 * `systemPreferences.isInvertedColorScheme()`
 * `systemPreferences.isHighContrastColorScheme()`
 
 Use the following `nativeTheme` properties instead:
+
 * `nativeTheme.shouldUseDarkColors`
 * `nativeTheme.shouldUseInvertedColorScheme`
 * `nativeTheme.shouldUseHighContrastColors`

docs/development/build-instructions-gn.md

@@ -1,6 +1,8 @@
 # Build Instructions
 
-Follow the guidelines below for building Electron.
+Follow the guidelines below for building **Electron itself**, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the [application distribution][application-distribution] guide.
+
+[application-distribution]: ../tutorial/application-distribution.md
 
 ## Platform prerequisites
 
@@ -86,8 +88,6 @@ $ gclient sync -f
 ```sh
 $ cd src
 $ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools
-# this next line is needed only if building with sccache
-$ export GN_EXTRA_ARGS="${GN_EXTRA_ARGS} cc_wrapper=\"${PWD}/electron/external_binaries/sccache\""
 $ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\") $GN_EXTRA_ARGS"
 ```
 
@@ -141,12 +141,6 @@ This will build all of what was previously 'libchromiumcontent' (i.e. the
 `content/` directory of `chromium` and its dependencies, incl. WebKit and V8),
 so it will take a while.
 
-To speed up subsequent builds, you can use [sccache][sccache]. Add the GN arg
-`cc_wrapper = "sccache"` by running `gn args out/Testing` to bring up an
-editor and adding a line to the end of the file.
-
-[sccache]: https://github.com/mozilla/sccache
-
 The built executable will be under `./out/Testing`:
 
 ```sh
@@ -189,7 +183,6 @@ Not all combinations of source and target CPU/OS are supported by Chromium.
 | Windows x64 | Windows x86   | Automatically tested |
 | Linux x64   | Linux x86     | Automatically tested |
 
-
 If you test other combinations and find them to work, please update this document :)
 
 See the GN reference for allowable values of [`target_os`][target_os values]

docs/development/build-instructions-linux.md

@@ -1,6 +1,8 @@
 # Build Instructions (Linux)
 
-Follow the guidelines below for building Electron on Linux.
+Follow the guidelines below for building **Electron itself** on Linux, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the [application distribution][application-distribution] guide.
+
+[application-distribution]: ../tutorial/application-distribution.md
 
 ## Prerequisites
 
@@ -55,6 +57,15 @@ $ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \
                    nss-devel python-dbusmock openjdk-8-jre
 ```
 
+On Arch Linux / Manjaro, install the following libraries:
+
+```sh
+$ sudo pacman -Syu base-devel clang libdbus gtk2 libnotify \
+                   libgnome-keyring alsa-lib libcap libcups libxtst \
+                   libxss nss gcc-multilib curl gperf bison \
+                   python2 python-dbusmock jdk8-openjdk
+```
+
 Other distributions may offer similar packages for installation via package
 managers such as pacman. Or one can compile from source code.
 

docs/development/build-instructions-macos.md

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

docs/development/build-instructions-windows.md

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

docs/development/clang-tidy.md

@@ -10,12 +10,12 @@ files, you need to have built Electron so that it knows which compiler flags
 were used. There is one required option for the script `--output-dir`, which
 tells the script which build directory to pull the compilation information
 from. A typical usage would be:
-`npm run lint:clang-tiy --out-dir ../out/Testing`
+`npm run lint:clang-tidy --out-dir ../out/Testing`
 
 With no filenames provided, all C/C++/Objective-C files will be checked.
 You can provide a list of files to be checked by passing the filenames after
 the options:
-`npm run lint:clang-tiy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc`
+`npm run lint:clang-tidy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc`
 
 While `clang-tidy` has a
 [long list](https://clang.llvm.org/extra/clang-tidy/checks/list.html)

docs/development/coding-style.md

@@ -25,7 +25,7 @@ You can run `npm run lint` to show any style issues detected by `cpplint` and
 ## C++ and Python
 
 For C++ and Python, we follow Chromium's [Coding
-Style](https://www.chromium.org/developers/coding-style). You can use
+Style](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md). You can use
 [clang-format](clang-format.md) to format the C++ code automatically. There is
 also a script `script/cpplint.py` to check whether all files conform.
 
@@ -66,11 +66,11 @@ formatted correctly.
 
 Electron APIs uses the same capitalization scheme as Node.js:
 
-- When the module itself is a class like `BrowserWindow`, use `PascalCase`.
-- When the module is a set of APIs, like `globalShortcut`, use `camelCase`.
-- When the API is a property of object, and it is complex enough to be in a
+* When the module itself is a class like `BrowserWindow`, use `PascalCase`.
+* When the module is a set of APIs, like `globalShortcut`, use `camelCase`.
+* When the API is a property of object, and it is complex enough to be in a
   separate chapter like `win.webContents`, use `mixedCase`.
-- For other non-module APIs, use natural titles, like `<webview> Tag` or
+* For other non-module APIs, use natural titles, like `<webview> Tag` or
   `Process Object`.
 
 When creating a new API, it is preferred to use getters and setters instead of

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/issues.md

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

docs/development/pull-requests.md

@@ -36,9 +36,9 @@ $ git fetch upstream
 Build steps and dependencies differ slightly depending on your operating system.
 See these detailed guides on building Electron locally:
 
-* [Building on macOS](https://electronjs.org/docs/development/build-instructions-macos)
-* [Building on Linux](https://electronjs.org/docs/development/build-instructions-linux)
-* [Building on Windows](https://electronjs.org/docs/development/build-instructions-windows)
+* [Building on macOS](build-instructions-macos.md)
+* [Building on Linux](build-instructions-linux.md)
+* [Building on Windows](build-instructions-windows.md)
 
 Once you've built the project locally, you're ready to start making changes!
 
@@ -63,7 +63,7 @@ or tests in the `spec/` folder.
 Please be sure to run `npm run lint` from time to time on any code changes
 to ensure that they follow the project's code style.
 
-See [coding style](https://electronjs.org/docs/development/coding-style) for
+See [coding style](coding-style.md) for
 more information about best practice when modifying code in different parts of
 the project.
 
@@ -91,29 +91,29 @@ Before a pull request can be merged, it **must** have a pull request title with
 
 Examples of commit messages with semantic prefixes:
 
-- `fix: don't overwrite prevent_default if default wasn't prevented`
-- `feat: add app.isPackaged() method`
-- `docs: app.isDefaultProtocolClient is now available on Linux`
+* `fix: don't overwrite prevent_default if default wasn't prevented`
+* `feat: add app.isPackaged() method`
+* `docs: app.isDefaultProtocolClient is now available on Linux`
 
 Common prefixes:
 
-- fix: A bug fix
-- feat: A new feature
-- docs: Documentation changes
-- test: Adding missing tests or correcting existing tests
-- build: Changes that affect the build system
-- ci: Changes to our CI configuration files and scripts
-- perf: A code change that improves performance
-- refactor: A code change that neither fixes a bug nor adds a feature
-- style: Changes that do not affect the meaning of the code (linting)
-- vendor: Bumping a dependency like libchromiumcontent or node
+* fix: A bug fix
+* feat: A new feature
+* docs: Documentation changes
+* test: Adding missing tests or correcting existing tests
+* build: Changes that affect the build system
+* ci: Changes to our CI configuration files and scripts
+* perf: A code change that improves performance
+* refactor: A code change that neither fixes a bug nor adds a feature
+* style: Changes that do not affect the meaning of the code (linting)
+* vendor: Bumping a dependency like libchromiumcontent or node
 
 Other things to keep in mind when writing a commit message:
 
 1. The first line should:
-   - contain a short description of the change (preferably 50 characters or less,
+   * contain a short description of the change (preferably 50 characters or less,
      and no more than 72 characters)
-   - be entirely in lowercase with the exception of proper nouns, acronyms, and
+   * be entirely in lowercase with the exception of proper nouns, acronyms, and
    the words that refer to code, like function/variable names
 2. Keep the second line blank.
 3. Wrap all other lines at 72 columns.
@@ -144,7 +144,7 @@ master.
 ### Step 7: Test
 
 Bug fixes and features should always come with tests. A
-[testing guide](https://electronjs.org/docs/development/testing) has been
+[testing guide](testing.md) has been
 provided to make the process easier. Looking at other tests to see how they
 should be structured can also help.
 

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

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

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

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

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

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

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

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

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

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

docs/fiddles/features/keyboard-shortcuts/global/index.html

@@ -7,10 +7,6 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
+    <p>Hit Alt+Ctrl+I on Windows or Opt+Cmd+I on Mac to see a message printed to the console.</p>
 </body>
 </html>

docs/fiddles/features/keyboard-shortcuts/global/main.js

@@ -4,9 +4,6 @@ function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
   })
 
   win.loadFile('index.html')

docs/fiddles/features/keyboard-shortcuts/interception-from-main/index.html

@@ -7,8 +7,6 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    We are using node <script>document.write(process.versions.node)</script>,
-    Chrome <script>document.write(process.versions.chrome)</script>,
-    and Electron <script>document.write(process.versions.electron)</script>.
+    <p>Hit Ctrl+I to see a message printed to the console.</p>
 </body>
 </html>

docs/fiddles/features/keyboard-shortcuts/interception-from-main/main.js

@@ -1,7 +1,7 @@
 const { app, BrowserWindow } = require('electron')
 
 app.whenReady().then(() => {
-  const win = new BrowserWindow({ width: 800, height: 600, webPreferences: { nodeIntegration: true } })
+  const win = new BrowserWindow({ width: 800, height: 600 })
 
   win.loadFile('index.html')
   win.webContents.on('before-input-event', (event, input) => {

docs/fiddles/features/keyboard-shortcuts/local/index.html

@@ -7,10 +7,6 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
+    <p>Hit Alt+Shift+I on Windows, or Opt+Cmd+I on mac to see a message printed to the console.</p>
 </body>
 </html>

docs/fiddles/features/keyboard-shortcuts/local/main.js

@@ -4,9 +4,6 @@ function createWindow () {
   const win = new BrowserWindow({
     width: 800,
     height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
   })
 
   win.loadFile('index.html')

docs/fiddles/features/keyboard-shortcuts/web-apis/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <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>Hello World!</title>
+  </head>
+  <body>
+    <h1>Hello World!</h1>
+    
+    <p>Hit any key with this window focused to see it captured here.</p>
+    <div><span>Last Key Pressed: </span><span id="last-keypress"></span></div>
+    <script src="./renderer.js"></script>
+  </body>
+</html>

docs/fiddles/features/keyboard-shortcuts/web-apis/main.js

@@ -0,0 +1,35 @@
+// Modules to control application life and create native browser window
+const {app, BrowserWindow} = require('electron')
+const path = require('path')
+
+function createWindow () {
+  // Create the browser window.
+  const mainWindow = new BrowserWindow({
+    width: 800,
+    height: 600,
+  })
+
+  // and load the index.html of the app.
+  mainWindow.loadFile('index.html')
+
+}
+
+// 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()
+  
+  app.on('activate', function () {
+    // On macOS it's common to re-create a window in the app when the
+    // dock icon is clicked and there are no other windows open.
+    if (BrowserWindow.getAllWindows().length === 0) createWindow()
+  })
+})
+
+// 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 () {
+  if (process.platform !== 'darwin') app.quit()
+})

docs/fiddles/features/keyboard-shortcuts/web-apis/renderer.js

@@ -0,0 +1,7 @@
+function handleKeyPress (event) {
+  // You can put code here to handle the keypress.
+  document.getElementById("last-keypress").innerText = event.key
+  console.log(`You pressed ${event.key}`)
+}
+
+window.addEventListener('keyup', handleKeyPress, true)

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

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

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

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

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

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

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

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

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

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

docs/fiddles/features/notifications/main/index.html

@@ -7,10 +7,6 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
+    <p>After launching this application, you should see the system notification.</p>
 </body>
 </html>

docs/fiddles/features/notifications/main/main.js

@@ -3,21 +3,17 @@ const { app, BrowserWindow, Notification } = require('electron')
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
+    height: 600
   })
 
   win.loadFile('index.html')
 }
 
+const NOTIFICATION_TITLE = 'Basic Notification'
+const NOTIFICATION_BODY = 'Notification from the Main process'
+
 function showNotification () {
-  const notification = {
-    title: 'Basic Notification',
-    body: 'Notification from the Main process'
-  }
-  new Notification(notification).show()
+  new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()
 }
 
 app.whenReady().then(createWindow).then(showNotification)

docs/fiddles/features/notifications/renderer/index.html

@@ -7,11 +7,9 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
+    <p>After launching this application, you should see the system notification.</p>
+    <p id="output">Click it to see the effect in this interface.</p>
+
     <script src="renderer.js"></script>
 </body>
 </html>

docs/fiddles/features/notifications/renderer/main.js

@@ -3,10 +3,7 @@ const { app, BrowserWindow } = require('electron')
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
+    height: 600
   })
 
   win.loadFile('index.html')

docs/fiddles/features/notifications/renderer/renderer.js

@@ -1,7 +1,6 @@
-const myNotification = new Notification('Title', {
-  body: 'Notification from the Renderer process'
-})
+const NOTIFICATION_TITLE = 'Title'
+const NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'
+const CLICK_MESSAGE = 'Notification clicked!'
 
-myNotification.onclick = () => {
-  console.log('Notification clicked')
-}
+new Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })
+  .onclick = () => document.getElementById("output").innerText = CLICK_MESSAGE

docs/fiddles/features/offscreen-rendering/index.html

@@ -1,15 +0,0 @@
-<html>
-<head>
-    <meta charset="UTF-8">
-    <title>Hello World!</title>
-    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
-</head>
-<body>
-    <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
-</body>
-</html>

docs/fiddles/features/offscreen-rendering/main.js

@@ -1,5 +1,6 @@
 const { app, BrowserWindow } = require('electron')
 const fs = require('fs')
+const path = require('path')
 
 app.disableHardwareAcceleration()
 
@@ -12,7 +13,7 @@ app.whenReady().then(() => {
     fs.writeFileSync('ex.png', image.toPNG())
   })
   win.webContents.setFrameRate(60)
-  console.log(`The screenshot has been successfully saved to ${process.cwd()}/ex.png`)
+  console.log(`The screenshot has been successfully saved to ${path.join(process.cwd(), 'ex.png')}`)
 })
 
 app.on('window-all-closed', () => {

docs/fiddles/features/online-detection/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Hello World!</title>
+    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
+</head>
+<body>
+    <h1>Connection status: <strong id='status'></strong></h1>
+    
+    <script src="renderer.js"></script>
+</body>
+</html>

docs/fiddles/features/online-detection/main.js

@@ -0,0 +1,26 @@
+const { app, BrowserWindow } = require('electron')
+
+function createWindow () {
+  const onlineStatusWindow = new BrowserWindow({
+    width: 300,
+    height: 200
+  })
+
+  onlineStatusWindow.loadFile('index.html')
+}
+
+app.whenReady().then(() => {
+  createWindow()
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      createWindow()
+    }
+  })
+})
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit()
+  }
+})

docs/fiddles/features/online-detection/main/index.html

@@ -1,17 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-    <title>Hello World!</title>
-    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
-</head>
-<body>
-    <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
-    <script src="renderer.js"></script>
-</body>
-</html>

docs/fiddles/features/online-detection/main/main.js

@@ -1,24 +0,0 @@
-const { app, BrowserWindow, ipcMain } = require('electron')
-
-let onlineStatusWindow
-
-app.whenReady().then(() => {
-  onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false, webPreferences: { nodeIntegration: true } })
-  onlineStatusWindow.loadURL(`file://${__dirname}/index.html`)
-})
-
-ipcMain.on('online-status-changed', (event, status) => {
-  console.log(status)
-})
-
-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
-})
-
-app.on('activate', () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})

docs/fiddles/features/online-detection/main/renderer.js

@@ -1,7 +0,0 @@
-const { ipcRenderer } = require('electron')
-const updateOnlineStatus = () => { ipcRenderer.send('online-status-changed', navigator.onLine ? 'online' : 'offline') }
-
-window.addEventListener('online', updateOnlineStatus)
-window.addEventListener('offline', updateOnlineStatus)
-
-updateOnlineStatus()

docs/fiddles/features/online-detection/renderer.js

@@ -0,0 +1,8 @@
+function onlineStatusIndicator () {
+  document.getElementById('status').innerHTML = navigator.onLine ? 'online' : 'offline'
+}
+
+window.addEventListener('online', onlineStatusIndicator)
+window.addEventListener('offline', onlineStatusIndicator)
+
+onlineStatusIndicator()

docs/fiddles/features/online-detection/renderer/index.html

@@ -1,17 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-    <title>Hello World!</title>
-    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
-</head>
-<body>
-    <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
-    <script src="renderer.js"></script>
-</body>
-</html>

docs/fiddles/features/online-detection/renderer/main.js

@@ -1,20 +0,0 @@
-const { app, BrowserWindow } = require('electron')
-
-let onlineStatusWindow
-
-app.whenReady().then(() => {
-  onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false })
-  onlineStatusWindow.loadURL(`file://${__dirname}/index.html`)
-})
-
-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
-})
-
-app.on('activate', () => {
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})

docs/fiddles/features/online-detection/renderer/renderer.js

@@ -1,6 +0,0 @@
-const alertOnlineStatus = () => { window.alert(navigator.onLine ? 'online' : 'offline') }
-
-window.addEventListener('online', alertOnlineStatus)
-window.addEventListener('offline', alertOnlineStatus)
-
-alertOnlineStatus()

docs/fiddles/features/progress-bar/index.html

@@ -7,10 +7,9 @@
 </head>
 <body>
     <h1>Hello World!</h1>
-    <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
-    </p>
+    <p>Keep an eye on the dock (Mac) or taskbar (Windows, Unity) for this application!</p>
+    <p>It should indicate a progress that advances from 0 to 100%.</p>
+    <p>It should then show indeterminate (Windows) or pin at 100% (other operating systems)
+      briefly and then loop.</p>
 </body>
 </html>

docs/fiddles/features/progress-bar/main.js

@@ -1,21 +1,39 @@
 const { app, BrowserWindow } = require('electron')
 
+let progressInterval
+
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
+    height: 600
   })
 
   win.loadFile('index.html')
-  win.setProgressBar(0.5)
-}
 
+  const INCREMENT = 0.03
+  const INTERVAL_DELAY = 100 // ms
+
+  let c = 0
+  progressInterval = setInterval(() => {
+    // update progress bar to next value
+    // values between 0 and 1 will show progress, >1 will show indeterminate or stick at 100%
+    win.setProgressBar(c)
+
+    // increment or reset progress bar
+    if (c < 2) {
+      c += INCREMENT
+    } else {
+      c = (-INCREMENT * 5) // reset to a bit less than 0 to show reset state
+    }
+  }, INTERVAL_DELAY)
+}
 
 app.whenReady().then(createWindow)
 
+// before the app is terminated, clear both timers
+app.on('before-quit', () => {
+  clearInterval(progressInterval)
+})
 
 app.on('window-all-closed', () => {
   if (process.platform !== 'darwin') {

docs/fiddles/features/recent-documents/index.html

@@ -2,15 +2,14 @@
 <html>
 <head>
     <meta charset="UTF-8">
-    <title>Hello World!</title>
+    <title>Recent Documents</title>
     <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
 </head>
 <body>
-    <h1>Hello World!</h1>
+    <h1>Recent Documents</h1>
     <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
+        Right click on the app icon to see recent documents.
+        You should see `recently-used.md` added to the list of recent files
     </p>
 </body>
 </html>

docs/fiddles/features/recent-documents/main.js

@@ -5,17 +5,15 @@ const path = require('path')
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
+    height: 600
   })
 
   win.loadFile('index.html')
 }
+
 const fileName = 'recently-used.md'
 fs.writeFile(fileName, 'Lorem Ipsum', () => {
-  app.addRecentDocument(path.join(process.cwd(), `${fileName}`))
+  app.addRecentDocument(path.join(__dirname, fileName))
 })
 
 app.whenReady().then(createWindow)

docs/fiddles/features/represented-file/index.html

@@ -4,13 +4,14 @@
     <meta charset="UTF-8">
     <title>Hello World!</title>
     <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
+    <link rel="stylesheet" type="text/css" href="./styles.css">
 </head>
 <body>
     <h1>Hello World!</h1>
     <p>
-        We are using node <script>document.write(process.versions.node)</script>,
-        Chrome <script>document.write(process.versions.chrome)</script>,
-        and Electron <script>document.write(process.versions.electron)</script>.
+      Click on the title with the <pre>Command</pre> or <pre>Control</pre> key pressed.
+      You should see a popup with the represented file at the top.
     </p>
+  </body>
 </body>
 </html>

docs/fiddles/features/represented-file/main.js

@@ -4,10 +4,7 @@ const os = require('os');
 function createWindow () {
   const win = new BrowserWindow({
     width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
+    height: 600
   })
 
   win.loadFile('index.html')

docs/fiddles/quick-start/index.html

@@ -8,8 +8,8 @@
 <body>
     <h1>Hello World!</h1>
     <p>
-        We are using node <span id="node-version"></span>,
-        Chrome <span id="chrome-version"></span>,
+        We are using Node.js <span id="node-version"></span>,
+        Chromium <span id="chrome-version"></span>,
         and Electron <span id="electron-version"></span>.
     </p>
 </body>

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 } = 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();
+});