lighthouse 11.4.0 → 11.5.0

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

@@ -7,8 +7,10 @@
 import {makeComputedArtifact} from '../computed-artifact.js';
 import {ProcessedTrace} from '../processed-trace.js';
 import * as RectHelpers from '../../lib/rect-helpers.js';
+import * as TraceEngine from '../../lib/trace-engine.js';
+import {Sentry} from '../../lib/sentry.js';
 
-/** @typedef {{ts: number, isMainFrame: boolean, weightedScore: number, impactedNodes?: LH.Artifacts.TraceImpactedNode[]}} LayoutShiftEvent */
+/** @typedef {{ts: number, isMainFrame: boolean, weightedScore: number, impactedNodes?: LH.Artifacts.TraceImpactedNode[], event: LH.TraceEvent}} LayoutShiftEvent */
 
 const RECENT_INPUT_WINDOW = 500;
 
@@ -67,6 +69,7 @@ class CumulativeLayoutShift {
         isMainFrame: event.args.data.is_main_frame,
         weightedScore: event.args.data.weighted_score_delta,
         impactedNodes: event.args.data.impacted_nodes,
+        event,
       });
     }
 
@@ -145,10 +148,29 @@ class CumulativeLayoutShift {
     return maxScore;
   }
 
+  /**
+   * @param {LayoutShiftEvent[]} allFrameShiftEvents
+   * @param {LayoutShiftEvent[]} mainFrameShiftEvents
+   */
+  static async computeWithSharedTraceEngine(allFrameShiftEvents, mainFrameShiftEvents) {
+    /** @param {LH.TraceEvent[]} events */
+    const run = async (events) => {
+      const processor = new TraceEngine.TraceProcessor({
+        LayoutShifts: TraceEngine.TraceHandlers.LayoutShifts,
+        Screenshots: TraceEngine.TraceHandlers.Screenshots,
+      });
+      await processor.parse(events);
+      return processor.data.LayoutShifts.sessionMaxScore;
+    };
+    const cumulativeLayoutShift = await run(allFrameShiftEvents.map(e => e.event));
+    const cumulativeLayoutShiftMainFrame = await run(mainFrameShiftEvents.map(e => e.event));
+    return {cumulativeLayoutShift, cumulativeLayoutShiftMainFrame};
+  }
+
   /**
    * @param {LH.Trace} trace
    * @param {LH.Artifacts.ComputedContext} context
-   * @return {Promise<{cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number, impactByNodeId: Map<number, number>}>}
+   * @return {Promise<{cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number, impactByNodeId: Map<number, number>, newEngineResult?: {cumulativeLayoutShift: number, cumulativeLayoutShiftMainFrame: number}, newEngineResultDiffered: boolean}>}
    */
   static async compute_(trace, context) {
     const processedTrace = await ProcessedTrace.request(trace, context);
@@ -157,11 +179,59 @@ class CumulativeLayoutShift {
         CumulativeLayoutShift.getLayoutShiftEvents(processedTrace);
     const impactByNodeId = CumulativeLayoutShift.getImpactByNodeId(allFrameShiftEvents);
     const mainFrameShiftEvents = allFrameShiftEvents.filter(e => e.isMainFrame);
+    const cumulativeLayoutShift = CumulativeLayoutShift.calculate(allFrameShiftEvents);
+    const cumulativeLayoutShiftMainFrame = CumulativeLayoutShift.calculate(mainFrameShiftEvents);
+
+    // Run with the new trace engine, and only throw an error if we are running our unit tests.
+    // Otherwise, simply report any differences or errors to Sentry.
+    // TODO: TraceEngine always drops `had_recent_input` events, but Lighthouse is more lenient.
+    //       See comment in `getLayoutShiftEvents`. We need to upstream this.
+    let newEngineResult;
+    let newEngineResultDiffered = false;
+    let tryNewTraceEngine = true;
+    if (allFrameShiftEvents.some(e => e.event.args.data?.had_recent_input)) {
+      tryNewTraceEngine = false;
+    }
+    if (tryNewTraceEngine) {
+      try {
+        newEngineResult =
+          await this.computeWithSharedTraceEngine(allFrameShiftEvents, mainFrameShiftEvents);
+        newEngineResultDiffered =
+          newEngineResult.cumulativeLayoutShift !== cumulativeLayoutShift ||
+          newEngineResult.cumulativeLayoutShiftMainFrame !== cumulativeLayoutShiftMainFrame;
+        if (newEngineResultDiffered) {
+          newEngineResultDiffered = true;
+          const expected = JSON.stringify({cumulativeLayoutShift, cumulativeLayoutShiftMainFrame});
+          const got = JSON.stringify(newEngineResult);
+          throw new Error(`new trace engine differed. expected: ${expected}, got: ${got}`);
+        }
+      } catch (err) {
+        console.error(err);
+        newEngineResultDiffered = true;
+
+        const error = new Error('Error when using new trace engine', {cause: err});
+        // @ts-expect-error Check for running from tests.
+        if (global.expect) {
+          throw error;
+        } else {
+          Sentry.captureException(error, {
+            tags: {computed: 'new-trace-engine'},
+            level: 'error',
+            extra: {
+              // Not sure if Sentry handles `cause`, so just in case add the info in a second place.
+              errorMsg: err.toString(),
+            },
+          });
+        }
+      }
+    }
 
     return {
-      cumulativeLayoutShift: CumulativeLayoutShift.calculate(allFrameShiftEvents),
-      cumulativeLayoutShiftMainFrame: CumulativeLayoutShift.calculate(mainFrameShiftEvents),
+      cumulativeLayoutShift,
+      cumulativeLayoutShiftMainFrame,
       impactByNodeId,
+      newEngineResult,
+      newEngineResultDiffered,
     };
   }
 }

