Merge branch 'v5' into upgrading-v5-doc

Author: tunetheweb

README.md

@@ -897,14 +897,6 @@ interface INPAttribution {
    * within the frame, only the first time is reported).
    */
   interactionTime: DOMHighResTimeStamp;
-  /**
-   * The best-guess timestamp of the next paint after the interaction.
-   * In general, this timestamp is the same as the `startTime + duration` of
-   * the event timing entry. However, since duration values are rounded to the
-   * nearest 8ms (and can be rounded down), this value is clamped to always be
-   * reported after the processing times.
-   */
-  nextPaintTime: DOMHighResTimeStamp;
   /**
    * The type of interaction, based on the event type of the `event` entry
    * that corresponds to the interaction (i.e. the first `event` entry
@@ -913,20 +905,19 @@ interface INPAttribution {
    * and for "keydown" or "keyup" events this will be "keyboard".
    */
   interactionType: 'pointer' | 'keyboard';
+  /**
+   * The best-guess timestamp of the next paint after the interaction.
+   * In general, this timestamp is the same as the `startTime + duration` of
+   * the event timing entry. However, since duration values are rounded to the
+   * nearest 8ms (and can be rounded down), this value is clamped to always be
+   * reported after the processing times.
+   */
+  nextPaintTime: DOMHighResTimeStamp;
   /**
    * An array of Event Timing entries that were processed within the same
    * animation frame as the INP candidate interaction.
    */
   processedEventEntries: PerformanceEventTiming[];
-  /**
-   * If the browser supports the Long Animation Frame API, this array will
-   * include any `long-animation-frame` entries that intersect with the INP
-   * candidate interaction's `startTime` and the `processingEnd` time of the
-   * last event processed within that animation frame. If the browser does not
-   * support the Long Animation Frame API or no `long-animation-frame` entries
-   * are detect, this array will be empty.
-   */
-  longAnimationFrameEntries: PerformanceLongAnimationFrameTiming[];
   /**
    * The time from when the user interacted with the page until when the
    * browser was first able to start processing event listeners for that
@@ -955,6 +946,68 @@ interface INPAttribution {
    * (e.g. usually in the `dom-interactive` phase) it can result in long delays.
    */
   loadState: LoadState;
+  /**
+   * If the browser supports the Long Animation Frame API, this array will
+   * include any `long-animation-frame` entries that intersect with the INP
+   * candidate interaction's `startTime` and the `processingEnd` time of the
+   * last event processed within that animation frame. If the browser does not
+   * support the Long Animation Frame API or no `long-animation-frame` entries
+   * are detected, this array will be empty.
+   */
+  longAnimationFrameEntries: PerformanceLongAnimationFrameTiming[];
+  /**
+   * Summary information about the longest script entry intersecting the INP
+   * duration. Note, only script entries above 5 milliseconds are reported by
+   * the Long Animation Frame API.
+   */
+  longestScript?: INPLongestScriptSummary;
+  /**
+   * The total duration of Long Animation Frame scripts that intersect the INP
+   * duration excluding any forced style and layout (that is included in
+   * totalStyleAndLayout). Note, this is limited to scripts > 5 milliseconds.
+   */
+  totalScriptDuration?: number;
+  /**
+   * The total style and layout duration from any Long Animation Frames
+   * intersecting the INP interaction. This includes any end-of-frame style and
+   * layout duration + any forced style and layout duration.
+   */
+  totalStyleAndLayoutDuration?: number;
+  /**
+   * The off main-thread presentation delay from the end of the last Long
+   * Animation Frame (where available) until the INP end point.
+   */
+  totalPaintDuration?: number;
+  /**
+   * The total unattributed time not included in any of the previous totals.
+   * This includes scripts < 5 milliseconds and other timings not attributed
+   * by Long Animation Frame (including when a frame is < 50ms and so has no
+   * Long Animation Frame).
+   * When no Long Animation Frames are present this will be undefined, rather
+   * than everything being unattributed to make it clearer when it's expected
+   * to be small.
+   */
+  totalUnattributedDuration?: number;
+}
+```
+
+#### `INPLongestScriptSummary`
+
+```ts
+interface INPLongestScriptSummary {
+  /**
+   * The longest Long Animation Frame script entry that intersects the INP
+   * interaction.
+   */
+  entry: PerformanceScriptTiming;
+  /**
+   * The INP subpart where the longest script ran.
+   */
+  subpart: 'input-delay' | 'processing-duration' | 'presentation-delay';
+  /**
+   * The amount of time the longest script intersected the INP duration.
+   */
+  intersectingDuration: number;
 }
 ```
 
@@ -1019,7 +1072,7 @@ interface LCPAttribution {
 #### `TTFBAttribution`
 
 ```ts
