FF132 fetchpriority docs updates

files/en-us/web/api/htmlimageelement/fetchpriority/index.md

@@ -6,35 +6,30 @@ page-type: web-api-instance-property
 browser-compat: api.HTMLImageElement.fetchPriority
 ---
 
-{{APIRef}}
+{{APIRef("HTML DOM")}}
 
-The **`fetchPriority`** property of the
-{{domxref("HTMLImageElement")}} interface represents a hint given to the browser on how
-it should prioritize the fetch of the image relative to other images.
+The **`fetchPriority`** property of the {{domxref("HTMLImageElement")}} interface represents a hint to the browser indicating how it should prioritize fetching a particular image relative to other images.
+It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/img#fetchpriority) attribute of the corresponding {{htmlelement("img")}} element, for the allowed values.
+
+The property allows a developer to signal that fetching a particular image early in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority.
+This in turn allows the browser to increase or decrease the priority, and potentially load the image earlier or later than it would otherwise.
+The property should be used sparingly, as excessive or incorrect prioritization can degrade performance.
+
+Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent.
 
 ## Value
 
-A string representing the priority hint. Possible values are:
+A string representing the priority hint.
+Possible values are:
 
 - `high`
-  - : Fetch the image at a high priority relative to other images.
+  - : Fetch the image at a high priority relative to other images with the same internal prioritization.
 - `low`
-  - : Fetch the image at a low priority relative to other images.
+  - : Fetch the image at a low priority relative to other images with the same internal prioritization.
 - `auto`
-  - : Default mode, which indicates no preference for the fetch priority.
-    The browser decides what is best for the user.
-
-The `fetchPriority` property allows you to signal high or low priority image
-fetches. This can be useful when applied to {{HTMLElement("img")}} elements
-to signal images that are "important" to the user experience early in the
-loading process.
-
-The effects of the hint on resource loading is browser-specific so make sure to
-test on multiple browser engines.
-
-Use it sparingly for exceptional cases where the browser may not be able to
-infer the best way to load the image automatically. Over use can result in
-degrading performance.
+  - : No user preference for the fetch priority.
+    This is the default.
+    It is used if no value is set or if an invalid value is set.
 
 ## Examples
 
@@ -56,3 +51,5 @@ img.src = "img/logo.png";
 
 - {{domxref("HTMLLinkElement.fetchPriority")}}
 - {{domxref("HTMLScriptElement.fetchPriority")}}
