lighthouse 11.3.0 → 11.4.0

package/core/audits/metrics/max-potential-fid.js

@@ -6,8 +6,18 @@
 
 import {Audit} from '../audit.js';
 import {MaxPotentialFID as ComputedFid} from '../../computed/metrics/max-potential-fid.js';
+import {ProcessedTrace} from '../../computed/processed-trace.js';
+import {ProcessedNavigation} from '../../computed/processed-navigation.js';
 import * as i18n from '../../lib/i18n/i18n.js';
 
+/**
+ * @typedef LoafDebugDetails
+ * @property {'debugdata'} type
+ * @property {LH.TraceEvent=} observedMaxDurationLoaf
+ * @property {LH.TraceEvent=} observedMaxBlockingLoaf
+ * @property {Array<{startTime: number, duration: number, blockingDuration: number}>} observedLoafs
+ */
+
 const UIStrings = {
   /** Description of the Maximum Potential First Input Delay metric that marks the maximum estimated time between the page receiving input (a user clicking, tapping, or typing) and the page responding. This description is displayed within a tooltip when the user hovers on the metric name to see more. No character length limits. The last sentence starting with 'Learn' becomes link text to additional documentation. */
   description: 'The maximum potential First Input Delay that your users could experience is the ' +
@@ -48,6 +58,59 @@ class MaxPotentialFID extends Audit {
     };
   }
 
+  /**
+   * Extract potential LoAF replacements for MPFID from the trace to log in
+   * debugdata details.
+   * @param {LH.Artifacts.ProcessedTrace} processedTrace
+   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+   * @return {LoafDebugDetails|undefined}
+   */
+  static getLongAnimationFrameDetails(processedTrace, processedNavigation) {
+    const {firstContentfulPaint, timeOrigin} = processedNavigation.timestamps;
+
+    const loafEvents = processedTrace.mainThreadEvents.filter(evt => {
+      return evt.name === 'LongAnimationFrame' && evt.ph === 'b';
+    });
+    if (loafEvents.length === 0) return;
+
+    let currentMaxDuration = -Infinity;
+    let currentMaxDurationLoaf;
+    let currentMaxBlocking = -Infinity;
+    let currentMaxBlockingLoaf;
+    const observedLoafs = [];
+    for (const loafEvent of loafEvents) {
+      const loafDuration = loafEvent.args?.data?.duration;
+      const loafBlocking = loafEvent.args?.data?.blockingDuration;
+      // Should never happen, so mostly keeping the type checker happy.
+      if (loafDuration === undefined || loafBlocking === undefined) continue;
+
+      observedLoafs.push({
+        startTime: (loafEvent.ts - timeOrigin) / 1000,
+        duration: loafDuration,
+        blockingDuration: loafBlocking,
+      });
+
+      // Max LoAFs are only considered after FCP.
+      if (loafEvent.ts < firstContentfulPaint) continue;
+
+      if (loafDuration > currentMaxDuration) {
+        currentMaxDuration = loafDuration;
+        currentMaxDurationLoaf = loafEvent;
+      }
+      if (loafBlocking > currentMaxBlocking) {
+        currentMaxBlocking = loafBlocking;
+        currentMaxBlockingLoaf = loafEvent;
+      }
+    }
+
+    return {
+      type: 'debugdata',
+      observedMaxDurationLoaf: currentMaxDurationLoaf,
+      observedMaxBlockingLoaf: currentMaxBlockingLoaf,
+      observedLoafs,
+    };
+  }
+
   /**
    * @param {LH.Artifacts} artifacts
    * @param {LH.Audit.Context} context
@@ -61,6 +124,11 @@ class MaxPotentialFID extends Audit {
       settings: context.settings, URL: artifacts.URL};
     const metricResult = await ComputedFid.request(metricComputationData, context);
 
+    const processedTrace = await ProcessedTrace.request(trace, context);
+    const processedNavigation = await ProcessedNavigation.request(trace, context);
+    const details = MaxPotentialFID.getLongAnimationFrameDetails(processedTrace,
+        processedNavigation);
+
     return {
       score: Audit.computeLogNormalScore(
         {p10: context.options.p10, median: context.options.median},
@@ -69,6 +137,7 @@ class MaxPotentialFID extends Audit {
       numericValue: metricResult.timing,
       numericUnit: 'millisecond',
       displayValue: str_(i18n.UIStrings.ms, {timeInMs: metricResult.timing}),
+      details,
     };
   }
 }

package/core/audits/resource-summary.d.ts

@@ -0,0 +1,11 @@
+export default ResourceSummary;
+declare class ResourceSummary extends Audit {
+    /**
+     * @param {LH.Artifacts} artifacts
+     * @param {LH.Audit.Context} context
+     * @return {Promise<LH.Audit.Product>}
+     */
+    static audit(artifacts: LH.Artifacts, context: LH.Audit.Context): Promise<LH.Audit.Product>;
+}
+import { Audit } from './audit.js';
+//# sourceMappingURL=resource-summary.d.ts.map

