lighthouse 12.3.0-dev.20250223 → 12.3.0-dev.20250225

package/core/audits/audit.js

@@ -478,6 +478,7 @@ class Audit {
 
       details: product.details,
       guidanceLevel: audit.meta.guidanceLevel,
+      replacesAudits: audit.meta.replacesAudits,
     };
   }
 

package/core/audits/insights/cls-culprits-insight.d.ts

@@ -1,5 +1,16 @@
 export default CLSCulpritsInsight;
+export type SubItem = {
+    extra?: LH.Audit.Details.NodeValue | LH.Audit.Details.UrlValue;
+    cause: LH.IcuMessage;
+};
 declare class CLSCulpritsInsight extends Audit {
+    /**
+     * @param {import('@paulirish/trace_engine/models/trace/insights/CLSCulprits.js').CLSCulpritsInsightModel} insight
+     * @param {import('../../lib/trace-engine.js').SaneSyntheticLayoutShift} event
+     * @param {LH.Artifacts.TraceElement[]} TraceElements
+     * @return {LH.Audit.Details.TableSubItems|undefined}
+     */
+    static getCulpritSubItems(insight: import("@paulirish/trace_engine/models/trace/insights/CLSCulprits.js").CLSCulpritsInsightModel, event: import("../../lib/trace-engine.js").SaneSyntheticLayoutShift, TraceElements: LH.Artifacts.TraceElement[]): LH.Audit.Details.TableSubItems | undefined;
     /**
      * @param {LH.Artifacts} artifacts
      * @param {LH.Audit.Context} context
@@ -7,5 +18,8 @@ declare class CLSCulpritsInsight extends Audit {
      */
     static audit(artifacts: LH.Artifacts, context: LH.Audit.Context): Promise<LH.Audit.Product>;
 }
+export namespace UIStrings {
+    let columnScore: string;
+}
 import { Audit } from '../audit.js';
 //# sourceMappingURL=cls-culprits-insight.d.ts.map

package/core/audits/insights/cls-culprits-insight.js

@@ -1,19 +1,32 @@
-/* eslint-disable no-unused-vars */ // TODO: remove once implemented.
-
 /**
  * @license
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import {UIStrings} from '@paulirish/trace_engine/models/trace/insights/CLSCulprits.js';
+import {UIStrings as InsightUIStrings} from '@paulirish/trace_engine/models/trace/insights/CLSCulprits.js';
 
 import {Audit} from '../audit.js';
 import * as i18n from '../../lib/i18n/i18n.js';
 import {adaptInsightToAuditProduct, makeNodeItemForNodeId} from './insight-audit.js';
+import TraceElements from '../../gather/gatherers/trace-elements.js';
+import {CumulativeLayoutShift} from '../../computed/metrics/cumulative-layout-shift.js';
+
+const MAX_LAYOUT_SHIFTS_PER_CLUSTER = 5;
+
+/** @typedef {{extra?: LH.Audit.Details.NodeValue | LH.Audit.Details.UrlValue, cause: LH.IcuMessage}} SubItem */
 
 // eslint-disable-next-line max-len
