lighthouse 12.3.0-dev.20250204 → 12.3.0-dev.20250206

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

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {UIStrings} from '@paulirish/trace_engine/models/trace/insights/LCPDiscovery.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/LCPDiscovery.js', UIStrings);
+
+class LCPDiscoveryInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'lcp-discovery-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    return adaptInsightToAuditProduct(artifacts, context, 'LCPDiscovery', (insight) => {
+      if (!insight.checklist) {
+        return;
+      }
+
+      return Audit.makeChecklistDetails(insight.checklist);
+    });
+  }
+}
+
+export default LCPDiscoveryInsight;

package/core/audits/insights/lcp-phases-insight.d.ts

@@ -0,0 +1,11 @@
+export default LCPPhasesInsight;
+declare class LCPPhasesInsight 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=lcp-phases-insight.d.ts.map

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

@@ -0,0 +1,52 @@
+/* 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/LCPPhases.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct, makeNodeItemForNodeId} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/LCPPhases.js', UIStrings);
+
+class LCPPhasesInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'lcp-phases-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @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, 'LCPPhases', (insight) => {
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = [
+      ];
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default LCPPhasesInsight;

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

@@ -0,0 +1,11 @@
+export default LongCriticalNetworkTreeInsight;
+declare class LongCriticalNetworkTreeInsight 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=long-critical-network-tree-insight.d.ts.map

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

@@ -0,0 +1,52 @@
+/* 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/LongCriticalNetworkTree.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct, makeNodeItemForNodeId} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/LongCriticalNetworkTree.js', UIStrings);
+
+class LongCriticalNetworkTreeInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'long-critical-network-tree-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @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, 'LongCriticalNetworkTree', (insight) => {
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = [
+      ];
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default LongCriticalNetworkTreeInsight;

package/core/audits/insights/render-blocking-insight.d.ts

@@ -0,0 +1,11 @@
+export default RenderBlockingInsight;
+declare class RenderBlockingInsight 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=render-blocking-insight.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {UIStrings} from '@paulirish/trace_engine/models/trace/insights/RenderBlocking.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/RenderBlocking.js', UIStrings);
+
+class RenderBlockingInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'render-blocking-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    // TODO: show UIStrings.noRenderBlocking if nothing was blocking?
+    return adaptInsightToAuditProduct(artifacts, context, 'RenderBlocking', (insight) => {
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+        {key: 'url', valueType: 'url', label: str_(i18n.UIStrings.columnURL)},
+        {key: 'totalBytes', valueType: 'bytes', label: str_(i18n.UIStrings.columnTransferSize)},
+        {key: 'wastedMs', valueType: 'timespanMs', label: str_(i18n.UIStrings.columnWastedMs)},
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = insight.renderBlockingRequests.map(request => ({
+        url: request.args.data.url,
+        totalBytes: request.args.data.encodedDataLength,
+        wastedMs: insight.requestIdToWastedMs?.get(request.args.data.requestId),
+      }));
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default RenderBlockingInsight;

package/core/audits/insights/slow-css-selector-insight.d.ts

@@ -0,0 +1,11 @@
+export default SlowCSSSelectorInsight;
+declare class SlowCSSSelectorInsight 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=slow-css-selector-insight.d.ts.map

package/core/audits/insights/slow-css-selector-insight.js

@@ -0,0 +1,52 @@
+/* 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/SlowCSSSelector.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct, makeNodeItemForNodeId} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/SlowCSSSelector.js', UIStrings);
+
+class SlowCSSSelectorInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'slow-css-selector-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @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, 'SlowCSSSelector', (insight) => {
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = [
+      ];
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default SlowCSSSelectorInsight;

package/core/audits/insights/third-parties-insight.d.ts

@@ -0,0 +1,11 @@
+export default ThirdPartiesInsight;
+declare class ThirdPartiesInsight 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=third-parties-insight.d.ts.map

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

@@ -0,0 +1,52 @@
+/* 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/ThirdParties.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct, makeNodeItemForNodeId} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/ThirdParties.js', UIStrings);
+
+class ThirdPartiesInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'third-parties-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @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, 'ThirdParties', (insight) => {
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = [
+      ];
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default ThirdPartiesInsight;

package/core/audits/insights/viewport-insight.d.ts

@@ -0,0 +1,11 @@
+export default ViewportInsight;
+declare class ViewportInsight 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=viewport-insight.d.ts.map

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

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {UIStrings} from '@paulirish/trace_engine/models/trace/insights/Viewport.js';
+
+import {Audit} from '../audit.js';
+import * as i18n from '../../lib/i18n/i18n.js';
+import {adaptInsightToAuditProduct, makeNodeItemForNodeId} from './insight-audit.js';
+
+// eslint-disable-next-line max-len
+const str_ = i18n.createIcuMessageFn('node_modules/@paulirish/trace_engine/models/trace/insights/Viewport.js', UIStrings);
+
+class ViewportInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'viewport-insight',
+      title: str_(UIStrings.title),
+      failureTitle: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    return adaptInsightToAuditProduct(artifacts, context, 'Viewport', (insight) => {
+      const nodeId = insight.viewportEvent?.args.data.node_id;
+
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+        {key: 'node', valueType: 'node', label: ''},
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = [
+        {node: makeNodeItemForNodeId(artifacts.TraceElements, nodeId)},
+      ];
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default ViewportInsight;

package/core/computed/metrics/lantern-metric.js

@@ -39,7 +39,11 @@ async function getComputationDataParamsFromTrace(data, context) {
   const graph = await PageDependencyGraph.request({...data, fromTrace: true}, context);
   const traceEngineResult = await TraceEngineResult.request(data, context);
   const frameId = traceEngineResult.data.Meta.mainFrameId;
-  const navigationId = traceEngineResult.data.Meta.mainFrameNavigations[0].args.data.navigationId;
+  const navigationId = traceEngineResult.data.Meta.mainFrameNavigations[0].args.data?.navigationId;
+  if (!navigationId) {
+    throw new Error(`Lantern metrics could not be calculated due to missing navigation id`);
+  }
+
   const processedNavigation = Lantern.TraceEngineComputationData.createProcessedNavigation(
     traceEngineResult.data, frameId, navigationId);
   const simulator = data.simulator || (await LoadSimulator.request(data, context));

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

@@ -13,10 +13,6 @@ declare class TraceEngineResult {
      * @return {Promise<LH.Artifacts.TraceEngineResult>}
      */
     static runTraceEngine(traceEvents: LH.TraceEvent[]): Promise<LH.Artifacts.TraceEngineResult>;
