Merge branch 'main' into update-web-standards-model

files/en-us/glossary/time_to_first_byte/index.md

@@ -8,14 +8,17 @@ page-type: glossary-definition
 
 **Time to First Byte** (TTFB) refers to the time between the browser requesting a page and when it receives the first byte of information from the server. This time includes {{Glossary("DNS")}} lookup and establishing the connection using a {{Glossary("TCP")}} handshake and {{Glossary("TLS")}} handshake if the request is made over {{Glossary("HTTPS")}}.
 
-TTFB is the time it takes between the start of the request and the start of the response, in milliseconds:
+TTFB is the time it takes between the start of the request and the start of the response, in milliseconds. This can be measured using the `{{domxref("PerformanceResourceTiming.requestStart", "requestStart")}}` attribute of {{domxref("PerformanceNavigationTiming")}}:
 
-```plain
-TTFB = responseStart - navigationStart
+```javascript
+const ttfb = performance.getEntriesByType("navigation")[0].responseStart;
 ```
 
+> [!NOTE]
+> For sites using {{HTTPStatus("103", "103 Early Hints")}}, TTFB is typically the _first bytes_ (after any redirects) — and so, the 103 interim response. Site owners wishing to measure the time until the final response should use `{{domxref("PerformanceResourceTiming.finalResponseHeadersStart", "finalResponseHeadersStart")}}`, where supported.
+
 ## See also
 
 - [A typical HTTP session](/en-US/docs/Web/HTTP/Session)
 - [PerformanceResourceTiming](/en-US/docs/Web/API/PerformanceResourceTiming)
-- [PerformanceTiming](/en-US/docs/Web/API/PerformanceTiming)
+- [PerformanceNavigationTiming](/en-US/docs/Web/API/PerformanceNavigationTiming)

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

@@ -26,6 +26,8 @@ The **`Animation`** interface of the [Web Animations API](/en-US/docs/Web/API/We
   - : Returns the current finished Promise for this animation.
 - {{domxref("Animation.id")}}
   - : Gets and sets the `String` used to identify the animation.
+- {{domxref("Animation.overallProgress")}} {{ReadOnlyInline}} {{experimental_inline}}
+  - : Returns a number between `0` and `1` indicating the animation's overall progress towards its finished state.
 - {{domxref("Animation.pending")}} {{ReadOnlyInline}}
   - : Indicates whether the animation is currently waiting for an asynchronous operation such as initiating playback or pausing a running animation.
 - {{domxref("Animation.playState")}} {{ReadOnlyInline}}

files/en-us/web/api/animation/overallprogress/index.md

@@ -0,0 +1,149 @@
+---
+title: "Animation: overallProgress property"
+short-title: overallProgress
+slug: Web/API/Animation/overallProgress
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.Animation.overallProgress
+---
+
+{{APIRef("Web Animations")}}{{seecompattable}}
+
+The **`overallProgress`** read-only property of the {{domxref("Animation")}} interface returns a number between `0` and `1` indicating the animation's overall progress towards its finished state. This is the overall progress across all of the animation's iterations, not each individual iteration.
+
+`overallProgress` works consistently across all animations, regardless of the type of {{domxref("AnimationTimeline", "timeline")}}.
+
+## Value
+
+A number between `0` and `1`, or `null` if the animation lacks a timeline, is inactive or hasn't been played yet, or if its {{domxref("Animation/currentTime", "currentTime")}} is set to a non-time value.
+
+If the animation's [`iterations`](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#iterations) property is set to `Infinity`, or if its {{domxref("Animation/currentTime", "currentTime")}} is set to a negative value, `overallProgress` will return `0`.
+
+If the animation's [`duration`](/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#duration) is set to `0`, `overallProgress` will return `1`.
+
+## Examples
+
+### Displaying a percentage progress
+
+This demo uses `overallProgress` to create a "percentage progress" readout, which is displayed to the screen while an animation runs.
+
+### HTML
+
+The HTML contains a {{htmlelement("button")}} to press to start the animation, a {{htmlelement("p")}} element in which to display the percentage progress, and a {{htmlelement("div")}} that will be animated.
+
+```html
+<button>Run animation</button>
+<p class="progress">Progress: 0%</p>
+<div class="box"></div>
+```
+
+The demo's CSS provides some rudimentary styling, which is not important for understanding how the JavaScript works, therefore we have hidden it for brevity.
+
+```css hidden
+* {
+  box-sizing: border-box;
+}
+
+html {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+body {
+  margin: 0;
+  width: 500px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+.progress {
+  font-weight: bold;
+}
+
+.box {
+  width: 100px;
+  height: 100px;
+  border-radius: 40px 20px;
+  border: 10px solid black;
+  background: lightseagreen;
+  margin: 0 auto;
+}
+```
+
+### JavaScript
+
+In the JavaScript, we start off by grabbing references to the {{htmlelement("button")}}, {{htmlelement("p")}}, and {{htmlelement("div")}} elements.
+
+We then create:
+
+- an `animation` variable which will reference the animation, once we've created it
+- a [keyframes](/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) array
+- an options object containing timing properties.
+
+```js
+const btn = document.querySelector("button");
+const progress = document.querySelector(".progress");
+const box = document.querySelector(".box");
+
+let animation;
+
+const keyframes = [{ rotate: "0deg" }, { rotate: "360deg" }];
+
+const timingProps = {
+  duration: 3000,
+  iterations: 1,
+};
+```
+
+Next we add a `"click"` event listener to the `<button>` via [`addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) so that, when pressed, it:
+
+1. Starts the animation running using {{domxref("Element.animate()")}}, passing it the keyframes and options defined earlier and assigning the returned {{domxref("Animation")}} instance to the `animation` variable.
+2. Runs a function called `updateProgress()` via the {{domxref("Window.requestAnimationFrame", "requestAnimationFrame()")}} method, which handles updating the percentage process display.
+
+```js
+btn.addEventListener("click", () => {
+  // Animate the box
+  animation = box.animate(keyframes, timingProps);
+  // Start updating the progress percentage via rAF()
+  requestAnimationFrame(updateProgress);
+});
+```
+
+Now let's define the `updateProgress()` function. This queries {{domxref("Animation.playState")}} to see if the animation is not finished. If it isn't finished, we grab the current value of `overallProgress`, multiplying it by 100 and rounding the result down to convert it to a whole percentage number, then update the `<p>` element's {{domxref("Node.textContent", "textContent")}} value with it. We then call `requestAnimationFrame(updateProgress)` again to re-run the progress percentage update.
+
+If the animation is finished, we replace the percentage progress with a "Finished!" message, and don't call `requestAnimationFrame(updateProgress)`, so the progress percentage updates stop.
+
+```js
+function updateProgress() {
+  // Check if the animation is finished
+  if (animation.playState !== "finished") {
+    // Convert overallProgress to a whole number percentage
+    const progressPercentage = Math.floor(animation.overallProgress * 100);
+    // Update the progress paragraph with the percentage
+    progress.textContent = `Progress: ${progressPercentage}%`;
+    // Only request the next frame if the animation is not finished
+    requestAnimationFrame(updateProgress);
+  } else {
+    progress.textContent = "Finished!";
+  }
+}
+```
+
+### Result
+
+The output looks like this. Try pressing the button to see the animation and associated progress indicator run.
+
+{{ EmbedLiveSample("Displaying a percentage progress", "100%", 250) }}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("Animation")}} for other methods and properties you can use to control web page animation.
+- [Web Animations API](/en-US/docs/Web/API/Web_Animations_API)

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