-const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/CLSCulprits.js', UIStrings);
+const insightStr_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/CLSCulprits.js', InsightUIStrings);
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /** Label for a column in a data table; entries in this column will be a number representing how large the layout shift was. */
+  columnScore: 'Layout shift score',
+};
+/* eslint-enable max-len */
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
 
 class CLSCulpritsInsight extends Audit {
   /**
@@ -22,31 +35,103 @@ class CLSCulpritsInsight extends Audit {
   static get meta() {
     return {
       id: 'cls-culprits-insight',
-      title: str_(UIStrings.title),
-      failureTitle: str_(UIStrings.title),
-      description: str_(UIStrings.description),
+      title: insightStr_(InsightUIStrings.title),
+      failureTitle: insightStr_(InsightUIStrings.title),
+      description: insightStr_(InsightUIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['layout-shifts', 'non-composited-animations', 'unsized-images'],
     };
   }
 
+  /**
+   * @param {import('@paulirish/trace_engine/models/trace/insights/CLSCulprits.js').CLSCulpritsInsightModel} insight
+   * @param {import('../../lib/trace-engine.js').SaneSyntheticLayoutShift} event
+   * @param {LH.Artifacts.TraceElement[]} TraceElements
+   * @return {LH.Audit.Details.TableSubItems|undefined}
+   */
+  static getCulpritSubItems(insight, event, TraceElements) {
+    const culprits = insight.shifts.get(event);
+    if (!culprits) {
+      return;
+    }
+
+    /** @type {SubItem[]} */
+    const subItems = [];
+    for (const backendNodeId of culprits.unsizedImages) {
+      subItems.push({
+        extra: makeNodeItemForNodeId(TraceElements, backendNodeId),
+        cause: insightStr_(InsightUIStrings.unsizedImages),
+      });
+    }
+    for (const request of culprits.fontRequests) {
+      const url = request.args.data.url;
+      subItems.push({
+        extra: {type: 'url', value: url},
+        cause: insightStr_(InsightUIStrings.fontRequest),
+      });
+    }
+    if (culprits.iframeIds.length) {
+      subItems.push({
+        cause: insightStr_(InsightUIStrings.injectedIframe),
+      });
+    }
+
+    if (subItems.length) {
+      return {type: 'subitems', items: subItems};
+    }
+  }
+
   /**
    * @param {LH.Artifacts} artifacts
    * @param {LH.Audit.Context} context
    * @return {Promise<LH.Audit.Product>}
    */
   static async audit(artifacts, context) {
-    // TODO: implement.
     return adaptInsightToAuditProduct(artifacts, context, 'CLSCulprits', (insight) => {
       /** @type {LH.Audit.Details.Table['headings']} */
       const headings = [
+        /* eslint-disable max-len */
+        {key: 'node', valueType: 'node', subItemsHeading: {key: 'extra'}, label: insightStr_(i18n.UIStrings.columnElement)},
+        {key: 'score', valueType: 'numeric', subItemsHeading: {key: 'cause', valueType: 'text'}, granularity: 0.001, label: str_(UIStrings.columnScore)},
+        /* eslint-enable max-len */
       ];
-      /** @type {LH.Audit.Details.Table['items']} */
-      const items = [
-      ];
-      return Audit.makeTableDetails(headings, items);
+
+      const tables = insight.clusters.map(cluster => {
+        const events =
+          /** @type {import('../../lib/trace-engine.js').SaneSyntheticLayoutShift[]} */ (
+            cluster.events.filter(e => !!e.args.data)
+          ).sort((a, b) => b.args.data.weighted_score_delta - a.args.data.weighted_score_delta)
+          .slice(0, MAX_LAYOUT_SHIFTS_PER_CLUSTER);
+        const impactByNodeId = CumulativeLayoutShift.getImpactByNodeId(events.map(e => ({
+          impactedNodes: e.args.data.impacted_nodes,
+          ts: e.ts,
+          isMainFrame: e.args.data.is_main_frame,
+          weightedScore: e.args.data.weighted_score_delta,
+          event: /** @type {any} */ (e),
+        })));
+
+        /** @type {LH.Audit.Details.Table['items']} */
+        const items = events.map(event => {
+          const biggestImpactNodeId = TraceElements.getBiggestImpactNodeForShiftEvent(
+            event.args.data.impacted_nodes || [], impactByNodeId, event);
+          return {
+            node: makeNodeItemForNodeId(artifacts.TraceElements, biggestImpactNodeId),
+            score: event.args.data?.weighted_score_delta,
+            subItems: this.getCulpritSubItems(insight, event, artifacts.TraceElements),
+          };
+        });
+        items.unshift({
+          node: {type: 'text', value: insightStr_(i18n.UIStrings.total)},
+          score: cluster.clusterCumulativeScore,
+        });
+        return Audit.makeTableDetails(headings, items);
+      });
+
+      return Audit.makeListDetails(tables);
     });
   }
 }
 
 export default CLSCulpritsInsight;
+export {UIStrings};

package/core/audits/insights/document-latency-insight.js

@@ -25,6 +25,7 @@ class DocumentLatencyInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['redirects', 'server-response-time', 'uses-text-compression'],
     };
   }
 

package/core/audits/insights/dom-size-insight.js

@@ -25,6 +25,7 @@ class DOMSizeInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['dom-size'],
     };
   }
 

