Merge branch 'main' into docs/introducing-api-history

docs/latest/README.md

@@ -105,7 +105,6 @@ These individual tutorials expand on topics discussed in the guide above.
 
 ### Custom DOM Elements:
 
-* [`File` Object](latest/api/file-object.md)
 * [`<webview>` Tag](latest/api/webview-tag.md)
 * [`window.open` Function](latest/api/window-open.md)
 

docs/latest/api/app.md

@@ -352,9 +352,10 @@ app.on('select-client-certificate', (event, webContents, url, list, callback) =>
 Returns:
 
 * `event` Event
-* `webContents` [WebContents](latest/api/web-contents.md)
+* `webContents` [WebContents](latest/api/web-contents.md) (optional)
 * `authenticationResponseDetails` Object
   * `url` URL
+  * `pid` number
 * `authInfo` Object
   * `isProxy` boolean
   * `scheme` string
@@ -365,7 +366,7 @@ Returns:
   * `username` string (optional)
   * `password` string (optional)
 
-Emitted when `webContents` wants to do basic auth.
+Emitted when `webContents` or [Utility process](latest/glossary.md#utility-process) wants to do basic auth.
 
 The default behavior is to cancel all authentications. To override this you
 should prevent the default behavior with `event.preventDefault()` and call

docs/latest/api/base-window.md

@@ -1083,6 +1083,15 @@ win.setSheetOffset(toolbarRect.height)
 
 #### `win.flashFrame(flag)`
 
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/35658
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: "`window.flashFrame(bool)` will flash dock icon continuously on macOS"
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+
 * `flag` boolean
 
 Starts or stops flashing the window to attract user's attention.

docs/latest/api/browser-view.md

@@ -1,12 +1,18 @@
 ---
 title: "BrowserView"
-description: "**Note**  The BrowserView class is deprecated, and replaced by the new  WebContentsView class."
+description: "YAML history deprecated: - pr-url: https://github.com/electron/electron/pull/35658 breaking-changes-header: deprecated-browserview"
 slug: browser-view
 hide_title: false
 ---
 
 # BrowserView
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 > **Note**
 > The `BrowserView` class is deprecated, and replaced by the new
 > [`WebContentsView`](latest/api/web-contents-view.md) class.
@@ -18,6 +24,12 @@ relative to its owning window. It is meant to be an alternative to the
 
 ## Class: BrowserView
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 > Create and control views.
 
 > **Note**
@@ -47,6 +59,12 @@ app.whenReady().then(() => {
 
 ### `new BrowserView([options])` _Experimental_ _Deprecated_
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 * `options` Object (optional)
   * `webPreferences` [WebPreferences](latest/api/structures/web-preferences.md) (optional) - Settings of web page's features.
     * `devTools` boolean (optional) - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
@@ -200,6 +218,12 @@ Objects created with `new BrowserView` have the following properties:
 
 #### `view.webContents` _Experimental_ _Deprecated_
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 A [`WebContents`](latest/api/web-contents.md) object owned by this view.
 
 ### Instance Methods
@@ -208,6 +232,16 @@ Objects created with `new BrowserView` have the following instance methods:
 
 #### `view.setAutoResize(options)` _Experimental_ _Deprecated_
 
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    description: "Standardized auto-resizing behavior across all platforms"
+    breaking-changes-header: behavior-changed-browserviewsetautoresize-behavior-on-macos
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 * `options` Object
   * `width` boolean (optional) - If `true`, the view's width will grow and shrink together
     with the window. `false` by default.
@@ -220,18 +254,36 @@ Objects created with `new BrowserView` have the following instance methods:
 
 #### `view.setBounds(bounds)` _Experimental_ _Deprecated_
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 * `bounds` [Rectangle](latest/api/structures/rectangle.md)
 
 Resizes and moves the view to the supplied bounds relative to the window.
 
 #### `view.getBounds()` _Experimental_ _Deprecated_
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 Returns [`Rectangle`](latest/api/structures/rectangle.md)
 
 The `bounds` of this BrowserView instance as `Object`.
 
 #### `view.setBackgroundColor(color)` _Experimental_ _Deprecated_
 
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+
 * `color` string - Color in Hex, RGB, ARGB, HSL, HSLA or named CSS color format. The alpha channel is
   optional for the hex type.
 

docs/latest/api/browser-window.md

@@ -1208,6 +1208,13 @@ win.setSheetOffset(toolbarRect.height)
 
 #### `win.flashFrame(flag)`
 
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: "`window.flashFrame(bool)` will flash dock icon continuously on macOS"
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+
 * `flag` boolean
 
 Starts or stops flashing the window to attract user's attention.

docs/latest/api/context-bridge.md

@@ -1,12 +1,19 @@
 ---
 title: "contextBridge"
-description: "Create a safe, bi-directional, synchronous bridge across isolated contexts"
+description: "YAML history changes: - pr-url: https://github.com/electron/electron/pull/40330 description: \"ipcRenderer can no longer be sent over the contextBridge\" breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge"
 slug: context-bridge
 hide_title: false
 ---
 
 # contextBridge
 
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+
 > Create a safe, bi-directional, synchronous bridge across isolated contexts
 
 Process: [Renderer](latest/glossary.md#renderer-process)
@@ -136,7 +143,7 @@ has been included below for completeness:
 | `Object` | Complex | ✅ | ✅ | Keys must be supported using only "Simple" types in this table.  Values must be supported in this table.  Prototype modifications are dropped.  Sending custom classes will copy values but not the prototype. |
 | `Array` | Complex | ✅ | ✅ | Same limitations as the `Object` type |
 | `Error` | Complex | ✅ | ✅ | Errors that are thrown are also copied, this can result in the message and stack trace of the error changing slightly due to being thrown in a different context, and any custom properties on the Error object [will be lost](https://github.com/electron/electron/issues/25596) |
-| `Promise` | Complex | ✅ | ✅ | N/A
+| `Promise` | Complex | ✅ | ✅ | N/A |
 | `Function` | Complex | ✅ | ✅ | Prototype modifications are dropped.  Sending classes or constructors will not work. |
 | [Cloneable Types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) | Simple | ✅ | ✅ | See the linked document on cloneable types |
 | `Element` | Complex | ✅ | ✅ | Prototype modifications are dropped.  Sending custom elements will not work. |

docs/latest/api/dialog.md

@@ -22,9 +22,9 @@ console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections']
 
 The `dialog` module has the following methods:
 
-### `dialog.showOpenDialogSync([browserWindow, ]options)`
+### `dialog.showOpenDialogSync([window, ]options)`
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `title` string (optional)
   * `defaultPath` string (optional)
@@ -54,7 +54,7 @@ The `dialog` module has the following methods:
 
 Returns `string[] | undefined`, the file paths chosen by the user; if the dialog is cancelled it returns `undefined`.
 
-The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
+The `window` argument allows the dialog to attach itself to a parent window, making it modal.
 
 The `filters` specifies an array of file types that can be displayed or
 selected when you want to limit the user to a specific type. For example:
@@ -79,15 +79,15 @@ and a directory selector, so if you set `properties` to
 `['openFile', 'openDirectory']` on these platforms, a directory selector will be
 shown.
 
-```js @ts-type={mainWindow:Electron.BrowserWindow}
+```js @ts-type={mainWindow:Electron.BaseWindow}
 dialog.showOpenDialogSync(mainWindow, {
   properties: ['openFile', 'openDirectory']
 })
 ```
 
-### `dialog.showOpenDialog([browserWindow, ]options)`
+### `dialog.showOpenDialog([window, ]options)`
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `title` string (optional)
   * `defaultPath` string (optional)
@@ -121,7 +121,7 @@ Returns `Promise<Object>` - Resolve with an object containing the following:
 * `filePaths` string[] - An array of file paths chosen by the user. If the dialog is cancelled this will be an empty 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.
+The `window` argument allows the dialog to attach itself to a parent window, making it modal.
 
 The `filters` specifies an array of file types that can be displayed or
 selected when you want to limit the user to a specific type. For example:
@@ -146,7 +146,7 @@ and a directory selector, so if you set `properties` to
 `['openFile', 'openDirectory']` on these platforms, a directory selector will be
 shown.
 
-```js @ts-type={mainWindow:Electron.BrowserWindow}
+```js @ts-type={mainWindow:Electron.BaseWindow}
 dialog.showOpenDialog(mainWindow, {
   properties: ['openFile', 'openDirectory']
 }).then(result => {
@@ -157,9 +157,9 @@ dialog.showOpenDialog(mainWindow, {
 })
 ```
 
-### `dialog.showSaveDialogSync([browserWindow, ]options)`
+### `dialog.showSaveDialogSync([window, ]options)`
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
   * `defaultPath` string (optional) - Absolute directory path, absolute file
@@ -183,14 +183,14 @@ dialog.showOpenDialog(mainWindow, {
 
 Returns `string`, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.
 
-The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
+The `window` argument allows the dialog to attach itself to a parent window, making it modal.
 
 The `filters` specifies an array of file types that can be displayed, see
 `dialog.showOpenDialog` for an example.
 
-### `dialog.showSaveDialog([browserWindow, ]options)`
+### `dialog.showSaveDialog([window, ]options)`
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `title` string (optional) - The dialog title. Cannot be displayed on some _Linux_ desktop environments.
   * `defaultPath` string (optional) - Absolute directory path, absolute file
@@ -217,17 +217,17 @@ Returns `Promise<Object>` - Resolve with an object containing the following:
 * `filePath` string - If the dialog is canceled, this will be an empty string.
 * `bookmark` string (optional) _macOS_ _mas_ - Base64 encoded string which contains the security scoped bookmark data for the saved file. `securityScopedBookmarks` must be enabled for this to be present. (For return values, see [table here](#bookmarks-array).)
 
-The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
+The `window` argument allows the dialog to attach itself to a parent window, making it modal.
 
 The `filters` specifies an array of file types that can be displayed, see
 `dialog.showOpenDialog` for an example.
 
 **Note:** On macOS, using the asynchronous version is recommended to avoid issues when
 expanding and collapsing the dialog.
 
-### `dialog.showMessageBoxSync([browserWindow, ]options)`
+### `dialog.showMessageBoxSync([wndow, ]options)`
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `message` string - Content of the message box.
   * `type` string (optional) - Can be `none`, `info`, `error`, `question` or
@@ -265,12 +265,12 @@ Returns `Integer` - the index of the clicked button.
 Shows a message box, it will block the process until the message box is closed.
 It returns the index of the clicked button.
 
-The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
-If `browserWindow` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
+The `window` argument allows the dialog to attach itself to a parent window, making it modal.
+If `window` is not shown dialog will not be attached to it. In such case it will be displayed as an independent window.
 
-### `dialog.showMessageBox([browserWindow, ]options)`
+### `dialog.showMessageBox([window, ]options)`
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `message` string - Content of the message box.
   * `type` string (optional) - Can be `none`, `info`, `error`, `question` or
@@ -320,7 +320,7 @@ Returns `Promise<Object>` - resolves with a promise containing the following pro
 
 Shows a message box.
 
-The `browserWindow` argument allows the dialog to attach itself to a parent window, making it modal.
+The `window` argument allows the dialog to attach itself to a parent window, making it modal.
 
 ### `dialog.showErrorBox(title, content)`
 
@@ -334,9 +334,9 @@ it is usually used to report errors in early stage of startup. If called
 before the app `ready`event on Linux, the message will be emitted to stderr,
 and no GUI dialog will appear.
 
-### `dialog.showCertificateTrustDialog([browserWindow, ]options)` _macOS_ _Windows_
+### `dialog.showCertificateTrustDialog([window, ]options)` _macOS_ _Windows_
 
-* `browserWindow` [BrowserWindow](latest/api/browser-window.md) (optional)
+* `window` [BaseWindow](latest/api/base-window.md) (optional)
 * `options` Object
   * `certificate` [Certificate](latest/api/structures/certificate.md) - The certificate to trust/import.
   * `message` string - The message to display to the user.
@@ -345,14 +345,14 @@ Returns `Promise<void>` - resolves when the certificate trust dialog is shown.
 
 On macOS, this displays a modal dialog that shows a message and certificate
 information, and gives the user the option of trusting/importing the
-certificate. If you provide a `browserWindow` argument the dialog will be
+certificate. If you provide a `window` argument the dialog will be
 attached to the parent window, making it modal.
 
 On Windows the options are more limited, due to the Win32 APIs used:
 
 * The `message` argument is not used, as the OS provides its own confirmation
    dialog.
-* The `browserWindow` argument is ignored since it is not possible to make
+* The `window` argument is ignored since it is not possible to make
    this confirmation dialog modal.
 
 ## Bookmarks array
@@ -369,10 +369,10 @@ On Windows the options are more limited, due to the Win32 APIs used:
 ## Sheets
 
 On macOS, dialogs are presented as sheets attached to a window if you provide
-a [`BrowserWindow`](latest/api/browser-window.md) reference in the `browserWindow` parameter, or modals if no
+a [`BaseWindow`](latest/api/base-window.md) reference in the `window` parameter, or modals if no
 window is provided.
 
-You can call `BrowserWindow.getCurrentWindow().setSheetOffset(offset)` to change
+You can call `BaseWindow.getCurrentWindow().setSheetOffset(offset)` to change
 the offset from the window frame where sheets are attached.
 
 [AbortSignal]: https://nodejs.org/api/globals.html#globals_class_abortsignal