-    /**
-     * @param {import('@paulirish/trace_engine/models/trace/insights/types.js').TraceInsightSets} insightSets
-     */
-    static localizeInsights(insightSets: import("@paulirish/trace_engine/models/trace/insights/types.js").TraceInsightSets): void;
     /**
      * @param {{trace: LH.Trace}} data
      * @param {LH.Artifacts.ComputedContext} context

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

@@ -4,7 +4,6 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import * as i18n from '../lib/i18n/i18n.js';
 import * as TraceEngine from '../lib/trace-engine.js';
 import {makeComputedArtifact} from './computed-artifact.js';
 import {CumulativeLayoutShift} from './metrics/cumulative-layout-shift.js';
@@ -28,34 +27,9 @@ class TraceEngineResult {
     ), {});
     if (!processor.parsedTrace) throw new Error('No data');
     if (!processor.insights) throw new Error('No insights');
-    this.localizeInsights(processor.insights);
     return {data: processor.parsedTrace, insights: processor.insights};
   }
 
-  /**
-   * @param {import('@paulirish/trace_engine/models/trace/insights/types.js').TraceInsightSets} insightSets
-   */
-  static localizeInsights(insightSets) {
-    for (const insightSet of insightSets.values()) {
-      for (const [name, model] of Object.entries(insightSet.model)) {
-        if (model instanceof Error) {
-          continue;
-        }
-
-        const key = `node_modules/@paulirish/trace_engine/models/trace/insights/${name}.js`;
-        const str_ = i18n.createIcuMessageFn(key, {
-          title: model.title,
-          description: model.description,
-        });
-
-        // @ts-expect-error coerce to string, should be fine
-        model.title = str_(model.title);
-        // @ts-expect-error coerce to string, should be fine
-        model.description = str_(model.description);
-      }
-    }
-  }
-
   /**
    * @param {{trace: LH.Trace}} data
    * @param {LH.Artifacts.ComputedContext} context

package/core/config/default-config.js

@@ -15,6 +15,8 @@ const UIStrings = {
   performanceCategoryTitle: 'Performance',
   /** Title of the speed metrics section of the Performance category. Within this section are various speed metrics which quantify the pageload performance into values presented in seconds and milliseconds. */
   metricGroupTitle: 'Metrics',