package/core/computed/trace-engine-result.d.ts

@@ -0,0 +1,40 @@
+export { TraceEngineResultComputed as TraceEngineResult };
+declare const TraceEngineResultComputed: typeof TraceEngineResult & {
+    request: (dependencies: {
+        trace: LH.Trace;
+    }, context: import("../../types/utility-types.js").default.ImmutableObject<{
+        computedCache: Map<string, import("../lib/arbitrary-equality-map.js").ArbitraryEqualityMap>;
+    }>) => Promise<{
+        LayoutShifts: {
+            clusters: {
+                events: import("../../types/trace-engine.js").LayoutShiftTraceEvent[];
+            }[];
+            sessionMaxScore: number;
+        };
+    }>;
+};
+/**
+ * @fileoverview Processes trace with the shared trace engine.
+ */
+declare class TraceEngineResult {
+    /**
+     * @param {LH.TraceEvent[]} traceEvents
+     */
+    static runTraceEngine(traceEvents: LH.TraceEvent[]): Promise<{
+        LayoutShifts: {
+            clusters: {
+                events: import("../../types/trace-engine.js").LayoutShiftTraceEvent[];
+            }[];
+            sessionMaxScore: number;
+        };
+    }>;
+    /**
+     * @param {{trace: LH.Trace}} data
+     * @param {LH.Artifacts.ComputedContext} context
+     * @return {Promise<LH.Artifacts.TraceEngineResult>}
+     */
+    static compute_(data: {
+        trace: LH.Trace;
+    }, context: LH.Artifacts.ComputedContext): Promise<LH.Artifacts.TraceEngineResult>;
+}
+//# sourceMappingURL=trace-engine-result.d.ts.map

