tabs.Tab.autoDiscardable in 116 (mdn#27494)

* origin/tabs.Tab.autoDiscardable in 116

* Updates for feedback

* Apply suggestions from review

Co-authored-by: Rob Wu <rob@robwu.nl>

---------

Co-authored-by: Rob Wu <rob@robwu.nl>

files/en-us/mozilla/add-ons/webextensions/api/tabs/discard/index.md

@@ -9,11 +9,11 @@ browser-compat: webextensions.api.tabs.discard
 
 Discards one or more tabs.
 
-Some browsers automatically "discard" tabs that they don't think are likely to be needed by the user soon. The tab stays visible in the tabstrip and the browser remembers its state, so if the user selects a tab that has been discarded, it is immediately restored.
+Some browsers automatically "discard" unused tabs to free memory. Discarded tabs stay visible in the tabstrip. The browser remembers the tab's state and restores it when the user selects the tab. The details of when tabs are and what is discarded are browser-specific.
 
-The details of exactly what is discarded are browser-specific, but in general, discarding a tab enables the browser to free some of the memory occupied by that tab.
+You can control whether the browser or this API discards a tab by setting its `autoDiscardable` property to `false` in {{WebExtAPIRef("tabs.update")}}. This setting prevents the browser from discarding the tab. The tab can then only be discarded with this API.
 
-The {{WebExtAPIRef("tabs.discard()")}} API enables an extension to discard one or more tabs. It's not possible to discard the currently active tab, or a tab whose document contains a [`beforeunload`](/en-US/docs/Web/API/Window/beforeunload_event) listener that would display a prompt.
+It's not possible to discard the active tab or a tab whose document contains a [`beforeunload`](/en-US/docs/Web/API/Window/beforeunload_event) listener that would display a prompt.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 

files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md

@@ -17,7 +17,7 @@ You can filter this event, making it only fire for tabs whose URLs match specifi
 
 ```js-nolint
 browser.tabs.onUpdated.addListener(
-  listener,  // function
+  listener, // function
   filter     // optional object
 )
 browser.tabs.onUpdated.removeListener(listener)
@@ -59,6 +59,7 @@ Events have three functions:
       - : `Array`. An array of strings consisting of supported {{WebExtAPIRef("tabs.Tab")}} object property names. Fires the event only for changes to one of the properties named in the array. These properties can be used:
 
         - "attention"
+        - "autoDiscardable"
         - "audible"
         - "discarded"
         - "favIconUrl"
@@ -87,6 +88,8 @@ Lists the changes to the state of the tab that is updated. To learn more about t
   - : `boolean`. Indicates whether the tab is drawing attention. For example, `attention` is `true` when the tab displays a modal dialog.
 - `audible` {{optional_inline}}
   - : `boolean`. The tab's new audible state.
+- `autoDiscardable` {{optional_inline}}
+  - : `boolean`. Whether the tab can be discarded by the browser. The default value is `true`. When set to `false`, the browser cannot automatically discard the tab. However, the tab can be discarded by {{WebExtAPIRef("tabs.discard")}}.
 - `discarded` {{optional_inline}}
   - : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory but is visible in the tab strip. Its content gets reloaded the next time it's activated.
 - `favIconUrl` {{optional_inline}}

files/en-us/mozilla/add-ons/webextensions/api/tabs/query/index.md

@@ -30,7 +30,7 @@ let querying = browser.tabs.query(queryObj)
     - `audible` {{optional_inline}}
       - : `boolean`. Whether the tabs are audible.
     - `autoDiscardable` {{optional_inline}}
-      - : `boolean`. Whether the tabs can be discarded automatically by the browser when resources are low.
+      - : `boolean`. Whether the tab can be discarded by the browser. The default value is `true`. When set to `false`, the browser cannot automatically discard the tab. However, the tab can be discarded by {{WebExtAPIRef("tabs.discard")}}.
     - `cookieStoreId` {{optional_inline}}
       - : `string` or `array` of `string`. Use this to return tabs whose `tab.cookieStoreId` matches any of the `cookieStoreId` strings. This option is only available if the add-on has the `"cookies"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
     - `currentWindow` {{optional_inline}}

files/en-us/mozilla/add-ons/webextensions/api/tabs/tab/index.md

@@ -24,7 +24,7 @@ Values of this type are objects. They contain the following properties:
 - `audible` {{optional_inline}}
   - : `boolean`. Indicates whether the tab is producing sound. However, the user will not hear the sound if the tab is muted (see the `mutedInfo` property).
 - `autoDiscardable` {{optional_inline}}
-  - : `boolean`. Whether the tab can be discarded automatically by the browser when resources are low.
+  - : `boolean`. Whether the tab can be discarded by the browser. The default value is `true`. When set to `false`, the browser cannot automatically discard the tab. However, the tab can be discarded by {{WebExtAPIRef("tabs.discard")}}.
 - `cookieStoreId` {{optional_inline}}
   - : `string`. The cookie store of the tab. If different tabs can have different cookie stores (for example, to support [contextual identity](https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers)), you can pass this as the `storeId` option into various methods of the {{WebExtAPIRef("cookies")}} API, to set and get cookies associated with this tab's cookie store. Only present if the extension has the `"cookies"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
 - `discarded` {{optional_inline}}

files/en-us/mozilla/add-ons/webextensions/api/tabs/update/index.md

@@ -33,7 +33,7 @@ let updating = browser.tabs.update(
     - `active` {{optional_inline}}
       - : `boolean`. Whether the tab should become active. Does not affect whether the window is focused (see {{WebExtAPIRef('windows.update')}}). If `true`, non-active highlighted tabs will stop being highlighted. If `false`, does nothing.
     - `autoDiscardable` {{optional_inline}}
-      - : `boolean`. Whether the tab should be discarded automatically by the browser when resources are low.
+      - : `boolean`. Whether the tab can be discarded by the browser. The default value is `true`. When set to `false`, the browser cannot automatically discard the tab. However, the tab can be discarded by {{WebExtAPIRef("tabs.discard")}}.
     - `highlighted` {{optional_inline}}
 
       - : `boolean`. Adds or removes the tab from the current selection. If `true` and the tab is not highlighted, it will become active by default.

files/en-us/mozilla/firefox/releases/116/index.md

@@ -56,6 +56,7 @@ This article provides information about the changes in Firefox 115 that affect d
 ## Changes for add-on developers
 
 - The URL of a page visited when an extension is uninstalled, provided in {{WebExtAPIRef("runtime.setUninstallURL")}}, can now be up to 1023 characters instead of 255 ([Firefox bug 1835723](https://bugzil.la/1835723)).
+- `autoDiscardable` is now supported in {{WebExtAPIRef("tabs.Tab")}}, {{WebExtAPIRef("tabs.onUpdated")}}, {{WebExtAPIRef("tabs.update")}}, and {{WebExtAPIRef("tabs.query")}} ([Firefox bug 1809094](https://bugzil.la/1809094)).
 
 ### Removals