+  /** Title of the insights section of the Performance category. Within this section are various insights to give developers tips on how to improve the performance of their page. */
+  insightGroupTitle: 'Insights',
   /** Title of an opportunity sub-section of the Performance category. Within this section are audits with imperative titles that suggest actions the user can take to improve the time of the first initial render of the webpage. */
   firstPaintImprovementsGroupTitle: 'First Paint Improvements',
   /** Description of an opportunity sub-section of the Performance category. Within this section are audits with imperative titles that suggest actions the user can take to improve the time of the first initial render of the webpage. */
@@ -308,11 +310,28 @@ const defaultConfig = {
     'seo/manual/structured-data',
     'work-during-interaction',
     'bf-cache',
+    'insights/cls-culprits-insight',
+    'insights/document-latency-insight',
+    'insights/dom-size-insight',
+    'insights/font-display-insight',
+    'insights/forced-reflow-insight',
+    'insights/image-delivery-insight',
+    'insights/interaction-to-next-paint-insight',
+    'insights/lcp-discovery-insight',
+    'insights/lcp-phases-insight',
+    'insights/long-critical-network-tree-insight',
+    'insights/render-blocking-insight',
+    'insights/slow-css-selector-insight',
+    'insights/third-parties-insight',
+    'insights/viewport-insight',
   ],
   groups: {
     'metrics': {
       title: str_(UIStrings.metricGroupTitle),
     },
+    'insights': {
+      title: str_(UIStrings.insightGroupTitle),
+    },
     'diagnostics': {
       title: str_(UIStrings.diagnosticsGroupTitle),
       description: str_(UIStrings.diagnosticsGroupDescription),
@@ -388,6 +407,22 @@ const defaultConfig = {
         {id: 'speed-index', weight: 10, group: 'metrics', acronym: 'SI'},
         {id: 'interaction-to-next-paint', weight: 0, group: 'metrics', acronym: 'INP'},
 
+        // Insight audits.
+        {id: 'cls-culprits-insight', weight: 0, group: 'hidden'},
+        {id: 'document-latency-insight', weight: 0, group: 'hidden'},
+        {id: 'dom-size-insight', weight: 0, group: 'hidden'},
+        {id: 'font-display-insight', weight: 0, group: 'hidden'},
+        {id: 'forced-reflow-insight', weight: 0, group: 'hidden'},
+        {id: 'image-delivery-insight', weight: 0, group: 'hidden'},
+        {id: 'interaction-to-next-paint-insight', weight: 0, group: 'hidden'},
+        {id: 'lcp-discovery-insight', weight: 0, group: 'hidden'},
+        {id: 'lcp-phases-insight', weight: 0, group: 'hidden'},
+        {id: 'long-critical-network-tree-insight', weight: 0, group: 'hidden'},
+        {id: 'render-blocking-insight', weight: 0, group: 'hidden'},
+        {id: 'slow-css-selector-insight', weight: 0, group: 'hidden'},
+        {id: 'third-parties-insight', weight: 0, group: 'hidden'},
+        {id: 'viewport-insight', weight: 0, group: 'hidden'},
+
         // These are our "invisible" metrics. Not displayed, but still in the LHR.
         {id: 'interactive', weight: 0, group: 'hidden', acronym: 'TTI'},
         {id: 'max-potential-fid', weight: 0, group: 'hidden'},

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

@@ -9,6 +9,14 @@ export type TraceElementData = {
     type?: string;
 };
 declare class TraceElements extends BaseGatherer {
+    /**
+     * @param {LH.Artifacts.TraceEngineResult} traceEngineResult
+     * @param {string|undefined} navigationId
+     * @return {Promise<Array<{nodeId: number}>>}
+     */
+    static getTraceEngineElements(traceEngineResult: LH.Artifacts.TraceEngineResult, navigationId: string | undefined): 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).