package/core/audits/resource-summary.js

@@ -0,0 +1,86 @@
+/**
+ * @license Copyright 2019 The Lighthouse Authors. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+
+import {Audit} from './audit.js';
+import {ResourceSummary as ComputedResourceSummary} from '../computed/resource-summary.js';
+import * as i18n from '../lib/i18n/i18n.js';
+
+const str_ = i18n.createIcuMessageFn(import.meta.url);
+
+class ResourceSummary extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'resource-summary',
+      title: 'Resources Summary',
+      description: 'Aggregates all network requests and groups them by type',
+      scoreDisplayMode: Audit.SCORING_MODES.INFORMATIVE,
+      requiredArtifacts: ['devtoolsLogs', 'URL'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    const devtoolsLog = artifacts.devtoolsLogs[Audit.DEFAULT_PASS];
+    const summary = await ComputedResourceSummary
+      .request({devtoolsLog, URL: artifacts.URL, budgets: context.settings.budgets}, context);
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      {key: 'label', valueType: 'text', label: str_(i18n.UIStrings.columnResourceType)},
+      {key: 'requestCount', valueType: 'numeric', label: str_(i18n.UIStrings.columnRequests)},
+      {key: 'transferSize', valueType: 'bytes', label: str_(i18n.UIStrings.columnTransferSize)},
+    ];
+
+
+    /** @type {Record<LH.Budget.ResourceType, LH.IcuMessage>} */
+    const strMappings = {
+      'total': str_(i18n.UIStrings.totalResourceType),
+      'document': str_(i18n.UIStrings.documentResourceType),
+      'script': str_(i18n.UIStrings.scriptResourceType),
+      'stylesheet': str_(i18n.UIStrings.stylesheetResourceType),
+      'image': str_(i18n.UIStrings.imageResourceType),
+      'media': str_(i18n.UIStrings.mediaResourceType),
+      'font': str_(i18n.UIStrings.fontResourceType),
+      'other': str_(i18n.UIStrings.otherResourceType),
+      'third-party': str_(i18n.UIStrings.thirdPartyResourceType),
+    };
+
+    const types = /** @type {Array<LH.Budget.ResourceType>} */ (Object.keys(summary));
+    const rows = types.map(type => {
+      return {
+        // ResourceType is included as an "id" for ease of use.
+        // It does not appear directly in the table.
+        resourceType: type,
+        label: strMappings[type],
+        requestCount: summary[type].count,
+        transferSize: summary[type].transferSize,
+      };
+    });
+    // Force third-party to be last, descending by size otherwise
+    const thirdPartyRow = rows.find(r => r.resourceType === 'third-party') || [];
+    const otherRows = rows.filter(r => r.resourceType !== 'third-party')
+      .sort((a, b) => {
+        return b.transferSize - a.transferSize;
+      });
+    const tableItems = otherRows.concat(thirdPartyRow);
+
+    const tableDetails = Audit.makeTableDetails(headings, tableItems);
+
+    return {
+      details: tableDetails,
+      score: null,
+    };
+  }
+}
+
+export default ResourceSummary;

package/core/audits/third-party-cookies.d.ts

