lighthouse 11.4.0-dev.20240102 → 11.4.0-dev.20240104

package/report/renderer/performance-category-renderer.js

@@ -211,73 +211,106 @@ export class PerformanceCategoryRenderer extends CategoryRenderer {
       filmstripEl && timelineEl.append(filmstripEl);
     }
 
-    const filterableMetrics = metricAudits.filter(a => !!a.relevantAudits);
-    // TODO: only add if there are opportunities & diagnostics rendered.
-    if (filterableMetrics.length) {
-      this.renderMetricAuditFilter(filterableMetrics, element);
-    }
+    const allInsights = category.auditRefs
+      .filter(audit => this._isPerformanceInsight(audit))
+      .map(auditRef => {
+        const {overallImpact, overallLinearImpact} = this.overallImpact(auditRef, metricAudits);
+        const guidanceLevel = auditRef.result.guidanceLevel || 1;
+        const auditEl = this.renderAudit(auditRef);
+
+        return {auditRef, auditEl, overallImpact, overallLinearImpact, guidanceLevel};
+      });
 
     // Diagnostics
-    const diagnosticAudits = category.auditRefs
-        .filter(audit => this._isPerformanceInsight(audit))
-        .filter(audit => !ReportUtils.showAsPassed(audit.result));
-
-    /** @type {Array<{auditRef:LH.ReportResult.AuditRef, overallImpact: number, overallLinearImpact: number, guidanceLevel: number}>} */
-    const auditImpacts = [];
-    diagnosticAudits.forEach(audit => {
-      const {
-        overallImpact: overallImpact,
-        overallLinearImpact: overallLinearImpact,
-      } = this.overallImpact(audit, metricAudits);
-      const guidanceLevel = audit.result.guidanceLevel ?? 1;
-      auditImpacts.push({auditRef: audit, overallImpact, overallLinearImpact, guidanceLevel});
-    });
+    const diagnosticAudits = allInsights
+      .filter(audit => !ReportUtils.showAsPassed(audit.auditRef.result));
+
+    const passedAudits = allInsights
+      .filter(audit => ReportUtils.showAsPassed(audit.auditRef.result));
 