-export interface TTFBAttribution {
+interface TTFBAttribution {
   /**
    * The total time from when the user initiates loading the page to when the
    * page starts to handle the request. Large values here are typically due

src/attribution/onINP.ts

@@ -23,9 +23,10 @@ import {whenIdleOrHidden} from '../lib/whenIdleOrHidden.js';
 import {onINP as unattributedOnINP} from '../onINP.js';
 import {
   INPAttribution,
+  INPAttributionReportOpts,
   INPMetric,
   INPMetricWithAttribution,
-  INPAttributionReportOpts,
+  INPLongestScriptSummary,
 } from '../types.js';
 
 interface pendingEntriesGroup {
@@ -238,7 +239,7 @@ export const onINP = (
   };
 
   interactionManager._onBeforeProcessingEntry = groupEntriesByRenderTime;
-  interactionManager._onAfterProcessingInteraction = saveInteractionTarget;
+  interactionManager._onAfterProcessingINPCandidate = saveInteractionTarget;
 
   const getIntersectingLoAFs = (
     start: DOMHighResTimeStamp,
@@ -260,6 +261,96 @@ export const onINP = (
     return intersectingLoAFs;
   };
 
+  const attributeLoAFDetails = (attribution: INPAttribution) => {
+    // If there is no LoAF data then nothing further to attribute
+    if (!attribution.longAnimationFrameEntries?.length) {
+      return;
+    }
+
+    const interactionTime = attribution.interactionTime;
+    const inputDelay = attribution.inputDelay;
+    const processingDuration = attribution.processingDuration;
+
+    // Stats across all LoAF entries and scripts.
+    let totalScriptDuration = 0;
+    let totalStyleAndLayoutDuration = 0;
+    let totalPaintDuration = 0;
+    let longestScriptDuration = 0;
+    let longestScriptEntry: PerformanceScriptTiming | undefined;
+    let longestScriptSubpart: INPLongestScriptSummary['subpart'] | undefined;
+
+    for (const loafEntry of attribution.longAnimationFrameEntries) {
+      totalStyleAndLayoutDuration =
+        totalStyleAndLayoutDuration +
+        loafEntry.startTime +
+        loafEntry.duration -
+        loafEntry.styleAndLayoutStart;
+
+      for (const script of loafEntry.scripts) {
+        const scriptEndTime = script.startTime + script.duration;
+        if (scriptEndTime < interactionTime) {
+          continue;
+        }
+        const intersectingScriptDuration =
+          scriptEndTime - Math.max(interactionTime, script.startTime);
+        // Since forcedStyleAndLayoutDuration doesn't provide timestamps, we
+        // apportion the total based on the intersectingScriptDuration. Not
+        // correct depending on when it occurred, but the best we can do.
+        const intersectingForceStyleAndLayoutDuration = script.duration
+          ? (intersectingScriptDuration / script.duration) *
+            script.forcedStyleAndLayoutDuration
+          : 0;
+        // For scripts we exclude forcedStyleAndLayout (same as DevTools does
+        // in it's summary totals) and instead include that in
+        // totalStyleAndLayoutDuration
+        totalScriptDuration +=
+          intersectingScriptDuration - intersectingForceStyleAndLayoutDuration;
+        totalStyleAndLayoutDuration += intersectingForceStyleAndLayoutDuration;
+
+        if (intersectingScriptDuration > longestScriptDuration) {
+          // Set the subpart this occurred in.
+          longestScriptSubpart =
+            script.startTime < interactionTime + inputDelay
+              ? 'input-delay'
+              : script.startTime >=
+                  interactionTime + inputDelay + processingDuration
+                ? 'presentation-delay'
+                : 'processing-duration';
+
+          longestScriptEntry = script;
+          longestScriptDuration = intersectingScriptDuration;
+        }
+      }
+    }
+
+    // Calculate the totalPaintDuration from the last LoAF after
+    // presentationDelay starts (where available)
+    const lastLoAF = attribution.longAnimationFrameEntries.at(-1);
+    const lastLoAFEndTime = lastLoAF
+      ? lastLoAF.startTime + lastLoAF.duration
+      : 0;
+    if (lastLoAFEndTime >= interactionTime + inputDelay + processingDuration) {
+      totalPaintDuration = attribution.nextPaintTime - lastLoAFEndTime;
+    }
+
+    if (longestScriptEntry && longestScriptSubpart) {
+      attribution.longestScript = {
+        entry: longestScriptEntry,
+        subpart: longestScriptSubpart,
+        intersectingDuration: longestScriptDuration,
+      };
+    }
+    attribution.totalScriptDuration = totalScriptDuration;
+    attribution.totalStyleAndLayoutDuration = totalStyleAndLayoutDuration;
+    attribution.totalPaintDuration = totalPaintDuration;
+    attribution.totalUnattributedDuration =
+      attribution.nextPaintTime -
+      interactionTime -
+      totalScriptDuration -
+      totalStyleAndLayoutDuration -
+      totalPaintDuration;
+  };
+
   const attributeINP = (metric: INPMetric): INPMetricWithAttribution => {
     const firstEntry = metric.entries[0];
     const group = entryToEntriesGroupMap.get(firstEntry)!;
@@ -309,8 +400,15 @@ export const onINP = (
       processingDuration: processingEnd - processingStart,
       presentationDelay: nextPaintTime - processingEnd,
       loadState: getLoadState(firstEntry.startTime),
+      longestScript: undefined,
+      totalScriptDuration: undefined,
+      totalStyleAndLayoutDuration: undefined,
+      totalPaintDuration: undefined,
+      totalUnattributedDuration: undefined,
     };
 
+    attributeLoAFDetails(attribution);
+
     // Use `Object.assign()` to ensure the original metric object is returned.
     const metricWithAttribution: INPMetricWithAttribution = Object.assign(
       metric,

src/lib/InteractionManager.ts

@@ -58,7 +58,7 @@ export class InteractionManager {
 
   _onBeforeProcessingEntry?: (entry: PerformanceEventTiming) => void;
 
-  _onAfterProcessingInteraction?: (interaction: Interaction) => void;
+  _onAfterProcessingINPCandidate?: (interaction: Interaction) => void;
 
   _resetInteractions() {
     prevInteractionCount = getInteractionCount();
@@ -138,8 +138,9 @@ export class InteractionManager {
           this._longestInteractionMap.delete(interaction.id);
         }
       }
-    }
 
-    this._onAfterProcessingInteraction?.(interaction!);
+      // Call any post-processing on the interaction
+      this._onAfterProcessingINPCandidate?.(interaction);
+    }
   }
 }

src/types.ts

@@ -88,9 +88,53 @@ declare global {
     readonly element: Element | null;
   }
 
+  // https://w3c.github.io/long-animation-frame/#sec-PerformanceLongAnimationFrameTiming
+  export type ScriptInvokerType =
+    | 'classic-script'
+    | 'module-script'
+    | 'event-listener'
+    | 'user-callback'
+    | 'resolve-promise'
+    | 'reject-promise';
+
+  // https://w3c.github.io/long-animation-frame/#sec-PerformanceLongAnimationFrameTiming
+  export type ScriptWindowAttribution =
+    | 'self'
+    | 'descendant'
+    | 'ancestor'
+    | 'same-page'
+    | 'other';
+
+  // https://w3c.github.io/long-animation-frame/#sec-PerformanceLongAnimationFrameTiming
+  interface PerformanceScriptTiming extends PerformanceEntry {
+    /* Overloading PerformanceEntry */
+    readonly startTime: DOMHighResTimeStamp;
+    readonly duration: DOMHighResTimeStamp;
+    readonly name: string;
+    readonly entryType: string;
+
+    readonly invokerType: ScriptInvokerType;
+    readonly invoker: string;
+    readonly executionStart: DOMHighResTimeStamp;
+    readonly sourceURL: string;
+    readonly sourceFunctionName: string;
+    readonly sourceCharPosition: number;
+    readonly pauseDuration: DOMHighResTimeStamp;
+    readonly forcedStyleAndLayoutDuration: DOMHighResTimeStamp;
+    readonly window?: Window;
+    readonly windowAttribution: ScriptWindowAttribution;
+  }
+
   // https://w3c.github.io/long-animation-frame/#sec-PerformanceLongAnimationFrameTiming
   interface PerformanceLongAnimationFrameTiming extends PerformanceEntry {
-    renderStart: DOMHighResTimeStamp;
-    duration: DOMHighResTimeStamp;
+    readonly startTime: DOMHighResTimeStamp;
+    readonly duration: DOMHighResTimeStamp;
+    readonly name: string;
+    readonly entryType: string;
+    readonly renderStart: DOMHighResTimeStamp;
+    readonly styleAndLayoutStart: DOMHighResTimeStamp;
+    readonly blockingDuration: DOMHighResTimeStamp;
+    readonly firstUIEventTimestamp: DOMHighResTimeStamp;
+    readonly scripts: PerformanceScriptTiming[];
   }
 }