core: add hidden audits for each insight

build/build-report.js

@@ -44,7 +44,7 @@ function buildStandaloneReport() {
     outfile: 'dist/report/standalone.js',
     format: 'iife',
     bundle: true,
-    minify: true,
+    minify: !process.env.DEBUG,
   });
 }
 

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

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {UIStrings} from '@paulirish/trace_engine/models/trace/insights/DOMSize.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/DOMSize.js', UIStrings);
+
+class DOMSizeInsight extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'dom-size-insight',
+      title: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+      scoreDisplayMode: Audit.SCORING_MODES.METRIC_SAVINGS,
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    return adaptInsightToAuditProduct(artifacts, context, 'DOMSize', (insight) => {
+      if (!insight.maxDOMStats?.args.data.maxChildren || !insight.maxDOMStats?.args.data.maxDepth) {
+        return;
+      }
+
+      const {maxChildren, maxDepth} = insight.maxDOMStats.args.data;
+
+      /** @type {LH.Audit.Details.Table['headings']} */
+      const headings = [
+        {key: 'statistic', valueType: 'text', label: 'Statistic'}, // TODO !
+        {key: 'node', valueType: 'node', label: str_(i18n.UIStrings.columnElement)},
+        {key: 'value', valueType: 'numeric', label: 'Value'}, // TODO !
+      ];
+      /** @type {LH.Audit.Details.Table['items']} */
+      const items = [
+        {
+          statistic: 'Most children',
+          node: makeNodeItemForNodeId(artifacts.TraceElements, maxChildren.nodeId),
+          value: {
+            type: 'numeric',
+            granularity: 1,
+            value: maxChildren.numChildren,
+          },
+        },
+        {
+          statistic: 'DOM depth',
+          node: makeNodeItemForNodeId(artifacts.TraceElements, maxDepth.nodeId),
+          value: {
+            type: 'numeric',
+            granularity: 1,
+            value: maxDepth.depth,
+          },
+        },
+      ];
+      return Audit.makeTableDetails(headings, items);
+    });
+  }
+}
+
+export default DOMSizeInsight;

core/audits/insights/insight-audit.js

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {NavigationInsights} from '../../computed/navigation-insights.js';
+import {Audit} from '../audit.js';
+
+/**
+ * @param {LH.Artifacts} artifacts
+ * @param {LH.Audit.Context} context
+ * @param {T} insightName
+ * @param {(insight: import('@paulirish/trace_engine/models/trace/insights/types.js').InsightModels[T]) => LH.Audit.Details|undefined} createDetails
+ * @template {keyof import('@paulirish/trace_engine/models/trace/insights/types.js').InsightModelsType} T
+ * @return {Promise<LH.Audit.Product>}
+ */
+async function adaptInsightToAuditProduct(artifacts, context, insightName, createDetails) {
+  const trace = artifacts.traces[Audit.DEFAULT_PASS];
+  const navInsights = await NavigationInsights.request(trace, context);
+  const insight = navInsights.model[insightName];
+  const details = createDetails(insight);
+  return {
+    score: insight.shouldShow ? 0 : 1,
+    metricSavings: insight.metricSavings,
+    warnings: insight.warnings,
+    details,
+  };
+}
+
+/**
+ * @param {LH.Artifacts.TraceElement[]} traceElements
+ * @param {number|null|undefined} nodeId
+ * @return {LH.Audit.Details.NodeValue|undefined}
+ */
+function makeNodeItemForNodeId(traceElements, nodeId) {
+  if (typeof nodeId !== 'number') {
+    return;
+  }
+
+  const traceElement =
+    traceElements.find(te => te.traceEventType === 'trace-engine' && te.nodeId === nodeId);
+  const node = traceElement?.node;
+  if (!node) {
+    return;
+  }
+
+  return Audit.makeNodeItem(node);
+}
+
+export {
+  adaptInsightToAuditProduct,
+  makeNodeItemForNodeId,
+};

core/audits/insights/viewport-insight.js