package/core/audits/insights/font-display-insight.js

@@ -27,6 +27,7 @@ class FontDisplayInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['font-display'],
     };
   }
 

package/core/audits/insights/image-delivery-insight.js

@@ -25,6 +25,12 @@ class ImageDeliveryInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: [
+        'modern-image-formats',
+        'uses-optimized-images',
+        'efficient-animated-content',
+        'uses-responsive-images',
+      ],
     };
   }
 

package/core/audits/insights/interaction-to-next-paint-insight.js

@@ -25,6 +25,7 @@ class InteractionToNextPaintInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['work-during-interaction'],
     };
   }
 

package/core/audits/insights/lcp-discovery-insight.js

@@ -25,6 +25,7 @@ class LCPDiscoveryInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['prioritize-lcp-image', 'lcp-lazy-loaded'],
     };
   }
 

package/core/audits/insights/lcp-phases-insight.js

@@ -25,6 +25,7 @@ class LCPPhasesInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['largest-contentful-paint-element'],
     };
   }
 

package/core/audits/insights/long-critical-network-tree-insight.js

@@ -27,6 +27,7 @@ class LongCriticalNetworkTreeInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['critical-request-chains'],
     };
   }
 

package/core/audits/insights/render-blocking-insight.js

@@ -25,6 +25,7 @@ class RenderBlockingInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['render-blocking-resources'],
     };
   }
 

package/core/audits/insights/third-parties-insight.js

@@ -32,6 +32,7 @@ class ThirdPartiesInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['third-party-summary'],
     };
   }
 

package/core/audits/insights/viewport-insight.js

@@ -25,6 +25,7 @@ class ViewportInsight extends Audit {
       description: str_(UIStrings.description),
       guidanceLevel: 3,
       requiredArtifacts: ['traces', 'TraceElements'],
+      replacesAudits: ['viewport'],
     };
   }
 

package/core/audits/layout-shifts.d.ts

@@ -26,7 +26,6 @@ export namespace UIStrings {
     let rootCauseUnsizedMedia: string;
     let rootCauseFontChanges: string;
     let rootCauseInjectedIframe: string;
-    let rootCauseRenderBlockingRequest: string;
     let displayValueShiftsFound: string;
 }
 import { Audit } from './audit.js';

package/core/audits/layout-shifts.js

@@ -29,8 +29,6 @@ const UIStrings = {
   rootCauseFontChanges: 'Web font loaded',
   /** A possible reason why that the layout shift occured. */
   rootCauseInjectedIframe: 'Injected iframe',
-  /** A possible reason why that the layout shift occured. */
-  rootCauseRenderBlockingRequest: 'A late network request adjusted the page layout',
   /** Label shown per-audit to show how many layout shifts are present. The `{# shifts found}` placeholder will be replaced with the number of layout shifts. */
   displayValueShiftsFound: `{shiftCount, plural, =1 {1 layout shift found} other {# layout shifts found}}`,
 };
@@ -49,7 +47,7 @@ class LayoutShifts extends Audit {
       description: str_(UIStrings.description),
       scoreDisplayMode: Audit.SCORING_MODES.METRIC_SAVINGS,
       guidanceLevel: 2,
-      requiredArtifacts: ['traces', 'RootCauses', 'TraceElements'],
+      requiredArtifacts: ['traces', 'TraceElements'],
     };
   }
 