@@ -0,0 +1,22 @@
+export default ThirdPartyCookies;
+declare class ThirdPartyCookies extends Audit {
+    /**
+     * https://source.chromium.org/chromium/chromium/src/+/d2fcd4ba302baeabf4b96d8fa9fdb7a215736c31:third_party/devtools-frontend/src/front_end/models/issues_manager/CookieIssue.ts;l=62-69
+     * @param {LH.Crdp.Audits.CookieIssueDetails} cookieIssue
+     * @return {string}
+     */
+    static getCookieId(cookieIssue: LH.Crdp.Audits.CookieIssueDetails): string;
+    /**
+     * @param {LH.Artifacts} artifacts
+     * @return {Promise<LH.Audit.Product>}
+     */
+    static audit(artifacts: LH.Artifacts): Promise<LH.Audit.Product>;
+}
+export namespace UIStrings {
+    const title: string;
+    const failureTitle: string;
+    const description: string;
+    const displayValue: string;
+}
+import { Audit } from './audit.js';
+//# sourceMappingURL=third-party-cookies.d.ts.map

package/core/audits/third-party-cookies.js

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Audits a page to determine if it is using third party cookies.
+ */
+
+import {Audit} from './audit.js';
+import * as i18n from '../lib/i18n/i18n.js';
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /** Title of a Lighthouse audit that provides detail on the use of third party cookies. This descriptive title is shown to users when the page does not use third party cookies. */
+  title: 'Avoids third-party cookies',
+  /** Title of a Lighthouse audit that provides detail on the use of third party cookies. This descriptive title is shown to users when the page uses third party cookies. */
+  failureTitle: 'Uses third-party cookies',
+  /** Description of a Lighthouse audit that tells the user why they should not use third party cookies on their page. This is displayed after a user expands the section to see more. No character length limits. The last sentence starting with 'Learn' becomes link text to additional documentation. */
+  description: 'Support for third-party cookies will be removed in a future version of Chrome. [Learn more about phasing out third-party cookies](https://developer.chrome.com/en/docs/privacy-sandbox/third-party-cookie-phase-out/).',
+  /** [ICU Syntax] Label for the audit identifying the number of third-party cookies. */
+  displayValue: `{itemCount, plural,
+    =1 {1 cookie found}
+    other {# cookies found}
+    }`,
+};
+/* eslint-enable max-len */
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+class ThirdPartyCookies extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'third-party-cookies',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.failureTitle),
+      description: str_(UIStrings.description),
+      requiredArtifacts: ['InspectorIssues'],
+    };
+  }
+
+  /**
+   * https://source.chromium.org/chromium/chromium/src/+/d2fcd4ba302baeabf4b96d8fa9fdb7a215736c31:third_party/devtools-frontend/src/front_end/models/issues_manager/CookieIssue.ts;l=62-69
+   * @param {LH.Crdp.Audits.CookieIssueDetails} cookieIssue
+   * @return {string}
+   */
+  static getCookieId(cookieIssue) {
+    if (!cookieIssue.cookie) {
+      return cookieIssue.rawCookieLine ?? 'no-cookie-info';
+    }
+
+    const {domain, path, name} = cookieIssue.cookie;
+    const cookieId = `${domain};${path};${name}`;
+    return cookieId;
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts) {
+    /** @type {Set<string>} */
+    const seenCookies = new Set();
+
+    /** @type {LH.Audit.Details.TableItem[]} */
+    const items = [];
+    for (const issue of artifacts.InspectorIssues.cookieIssue) {
+      const isPhaseoutWarn = issue.cookieWarningReasons.includes('WarnThirdPartyPhaseout');
+      const isPhaseoutExclude = issue.cookieExclusionReasons.includes('ExcludeThirdPartyPhaseout');
+      if (!isPhaseoutWarn && !isPhaseoutExclude) continue;
+
+      // According to JSDOC for `issue.cookie`, if `cookie` is undefined then `rawCookieLine`
+      // should be set and no valid cookie could be created. It should be safe to skip in this case.
+      const name = issue.cookie?.name || issue.rawCookieLine;
+      if (!name) continue;
+
+      const cookieId = this.getCookieId(issue);
+      if (seenCookies.has(cookieId)) continue;
+      seenCookies.add(cookieId);
+
+      items.push({
+        name,
+        url: issue.cookieUrl,
+      });
+    }
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      {key: 'name', valueType: 'text', label: str_(i18n.UIStrings.columnName)},
+      {key: 'url', valueType: 'url', label: str_(i18n.UIStrings.columnURL)},
+    ];
+    const details = Audit.makeTableDetails(headings, items);
+
+    let displayValue;
+    if (items.length > 0) {
+      displayValue = str_(UIStrings.displayValue, {itemCount: items.length});
+    }
+
+    return {
+      score: items.length ? 0 : 1,
+      displayValue,
+      details,
+    };
+  }
+}
+
+export default ThirdPartyCookies;
+export {UIStrings};