@@ -85,9 +85,13 @@ observer.observe({ type: "largest-contentful-paint", buffered: true });
 
 ### Cross-origin image render time
 
-For security reasons, the value of the {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} property is `0` if the resource is a cross-origin request. Instead the {{domxref("LargestContentfulPaint.loadTime", "loadTime")}} is exposed. To expose cross-origin render time information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+For security reasons, the value of the {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} property was originally `0` if the resource is a cross-origin request. Instead the {{domxref("LargestContentfulPaint.loadTime", "loadTime")}} property should be used as a fallback.
 
-For example, to allow `https://developer.mozilla.org` to see `renderTime`, the cross-origin resource should send:
+Browsers [may now expose a slightly coarsened render time](https://github.com/w3c/paint-timing/issues/104) in these situations. Check for [browser support](#browser_compatibility).
+
+To expose more accurate cross-origin render-time information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see an accurate `renderTime`, the cross-origin resource should send:
 
 ```http
 Timing-Allow-Origin: https://developer.mozilla.org

files/en-us/web/api/largestcontentfulpaint/rendertime/index.md

@@ -34,9 +34,13 @@ observer.observe({ type: "largest-contentful-paint", buffered: true });
 
 ### Cross-origin image render time
 
-For security reasons, the value of the `renderTime` property is `0` if the resource is a cross-origin request. Instead the {{domxref("LargestContentfulPaint.loadTime", "loadTime")}} is exposed. To expose cross-origin render time information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+For security reasons, the value of the {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} property was originally `0` if the resource is a cross-origin request. Instead the {{domxref("LargestContentfulPaint.loadTime", "loadTime")}} property should be used as a fallback.
 
-For example, to allow `https://developer.mozilla.org` to see `renderTime`, the cross-origin resource should send:
+Browsers [may now expose a slightly coarsened render time](https://github.com/w3c/paint-timing/issues/104) in threse situations. Check for [browser support](#browser_compatibility).
+
+To expose more accurate cross-origin render-time information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see an accurate `renderTime`, the cross-origin resource should send:
 
 ```http
 Timing-Allow-Origin: https://developer.mozilla.org

files/en-us/web/api/performanceelementtiming/rendertime/index.md

@@ -47,9 +47,13 @@ observer.observe({ type: "element", buffered: true });
 
 ### Cross-origin image render time
 
-For security reasons, the value of the `renderTime` property is `0` if the resource is a cross-origin request. To expose cross-origin render time information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+For security reasons, the value of the `renderTime` property was originally `0` if the resource is a cross-origin request. Instead the `loadTime` property should be used as a fallback.
 
-For example, to allow `https://developer.mozilla.org` to see `renderTime`, the cross-origin resource should send:
+Browsers [may now expose a slightly coarsened render time](https://github.com/w3c/paint-timing/issues/104) in these situations. Check for [browser support](#browser_compatibility).
+
+To expose more accurate cross-origin render-time information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see an accurate `renderTime`, the cross-origin resource should send:
 
 ```http
 Timing-Allow-Origin: https://developer.mozilla.org

files/en-us/web/api/performanceresourcetiming/finalresponseheadersstart/index.md

@@ -0,0 +1,103 @@
+---
+title: "PerformanceResourceTiming: finalResponseHeadersStart property"
+short-title: finalResponseHeadersStart
+slug: Web/API/PerformanceResourceTiming/finalResponseHeadersStart
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.PerformanceResourceTiming.finalResponseHeadersStart
+---
+
+{{APIRef("Performance API")}}{{AvailableInWorkers}}{{SeeCompatTable}}
+
+The **`finalResponseHeadersStart`** read-only property returns a {{domxref("DOMHighResTimeStamp","timestamp")}} immediately after the browser receives the first byte of the final document response (for example, 200 OK) from the server.
+
+This differs from **`{{domxref("PerformanceResourceTiming.requestStart", "requestStart")}}`** (which may also be represented as **`{{domxref("PerformanceResourceTiming.firstInterimResponseStart", "firstInterimResponseStart")}}`**), as this starts from the first bytes of any response including interim responses (for example, 103 Early Hints) with the final response coming potentially much later.
+
+When there are no interim responses, `requestStart` is the same as `finalResponseHeadersStart` and `firstInterimResponseStart` is 0.
+
+There is no _end_ property for `finalResponseHeadersStart`.
+
+## Value
+
+The `finalResponseHeadersStart` property can have the following values:
+
+- A {{domxref("DOMHighResTimeStamp")}} immediately after the browser receives the first bytes of the final response from the server.
+- `0` if the resource is a cross-origin request and no {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header is used.
+
+## Examples
+
+### Measuring request time
+
+The `finalResponseHeadersStart` and {{domxref("PerformanceResourceTiming.requestStart", "requestStart")}} properties can be used to measure how long it takes for the browser to start receive the final response after the sending the request.
+
+```js
+const request = entry.finalResponseHeadersStart - entry.requestStart;
+```
+
+The following example uses a {{domxref("PerformanceObserver")}} to notify of new `resource` performance entries as they are recorded in the browser's performance timeline. The `buffered` option is used for accessing entries from before the observer creation.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    const request = entry.finalResponseHeadersStart - entry.requestStart;
+    if (request > 0) {
+      console.log(`${entry.name}: final response time: ${request}ms`);
+    }
+  });
+});
+
+observer.observe({ type: "resource", buffered: true });
+```
+
+The following example uses {{domxref("Performance.getEntriesByType()")}}, which only shows `resource` performance entries present in the browser's performance timeline at the time you call the method.
+
+```js
+const resources = performance.getEntriesByType("resource");
+resources.forEach((entry) => {
+  const request = entry.finalResponseHeadersStart - entry.requestStart;
+  if (request > 0) {
+    console.log(`${entry.name}: final response time: ${request}ms`);
+  }
+});
+```
+
+The following example shows how to measure the time between the first and final response headers.
+
+```js
+const observer = new PerformanceObserver((list) => {
+  list.getEntries().forEach((entry) => {
+    const diff = entry.finalResponseHeadersStart - entry.responseStart;
+    if ((entry.finalResponseHeadersStart > 0) & (diff > 0)) {
+      console.log(
+        `${entry.name}: time between first and final response start: ${diff}ms`,
+      );
+    }
+  });
+});
+
+observer.observe({ type: "resource", buffered: true });
+```
+
+### Cross-origin timing information
+
+If the value of the `finalResponseHeadersStart` property is `0`, the resource might be a cross-origin request. To allow seeing cross-origin timing information, the {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header needs to be set.
+
+For example, to allow `https://developer.mozilla.org` to see timing resources, the cross-origin resource should send:
+
+```http
+Timing-Allow-Origin: https://developer.mozilla.org
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{HTTPHeader("Timing-Allow-Origin")}}
+- {{domxref("PerformanceResourceTiming.firstInterimResponseStart", "firstInterimResponseStart")}}

files/en-us/web/api/performanceresourcetiming/firstinterimresponsestart/index.md

@@ -19,17 +19,19 @@ There is no _end_ property for `firstInterimResponseStart`.
 The `firstInterimResponseStart` property can have the following values:
 
 - A {{domxref("DOMHighResTimeStamp")}} immediately after the browser receives the first interim bytes of the response from the server.
-- `0` if the resource sent no interim response
+- `0` if the resource sent no interim response.
 - `0` if the resource is a cross-origin request and no {{HTTPHeader("Timing-Allow-Origin")}} HTTP response header is used.
 
 > [!NOTE]
 > As Early Hints are typically only supported on the main navigation request, which is by definition same-origin, a `0` typically indicates Early Hints were **not** used.
 
+When the `firstInterimResponseStart` is non-zero, that indicates it should be the same value as {{domxref("PerformanceResourceTiming.requestStart", "requestStart")}} for [supporting browsers](#browser_compatibility).
+
 ## Examples
 
 ### Measuring request time
 
-The `firstInterimResponseStart` and {{domxref("PerformanceResourceTiming.requestStart", "requestStart")}} properties can be used to measure how long it takes to the browser to receive an interim response after the sending the request.
+The `firstInterimResponseStart` and `requestStart` properties can be used to measure how long it takes to the browser to receive an interim response after the sending the request.
 
 ```js
 const request = entry.firstInterimResponseStart - entry.requestStart;
@@ -83,3 +85,4 @@ Timing-Allow-Origin: https://developer.mozilla.org
 ## See also
 
 - {{HTTPHeader("Timing-Allow-Origin")}}
+- {{domxref("PerformanceResourceTiming.finalResponseHeadersStart", "finalResponseHeadersStart")}}

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

@@ -22,7 +22,7 @@ The properties of this interface allow you to calculate certain resource timing
 - Measuring TCP handshake time (`connectEnd` - `connectStart`)
 - Measuring DNS lookup time (`domainLookupEnd` - `domainLookupStart`)
 - Measuring redirection time (`redirectEnd` - `redirectStart`)
-- Measuring interim request time (`firstInterimResponseStart` - `requestStart`)
+- Measuring interim request time (`firstInterimResponseStart` - `finalResponseHeadersStart`)
 - Measuring request time (`responseStart` - `requestStart`)
 - Measuring TLS negotiation time (`requestStart` - `secureConnectionStart`)
 - Measuring time to fetch (without redirects) (`responseEnd` - `fetchStart`)
@@ -76,7 +76,9 @@ The interface supports the following timestamp properties which you can see in t
 - {{domxref('PerformanceResourceTiming.firstInterimResponseStart')}} {{experimental_inline}} {{ReadOnlyInline}}
   - : A {{domxref("DOMHighResTimeStamp")}} that represents the interim response time (for example, 100 Continue or 103 Early Hints).
 - {{domxref('PerformanceResourceTiming.responseStart')}} {{ReadOnlyInline}}
-  - : A {{domxref("DOMHighResTimeStamp")}} immediately after the browser receives the first byte of the response from the server.
+  - : A {{domxref("DOMHighResTimeStamp")}} immediately after the browser receives the first byte of the response from the server (which may be an interim response).
+- {{domxref('PerformanceResourceTiming.finalResponseHeadersStart')}} {{experimental_inline}} {{ReadOnlyInline}}
+  - : A {{domxref("DOMHighResTimeStamp")}} that represents the final headers response time (for example, 200 Success), after any interim response time.
 - {{domxref('PerformanceResourceTiming.responseEnd')}} {{ReadOnlyInline}}
   - : A {{domxref("DOMHighResTimeStamp")}} immediately after the browser receives the last byte of the resource or immediately before the transport connection is closed, whichever comes first.