@@ -67,11 +65,21 @@ class LayoutShifts extends Audit {
     const traceElements = artifacts.TraceElements
       .filter(element => element.traceEventType === 'layout-shift');
 
+    /** @type {LH.Artifacts.TraceEngineRootCauses} */
+    const allRootCauses = {
+      layoutShifts: new Map(),
+    };
+    for (const insightSet of traceEngineResult.insights.values()) {
+      for (const [shift, reasons] of insightSet.model.CLSCulprits.shifts) {
+        allRootCauses.layoutShifts.set(shift, reasons);
+      }
+    }
+
     /** @type {Item[]} */
     const items = [];
     const layoutShiftEvents =
       /** @type {import('../lib/trace-engine.js').SaneSyntheticLayoutShift[]} */(
-        clusters.flatMap(c => c.events)
+        clusters.flatMap(c => c.events).filter(e => !!e.args.data)
       );
     const topLayoutShiftEvents = layoutShiftEvents
       .sort((a, b) => b.args.data.weighted_score_delta - a.args.data.weighted_score_delta)
@@ -82,41 +90,30 @@ class LayoutShifts extends Audit {
       const biggestImpactElement = traceElements.find(t => t.nodeId === biggestImpactNodeId);
 
       // Turn root causes into sub-items.
-      const index = layoutShiftEvents.indexOf(event);
-      const rootCauses = artifacts.RootCauses.layoutShifts[index];
+      const rootCauses = allRootCauses.layoutShifts.get(event);
       /** @type {SubItem[]} */
       const subItems = [];
       if (rootCauses) {
-        for (const cause of rootCauses.unsizedMedia) {
+        for (const backendNodeId of rootCauses.unsizedImages) {
           const element = artifacts.TraceElements.find(
-            t => t.traceEventType === 'layout-shift' && t.nodeId === cause.node.backendNodeId);
+            t => t.traceEventType === 'trace-engine' && t.nodeId === backendNodeId);
           subItems.push({
             extra: element ? Audit.makeNodeItem(element.node) : undefined,
             cause: str_(UIStrings.rootCauseUnsizedMedia),
           });
         }
-        for (const cause of rootCauses.fontChanges) {
-          const url = cause.request.args.data.url;
+        for (const request of rootCauses.fontRequests) {
+          const url = request.args.data.url;
           subItems.push({
             extra: {type: 'url', value: url},
             cause: str_(UIStrings.rootCauseFontChanges),
           });
         }
-        for (const cause of rootCauses.iframes) {
-          const element = artifacts.TraceElements.find(
-            t => t.traceEventType === 'layout-shift' && t.nodeId === cause.iframe.backendNodeId);
+        if (rootCauses.iframeIds.length) {
           subItems.push({
-            extra: element ? Audit.makeNodeItem(element.node) : undefined,
             cause: str_(UIStrings.rootCauseInjectedIframe),
           });
         }
-        for (const cause of rootCauses.renderBlockingRequests) {
-          const url = cause.request.args.data.url;
-          subItems.push({
-            extra: {type: 'url', value: url},
-            cause: str_(UIStrings.rootCauseRenderBlockingRequest),
-          });
-        }
       }
 
       items.push({

package/core/config/default-config.js

@@ -109,7 +109,6 @@ 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'},

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

@@ -56,8 +56,8 @@ declare class TraceElements extends BaseGatherer {
         nodeId: number;
         type: string;
     } | undefined>;
-    /** @type {LH.Gatherer.GathererMeta<'Trace'|'RootCauses'>} */
-    meta: LH.Gatherer.GathererMeta<"Trace" | "RootCauses">;
+    /** @type {LH.Gatherer.GathererMeta<'Trace'>} */
+    meta: LH.Gatherer.GathererMeta<"Trace">;
     /** @type {Map<string, string>} */
     animationIdToName: Map<string, string>;
     /** @param {LH.Crdp.Animation.AnimationStartedEvent} args */

package/core/gather/gatherers/trace-elements.js

@@ -23,7 +23,6 @@ import {LighthouseError} from '../../lib/lh-error.js';
 import {Responsiveness} from '../../computed/metrics/responsiveness.js';
 import {CumulativeLayoutShift} from '../../computed/metrics/cumulative-layout-shift.js';
 import {ExecutionContext} from '../driver/execution-context.js';
-import RootCauses from './root-causes.js';
 import {TraceEngineResult} from '../../computed/trace-engine-result.js';
 
 /** @typedef {{nodeId: number, animations?: {name?: string, failureReasonsMask?: number, unsupportedProperties?: string[]}[], type?: string}} TraceElementData */
@@ -46,10 +45,10 @@ function getNodeDetailsData() {
 /* c8 ignore stop */
 
 class TraceElements extends BaseGatherer {
-  /** @type {LH.Gatherer.GathererMeta<'Trace'|'RootCauses'>} */
+  /** @type {LH.Gatherer.GathererMeta<'Trace'>} */
   meta = {
     supportedModes: ['timespan', 'navigation'],
-    dependencies: {Trace: Trace.symbol, RootCauses: RootCauses.symbol},
+    dependencies: {Trace: Trace.symbol},
   };
 
   /** @type {Map<string, string>} */
@@ -103,13 +102,23 @@ class TraceElements extends BaseGatherer {
       seen.add(obj);
 
       if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
-        Object.keys(obj).forEach(key => {
-          if (typeof obj[key] === 'object') {
-            recursiveObjectEnumerate(obj[key], cb, seen);
-          } else {
-            cb(obj, key);
+        if (obj instanceof Map) {
+          for (const [key, val] of obj) {
+            if (typeof val === 'object') {
+              recursiveObjectEnumerate(val, cb, seen);
+            } else {
+              cb(val, key);
+            }
           }
-        });
+        } else {
+          Object.keys(obj).forEach(key => {
+            if (typeof obj[key] === 'object') {
+              recursiveObjectEnumerate(obj[key], cb, seen);
+            } else {
+              cb(obj[key], key);
+            }
+          });
+        }
       } else if (Array.isArray(obj)) {
         obj.forEach(item => {
           if (typeof item === 'object' || Array.isArray(item)) {
@@ -121,12 +130,18 @@ class TraceElements extends BaseGatherer {
 
     /** @type {number[]} */
     const nodeIds = [];
-    recursiveObjectEnumerate(insightSet.model, (obj, key) => {
-      if (typeof obj[key] === 'number' && (key === 'nodeId' || key === 'node_id')) {
-        nodeIds.push(obj[key]);
+    recursiveObjectEnumerate(insightSet.model, (val, key) => {
+      const keys = ['nodeId', 'node_id'];
+      if (typeof val === 'number' && keys.includes(key)) {
+        nodeIds.push(val);
       }
     }, new Set());
 
+    // TODO: would be better if unsizedImages was `Array<{nodeId}>`.
+    for (const shift of insightSet.model.CLSCulprits.shifts.values()) {
+      nodeIds.push(...shift.unsizedImages);
+    }
+
     return [...new Set(nodeIds)].map(id => ({nodeId: id}));
   }
 
@@ -212,14 +227,6 @@ class TraceElements extends BaseGatherer {
           nodeIds.push(biggestImpactedNodeId);
         }
 
-        const index = layoutShiftEvents.indexOf(event);
-        const shiftRootCauses = rootCauses.layoutShifts[index];
-        if (shiftRootCauses) {
-          for (const cause of shiftRootCauses.unsizedMedia) {
-            nodeIds.push(cause.node.backendNodeId);
-          }
-        }
-
         return nodeIds.map(nodeId => ({nodeId}));
       });
   }

package/core/lib/bf-cache-strings.d.ts

@@ -1,6 +1,6 @@
-/** @type {Record<string, {name: LH.IcuMessage} | undefined>} */
+/** @type {Record<string, {name: LH.IcuMessage|string} | undefined>} */
 export const NotRestoredReasonDescription: Record<string, {
-    name: LH.IcuMessage;
+    name: LH.IcuMessage | string;
 } | undefined>;
 export namespace UIStrings {
     let notMainFrame: string;
@@ -77,7 +77,6 @@ export namespace UIStrings {
     let printing: string;
     let webDatabase: string;
     let pictureInPicture: string;
-    let portal: string;
     let speechRecognizer: string;
     let idleManager: string;
     let paymentManager: string;
@@ -87,6 +86,7 @@ export namespace UIStrings {
     let outstandingNetworkRequestDirectSocket: string;
     let injectedJavascript: string;
     let injectedStyleSheet: string;
+    let contentDiscarded: string;
     let contentSecurityHandler: string;
     let contentWebAuthenticationAPI: string;
     let contentFileChooser: string;
@@ -117,8 +117,11 @@ export namespace UIStrings {
     let errorDocument: string;
     let fencedFramesEmbedder: string;
     let keepaliveRequest: string;
-    let authorizationHeader: string;
+    let jsNetworkRequestReceivedCacheControlNoStoreResource: string;
     let indexedDBEvent: string;
     let cookieDisabled: string;
+    let webRTCSticky: string;
+    let webTransportSticky: string;
+    let webSocketSticky: string;
 }
 //# sourceMappingURL=bf-cache-strings.d.ts.map