@@ -0,0 +1,61 @@
+/**
+ * @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),
+      description: str_(UIStrings.description),
+      guidanceLevel: 3,
+      requiredArtifacts: ['traces', 'TraceElements'],
+      scoreDisplayMode: Audit.SCORING_MODES.METRIC_SAVINGS,
+    };
+  }
+
+  /**
+   * @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;
+      const htmlSnippet = insight.viewportEvent ?
+        `<meta name=viewport content="${insight.viewportEvent.args.data.content}">` :
+        null;
+
+      /** @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)},
+      ];
+      const table = Audit.makeTableDetails(headings, items);
+
+      return Audit.makeListDetails([
+        table,
+        {type: 'debugdata', items: [htmlSnippet]},
+      ]);
+    });
+  }
+}
+
+export default ViewportInsight;

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,16 @@ const defaultConfig = {
     'seo/manual/structured-data',
     'work-during-interaction',
     'bf-cache',
+    'insights/dom-size-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 +395,9 @@ const defaultConfig = {
         {id: 'speed-index', weight: 10, group: 'metrics', acronym: 'SI'},
         {id: 'interaction-to-next-paint', weight: 0, group: 'metrics', acronym: 'INP'},
 
+        {id: 'dom-size-insight', weight: 0, group: 'insights'},
+        {id: 'viewport-insight', weight: 0, group: 'insights'},
+
         // 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'},

core/gather/gatherers/trace-elements.js

@@ -65,6 +65,29 @@ class TraceElements extends BaseGatherer {
     if (name) this.animationIdToName.set(id, name);
   }
 
+  /**
+   * @param {LH.Artifacts.TraceEngineResult} traceEngineResult
+   * @param {string} mainFrameId
+   * @return {Promise<Array<{nodeId: number}>>}
+   */
+  static async getTraceEngineElements(traceEngineResult, mainFrameId) {
+    // Can only resolve elements for the latest insight set, which should correspond
+    // to the current frame id. Can't resolve elements for pages that are gone.
+    const insightSet = [...traceEngineResult.insights.values()]
+      .reverse().find(insightSet => insightSet.frameId === mainFrameId);
+    if (!insightSet) {
+      return [];
+    }
+
+    const nodeIds = [
+      insightSet.model.DOMSize.maxDOMStats?.args.data.maxChildren?.nodeId,
+      insightSet.model.DOMSize.maxDOMStats?.args.data.maxDepth?.nodeId,
+      insightSet.model.Viewport.viewportEvent?.args.data.node_id,
+    ];
+
+    return nodeIds.filter(id => id !== undefined).map(id => ({nodeId: id}));
+  }
+
   /**
    * 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).
@@ -320,6 +343,11 @@ class TraceElements extends BaseGatherer {
     const processedTrace = await ProcessedTrace.request(trace, context);
     const {mainThreadEvents} = processedTrace;
 
+    const frameTreeResponse = await session.sendCommand('Page.getFrameTree');
+    const mainFrameId = frameTreeResponse.frameTree.frame.id;
+
+    const traceEngineData = await TraceElements.getTraceEngineElements(
+      traceEngineResult, mainFrameId);
     const lcpNodeData = await TraceElements.getLcpElement(trace, context);
     const shiftsData = await TraceElements.getTopLayoutShifts(
       trace, traceEngineResult.data, rootCauses, context);
@@ -328,6 +356,7 @@ class TraceElements extends BaseGatherer {
 
     /** @type {Map<string, TraceElementData[]>} */
     const backendNodeDataMap = new Map([
+      ['trace-engine', traceEngineData],
       ['largest-contentful-paint', lcpNodeData ? [lcpNodeData] : []],
       ['layout-shift', shiftsData],
       ['animation', animatedElementData],
@@ -336,6 +365,7 @@ class TraceElements extends BaseGatherer {
 
     /** @type {Map<number, LH.Crdp.Runtime.CallFunctionOnResponse | null>} */
     const callFunctionOnCache = new Map();
+    /** @type {LH.Artifacts.TraceElement[]} */
     const traceElements = [];
     for (const [traceEventType, backendNodeData] of backendNodeDataMap) {
       for (let i = 0; i < backendNodeData.length; i++) {

core/runner.js

@@ -499,6 +499,7 @@ vs
       ...fs.readdirSync(path.join(moduleDir, './audits/byte-efficiency'))
           .map(f => `byte-efficiency/${f}`),
       ...fs.readdirSync(path.join(moduleDir, './audits/manual')).map(f => `manual/${f}`),
+      ...fs.readdirSync(path.join(moduleDir, './audits/insights')).map(f => `insights/${f}`),
     ];
     return fileList.filter(f => {
       return /\.js$/.test(f) && !ignoredFiles.includes(f);