package/core/computed/trace-engine-result.js

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as TraceEngine from '../lib/trace-engine.js';
+import {makeComputedArtifact} from './computed-artifact.js';
+import {CumulativeLayoutShift} from './metrics/cumulative-layout-shift.js';
+import {ProcessedTrace} from './processed-trace.js';
+
+/**
+ * @fileoverview Processes trace with the shared trace engine.
+ */
+class TraceEngineResult {
+  /**
+   * @param {LH.TraceEvent[]} traceEvents
+   */
+  static async runTraceEngine(traceEvents) {
+    const engine = new TraceEngine.TraceProcessor({
+      AuctionWorklets: TraceEngine.TraceHandlers.AuctionWorklets,
+      Initiators: TraceEngine.TraceHandlers.Initiators,
+      LayoutShifts: TraceEngine.TraceHandlers.LayoutShifts,
+      NetworkRequests: TraceEngine.TraceHandlers.NetworkRequests,
+      Renderer: TraceEngine.TraceHandlers.Renderer,
+      Samples: TraceEngine.TraceHandlers.Samples,
+      Screenshots: TraceEngine.TraceHandlers.Screenshots,
+    });
+    await engine.parse(traceEvents);
+    return engine.data;
+  }
+
+  /**
+   * @param {{trace: LH.Trace}} data
+   * @param {LH.Artifacts.ComputedContext} context
+   * @return {Promise<LH.Artifacts.TraceEngineResult>}
+   */
+  static async compute_(data, context) {
+    // In CumulativeLayoutShift.getLayoutShiftEvents we handle a bug in Chrome layout shift
+    // trace events re: changing the viewport emulation resulting in incorrectly set `had_recent_input`.
+    // Below, the same logic is applied to set those problem events' `had_recent_input` to false, so that
+    // the trace engine will count them.
+    // The trace events are copied-on-write, so the original trace remains unmodified.
+    const processedTrace = await ProcessedTrace.request(data.trace, context);
+    const layoutShiftEvents = new Set(
+      CumulativeLayoutShift.getLayoutShiftEvents(processedTrace).map(e => e.event));
+
+    // Avoid modifying the input array.
+    const traceEvents = [...data.trace.traceEvents];
+    for (let i = 0; i < traceEvents.length; i++) {
+      let event = traceEvents[i];
+      if (event.name !== 'LayoutShift') continue;
+      if (!event.args.data) continue;
+
+      const isConsidered = layoutShiftEvents.has(event);
+      if (event.args.data.had_recent_input && isConsidered) {
+        event = JSON.parse(JSON.stringify(event));
+        // @ts-expect-error impossible for data to be missing.
+        event.args.data.had_recent_input = false;
+        traceEvents[i] = event;
+      }
+    }
+
+    return TraceEngineResult.runTraceEngine(traceEvents);
+  }
+}
+
+const TraceEngineResultComputed = makeComputedArtifact(TraceEngineResult, ['trace']);
+export {TraceEngineResultComputed as TraceEngineResult};

package/core/computed/unused-css.js

@@ -7,7 +7,7 @@
 import {makeComputedArtifact} from './computed-artifact.js';
 import {NetworkRecords} from './network-records.js';
 import {Util} from '../../shared/util.js';
-import {estimateTransferSize} from '../lib/script-helpers.js';
+import {estimateCompressedContentSize} from '../lib/script-helpers.js';
 
 const PREVIEW_LENGTH = 100;
 
@@ -70,15 +70,15 @@ class UnusedCSS {
       usedUncompressedBytes += usedRule.endOffset - usedRule.startOffset;
     }
 
-    const totalTransferredBytes = estimateTransferSize(
+    const compressedSize = estimateCompressedContentSize(
         stylesheetInfo.networkRecord, totalUncompressedBytes, 'Stylesheet');
     const percentUnused = (totalUncompressedBytes - usedUncompressedBytes) / totalUncompressedBytes;
-    const wastedBytes = Math.round(percentUnused * totalTransferredBytes);
+    const wastedBytes = Math.round(percentUnused * compressedSize);
 
     return {
       wastedBytes,
       wastedPercent: percentUnused * 100,
-      totalBytes: totalTransferredBytes,
+      totalBytes: compressedSize,
     };
   }
 

package/core/computed/viewport-meta.d.ts

@@ -12,6 +12,10 @@ export type ViewportMetaResult = {
      * Warnings if the parser encountered invalid content in the viewport tag.
      */
     parserWarnings: Array<string>;
+    /**
+     * The `content` attribute value, if a viewport was defined.
+     */
+    rawContentString: string | undefined;
 };
 declare const ViewportMetaComputed: typeof ViewportMeta & {
     request: (dependencies: {

package/core/computed/viewport-meta.js

@@ -21,11 +21,13 @@ class ViewportMeta {
         hasViewportTag: false,
         isMobileOptimized: false,
         parserWarnings: [],
+        rawContentString: undefined,
       };
     }
 
     const warnings = [];
-    const parsedProps = Parser.parseMetaViewPortContent(viewportMeta.content || '');
+    const rawContentString = viewportMeta.content || '';
+    const parsedProps = Parser.parseMetaViewPortContent(rawContentString);
 
     if (Object.keys(parsedProps.unknownProperties).length) {
       warnings.push(`Invalid properties found: ${JSON.stringify(parsedProps.unknownProperties)}`);
@@ -42,6 +44,7 @@ class ViewportMeta {
         hasViewportTag: true,
         isMobileOptimized: false,
         parserWarnings: warnings,
+        rawContentString,
       };
     }
 
@@ -51,6 +54,7 @@ class ViewportMeta {
       hasViewportTag: true,
       isMobileOptimized,
       parserWarnings: warnings,
+      rawContentString,
     };
   }
 }