+- HTTP {{httpheader("Link")}} header
+- [Optimize resource loading with the Fetch Priority API](https://web.dev/articles/fetch-priority?hl=en#browser_priority_and_fetchpriority) for information about how this API affects priorities on Chrome.

files/en-us/web/api/htmllinkelement/fetchpriority/index.md

@@ -8,37 +8,28 @@ browser-compat: api.HTMLLinkElement.fetchPriority
 
 {{APIRef("HTML DOM")}}
 
-The **`fetchPriority`** property of the
-{{domxref("HTMLLinkElement")}} interface represents a hint given to the browser
-on how it should prioritize the preload of the given resource relative to other
-resources of the same
-[type](/en-US/docs/Web/HTML/Attributes/rel/preload#what_types_of_content_can_be_preloaded).
+The **`fetchPriority`** property of the {{domxref("HTMLLinkElement")}} interface represents a hint to the browser indicating how it should prioritize fetching a particular resource relative to other resources of the same type.
+It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/link#fetchpriority) attribute of the corresponding {{htmlelement("link")}} element, for the allowed values.
+
+The property allows a developer to signal that fetching a particular resource early in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority, in particular when preloading resources.
+This in turn allows the browser to increase or decrease the priority, and potentially load the resource earlier or later than it would otherwise.
+The property should be used sparingly, as excessive or incorrect prioritization can degrade performance.
+
+Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent.
 
 ## Value
 
-A string representing the priority hint. Possible values are:
+A string representing the priority hint.
+Possible values are:
 
 - `high`
-  - : Fetch the preload resource at a high priority relative to other resources
-    of the same type.
+  - : Fetch the resource at a high priority relative to other resources of the same type and internal prioritization.
 - `low`
-  - : Fetch the preload resource at a low priority relative to other resources of
-    the same type.
+  - : Fetch the resource at a low priority relative to other resources of the same type and internal prioritization.
 - `auto`
-  - : Default mode, which indicates no preference for
-    the fetch priority. The browser decides what is best for the user.
-
-The `fetchPriority` property allows you to signal high or low priority preload
-fetches. This can be useful when applied to {{HTMLElement("link")}} elements
-to signal preloads that are more or less important to the user experience early
-in the loading process.
-
-The effects of the hint on resource loading is browser-specific so make sure to
-test on multiple browser engines.
-
-Use it sparingly for exceptional cases where the browser may not be able to
-infer the best way to load the resource automatically. Over use can result in
-degrading performance.
+  - : No user preference for the fetch priority.
+    This is the default.
+    It is used if no value is set or if an invalid value is set.
 
 ## Examples
 
@@ -63,3 +54,5 @@ document.head.appendChild(preloadLink);
 
 - {{domxref("HTMLImageElement.fetchPriority")}}
 - {{domxref("HTMLScriptElement.fetchPriority")}}
+- HTTP {{httpheader("Link")}} header
+- [Optimize resource loading with the Fetch Priority API](https://web.dev/articles/fetch-priority?hl=en#browser_priority_and_fetchpriority) for information about how this API affects priorities on Chrome.

files/en-us/web/api/htmlscriptelement/fetchpriority/index.md

@@ -8,9 +8,14 @@ browser-compat: api.HTMLScriptElement.fetchPriority
 
 {{APIRef("HTML DOM")}}
 
-The **`fetchPriority`** property of the {{domxref("HTMLScriptElement")}} interface represents a hint given to the browser on how it should prioritize fetching of an external script relative to other external scripts.
+The **`fetchPriority`** property of the {{domxref("HTMLScriptElement")}} interface represents a hint to the browser indicating how it should prioritize fetching an external script relative to other external scripts.
+It reflects the [`fetchpriority`](/en-US/docs/Web/HTML/Element/script#fetchpriority) attribute of the {{HTMLElement("script")}} element, for the allowed values.
 
-It reflects the `fetchpriority` attribute of the {{HTMLElement("script")}} element.
+The property allows a developer to signal that fetching a particular script early in the loading process has more or less impact on user experience than a browser can reasonably infer when assigning an internal priority.
+This in turn allows the browser to increase or decrease the priority, and potentially load the script earlier or later than it would otherwise.
+The property should be used sparingly, as excessive or incorrect prioritization can degrade performance.
+
+Note that both the internal priority of any fetch operation, and the impact of `fetchPriority` on the priority, are entirely browser dependent.
 
 ## Value
 
@@ -21,22 +26,9 @@ A string representing the priority hint. Possible values are:
 - `low`
   - : Fetch the external script at a low priority relative to other external scripts.
 - `auto`
-  - : Default mode, which indicates no preference for the fetch priority.
-    The browser decides what is best for the user.
-
-If the `fetchpriority` attribute is not specified or is specified with any other value, it is the same as specifying it as `auto`.
-
-The `fetchPriority` property allows you to signal high or low priority external script
-fetches. This can be useful when applied to {{HTMLElement("script")}} elements
-to signal external scripts that are "important" to the user experience early in the
-loading process.
-
-The effects of the hint on resource loading is browser-specific so make sure to
-test on multiple browser engines.
-
-Use it sparingly for exceptional cases where the browser may not be able to
-infer the best way to load the external script automatically. Over use can result in
-degrading performance.
+  - : No user preference for the fetch priority.
+    This is the default.
+    It is used if no value is set or if an invalid value is set.
 
 ## Examples
 
@@ -61,3 +53,5 @@ console.log(el.fetchPriority); // Output: "high"
 
 - {{domxref("HTMLImageElement.fetchPriority")}}
 - {{domxref("HTMLLinkElement.fetchPriority")}}
+- HTTP {{httpheader("Link")}} header
+- [Optimize resource loading with the Fetch Priority API](https://web.dev/articles/fetch-priority?hl=en#browser_priority_and_fetchpriority) for information about how this API affects priorities on Chrome.

files/en-us/web/api/request/request/index.md

@@ -54,33 +54,13 @@ new Request(input, options)
 
 ### Exceptions
 
-<table class="no-markdown">
-  <thead>
-    <tr>
-      <th scope="col">Type</th>
-      <th scope="col">Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><code>TypeError</code></td>
-      <td>
-        Since <a href="/en-US/docs/Mozilla/Firefox/Releases/43">Firefox 43</a>,
-        <code>Request()</code> will throw a TypeError if the URL has
-        credentials, such as http://user:[email protected].
-      </td>
-    </tr>
-  </tbody>
-</table>
+- `TypeError`
+  - The URL has credentials, such as `http://user:[email protected]` or cannot be parsed.
 
 ## Examples
 
-In our [Fetch Request example](https://github.com/mdn/dom-examples/tree/main/fetch/fetch-request) (see [Fetch Request live](https://mdn.github.io/dom-examples/fetch/fetch-request/)) we
-create a new `Request` object using the constructor, then fetch it using a
-{{domxref("Window/fetch", "fetch()")}} call. Since we are fetching an image, we run
-{{domxref("Response.blob")}} on the response to give it the proper MIME type so it will be
-handled properly, then create an Object URL of it and display it in an
-{{htmlelement("img")}} element.
+In our [Fetch Request example](https://github.com/mdn/dom-examples/tree/main/fetch/fetch-request) (see [Fetch Request live](https://mdn.github.io/dom-examples/fetch/fetch-request/)) we create a new `Request` object using the constructor, then fetch it using a {{domxref("Window/fetch", "fetch()")}} call.
+Since we are fetching an image, we run {{domxref("Response.blob")}} on the response to give it the proper MIME type so it will be handled properly, then create an Object URL of it and display it in an {{htmlelement("img")}} element.
 
 ```js
 const myImage = document.querySelector("img");

files/en-us/web/api/requestinit/index.md

@@ -169,7 +169,8 @@ You can also construct a `Request` with a `RequestInit`, and pass the `Request`
     - `low`
       - : A low priority fetch request relative to other requests of the same type.
     - `auto`
-      - : Automatically determine the priority of the fetch request relative to other requests of the same type.
+      - : No user preference for the fetch priority.
+        It is used if no value is set or if an invalid value is set.
 
     Defaults to `auto`.
 

files/en-us/web/html/element/img/index.md

@@ -144,14 +144,17 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
 - `fetchpriority`
 
-  - : Provides a hint of the relative priority to use when fetching the image. Allowed values:
+  - : Provides a hint of the relative priority to use when fetching the image.
+    Allowed values:
 
     - `high`
-      - : Signals a high-priority fetch relative to other images.
+      - : Fetch the image at a high priority relative to other images.
     - `low`
-      - : Signals a low-priority fetch relative to other images.
+      - : Fetch the image at a low priority relative to other images.
     - `auto`
-      - : Default: Signals automatic determination of fetch priority relative to other images.
+      - : No user preference for the fetch priority.
+        This is the default.
+        It is used if no value or an invalid value is set.
 
 - `height`
 

files/en-us/web/html/element/link/index.md

@@ -201,14 +201,17 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
 - `fetchpriority`
 
-  - : Provides a hint of the relative priority to use when fetching a preloaded resource. Allowed values:
+  - : Provides a hint of the relative priority to use when fetching a resource of a particular type.
+    Allowed values:
 
     - `high`
-      - : Signals a high-priority fetch relative to other resources of the same type.
+      - : Fetch the resource at a high priority relative to other resources of the same type.
     - `low`
-      - : Signals a low-priority fetch relative to other resources of the same type.
+      - : Fetch the resource at a low priority relative to other resources of the same type.
     - `auto`
-      - : Default: Signals automatic determination of fetch priority relative to other resources of the same type.
+      - : No user preference for the fetch priority.
+        This is the default.
+        It is used if no value or an invalid value is set.
 
 - `href`
   - : This attribute specifies the {{glossary("URL")}} of the linked resource. A URL can be absolute or relative.

files/en-us/web/html/element/script/index.md

@@ -81,14 +81,17 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
 
 - `fetchpriority`
 
-  - : Provides a hint of the relative priority to use when fetching an external script. Allowed values:
+  - : Provides a hint of the relative priority to use when fetching an external script.
+    Allowed values:
 
     - `high`
-      - : Signals a high-priority fetch relative to other external scripts.
+      - : Fetch the external script at a high priority relative to other external scripts.
     - `low`
-      - : Signals a low-priority fetch relative to other external scripts.
+      - : Fetch the external script at a low priority relative to other external scripts.
     - `auto`
-      - : Default: Signals automatic determination of fetch priority relative to other external scripts.
+      - : No user preference for the fetch priority.
+        This is the default.
+        It is used if no value or an invalid value is set.
 
 - `integrity`
   - : This attribute contains inline metadata that a user agent can use to verify that a fetched resource has been delivered without unexpected manipulation. The attribute must not specified when the `src` attribute is not specified. See [Subresource Integrity](/en-US/docs/Web/Security/Subresource_Integrity).

files/en-us/web/http/headers/link/index.md

@@ -9,7 +9,8 @@ browser-compat: http.headers.Link
 
 The HTTP **`Link`** [entity header](/en-US/docs/Glossary/Entity_header) field provides a means for serializing one or more links in HTTP headers. This header has the same semantics as the HTML {{HTMLElement("link")}} element. The benefit of using the `Link` header is that the browser can start preconnecting or preloading resources before the HTML itself is fetched and processed.
 
-In practice, most [link types](/en-US/docs/Web/HTML/Attributes/rel) don't have an effect in the HTTP header. For example, the `icon` relation only works in HTML, and `stylesheet` does not work reliably across browsers (only in Firefox). The only relations that work reliably are `preconnect` and `preload`, which can be combined with {{HTTPStatus(103, "103 Early Hints")}}.
+In practice, most [link types](/en-US/docs/Web/HTML/Attributes/rel) don't have an effect in the HTTP header. For example, the `icon` relation only works in HTML, and `stylesheet` does not work reliably across browsers (only in Firefox).
+The only relations that work reliably are [`preconnect`](/en-US/docs/Web/HTML/Attributes/rel/preconnect) and [`preload`](/en-US/docs/Web/HTML/Attributes/rel/preload), which can be combined with {{HTTPStatus(103, "103 Early Hints")}}.
 
 ## Syntax
 
@@ -26,6 +27,8 @@ The link header contains parameters, which are separated with `;` and are equiva
 
 ## Examples
 
+### Enclose URLs in angle brackets
+
 The URI (absolute or relative) must be enclosed between `<` and `>`:
 
 ```http example-good
@@ -56,6 +59,20 @@ You can specify multiple links separated by commas, for example:
 Link: <https://one.example.com>; rel="preconnect", <https://two.example.com>; rel="preconnect", <https://three.example.com>; rel="preconnect"
 ```
 
+### Controlling fetch priority
+
+Even when using [`preload`](/en-US/docs/Web/HTML/Attributes/rel/preload) to fetch a resource as early as possible, different types of content will be fetched earlier or later based on the browser's internal prioritization.
+The [`fetchpriority`](/en-US/docs/Web/HTML/Element/link#fetchpriority) attribute can be used to hint to the browser that a particular resource will have a greater or lesser relative impact on user experience than other resources of the same type.
+
+For example, the header below might be used to preload `style.css` at higher priority than other stylesheets:
+
+```http
+Link: </style.css>; rel=preload; as=style; fetchpriority="high"
+```
+
+Note that both the internal prioritization for fetching resources and the effect of the `fetchpriority` are browser dependent.
+The `fetchpriority` attribute should be used sparingly, and only in cases where a browser would be unable to infer that a particular resource should be treated with a different priority.
+
 ## Specifications
 
 {{Specifications}}
@@ -68,3 +85,4 @@ Link: <https://one.example.com>; rel="preconnect", <https://two.example.com>; re
 
 - {{HTTPStatus(103, "103 Early Hints")}}
 - {{HTMLElement("link")}}
+- [Optimize resource loading with the Fetch Priority API](https://web.dev/articles/fetch-priority?hl=en#browser_priority_and_fetchpriority) for information about how this API affects priorities on Chrome.

files/en-us/web/http/status/103/index.md

@@ -127,4 +127,5 @@ Content-Type: text/html
 - [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/CSP)
 - [`rel="preconnect"`](/en-US/docs/Web/HTML/Attributes/rel/preconnect) ({{htmlelement("link")}} attribute)
 - [`rel="preload"`](/en-US/docs/Web/HTML/Attributes/rel/preload) ({{htmlelement("link")}} attribute)
+- [`fetchpriority`](/en-US/docs/Web/HTML/Element/link#fetchpriority) ({{htmlelement("link")}} attribute)
 - [Early Hints update: How Cloudflare, Google, and Shopify are working together to build a faster Internet for everyone](https://blog.cloudflare.com/early-hints-performance/) from the CloudFlare blog