package/core/audits/third-party-summary.d.ts

@@ -25,6 +25,25 @@ export type SummaryMaps = {
      */
     urls: Map<LH.Artifacts.Entity, string[]>;
 };
+/**
+ * @typedef Summary
+ * @property {number} mainThreadTime
+ * @property {number} transferSize
+ * @property {number} blockingTime
+ * @property {number} tbtImpact
+ */
+/**
+ * @typedef URLSummary
+ * @property {number} transferSize
+ * @property {number} blockingTime
+ * @property {number} tbtImpact
+ * @property {string | LH.IcuMessage} url
+ */
+/** @typedef SummaryMaps
+ * @property {Map<LH.Artifacts.Entity, Summary>} byEntity Map of impact summaries for each entity.
+ * @property {Map<string, Summary>} byURL Map of impact summaries for each URL.
+ * @property {Map<LH.Artifacts.Entity, string[]>} urls Map of URLs under each entity.
+ */
 declare class ThirdPartySummary extends Audit {
     /**
      *
@@ -38,10 +57,9 @@ declare class ThirdPartySummary extends Audit {
     /**
      * @param {LH.Artifacts.Entity} entity
      * @param {SummaryMaps} summaries
-     * @param {Summary} stats
      * @return {Array<URLSummary>}
      */
-    static makeSubItems(entity: LH.Artifacts.Entity, summaries: SummaryMaps, stats: Summary): Array<URLSummary>;
+    static makeSubItems(entity: LH.Artifacts.Entity, summaries: SummaryMaps): Array<URLSummary>;
     /**
      * @param {LH.Artifacts} artifacts
      * @param {LH.Audit.Context} context

package/core/audits/third-party-summary.js

@@ -55,15 +55,6 @@ const PASS_THRESHOLD_IN_MS = 250;
  * @property {Map<LH.Artifacts.Entity, string[]>} urls Map of URLs under each entity.
  */
 
-/**
- * Don't bother showing resources smaller than 4KiB since they're likely to be pixels, which isn't
- * too actionable.
- */
-const MIN_TRANSFER_SIZE_FOR_SUBITEMS = 4096;
-
-/** Show at most 5 sub items in the resource breakdown. */
-const MAX_SUBITEMS = 5;
-
 class ThirdPartySummary extends Audit {
   /**
    * @return {LH.Audit.Meta}
@@ -146,51 +137,15 @@ class ThirdPartySummary extends Audit {
   /**
    * @param {LH.Artifacts.Entity} entity
    * @param {SummaryMaps} summaries
-   * @param {Summary} stats
    * @return {Array<URLSummary>}
    */
-  static makeSubItems(entity, summaries, stats) {
+  static makeSubItems(entity, summaries) {
     const entityURLs = summaries.urls.get(entity) || [];
-    let items = entityURLs
+    const items = entityURLs
       .map(url => /** @type {URLSummary} */ ({url, ...summaries.byURL.get(url)}))
-      // Filter out any cases where byURL was missing entries.
-      .filter((stat) => stat.transferSize > 0)
       // Sort by blocking time first, then transfer size to break ties.
       .sort((a, b) => (b.blockingTime - a.blockingTime) || (b.transferSize - a.transferSize));
 
-    const subitemSummary = {transferSize: 0, blockingTime: 0, tbtImpact: 0};
-    const minTransferSize = Math.max(MIN_TRANSFER_SIZE_FOR_SUBITEMS, stats.transferSize / 20);
-    const maxSubItems = Math.min(MAX_SUBITEMS, items.length);
-    let numSubItems = 0;
-    while (numSubItems < maxSubItems) {
-      const nextSubItem = items[numSubItems];
-      if (nextSubItem.blockingTime === 0 && nextSubItem.transferSize < minTransferSize) {
-        // Don't include the resource in the sub-item breakdown because it didn't have a big
-        // enough impact on its own.
-        break;
-      }
-
-      numSubItems++;
-      subitemSummary.transferSize += nextSubItem.transferSize;
-      subitemSummary.blockingTime += nextSubItem.blockingTime;
-      subitemSummary.tbtImpact += nextSubItem.tbtImpact;
-    }
-    if (!subitemSummary.blockingTime && !subitemSummary.transferSize) {
-      // Don't bother breaking down if there are no large resources.
-      return [];
-    }
-    // Only show the top N entries for brevity. If there is more than one remaining entry
-    // we'll replace the tail entries with single remainder entry.
-    items = items.slice(0, numSubItems);
-    const remainder = {
-      url: str_(i18n.UIStrings.otherResourcesLabel),
-      transferSize: stats.transferSize - subitemSummary.transferSize,
-      blockingTime: stats.blockingTime - subitemSummary.blockingTime,
-      tbtImpact: stats.tbtImpact - subitemSummary.tbtImpact,
-    };
-    if (remainder.transferSize > minTransferSize) {
-      items.push(remainder);
-    }
     return items;
   }
 
@@ -231,7 +186,7 @@ class ThirdPartySummary extends Audit {
           entity: entity.name,
           subItems: {
             type: /** @type {const} */ ('subitems'),
-            items: ThirdPartySummary.makeSubItems(entity, summaries, stats),
+            items: ThirdPartySummary.makeSubItems(entity, summaries),
           },
         };
       })

package/core/computed/entity-classification.js

@@ -59,7 +59,7 @@ class EntityClassification {
     // Make up an entity only for valid http/https URLs.
     if (!parsedUrl.protocol.startsWith('http')) return;
 
-    const rootDomain = Util.getRootDomain(url);
+    const rootDomain = UrlUtils.getRootDomain(url);
     if (!rootDomain) return;
     if (entityCache.has(rootDomain)) return entityCache.get(rootDomain);
 

package/core/computed/metrics/cumulative-layout-shift.d.ts

@@ -11,6 +11,7 @@ declare const CumulativeLayoutShiftComputed: typeof CumulativeLayoutShift & {
     }>) => Promise<{
         cumulativeLayoutShift: number;
         cumulativeLayoutShiftMainFrame: number;
+        impactByNodeId: Map<number, number>;
     }>;
 };
 declare class CumulativeLayoutShift {
@@ -23,6 +24,16 @@ declare class CumulativeLayoutShift {
      * @return {Array<LayoutShiftEvent>}
      */
     static getLayoutShiftEvents(processedTrace: LH.Artifacts.ProcessedTrace): Array<LayoutShiftEvent>;
+    /**
+     * Each layout shift event has a 'score' which is the amount added to the CLS as a result of the given shift(s).
+     * We calculate the score per element by taking the 'score' of each layout shift event and
+     * distributing it between all the nodes that were shifted, proportianal to the impact region of
+     * each shifted element.
+     *
+     * @param {LayoutShiftEvent[]} layoutShiftEvents
+     * @return {Map<number, number>}
+     */
+    static getImpactByNodeId(layoutShiftEvents: LayoutShiftEvent[]): Map<number, number>;
     /**
      * Calculates cumulative layout shifts per cluster (session) of LayoutShift
      * events -- where a new cluster is created when there's a gap of more than
@@ -35,11 +46,12 @@ declare class CumulativeLayoutShift {
     /**
      * @param {LH.Trace} trace
      * @param {LH.Artifacts.ComputedContext} context
-     * @return {Promise<{cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number}>}
+     * @return {Promise<{cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number, impactByNodeId: Map<number, number>}>}
      */
     static compute_(trace: LH.Trace, context: LH.Artifacts.ComputedContext): Promise<{
         cumulativeLayoutShift: number;
         cumulativeLayoutShiftMainFrame: number;
+        impactByNodeId: Map<number, number>;
     }>;
 }
 import { ProcessedTrace } from '../processed-trace.js';

package/core/computed/metrics/cumulative-layout-shift.js

@@ -6,6 +6,7 @@
 
 import {makeComputedArtifact} from '../computed-artifact.js';
 import {ProcessedTrace} from '../processed-trace.js';
+import * as RectHelpers from '../../lib/rect-helpers.js';
 
 /** @typedef {{ts: number, isMainFrame: boolean, weightedScore: number, impactedNodes?: LH.Artifacts.TraceImpactedNode[]}} LayoutShiftEvent */
 
@@ -72,6 +73,49 @@ class CumulativeLayoutShift {
     return layoutShiftEvents;
   }
 
+  /**
+   * Each layout shift event has a 'score' which is the amount added to the CLS as a result of the given shift(s).
+   * We calculate the score per element by taking the 'score' of each layout shift event and
+   * distributing it between all the nodes that were shifted, proportianal to the impact region of
+   * each shifted element.
+   *
+   * @param {LayoutShiftEvent[]} layoutShiftEvents
+   * @return {Map<number, number>}
+   */
+  static getImpactByNodeId(layoutShiftEvents) {
+    /** @type {Map<number, number>} */
+    const impactByNodeId = new Map();
+
+    for (const event of layoutShiftEvents) {
+      if (!event.impactedNodes) continue;
+
+      let totalAreaOfImpact = 0;
+      /** @type {Map<number, number>} */
+      const pixelsMovedPerNode = new Map();
+
+      for (const node of event.impactedNodes) {
+        if (!node.node_id || !node.old_rect || !node.new_rect) continue;
+
+        const oldRect = RectHelpers.traceRectToLHRect(node.old_rect);
+        const newRect = RectHelpers.traceRectToLHRect(node.new_rect);
+        const areaOfImpact = RectHelpers.getRectArea(oldRect) +
+          RectHelpers.getRectArea(newRect) -
+          RectHelpers.getRectOverlapArea(oldRect, newRect);
+
+        pixelsMovedPerNode.set(node.node_id, areaOfImpact);
+        totalAreaOfImpact += areaOfImpact;
+      }
+
+      for (const [nodeId, pixelsMoved] of pixelsMovedPerNode.entries()) {
+        let clsContribution = impactByNodeId.get(nodeId) || 0;
+        clsContribution += (pixelsMoved / totalAreaOfImpact) * event.weightedScore;
+        impactByNodeId.set(nodeId, clsContribution);
+      }
+    }
+
+    return impactByNodeId;
+  }
+
   /**
    * Calculates cumulative layout shifts per cluster (session) of LayoutShift
    * events -- where a new cluster is created when there's a gap of more than
@@ -104,18 +148,20 @@ class CumulativeLayoutShift {
   /**
    * @param {LH.Trace} trace
    * @param {LH.Artifacts.ComputedContext} context
-   * @return {Promise<{cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number}>}
+   * @return {Promise<{cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number, impactByNodeId: Map<number, number>}>}
    */
   static async compute_(trace, context) {
     const processedTrace = await ProcessedTrace.request(trace, context);
 
     const allFrameShiftEvents =
         CumulativeLayoutShift.getLayoutShiftEvents(processedTrace);
+    const impactByNodeId = CumulativeLayoutShift.getImpactByNodeId(allFrameShiftEvents);
     const mainFrameShiftEvents = allFrameShiftEvents.filter(e => e.isMainFrame);
 
     return {
       cumulativeLayoutShift: CumulativeLayoutShift.calculate(allFrameShiftEvents),
       cumulativeLayoutShiftMainFrame: CumulativeLayoutShift.calculate(mainFrameShiftEvents),
+      impactByNodeId,
     };
   }
 }