@@ -63,4 +67,5 @@ export {ViewportMetaComputed as ViewportMeta};
  * @property {boolean} hasViewportTag Whether the page has any viewport tag.
  * @property {boolean} isMobileOptimized Whether the viewport tag is optimized for mobile screens.
  * @property {Array<string>} parserWarnings Warnings if the parser encountered invalid content in the viewport tag.
+ * @property {string|undefined} rawContentString The `content` attribute value, if a viewport was defined.
  */

package/core/config/default-config.js

@@ -129,6 +129,7 @@ const defaultConfig = {
     // Artifacts which can be depended on come first.
     {id: 'DevtoolsLog', gatherer: 'devtools-log'},
     {id: 'Trace', gatherer: 'trace'},
+    {id: 'RootCauses', gatherer: 'root-causes'},
 
     {id: 'Accessibility', gatherer: 'accessibility'},
     {id: 'AnchorElements', gatherer: 'anchor-elements'},
@@ -222,6 +223,7 @@ const defaultConfig = {
     'largest-contentful-paint-element',
     'lcp-lazy-loaded',
     'layout-shift-elements',
+    'layout-shifts',
     'long-tasks',
     'no-unload-listeners',
     'non-composited-animations',
@@ -476,7 +478,7 @@ const defaultConfig = {
         {id: 'third-party-facades', weight: 0},
         {id: 'largest-contentful-paint-element', weight: 0},
         {id: 'lcp-lazy-loaded', weight: 0},
-        {id: 'layout-shift-elements', weight: 0},
+        {id: 'layout-shifts', weight: 0},
         {id: 'uses-passive-event-listeners', weight: 0},
         {id: 'no-document-write', weight: 0},
         {id: 'long-tasks', weight: 0},
@@ -502,6 +504,7 @@ const defaultConfig = {
         {id: 'final-screenshot', weight: 0, group: 'hidden'},
         {id: 'script-treemap-data', weight: 0, group: 'hidden'},
         {id: 'resource-summary', weight: 0, group: 'hidden'},
+        {id: 'layout-shift-elements', weight: 0, group: 'hidden'},
       ],
     },
     'accessibility': {

package/core/config/metrics-to-audits.js

@@ -43,6 +43,7 @@ const tbtRelevantAudits = [
 
 const clsRelevantAudits = [
   'layout-shift-elements',
+  'layout-shifts',
   'non-composited-animations',
   'unsized-images',
   // 'preload-fonts', // actually in BP, rather than perf

package/core/gather/driver/target-manager.js

@@ -125,9 +125,11 @@ class TargetManager extends ProtocolEventEmitter {
   async _onSessionAttached(cdpSession) {
     const newSession = new ProtocolSession(cdpSession);
 
+    let targetType;
+
     try {
       const {targetInfo} = await newSession.sendCommand('Target.getTargetInfo');
-      const targetType = targetInfo.type;
+      targetType = targetInfo.type;
 
       // TODO: should detach from target in this case?
       // See pptr: https://github.com/puppeteer/puppeteer/blob/733cbecf487c71483bee8350e37030edb24bc021/src/common/Page.ts#L495-L526
@@ -168,6 +170,13 @@ class TargetManager extends ProtocolEventEmitter {
       // Sometimes targets can be closed before we even have a chance to listen to their network activity.
       if (/Target closed/.test(err.message)) return;
 
+      // Worker targets can be a bit fickle and we only enable them for diagnostic purposes.
+      // We shouldn't throw a fatal error if there were issues attaching to them.
+      if (targetType === 'worker') {
+        log.warn('target-manager', `Issue attaching to worker target: ${err}`);
+        return;
+      }
+
       throw err;
     } finally {
       // Resume the target if it was paused, but if it's unnecessary, we don't care about the error.

package/core/gather/driver/wait-for-condition.js

@@ -540,7 +540,7 @@ function waitForUserToContinue(driver) {
   }
   /* c8 ignore stop */
 
-  driver.defaultSession.setNextProtocolTimeout(2 ** 31 - 1);
+  driver.defaultSession.setNextProtocolTimeout(Infinity);
   return driver.executionContext.evaluate(createInPagePromise, {args: []});
 }
 

package/core/gather/gatherers/dobetterweb/response-compression.js

@@ -23,12 +23,6 @@ import {fetchResponseBodyFromCache} from '../../driver/network.js';
 import {NetworkRecords} from '../../../computed/network-records.js';
 
 const CHROME_EXTENSION_PROTOCOL = 'chrome-extension:';
-const compressionHeaders = [
-  'content-encoding',
-  'x-original-content-encoding',
-  'x-content-encoding-over-network',
-];
-const compressionTypes = ['gzip', 'br', 'deflate'];
 const binaryMimeTypes = ['image', 'audio', 'video'];
 /** @type {LH.Crdp.Network.ResourceType[]} */
 const textResourceTypes = [
@@ -71,12 +65,7 @@ class ResponseCompression extends BaseGatherer {
         return;
       }
 
-      const isContentEncoded = (record.responseHeaders || []).find(header =>
-        compressionHeaders.includes(header.name.toLowerCase()) &&
-        compressionTypes.includes(header.value)
-      );
-
-      if (!isContentEncoded) {
+      if (!NetworkRequest.isContentEncoded(record)) {
         unoptimizedResponses.push({
           requestId: record.requestId,
           url: record.url,

package/core/gather/gatherers/root-causes.d.ts

@@ -0,0 +1,20 @@
+export default RootCauses;
+declare class RootCauses extends BaseGatherer {
+    static symbol: symbol;
+    /**
+     * @param {LH.Gatherer.Driver} driver
+     * @param {LH.Artifacts.TraceEngineResult} traceEngineResult
+     * @return {Promise<LH.Artifacts.TraceEngineRootCauses>}
+     */
+    static runRootCauseAnalysis(driver: LH.Gatherer.Driver, traceEngineResult: LH.Artifacts.TraceEngineResult): Promise<LH.Artifacts.TraceEngineRootCauses>;
+    /** @type {LH.Gatherer.GathererMeta<'Trace'>} */
+    meta: LH.Gatherer.GathererMeta<'Trace'>;
+    /**
+     * @param {LH.Gatherer.Context<'Trace'>} context
+     * @return {Promise<LH.Artifacts.TraceEngineRootCauses>}
+     */
+    getArtifact(context: LH.Gatherer.Context<'Trace'>): Promise<LH.Artifacts.TraceEngineRootCauses>;
+}
+import BaseGatherer from '../base-gatherer.js';
+import { TraceEngineResult } from '../../computed/trace-engine-result.js';
+//# sourceMappingURL=root-causes.d.ts.map

package/core/gather/gatherers/root-causes.js

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import BaseGatherer from '../base-gatherer.js';
+import Trace from './trace.js';
+import * as TraceEngine from '../../lib/trace-engine.js';
+import {TraceEngineResult} from '../../computed/trace-engine-result.js';
+
+class RootCauses extends BaseGatherer {
+  static symbol = Symbol('RootCauses');
+
+  /** @type {LH.Gatherer.GathererMeta<'Trace'>} */
+  meta = {
+    symbol: RootCauses.symbol,
+    supportedModes: ['timespan', 'navigation'],
+    dependencies: {Trace: Trace.symbol},
+  };
+
+  /**
+   * @param {LH.Gatherer.Driver} driver
+   * @param {LH.Artifacts.TraceEngineResult} traceEngineResult
+   * @return {Promise<LH.Artifacts.TraceEngineRootCauses>}
+   */
+  static async runRootCauseAnalysis(driver, traceEngineResult) {
+    await driver.defaultSession.sendCommand('DOM.enable');
+    await driver.defaultSession.sendCommand('CSS.enable');
+
+    // DOM.getDocument is necessary for pushNodesByBackendIdsToFrontend to properly retrieve
+    // nodeIds if the DOM domain was enabled before this gatherer, invoke it to be safe.
+    await driver.defaultSession.sendCommand('DOM.getDocument', {depth: -1, pierce: true});
+
+    const protocolInterface = {
+      /** @param {string} url */
+      // eslint-disable-next-line no-unused-vars
+      getInitiatorForRequest(url) {
+        return null;
+      },
+      /** @param {number[]} backendNodeIds */
+      async pushNodesByBackendIdsToFrontend(backendNodeIds) {
+        const response = await driver.defaultSession.sendCommand(
+          'DOM.pushNodesByBackendIdsToFrontend', {backendNodeIds});
+        return response.nodeIds;
+      },
+      /** @param {number} nodeId */
+      async getNode(nodeId) {
+        try {
+          const response = await driver.defaultSession.sendCommand('DOM.describeNode', {nodeId});
+          // This always zero, so let's fix it here.
+          // https://bugs.chromium.org/p/chromium/issues/detail?id=1515175
+          response.node.nodeId = nodeId;
+          return response.node;
+        } catch (err) {
+          if (err.message.includes('Could not find node with given id')) {
+            // TODO: when injecting an iframe, the engine gets the node of that frame's document element.
+            // But we don't have a way to access that frame. We just have our default session.
+            // Ex:
+            // node cli http://localhost:10503/shift-attribution.html --quiet --only-audits layout-shifts
+            // To fix we must:
+            // - Change trace engine `getNode` protocol interface to also give frame id
+            // - Expand our driver.targetManager to know how to talk to a session connected to a specific frame
+            // When this is fixed, remove this try/catch.
+            // Note: this could be buggy by giving the wrong node detail if a node id meant for a non-main frame
+            // happens to match one from the main frame ... which is pretty likely...
+            return null;
+          }
+          throw err;
+        }
+      },
+      /** @param {number} nodeId */
+      async getComputedStyleForNode(nodeId) {
+        try {
+          const response = await driver.defaultSession.sendCommand(
+            'CSS.getComputedStyleForNode', {nodeId});
+          return response.computedStyle;
+        } catch {
+          return [];
+        }
+      },
+      /** @param {number} nodeId */
+      async getMatchedStylesForNode(nodeId) {
+        try {
+          const response = await driver.defaultSession.sendCommand(
+            'CSS.getMatchedStylesForNode', {nodeId});
+          return response;
+        } catch {
+          return [];
+        }
+      },
+      /** @param {string} url */
+      // eslint-disable-next-line no-unused-vars
+      async fontFaceForSource(url) {
+        return null;
+      },
+    };
+
+    /** @type {LH.Artifacts.TraceEngineRootCauses} */
+    const rootCauses = {
+      layoutShifts: {},
+    };
+    const rootCausesEngine = new TraceEngine.RootCauses(protocolInterface);
+    const layoutShiftEvents = traceEngineResult.LayoutShifts.clusters.flatMap(c => c.events);
+    for (const event of layoutShiftEvents) {
+      const r = await rootCausesEngine.layoutShifts.rootCausesForEvent(traceEngineResult, event);
+      for (const cause of r.fontChanges) {
+        // TODO: why isn't trace engine unwrapping this promise ...
+        cause.fontFace = await cause.fontFace;
+      }
+      rootCauses.layoutShifts[layoutShiftEvents.indexOf(event)] = r;
+    }
+
+    // Yeah this gatherer enabled it, and so you'd think it should disable it too...
+    // ...but we don't give gatherers their own session so this stomps on others.
+    // await driver.defaultSession.sendCommand('DOM.disable');
+    await driver.defaultSession.sendCommand('CSS.disable');
+
+    return rootCauses;
+  }
+
+  /**
+   * @param {LH.Gatherer.Context<'Trace'>} context
+   * @return {Promise<LH.Artifacts.TraceEngineRootCauses>}
+   */
+  async getArtifact(context) {
+    const trace = context.dependencies.Trace;
+    const traceEngineResult = await TraceEngineResult.request({trace}, context);
+    return RootCauses.runRootCauseAnalysis(context.driver, traceEngineResult);
+  }
+}
+
+export default RootCauses;

package/core/gather/gatherers/trace-elements.d.ts

@@ -10,13 +10,38 @@ export type TraceElementData = {
 };
 declare class TraceElements extends BaseGatherer {
     /**
-     * This function finds the top (up to 15) elements that contribute to the CLS score of the page.
+     * This function finds the top (up to 15) elements that shift on the page.
      *
      * @param {LH.Trace} trace
      * @param {LH.Gatherer.Context} context
-     * @return {Promise<Array<TraceElementData>>}
+     * @return {Promise<Array<{nodeId: number}>>}
      */
-    static getTopLayoutShiftElements(trace: LH.Trace, context: LH.Gatherer.Context): Promise<Array<TraceElementData>>;
+    static getTopLayoutShiftElements(trace: LH.Trace, context: LH.Gatherer.Context): Promise<Array<{
+        nodeId: number;
+    }>>;
+    /**
+     * We want to a single representative node to represent the shift, so let's pick
+     * the one with the largest impact (size x distance moved).
+     *
+     * @param {LH.Artifacts.TraceImpactedNode[]} impactedNodes
+     * @param {Map<number, number>} impactByNodeId
+     * @return {number|undefined}
+     */
+    static getBiggestImpactNodeForShiftEvent(impactedNodes: LH.Artifacts.TraceImpactedNode[], impactByNodeId: Map<number, number>): number | undefined;
+    /**
+     * This function finds the top (up to 15) layout shifts on the page, and returns
+     * the id of the largest impacted node of each shift, along with any related nodes
+     * that may have caused the shift.
+     *
+     * @param {LH.Trace} trace
+     * @param {LH.Artifacts.TraceEngineResult} traceEngineResult
+     * @param {LH.Artifacts.TraceEngineRootCauses} rootCauses
+     * @param {LH.Gatherer.Context} context
+     * @return {Promise<Array<{nodeId: number}>>}
+     */
+    static getTopLayoutShifts(trace: LH.Trace, traceEngineResult: LH.Artifacts.TraceEngineResult, rootCauses: LH.Artifacts.TraceEngineRootCauses, context: LH.Gatherer.Context): Promise<Array<{
+        nodeId: number;
+    }>>;
     /**
      * @param {LH.Trace} trace
      * @param {LH.Gatherer.Context} context
@@ -32,8 +57,8 @@ declare class TraceElements extends BaseGatherer {
         nodeId: number;
         type: string;
     } | undefined>;
-    /** @type {LH.Gatherer.GathererMeta<'Trace'>} */
-    meta: LH.Gatherer.GathererMeta<'Trace'>;
+    /** @type {LH.Gatherer.GathererMeta<'Trace'|'RootCauses'>} */
+    meta: LH.Gatherer.GathererMeta<'Trace' | 'RootCauses'>;
     /** @type {Map<string, string>} */
     animationIdToName: Map<string, string>;
     /** @param {LH.Crdp.Animation.AnimationStartedEvent} args */
@@ -53,11 +78,17 @@ declare class TraceElements extends BaseGatherer {
      */
     stopInstrumentation(context: LH.Gatherer.Context): Promise<void>;
     /**
-     * @param {LH.Gatherer.Context<'Trace'>} context
+     * @param {LH.Gatherer.ProtocolSession} session
+     * @param {number} backendNodeId
+     */
+    getNodeDetails(session: LH.Gatherer.ProtocolSession, backendNodeId: number): Promise<import("devtools-protocol").Protocol.Runtime.CallFunctionOnResponse | null>;
+    /**
+     * @param {LH.Gatherer.Context<'Trace'|'RootCauses'>} context
      * @return {Promise<LH.Artifacts.TraceElement[]>}
      */
-    getArtifact(context: LH.Gatherer.Context<'Trace'>): Promise<LH.Artifacts.TraceElement[]>;
+    getArtifact(context: LH.Gatherer.Context<'Trace' | 'RootCauses'>): Promise<LH.Artifacts.TraceElement[]>;
 }
 import BaseGatherer from '../base-gatherer.js';
 import Trace from './trace.js';
+import { TraceEngineResult } from '../../computed/trace-engine-result.js';
 //# sourceMappingURL=trace-elements.d.ts.map