lighthouse 11.4.0-dev.20240103 → 11.4.0-dev.20240104

package/cli/test/smokehouse/core-tests.js

@@ -63,6 +63,7 @@ import seoPassing from './test-definitions/seo-passing.js';
 import seoStatus403 from './test-definitions/seo-status-403.js';
 import seoTapTargets from './test-definitions/seo-tap-targets.js';
 import serviceWorkerReloaded from './test-definitions/service-worker-reloaded.js';
+import shiftAttribution from './test-definitions/shift-attribution.js';
 import sourceMaps from './test-definitions/source-maps.js';
 import timing from './test-definitions/timing.js';
 
@@ -127,6 +128,7 @@ const smokeTests = [
   seoStatus403,
   seoTapTargets,
   serviceWorkerReloaded,
+  shiftAttribution,
   sourceMaps,
   timing,
 ];

package/core/audits/audit.d.ts

@@ -146,6 +146,11 @@ export class Audit {
      * @return {number|null}
      */
     static _normalizeAuditScore(score: number | null, scoreDisplayMode: LH.Audit.ScoreDisplayMode, auditId: string): number | null;
+    /**
+     * @param {LH.Audit.ProductMetricSavings|undefined} metricSavings
+     * @return {LH.Audit.ProductMetricSavings|undefined}
+     */
+    static _quantizeMetricSavings(metricSavings: LH.Audit.ProductMetricSavings | undefined): LH.Audit.ProductMetricSavings | undefined;
     /**
      * @param {typeof Audit} audit
      * @param {string | LH.IcuMessage} errorMessage

package/core/audits/audit.js

@@ -10,6 +10,15 @@ import {Util} from '../../shared/util.js';
 
 const DEFAULT_PASS = 'defaultPass';
 
+/** @type {Record<keyof LH.Audit.ProductMetricSavings, number>} */
+const METRIC_SAVINGS_PRECISION = {
+  FCP: 50,
+  LCP: 50,
+  INP: 50,
+  TBT: 50,
+  CLS: 0.001,
+};
+
 /**
  * @typedef TableOptions
  * @property {number=} wastedMs
@@ -339,6 +348,34 @@ class Audit {
     return score;
   }
 
+  /**
+   * @param {LH.Audit.ProductMetricSavings|undefined} metricSavings
+   * @return {LH.Audit.ProductMetricSavings|undefined}
+   */
+  static _quantizeMetricSavings(metricSavings) {
+    if (!metricSavings) return;
+
+    /** @type {LH.Audit.ProductMetricSavings} */
+    const normalizedMetricSavings = {...metricSavings};
+
+    // eslint-disable-next-line max-len
+    for (const key of /** @type {Array<keyof LH.Audit.ProductMetricSavings>} */ (Object.keys(metricSavings))) {
+      let value = metricSavings[key];
+      if (value === undefined) continue;
+
+      value = Math.max(value, 0);
+
+      const precision = METRIC_SAVINGS_PRECISION[key];
+      if (precision !== undefined) {
+        value = Math.round(value / precision) * precision;
+      }
+
+      normalizedMetricSavings[key] = value;
+    }
+
+    return normalizedMetricSavings;
+  }
+
   /**
    * @param {typeof Audit} audit
    * @param {string | LH.IcuMessage} errorMessage
@@ -378,10 +415,13 @@ class Audit {
       scoreDisplayMode = product.scoreDisplayMode;
     }
 
+    const metricSavings = Audit._quantizeMetricSavings(product.metricSavings);
+    const hasSomeSavings = Object.values(metricSavings || {}).some(v => v);
+
     if (scoreDisplayMode === Audit.SCORING_MODES.METRIC_SAVINGS) {
       if (score && score >= Util.PASS_THRESHOLD) {
         score = 1;
-      } else if (Object.values(product.metricSavings || {}).some(v => v)) {
+      } else if (hasSomeSavings) {
         score = 0;
       } else {
         score = 0.5;
@@ -419,7 +459,7 @@ class Audit {
       errorStack: product.errorStack,
       warnings: product.warnings,
       scoringOptions: product.scoringOptions,
-      metricSavings: product.metricSavings,
+      metricSavings,
 
       details: product.details,
       guidanceLevel: audit.meta.guidanceLevel,

package/core/audits/byte-efficiency/byte-efficiency-audit.js

@@ -194,7 +194,7 @@ class ByteEfficiencyAudit extends Audit {
 
     const wastedBytes = results.reduce((sum, item) => sum + item.wastedBytes, 0);
 
-    /** @type {LH.Audit.MetricSavings} */
+    /** @type {LH.Audit.ProductMetricSavings} */
     const metricSavings = {
       FCP: 0,
       LCP: 0,

package/core/audits/layout-shift-elements.js

@@ -45,7 +45,7 @@ class LayoutShiftElements extends Audit {
 
     /** @type {Array<{node: LH.Audit.Details.ItemValue, score: number}>} */
     const clsElementData = artifacts.TraceElements
-      .filter(element => element.traceEventType === 'layout-shift')
+      .filter(element => element.traceEventType === 'layout-shift-element')
       .map(element => ({
         node: Audit.makeNodeItem(element.node),
         score: impactByNodeId.get(element.nodeId) || 0,

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

@@ -0,0 +1,33 @@
+export default LayoutShifts;
+export type Item = LH.Audit.Details.TableItem & {
+    node?: LH.Audit.Details.NodeValue;
+    score: number;
+    subItems?: {
+        type: 'subitems';
+        items: SubItem[];
+    };
+};
+export type SubItem = {
+    extra?: LH.Audit.Details.NodeValue | LH.Audit.Details.UrlValue;
+    cause: LH.IcuMessage;
+};
+declare class LayoutShifts 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>;
+}
+export namespace UIStrings {
+    const title: string;
+    const description: string;
+    const columnScore: string;
+    const rootCauseUnsizedMedia: string;
+    const rootCauseFontChanges: string;
+    const rootCauseInjectedIframe: string;
+    const rootCauseRenderBlockingRequest: string;
+    const displayValueShiftsFound: string;
+}
+import { Audit } from './audit.js';
+//# sourceMappingURL=layout-shifts.d.ts.map

package/core/audits/layout-shifts.js

@@ -0,0 +1,158 @@
+/**
+ * @license Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {Audit} from './audit.js';
+import * as i18n from '../lib/i18n/i18n.js';
+import {CumulativeLayoutShift as CumulativeLayoutShiftComputed} from '../computed/metrics/cumulative-layout-shift.js';
+import CumulativeLayoutShift from './metrics/cumulative-layout-shift.js';
+import TraceElements from '../gather/gatherers/trace-elements.js';
+import {TraceEngineResult} from '../computed/trace-engine-result.js';
+
+const MAX_LAYOUT_SHIFTS = 15;
+
+/** @typedef {LH.Audit.Details.TableItem & {node?: LH.Audit.Details.NodeValue, score: number, subItems?: {type: 'subitems', items: SubItem[]}}} Item */
+/** @typedef {{extra?: LH.Audit.Details.NodeValue | LH.Audit.Details.UrlValue, cause: LH.IcuMessage}} SubItem */
+
+/* eslint-disable max-len */
+const UIStrings = {
+  /** Descriptive title of a diagnostic audit that provides the top elements affected by layout shifts. */
+  title: 'Avoid large layout shifts',
+  /** Description of a diagnostic audit that provides the top elements affected by layout shifts. "windowing" means the metric value is calculated using the subset of events in a small window of time during the run. "normalization" is a good substitute for "windowing". The last sentence starting with 'Learn' becomes link text to additional documentation. */
+  description: '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)',
+  /** 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',
+  /** A possible reason why that the layout shift occured. */
+  rootCauseUnsizedMedia: 'Media element lacking an explicit size',
+  /** A possible reason why that the layout shift occured. */
+  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}}`,
+};
+/* eslint-enable max-len */
+
+const str_ = i18n.createIcuMessageFn(import.meta.url, UIStrings);
+
+class LayoutShifts extends Audit {
+  /**
+   * @return {LH.Audit.Meta}
+   */
+  static get meta() {
+    return {
+      id: 'layout-shifts',
+      title: str_(UIStrings.title),
+      description: str_(UIStrings.description),
+      scoreDisplayMode: Audit.SCORING_MODES.METRIC_SAVINGS,
+      guidanceLevel: 2,
+      requiredArtifacts: ['traces', 'RootCauses', 'TraceElements'],
+    };
+  }
+
+  /**
+   * @param {LH.Artifacts} artifacts
+   * @param {LH.Audit.Context} context
+   * @return {Promise<LH.Audit.Product>}
+   */
+  static async audit(artifacts, context) {
+    const trace = artifacts.traces[Audit.DEFAULT_PASS];
+    const traceEngineResult = await TraceEngineResult.request({trace}, context);
+    const clusters = traceEngineResult.LayoutShifts.clusters ?? [];
+    const {cumulativeLayoutShift: clsSavings, impactByNodeId} =
+      await CumulativeLayoutShiftComputed.request(trace, context);
+    const traceElements = artifacts.TraceElements
+      .filter(element => element.traceEventType === 'layout-shift');
+
+    /** @type {Item[]} */
+    const items = [];
+    const layoutShiftEvents = clusters.flatMap(c => c.events);
+    const topLayoutShiftEvents = layoutShiftEvents
+      .sort((a, b) => b.args.data.weighted_score_delta - a.args.data.weighted_score_delta)
+      .slice(0, MAX_LAYOUT_SHIFTS);
+    for (const event of topLayoutShiftEvents) {
+      const biggestImpactNodeId = TraceElements.getBiggestImpactNodeForShiftEvent(
+        event.args.data.impacted_nodes, impactByNodeId);
+      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];
+      /** @type {SubItem[]} */
+      const subItems = [];
+      if (rootCauses) {
+        for (const cause of rootCauses.unsizedMedia) {
+          const element = artifacts.TraceElements.find(
+            t => t.traceEventType === 'layout-shift' && t.nodeId === cause.node.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;
+          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);
+          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({
+        node: biggestImpactElement ? Audit.makeNodeItem(biggestImpactElement.node) : undefined,
+        score: event.args.data.weighted_score_delta,
+        subItems: subItems.length ? {type: 'subitems', items: subItems} : undefined,
+      });
+    }
+
+    /** @type {LH.Audit.Details.Table['headings']} */
+    const headings = [
+      /* eslint-disable max-len */
+      {key: 'node', valueType: 'node', subItemsHeading: {key: 'extra'}, label: str_(i18n.UIStrings.columnElement)},
+      {key: 'score', valueType: 'numeric', subItemsHeading: {key: 'cause', valueType: 'text'}, granularity: 0.001, label: str_(UIStrings.columnScore)},
+      /* eslint-enable max-len */
+    ];
+
+    const details = Audit.makeTableDetails(headings, items);
+
+    let displayValue;
+    if (items.length > 0) {
+      displayValue = str_(UIStrings.displayValueShiftsFound,
+        {shiftCount: items.length});
+    }
+
+    const passed = clsSavings <= CumulativeLayoutShift.defaultOptions.p10;
+
+    return {
+      score: passed ? 1 : 0,
+      scoreDisplayMode: passed ? Audit.SCORING_MODES.INFORMATIVE : undefined,
+      metricSavings: {
+        CLS: clsSavings,
+      },
+      notApplicable: details.items.length === 0,
+      displayValue,
+      details,
+    };
+  }
+}
+
+export default LayoutShifts;
+export {UIStrings};

package/core/audits/viewport.js

@@ -63,12 +63,22 @@ class Viewport extends Audit {
       inpSavings = 0;
     }
 
+    /** @type {LH.Audit.Details.DebugData|undefined} */
+    let details;
+    if (viewportMeta.rawContentString !== undefined) {
+      details = {
+        type: 'debugdata',
+        viewportContent: viewportMeta.rawContentString,
+      };
+    }
+
     return {
       score: Number(viewportMeta.isMobileOptimized),
       metricSavings: {
         INP: inpSavings,
       },
       warnings: viewportMeta.parserWarnings,
+      details,
     };
   }
 }

package/core/computed/metrics/cumulative-layout-shift.d.ts

@@ -54,8 +54,8 @@ declare class CumulativeLayoutShift {
      * @param {LayoutShiftEvent[]} mainFrameShiftEvents
      */
     static computeWithSharedTraceEngine(allFrameShiftEvents: LayoutShiftEvent[], mainFrameShiftEvents: LayoutShiftEvent[]): Promise<{
-        cumulativeLayoutShift: any;
-        cumulativeLayoutShiftMainFrame: any;
+        cumulativeLayoutShift: number;
+        cumulativeLayoutShiftMainFrame: number;
     }>;
     /**
      * @param {LH.Trace} trace

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/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',
@@ -477,6 +479,7 @@ const defaultConfig = {
         {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},

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/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