package/core/computed/metrics/lantern-first-contentful-paint.d.ts

@@ -11,6 +11,16 @@ declare const LanternFirstContentfulPaintComputed: typeof LanternFirstContentful
 /** @typedef {import('../../lib/dependency-graph/cpu-node').CPUNode} CPUNode */
 /** @typedef {import('../../lib/dependency-graph/network-node').NetworkNode} NetworkNode */
 declare class LanternFirstContentfulPaint extends LanternMetric {
+    /**
+     * @typedef FirstPaintBasedGraphOpts
+     * @property {number} cutoffTimestamp The timestamp used to filter out tasks that occured after
+     *    our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+     * @property {function(NetworkNode):boolean} treatNodeAsRenderBlocking The function that determines
+     *    which resources should be considered *possibly* render-blocking.
+     * @property {(function(CPUNode):boolean)=} additionalCpuNodesToTreatAsRenderBlocking The function that
+     *    determines which CPU nodes should also be included in our blocking node IDs set,
+     *    beyond what getRenderBlockingNodeData() already includes.
+     */
     /**
      * This function computes the set of URLs that *appeared* to be render-blocking based on our filter,
      * *but definitely were not* render-blocking based on the timing of their EvaluateScript task.
@@ -18,31 +28,55 @@ declare class LanternFirstContentfulPaint extends LanternMetric {
      * given timestamp.
      *
      * @param {Node} graph
-     * @param {number} filterTimestamp The timestamp used to filter out tasks that occured after our
-     *    paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
-     * @param {function(NetworkNode):boolean} blockingScriptFilter The function that determines which scripts
-     *    should be considered *possibly* render-blocking.
-     * @param {(function(CPUNode):boolean)=} extraBlockingCpuNodesToIncludeFilter The function that determines which CPU nodes
-     *    should also be included in our blocking node IDs set.
-     * @return {{definitelyNotRenderBlockingScriptUrls: Set<string>, blockingCpuNodeIds: Set<string>}}
+     * @param {FirstPaintBasedGraphOpts} opts
+     * @return {{definitelyNotRenderBlockingScriptUrls: Set<string>, renderBlockingCpuNodeIds: Set<string>}}
      */
-    static getBlockingNodeData(graph: Node, filterTimestamp: number, blockingScriptFilter: (arg0: NetworkNode) => boolean, extraBlockingCpuNodesToIncludeFilter?: ((arg0: CPUNode) => boolean) | undefined): {
+    static getRenderBlockingNodeData(graph: Node, { cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking }: {
+        /**
+         * The timestamp used to filter out tasks that occured after
+         * our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+         */
+        cutoffTimestamp: number;
+        /**
+         * The function that determines
+         * which resources should be considered *possibly* render-blocking.
+         */
+        treatNodeAsRenderBlocking: (arg0: NetworkNode) => boolean;
+        /**
+         * The function that
+         * determines which CPU nodes should also be included in our blocking node IDs set,
+         * beyond what getRenderBlockingNodeData() already includes.
+         */
+        additionalCpuNodesToTreatAsRenderBlocking?: ((arg0: CPUNode) => boolean) | undefined;
+    }): {
         definitelyNotRenderBlockingScriptUrls: Set<string>;
-        blockingCpuNodeIds: Set<string>;
+        renderBlockingCpuNodeIds: Set<string>;
     };
     /**
      * This function computes the graph required for the first paint of interest.
      *
      * @param {Node} dependencyGraph
-     * @param {number} paintTs The timestamp used to filter out tasks that occured after our
-     *    paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
-     * @param {function(NetworkNode):boolean} blockingResourcesFilter The function that determines which resources
-     *    should be considered *possibly* render-blocking.
-     * @param {(function(CPUNode):boolean)=} extraBlockingCpuNodesToIncludeFilter The function that determines which CPU nodes
-     *    should also be included in our blocking node IDs set.
+     * @param {FirstPaintBasedGraphOpts} opts
      * @return {Node}
      */
-    static getFirstPaintBasedGraph(dependencyGraph: Node, paintTs: number, blockingResourcesFilter: (arg0: NetworkNode) => boolean, extraBlockingCpuNodesToIncludeFilter?: ((arg0: CPUNode) => boolean) | undefined): Node;
+    static getFirstPaintBasedGraph(dependencyGraph: Node, { cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking }: {
+        /**
+         * The timestamp used to filter out tasks that occured after
+         * our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+         */
+        cutoffTimestamp: number;
+        /**
+         * The function that determines
+         * which resources should be considered *possibly* render-blocking.
+         */
+        treatNodeAsRenderBlocking: (arg0: NetworkNode) => boolean;
+        /**
+         * The function that
+         * determines which CPU nodes should also be included in our blocking node IDs set,
+         * beyond what getRenderBlockingNodeData() already includes.
+         */
+        additionalCpuNodesToTreatAsRenderBlocking?: ((arg0: CPUNode) => boolean) | undefined;
+    }): Node;
 }
 import { LanternMetric } from './lantern-metric.js';
 //# sourceMappingURL=lantern-first-contentful-paint.d.ts.map