-    auditImpacts.sort((a, b) => {
-      // Performance diagnostics should only have score display modes of "informative" and "metricSavings"
-      // If the score display mode is "metricSavings", the `score` will be a coarse approximation of the overall impact.
-      // Therefore, it makes sense to sort audits by score first to ensure visual clarity with the score icons.
-      const scoreA = a.auditRef.result.scoreDisplayMode === 'informative'
-        ? 100
-        : Number(a.auditRef.result.score);
-      const scoreB = b.auditRef.result.scoreDisplayMode === 'informative'
-        ? 100
-        : Number(b.auditRef.result.score);
-      if (scoreA !== scoreB) return scoreA - scoreB;
-
-      // Overall impact is the estimated improvement to the performance score
-      if (a.overallImpact !== b.overallImpact) {
-        return b.overallImpact * b.guidanceLevel - a.overallImpact * a.guidanceLevel;
+    const [groupEl, footerEl] = this.renderAuditGroup(groups['diagnostics']);
+    groupEl.classList.add('lh-audit-group--diagnostics');
+
+    /**
+     * @param {string} acronym
+     */
+    function refreshFilteredAudits(acronym) {
+      for (const audit of allInsights) {
+        if (acronym === 'All') {
+          audit.auditEl.hidden = false;
+        } else {
+          const shouldHide = audit.auditRef.result.metricSavings?.[acronym] === undefined;
+          audit.auditEl.hidden = shouldHide;
+        }
       }
 
-      // Fall back to the linear impact if the normal impact is rounded down to 0
-      if (
-        a.overallImpact === 0 && b.overallImpact === 0 &&
-        a.overallLinearImpact !== b.overallLinearImpact
-      ) {
-        return b.overallLinearImpact * b.guidanceLevel - a.overallLinearImpact * a.guidanceLevel;
+      diagnosticAudits.sort((a, b) => {
+        // If the score display mode is "metricSavings", the `score` will be a coarse indicator of the overall impact.
+        // Therefore, it makes sense to sort audits by score first to ensure visual clarity with the score icons.
+        const scoreA = a.auditRef.result.scoreDisplayMode === 'informative'
+          ? 100
+          : Number(a.auditRef.result.score);
+        const scoreB = b.auditRef.result.scoreDisplayMode === 'informative'
+          ? 100
+          : Number(b.auditRef.result.score);
+        if (scoreA !== scoreB) return scoreA - scoreB;
+
+        // If there is a metric filter applied, we should sort by the impact to that specific metric.
+        if (acronym !== 'All') {
+          const aSavings = a.auditRef.result.metricSavings?.[acronym] ?? -1;
+          const bSavings = b.auditRef.result.metricSavings?.[acronym] ?? -1;
+          if (aSavings !== bSavings) return bSavings - aSavings;
+        }
+
+        // Overall impact is the estimated improvement to the performance score
+        if (a.overallImpact !== b.overallImpact) {
+          return b.overallImpact * b.guidanceLevel - a.overallImpact * a.guidanceLevel;
+        }
+
+        // Fall back to the linear impact if the normal impact is rounded down to 0
+        if (
+          a.overallImpact === 0 && b.overallImpact === 0 &&
+          a.overallLinearImpact !== b.overallLinearImpact
+        ) {
+          return b.overallLinearImpact * b.guidanceLevel - a.overallLinearImpact * a.guidanceLevel;
+        }
+
+        // Audits that have no estimated savings should be prioritized by the guidance level
+        return b.guidanceLevel - a.guidanceLevel;
+      });
+
+      for (const audit of diagnosticAudits) {
+        groupEl.insertBefore(audit.auditEl, footerEl);
       }
+    }
 
-      // Audits that have no estimated savings should be prioritized by the guidance level
-      return b.guidanceLevel - a.guidanceLevel;
-    });
+    /** @type {Set<string>} */
+    const filterableMetricAcronyms = new Set();
+    for (const audit of diagnosticAudits) {
+      const metricSavings = audit.auditRef.result.metricSavings || {};
+      for (const [key, value] of Object.entries(metricSavings)) {
+        if (typeof value === 'number') filterableMetricAcronyms.add(key);
+      }
+    }
 
-    if (auditImpacts.length) {
-      const [groupEl, footerEl] = this.renderAuditGroup(groups['diagnostics']);
-      auditImpacts.forEach(item => groupEl.insertBefore(this.renderAudit(item.auditRef), footerEl));
-      groupEl.classList.add('lh-audit-group--diagnostics');
-      element.append(groupEl);
+    const filterableMetrics =
+      metricAudits.filter(a => a.acronym && filterableMetricAcronyms.has(a.acronym));
+
+    // TODO: only add if there are opportunities & diagnostics rendered.
+    if (filterableMetrics.length) {
+      this.renderMetricAuditFilter(filterableMetrics, element, refreshFilteredAudits);
     }
 
-    // Passed audits
-    const passedAudits = category.auditRefs
-        .filter(audit =>
-          this._isPerformanceInsight(audit) && ReportUtils.showAsPassed(audit.result));
+    refreshFilteredAudits('All');
+
+    if (diagnosticAudits.length) {
+      element.append(groupEl);
+    }
 
     if (!passedAudits.length) return element;
 
     const clumpOpts = {
-      auditRefs: passedAudits,
+      auditRefsOrEls: passedAudits.map(audit => audit.auditEl),
       groupDefinitions: groups,
     };
     const passedElem = this.renderClump('passed', clumpOpts);
@@ -318,16 +351,17 @@ export class PerformanceCategoryRenderer extends CategoryRenderer {
    * Render the control to filter the audits by metric. The filtering is done at runtime by CSS only
    * @param {LH.ReportResult.AuditRef[]} filterableMetrics
    * @param {HTMLDivElement} categoryEl
+   * @param {(acronym: string) => void} onFilterChange
    */
-  renderMetricAuditFilter(filterableMetrics, categoryEl) {
+  renderMetricAuditFilter(filterableMetrics, categoryEl, onFilterChange) {
     const metricFilterEl = this.dom.createElement('div', 'lh-metricfilter');
     const textEl = this.dom.createChildOf(metricFilterEl, 'span', 'lh-metricfilter__text');
     textEl.textContent = Globals.strings.showRelevantAudits;
 
-    const filterChoices = /** @type {LH.ReportResult.AuditRef[]} */ ([
-      ({acronym: 'All'}),
+    const filterChoices = [
+      /** @type {const} */ ({acronym: 'All', id: 'All'}),
       ...filterableMetrics,
-    ]);
+    ];
 
     // Form labels need to reference unique IDs, but multiple reports rendered in the same DOM (eg PSI)
     // would mean ID conflict.  To address this, we 'scope' these radio inputs with a unique suffix.
@@ -341,7 +375,7 @@ export class PerformanceCategoryRenderer extends CategoryRenderer {
 
       const labelEl = this.dom.createChildOf(metricFilterEl, 'label', 'lh-metricfilter__label');
       labelEl.htmlFor = elemId;
-      labelEl.title = metric.result?.title;
+      labelEl.title = 'result' in metric ? metric.result.title : '';
       labelEl.textContent = metric.acronym || metric.id;
 
       if (metric.acronym === 'All') {
@@ -357,17 +391,7 @@ export class PerformanceCategoryRenderer extends CategoryRenderer {
         }
         categoryEl.classList.toggle('lh-category--filtered', metric.acronym !== 'All');
 
-        for (const perfAuditEl of categoryEl.querySelectorAll('div.lh-audit')) {
-          if (metric.acronym === 'All') {
-            perfAuditEl.hidden = false;
-            continue;
-          }
-
-          perfAuditEl.hidden = true;
-          if (metric.relevantAudits && metric.relevantAudits.includes(perfAuditEl.id)) {
-            perfAuditEl.hidden = false;
-          }
-        }
+        onFilterChange(metric.acronym || 'All');
 
         // Hide groups/clumps if all child audits are also hidden.
         const groupEls = categoryEl.querySelectorAll('div.lh-audit-group, details.lh-audit-group');

package/report/renderer/pwa-category-renderer.js

@@ -29,8 +29,11 @@ export class PwaCategoryRenderer extends CategoryRenderer {
 
     // Manual audits are still in a manual clump.
     const manualAuditRefs = auditRefs.filter(ref => ref.result.scoreDisplayMode === 'manual');
-    const manualElem = this.renderClump('manual',
-      {auditRefs: manualAuditRefs, description: category.manualDescription, openByDefault: true});
+    const manualElem = this.renderClump('manual', {
+      auditRefsOrEls: manualAuditRefs,
+      description: category.manualDescription,
+      openByDefault: true,
+    });
     categoryElem.append(manualElem);
 
     return categoryElem;

package/shared/localization/locales/en-US.json

@@ -1166,6 +1166,30 @@
   "core/audits/layout-shift-elements.js | title": {
     "message": "Avoid large layout shifts"
   },
+  "core/audits/layout-shifts.js | columnScore": {
+    "message": "Layout shift score"
+  },
+  "core/audits/layout-shifts.js | description": {
+    "message": "These are the largest layout shifts observed on the page. Each table item represents a single layout shift, and shows the element that shifted the most. Below each item are possible root causes that led to the layout shift. Some of these layout shifts may not be included in the CLS metric value due to [windowing](https://web.dev/articles/cls#what_is_cls). [Learn how to improve CLS](https://web.dev/articles/optimize-cls)"
+  },
+  "core/audits/layout-shifts.js | displayValueShiftsFound": {
+    "message": "{shiftCount, plural, =1 {1 layout shift found} other {# layout shifts found}}"
+  },
+  "core/audits/layout-shifts.js | rootCauseFontChanges": {
+    "message": "Web font loaded"
+  },
+  "core/audits/layout-shifts.js | rootCauseInjectedIframe": {
+    "message": "Injected iframe"
+  },
+  "core/audits/layout-shifts.js | rootCauseRenderBlockingRequest": {
+    "message": "A late network request adjusted the page layout"
+  },
+  "core/audits/layout-shifts.js | rootCauseUnsizedMedia": {
+    "message": "Media element lacking an explicit size"
+  },
+  "core/audits/layout-shifts.js | title": {
+    "message": "Avoid large layout shifts"
+  },
   "core/audits/lcp-lazy-loaded.js | description": {
     "message": "Above-the-fold images that are lazily loaded render later in the page lifecycle, which can delay the largest contentful paint. [Learn more about optimal lazy loading](https://web.dev/articles/lcp-lazy-loading)."
   },

package/shared/localization/locales/en-XL.json

@@ -1166,6 +1166,30 @@
   "core/audits/layout-shift-elements.js | title": {
     "message": "Âv́ôíd̂ ĺâŕĝé l̂áŷóût́ ŝh́îf́t̂ś"
   },
+  "core/audits/layout-shifts.js | columnScore": {
+    "message": "L̂áŷóût́ ŝh́îf́t̂ śĉór̂é"
+  },
+  "core/audits/layout-shifts.js | description": {
+    "message": "T̂h́êśê ár̂é t̂h́ê ĺâŕĝéŝt́ l̂áŷóût́ ŝh́îf́t̂ś ôb́ŝér̂v́êd́ ôń t̂h́ê ṕâǵê. Éâćĥ t́âb́l̂é ît́êḿ r̂ép̂ŕêśêńt̂ś â śîńĝĺê ĺâýôút̂ śĥíf̂t́, âńd̂ śĥóŵś t̂h́ê él̂ém̂én̂t́ t̂h́ât́ ŝh́îf́t̂éd̂ t́ĥé m̂óŝt́. B̂él̂óŵ éâćĥ ít̂ém̂ ár̂é p̂óŝśîb́l̂é r̂óôt́ ĉáûśêś t̂h́ât́ l̂éd̂ t́ô t́ĥé l̂áŷóût́ ŝh́îf́t̂. Śôḿê óf̂ t́ĥéŝé l̂áŷóût́ ŝh́îf́t̂ś m̂áŷ ńôt́ b̂é îńĉĺûd́êd́ îń t̂h́ê ĆL̂Ś m̂ét̂ŕîć v̂ál̂úê d́ûé t̂ó [ŵín̂d́ôẃîńĝ](https://web.dev/articles/cls#what_is_cls). [Ĺêár̂ń ĥóŵ t́ô ím̂ṕr̂óv̂é ĈĹŜ](https://web.dev/articles/optimize-cls)"
+  },
+  "core/audits/layout-shifts.js | displayValueShiftsFound": {
+    "message": "{shiftCount, plural, =1 {1 l̂áŷóût́ ŝh́îf́t̂ f́ôún̂d́} other {# l̂áŷóût́ ŝh́îf́t̂ś f̂óûńd̂}}"
+  },
+  "core/audits/layout-shifts.js | rootCauseFontChanges": {
+    "message": "Ŵéb̂ f́ôńt̂ ĺôád̂éd̂"
+  },
+  "core/audits/layout-shifts.js | rootCauseInjectedIframe": {
+    "message": "Îńĵéĉt́êd́ îf́r̂ám̂é"
+  },
+  "core/audits/layout-shifts.js | rootCauseRenderBlockingRequest": {
+    "message": "Â ĺât́ê ńêt́ŵór̂ḱ r̂éq̂úêśt̂ ád̂j́ûśt̂éd̂ t́ĥé p̂áĝé l̂áŷóût́"
+  },
+  "core/audits/layout-shifts.js | rootCauseUnsizedMedia": {
+    "message": "M̂éd̂íâ él̂ém̂én̂t́ l̂áĉḱîńĝ án̂ éx̂ṕl̂íĉít̂ śîźê"
+  },
+  "core/audits/layout-shifts.js | title": {
+    "message": "Âv́ôíd̂ ĺâŕĝé l̂áŷóût́ ŝh́îf́t̂ś"
+  },
   "core/audits/lcp-lazy-loaded.js | description": {
     "message": "Âb́ôv́ê-t́ĥé-f̂ól̂d́ îḿâǵêś t̂h́ât́ âŕê ĺâźîĺŷ ĺôád̂éd̂ ŕêńd̂ér̂ ĺât́êŕ îń t̂h́ê ṕâǵê ĺîf́êćŷćl̂é, ŵh́îćĥ ćâń d̂él̂áŷ t́ĥé l̂ár̂ǵêśt̂ ćôńt̂én̂t́f̂úl̂ ṕâín̂t́. [L̂éâŕn̂ ḿôŕê áb̂óût́ ôṕt̂ím̂ál̂ ĺâźŷ ĺôád̂ín̂ǵ](https://web.dev/articles/lcp-lazy-loading)."
   },

package/types/artifacts.d.ts

@@ -23,6 +23,7 @@ import LHResult from './lhr/lhr.js'
 import Protocol from './protocol.js';
 import Util from './utility-types.js';
 import Audit from './audit.js';
+import {TraceProcessor, LayoutShiftRootCauses} from './trace-engine.js';
 
 export type Artifacts = BaseArtifacts & GathererArtifacts;
 
@@ -142,6 +143,8 @@ export interface GathererArtifacts extends PublicGathererArtifacts {
   ResponseCompression: {requestId: string, url: string, mimeType: string, transferSize: number, resourceSize: number, gzipSize?: number}[];
   /** Information on fetching and the content of the /robots.txt file. */
   RobotsTxt: {status: number|null, content: string|null, errorMessage?: string};
+  /** The result of calling the shared trace engine root cause analysis. */
+  RootCauses: Artifacts.TraceEngineRootCauses;
   /** Information on all scripts in the page. */
   Scripts: Artifacts.Script[];
   /** Version information for all ServiceWorkers active after the first page load. */
@@ -559,13 +562,19 @@ declare module Artifacts {
   }
 
   interface TraceElement {
-    traceEventType: 'largest-contentful-paint'|'layout-shift'|'animation'|'responsiveness';
+    traceEventType: 'largest-contentful-paint'|'layout-shift'|'layout-shift-element'|'animation'|'responsiveness';
     node: NodeDetails;
     nodeId: number;
     animations?: {name?: string, failureReasonsMask?: number, unsupportedProperties?: string[]}[];
     type?: string;
   }
 
+  type TraceEngineResult = TraceProcessor['data'];
+
+  interface TraceEngineRootCauses {
+    layoutShifts: Record<number, LayoutShiftRootCauses>;
+  }
+
   interface ViewportDimensions {
     innerWidth: number;
     innerHeight: number;

package/types/audit.d.ts

@@ -20,6 +20,14 @@ declare module Audit {
   export type ScoreDisplayModes = AuditResult.ScoreDisplayModes;
   export type MetricSavings = AuditResult.MetricSavings;
 
+  export type ProductMetricSavings = {
+    FCP?: number;
+    LCP?: number;
+    TBT?: number;
+    CLS?: number;
+    INP?: number;
+  };
+
   type Context = Util.Immutable<{
     /** audit options */
     options: Record<string, any>;
@@ -87,7 +95,7 @@ declare module Audit {
     /** If an audit encounters unusual execution circumstances, strings can be put in this optional array to add top-level warnings to the LHR. */
     runWarnings?: Array<IcuMessage>;
     /** Estimates of how much this audit affects various performance metrics. Values will be in the unit of the respective metrics. */
-    metricSavings?: MetricSavings;
+    metricSavings?: ProductMetricSavings;
     /** Score details including p10 and median for calculating an audit's log-normal score. */
     scoringOptions?: ScoreOptions;
     /** A string identifying how the score should be interpreted for display. Overrides audit meta `scoreDisplayMode` if defined. */

package/types/config.d.ts

@@ -9,6 +9,7 @@ import {Audit} from '../core/audits/audit.js';
 import {SharedFlagsSettings, ConfigSettings} from './lhr/settings.js';
 import Gatherer from './gatherer.js';
 import {IcuMessage} from './lhr/i18n.js';
+import Result from './lhr/lhr.js';
 
 interface ClassOf<T> {
   new (): T;

package/types/lhr/audit-result.d.ts

@@ -31,13 +31,7 @@ interface ScoreDisplayModes {
 
 type ScoreDisplayMode = ScoreDisplayModes[keyof ScoreDisplayModes];
 
-interface MetricSavings {
-  LCP?: number;
-  FCP?: number;
-  CLS?: number;
-  TBT?: number;
-  INP?: number;
-}
+export type MetricSavings = Partial<Record<string, number>>;
 
 /** Audit result returned in Lighthouse report. All audits offer a description and score of 0-1. */
 export interface Result {