lighthouse 11.7.0 → 12.0.0-dev.20240422

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

@@ -28,7 +28,6 @@ import {TraceEngineResult} from '../../computed/trace-engine-result.js';
 
 /** @typedef {{nodeId: number, animations?: {name?: string, failureReasonsMask?: number, unsupportedProperties?: string[]}[], type?: string}} TraceElementData */
 
-const MAX_LAYOUT_SHIFT_ELEMENTS = 15;
 const MAX_LAYOUT_SHIFTS = 15;
 
 /**
@@ -66,41 +65,55 @@ class TraceElements extends BaseGatherer {
     if (name) this.animationIdToName.set(id, name);
   }
 
-  /**
-   * This function finds the top (up to 15) elements that shift on the page.
-   *
-   * @param {LH.Trace} trace
-   * @param {LH.Gatherer.Context} context
-   * @return {Promise<Array<{nodeId: number}>>}
-   */
-  static async getTopLayoutShiftElements(trace, context) {
-    const {impactByNodeId} = await CumulativeLayoutShift.request(trace, context);
-
-    return [...impactByNodeId.entries()]
-      .sort((a, b) => b[1] - a[1])
-      .slice(0, MAX_LAYOUT_SHIFT_ELEMENTS)
-      .map(([nodeId]) => ({nodeId}));
-  }
-
   /**
    * 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).
    *
    * @param {LH.Artifacts.TraceImpactedNode[]} impactedNodes
    * @param {Map<number, number>} impactByNodeId
+   * @param {import('../../lib/trace-engine.js').SaneSyntheticLayoutShift} event Only for debugging
    * @return {number|undefined}
    */
-  static getBiggestImpactNodeForShiftEvent(impactedNodes, impactByNodeId) {
-    let biggestImpactNodeId;
-    let biggestImpactNodeScore = Number.NEGATIVE_INFINITY;
-    for (const node of impactedNodes) {
-      const impactScore = impactByNodeId.get(node.node_id);
-      if (impactScore !== undefined && impactScore > biggestImpactNodeScore) {
-        biggestImpactNodeId = node.node_id;
-        biggestImpactNodeScore = impactScore;
+  static getBiggestImpactNodeForShiftEvent(impactedNodes, impactByNodeId, event) {
+    try {
+      let biggestImpactNodeId;
+      let biggestImpactNodeScore = Number.NEGATIVE_INFINITY;
+      for (const node of impactedNodes) {
+        const impactScore = impactByNodeId.get(node.node_id);
+        if (impactScore !== undefined && impactScore > biggestImpactNodeScore) {
+          biggestImpactNodeId = node.node_id;
+          biggestImpactNodeScore = impactScore;
+        }
       }
+      return biggestImpactNodeId;
+    } catch (err) {
+      // See https://github.com/GoogleChrome/lighthouse/issues/15870
+      // `impactedNodes` should always be an array here, but it can randomly be something else for
+      // currently unknown reasons. This exception handling will help us identify what
+      // `impactedNodes` really is and also prevent the error from being fatal.
+
+      // It's possible `impactedNodes` is not JSON serializable, so let's add more supplemental
+      // fields just in case.
+      const impactedNodesType = typeof impactedNodes;
+      const impactedNodesClassName = impactedNodes?.constructor?.name;
+
+      let impactedNodesJson;
+      let eventJson;
+      try {
+        impactedNodesJson = JSON.parse(JSON.stringify(impactedNodes));
+        eventJson = JSON.parse(JSON.stringify(event));
+      } catch {}
+
+      Sentry.captureException(err, {
+        extra: {
+          impactedNodes: impactedNodesJson,
+          event: eventJson,
+          impactedNodesType,
+          impactedNodesClassName,
+        },
+      });
+      return;
     }
-    return biggestImpactNodeId;
   }
 
   /**
@@ -109,7 +122,7 @@ class TraceElements extends BaseGatherer {
    * that may have caused the shift.
    *
    * @param {LH.Trace} trace
-   * @param {LH.Artifacts.TraceEngineResult} traceEngineResult
+   * @param {LH.Artifacts.TraceEngineResult['data']} traceEngineResult
    * @param {LH.Artifacts.TraceEngineRootCauses} rootCauses
    * @param {LH.Gatherer.Context} context
    * @return {Promise<Array<{nodeId: number}>>}
@@ -129,7 +142,7 @@ class TraceElements extends BaseGatherer {
         const nodeIds = [];
         const impactedNodes = event.args.data.impacted_nodes || [];
         const biggestImpactedNodeId =
-          this.getBiggestImpactNodeForShiftEvent(impactedNodes, impactByNodeId);
+          this.getBiggestImpactNodeForShiftEvent(impactedNodes, impactByNodeId, event);
         if (biggestImpactedNodeId !== undefined) {
           nodeIds.push(biggestImpactedNodeId);
         }
@@ -308,16 +321,14 @@ class TraceElements extends BaseGatherer {
     const {mainThreadEvents} = processedTrace;
 
     const lcpNodeData = await TraceElements.getLcpElement(trace, context);
-    const shiftElementsNodeData = await TraceElements.getTopLayoutShiftElements(trace, context);
     const shiftsData = await TraceElements.getTopLayoutShifts(
-      trace, traceEngineResult, rootCauses, context);
+      trace, traceEngineResult.data, rootCauses, context);
     const animatedElementData = await this.getAnimatedElements(mainThreadEvents);
     const responsivenessElementData = await TraceElements.getResponsivenessElement(trace, context);
 
     /** @type {Map<string, TraceElementData[]>} */
     const backendNodeDataMap = new Map([
       ['largest-contentful-paint', lcpNodeData ? [lcpNodeData] : []],
-      ['layout-shift-element', shiftElementsNodeData],
       ['layout-shift', shiftsData],
       ['animation', animatedElementData],
       ['responsiveness', responsivenessElementData ? [responsivenessElementData] : []],

package/core/gather/navigation-runner.js

@@ -92,7 +92,9 @@ async function _navigate(navigationContext) {
     return {requestedUrl, mainDocumentUrl, navigationError: undefined};
   } catch (err) {
     if (!(err instanceof LighthouseError)) throw err;
-    if (err.code !== 'NO_FCP' && err.code !== 'PAGE_HUNG') throw err;
+    if (err.code !== 'NO_FCP' && err.code !== 'PAGE_HUNG' && err.code !== 'TARGET_CRASHED') {
+      throw err;
+    }
     if (typeof requestor !== 'string') throw err;
 
     // TODO: Make the urls optional here so we don't need to throw an error with a callback requestor.

package/core/gather/session.d.ts

@@ -40,6 +40,14 @@ export class ProtocolSession extends ProtocolSession_base implements LH.Gatherer
      * @return {Promise<LH.CrdpCommands[C]['returnType']>}
      */
     sendCommand<C extends keyof import("puppeteer-core").ProtocolMapping.Commands>(method: C, ...params: import("puppeteer-core").ProtocolMapping.Commands[C]["paramsType"]): Promise<import("puppeteer-core").ProtocolMapping.Commands[C]["returnType"]>;
+    /**
+     * Send and if there's an error response, do not reject.
+     * @template {keyof LH.CrdpCommands} C
+     * @param {C} method
+     * @param {LH.CrdpCommands[C]['paramsType']} params
+     * @return {Promise<void>}
+     */
+    sendCommandAndIgnore<C_1 extends keyof import("puppeteer-core").ProtocolMapping.Commands>(method: C_1, ...params: import("puppeteer-core").ProtocolMapping.Commands[C_1]["paramsType"]): Promise<void>;
     /**
      * Disposes of a session so that it can no longer talk to Chrome.
      * @return {Promise<void>}

package/core/gather/session.js

@@ -100,6 +100,7 @@ class ProtocolSession extends CrdpEventEmitter {
     /** @type {NodeJS.Timer|undefined} */
     let timeout;
     const timeoutPromise = new Promise((resolve, reject) => {
+      // Unexpected setTimeout invocation to preserve the error stack. https://github.com/GoogleChrome/lighthouse/issues/13332
       // eslint-disable-next-line max-len
       timeout = setTimeout(reject, timeoutMs, new LighthouseError(LighthouseError.errors.PROTOCOL_TIMEOUT, {
         protocolMethod: method,
@@ -120,6 +121,18 @@ class ProtocolSession extends CrdpEventEmitter {
     });
   }
 
+  /**
+   * Send and if there's an error response, do not reject.
+   * @template {keyof LH.CrdpCommands} C
+   * @param {C} method
+   * @param {LH.CrdpCommands[C]['paramsType']} params
+   * @return {Promise<void>}
+   */
+  sendCommandAndIgnore(method, ...params) {
+    return this.sendCommand(method, ...params)
+      .catch(e => log.verbose('session', method, e.message)).then(_ => void 0);
+  }
+
   /**
    * Disposes of a session so that it can no longer talk to Chrome.
    * @return {Promise<void>}
@@ -127,7 +140,7 @@ class ProtocolSession extends CrdpEventEmitter {
   async dispose() {
     // @ts-expect-error Puppeteer expects the handler params to be type `unknown`
     this._cdpSession.off('*', this._handleProtocolEvent);
-    await this._cdpSession.detach();
+    await this._cdpSession.detach().catch(e => log.verbose('session', 'detach failed', e.message));
   }
 }
 

package/core/lib/emulation.js

@@ -128,7 +128,7 @@ function enableNetworkThrottling(session, throttlingSettings) {
  * @return {Promise<void>}
  */
 function clearNetworkThrottling(session) {
-  return session.sendCommand('Network.emulateNetworkConditions', NO_THROTTLING_METRICS);
+  return session.sendCommandAndIgnore('Network.emulateNetworkConditions', NO_THROTTLING_METRICS);
 }
 
 /**
@@ -146,7 +146,7 @@ function enableCPUThrottling(session, throttlingSettings) {
  * @return {Promise<void>}
  */
 function clearCPUThrottling(session) {
-  return session.sendCommand('Emulation.setCPUThrottlingRate', NO_CPU_THROTTLE_METRICS);
+  return session.sendCommandAndIgnore('Emulation.setCPUThrottlingRate', NO_CPU_THROTTLE_METRICS);
 }
 
 export {

package/core/lib/i18n/i18n.d.ts

@@ -19,7 +19,6 @@ export namespace UIStrings {
     const columnRequests: string;
     const columnName: string;
     const columnSource: string;
-    const columnOverBudget: string;
     const columnElement: string;
     const columnStartTime: string;
     const columnDuration: string;

package/core/lib/i18n/i18n.js

@@ -57,8 +57,6 @@ const UIStrings = {
   columnName: 'Name',
   /** Label for a column in a data table; entries will be the locations of JavaScript or CSS code, e.g. the name of a Javascript package or module. */
   columnSource: 'Source',
-  /** Label for a column in a data table; entries will be how much a predetermined budget has been exeeded by. Depending on the context, this number could represent an excess in quantity or size of network requests, or, an excess in the duration of time that it takes for the page to load.*/
-  columnOverBudget: 'Over Budget',
   /** Label for a column in a data table; entries will be a representation of a DOM element. */
   columnElement: 'Element',
   /** Label for a column in a data table; entries will be the number of milliseconds since the page started loading. */

package/core/lib/lantern/cpu-node.d.ts

@@ -6,11 +6,17 @@ export class CPUNode<T = any> extends BaseNode<T> {
     /**
      * @param {LH.TraceEvent} parentEvent
      * @param {LH.TraceEvent[]=} childEvents
+     * @param {number=} correctedEndTs
      */
-    constructor(parentEvent: LH.TraceEvent, childEvents?: LH.TraceEvent[] | undefined);
+    constructor(parentEvent: LH.TraceEvent, childEvents?: LH.TraceEvent[] | undefined, correctedEndTs?: number | undefined);
     _event: LH.TraceEvent;
     _childEvents: LH.TraceEvent[];
+    _correctedEndTs: number | undefined;
     get type(): "cpu";
+    /**
+     * @return {number}
+     */
+    get duration(): number;
     /**
      * @return {LH.TraceEvent}
      */

package/core/lib/lantern/cpu-node.js

@@ -15,13 +15,15 @@ class CPUNode extends BaseNode {
   /**
    * @param {LH.TraceEvent} parentEvent
    * @param {LH.TraceEvent[]=} childEvents
+   * @param {number=} correctedEndTs
    */
-  constructor(parentEvent, childEvents = []) {
+  constructor(parentEvent, childEvents = [], correctedEndTs) {
     const nodeId = `${parentEvent.tid}.${parentEvent.ts}`;
     super(nodeId);
 
     this._event = parentEvent;
     this._childEvents = childEvents;
+    this._correctedEndTs = correctedEndTs;
   }
 
   get type() {
@@ -39,9 +41,17 @@ class CPUNode extends BaseNode {
    * @return {number}
    */
   get endTime() {
+    if (this._correctedEndTs) return this._correctedEndTs;
     return this._event.ts + this._event.dur;
   }
 
+  /**
+   * @return {number}
+   */
+  get duration() {
+    return this.endTime - this.startTime;
+  }
+
   /**
    * @return {LH.TraceEvent}
    */
@@ -83,7 +93,7 @@ class CPUNode extends BaseNode {
    * @return {CPUNode}
    */
   cloneWithoutRelationships() {
-    return new CPUNode(this._event, this._childEvents);
+    return new CPUNode(this._event, this._childEvents, this._correctedEndTs);
   }
 }
 

package/core/lib/lantern/lantern-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class LanternError extends Error {
+}
+//# sourceMappingURL=lantern-error.d.ts.map

package/core/lib/lantern/lantern-error.js

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+class LanternError extends Error {}
+
+export {LanternError};

package/core/lib/lantern/metric.js

@@ -101,19 +101,15 @@ class Metric {
     const optimisticGraph = this.getOptimisticGraph(graph, processedNavigation);
     const pessimisticGraph = this.getPessimisticGraph(graph, processedNavigation);
 
-    /** @type {{flexibleOrdering?: boolean, label?: string}} */
     let simulateOptions = {label: `optimistic${metricName}`};
     const optimisticSimulation = simulator.simulate(optimisticGraph, simulateOptions);
 
-    simulateOptions = {label: `optimisticFlex${metricName}`, flexibleOrdering: true};
-    const optimisticFlexSimulation = simulator.simulate(optimisticGraph, simulateOptions);
-
     simulateOptions = {label: `pessimistic${metricName}`};
     const pessimisticSimulation = simulator.simulate(pessimisticGraph, simulateOptions);
 
     const optimisticEstimate = this.getEstimateFromSimulation(
-      optimisticSimulation.timeInMs < optimisticFlexSimulation.timeInMs ?
-        optimisticSimulation : optimisticFlexSimulation, {...extras, optimistic: true}
+      optimisticSimulation,
+      {...extras, optimistic: true}
     );
 
     const pessimisticEstimate = this.getEstimateFromSimulation(

package/core/lib/lantern/metrics/first-contentful-paint.d.ts

@@ -0,0 +1,79 @@
+export type Node = import('../base-node.js').Node;
+export type NetworkNode<T> = import('../network-node.js').NetworkNode<T>;
+export type CpuNode = import('../cpu-node.js').CPUNode;
+/** @typedef {import('../base-node.js').Node} Node */
+/** @template T @typedef {import('../network-node.js').NetworkNode<T>} NetworkNode */
+/** @typedef {import('../cpu-node.js').CPUNode} CpuNode */
+export class FirstContentfulPaint extends Metric {
+    /**
+     * @template T
+     * @typedef FirstPaintBasedGraphOpts
+     * @property {number} cutoffTimestamp The timestamp used to filter out tasks that occured after
+     *    our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+     * @property {function(NetworkNode<T>):boolean} treatNodeAsRenderBlocking The function that determines
+     *    which resources should be considered *possibly* render-blocking.
+     * @property {(function(CpuNode):boolean)=} additionalCpuNodesToTreatAsRenderBlocking The function that
+     *    determines which CPU nodes should also be included in our blocking node IDs set,
+     *    beyond what getRenderBlockingNodeData() already includes.
+     */
+    /**
+     * This function computes the set of URLs that *appeared* to be render-blocking based on our filter,
+     * *but definitely were not* render-blocking based on the timing of their EvaluateScript task.
+     * It also computes the set of corresponding CPU node ids that were needed for the paint at the
+     * given timestamp.
+     *
+     * @template [T=unknown]
+     * @param {Node} graph
+     * @param {FirstPaintBasedGraphOpts<T>} opts
+     * @return {{definitelyNotRenderBlockingScriptUrls: Set<string>, renderBlockingCpuNodeIds: Set<string>}}
+     */
+    static getRenderBlockingNodeData<T = unknown>(graph: Node, { cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking }: {
+        /**
+         * The timestamp used to filter out tasks that occured after
+         * our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+         */
+        cutoffTimestamp: number;
+        /**
+         * The function that determines
+         * which resources should be considered *possibly* render-blocking.
+         */
+        treatNodeAsRenderBlocking: (arg0: import("../network-node.js").NetworkNode<T>) => boolean;
+        /**
+         * The function that
+         * determines which CPU nodes should also be included in our blocking node IDs set,
+         * beyond what getRenderBlockingNodeData() already includes.
+         */
+        additionalCpuNodesToTreatAsRenderBlocking?: ((arg0: CpuNode) => boolean) | undefined;
+    }): {
+        definitelyNotRenderBlockingScriptUrls: Set<string>;
+        renderBlockingCpuNodeIds: Set<string>;
+    };
+    /**
+     * This function computes the graph required for the first paint of interest.
+     *
+     * @template [T=unknown]
+     * @param {Node} dependencyGraph
+     * @param {FirstPaintBasedGraphOpts<T>} opts
+     * @return {Node}
+     */
+    static getFirstPaintBasedGraph<T_1 = unknown>(dependencyGraph: Node, { cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking }: {
+        /**
+         * The timestamp used to filter out tasks that occured after
+         * our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+         */
+        cutoffTimestamp: number;
+        /**
+         * The function that determines
+         * which resources should be considered *possibly* render-blocking.
+         */
+        treatNodeAsRenderBlocking: (arg0: import("../network-node.js").NetworkNode<T_1>) => boolean;
+        /**
+         * The function that
+         * determines which CPU nodes should also be included in our blocking node IDs set,
+         * beyond what getRenderBlockingNodeData() already includes.
+         */
+        additionalCpuNodesToTreatAsRenderBlocking?: ((arg0: CpuNode) => boolean) | undefined;
+    }): Node;
+}
+import { Metric } from '../metric.js';
+//# sourceMappingURL=first-contentful-paint.d.ts.map

package/core/lib/lantern/metrics/first-contentful-paint.js

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Lantern from '../types/lantern.js';
+import {Metric} from '../metric.js';
+import {BaseNode} from '../base-node.js';
+
+/** @typedef {import('../base-node.js').Node} Node */
+/** @template T @typedef {import('../network-node.js').NetworkNode<T>} NetworkNode */
+/** @typedef {import('../cpu-node.js').CPUNode} CpuNode */
+
+class FirstContentfulPaint extends Metric {
+  /**
+   * @return {Lantern.Simulation.MetricCoefficients}
+   */
+  static get COEFFICIENTS() {
+    return {
+      intercept: 0,
+      optimistic: 0.5,
+      pessimistic: 0.5,
+    };
+  }
+
+  /**
+   * @template T
+   * @typedef FirstPaintBasedGraphOpts
+   * @property {number} cutoffTimestamp The timestamp used to filter out tasks that occured after
+   *    our paint of interest. Typically this is First Contentful Paint or First Meaningful Paint.
+   * @property {function(NetworkNode<T>):boolean} treatNodeAsRenderBlocking The function that determines
+   *    which resources should be considered *possibly* render-blocking.
+   * @property {(function(CpuNode):boolean)=} additionalCpuNodesToTreatAsRenderBlocking The function that
+   *    determines which CPU nodes should also be included in our blocking node IDs set,
+   *    beyond what getRenderBlockingNodeData() already includes.
+   */
+
+  /**
+   * This function computes the set of URLs that *appeared* to be render-blocking based on our filter,
+   * *but definitely were not* render-blocking based on the timing of their EvaluateScript task.
+   * It also computes the set of corresponding CPU node ids that were needed for the paint at the
+   * given timestamp.
+   *
+   * @template [T=unknown]
+   * @param {Node} graph
+   * @param {FirstPaintBasedGraphOpts<T>} opts
+   * @return {{definitelyNotRenderBlockingScriptUrls: Set<string>, renderBlockingCpuNodeIds: Set<string>}}
+   */
+  static getRenderBlockingNodeData(
+      graph,
+      {cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking}
+  ) {
+    /** @type {Map<string, CpuNode>} A map of blocking script URLs to the earliest EvaluateScript task node that executed them. */
+    const scriptUrlToNodeMap = new Map();
+
+    /** @type {Array<CpuNode>} */
+    const cpuNodes = [];
+    graph.traverse(node => {
+      if (node.type === BaseNode.TYPES.CPU) {
+        // A task is *possibly* render blocking if it *started* before cutoffTimestamp.
+        // We use startTime here because the paint event can be *inside* the task that was render blocking.
+        if (node.startTime <= cutoffTimestamp) cpuNodes.push(node);
+
+        // Build our script URL map to find the earliest EvaluateScript task node.
+        const scriptUrls = node.getEvaluateScriptURLs();
+        for (const url of scriptUrls) {
+          // Use the earliest CPU node we find.
+          const existing = scriptUrlToNodeMap.get(url) || node;
+          scriptUrlToNodeMap.set(url, node.startTime < existing.startTime ? node : existing);
+        }
+      }
+    });
+
+    cpuNodes.sort((a, b) => a.startTime - b.startTime);
+
+    // A script is *possibly* render blocking if it finished loading before cutoffTimestamp.
+    const possiblyRenderBlockingScriptUrls = Metric.getScriptUrls(graph, node => {
+      // The optimistic LCP treatNodeAsRenderBlocking fn wants to exclude some images in the graph,
+      // but here it only receives scripts to evaluate. It's a no-op in this case, but it will
+      // matter below in the getFirstPaintBasedGraph clone operation.
+      return node.endTime <= cutoffTimestamp && treatNodeAsRenderBlocking(node);
+    });
+
+    // A script is *definitely not* render blocking if its EvaluateScript task started after cutoffTimestamp.
+    /** @type {Set<string>} */
+    const definitelyNotRenderBlockingScriptUrls = new Set();
+    /** @type {Set<string>} */
+    const renderBlockingCpuNodeIds = new Set();
+    for (const url of possiblyRenderBlockingScriptUrls) {
+      // Lookup the CPU node that had the earliest EvaluateScript for this URL.
+      const cpuNodeForUrl = scriptUrlToNodeMap.get(url);
+
+      // If we can't find it at all, we can't conclude anything, so just skip it.
+      if (!cpuNodeForUrl) continue;
+
+      // If we found it and it was in our `cpuNodes` set that means it finished before cutoffTimestamp, so it really is render-blocking.
+      if (cpuNodes.includes(cpuNodeForUrl)) {
+        renderBlockingCpuNodeIds.add(cpuNodeForUrl.id);
+        continue;
+      }
+
+      // We couldn't find the evaluate script in the set of CPU nodes that ran before our paint, so
+      // it must not have been necessary for the paint.
+      definitelyNotRenderBlockingScriptUrls.add(url);
+    }
+
+    // The first layout, first paint, and first ParseHTML are almost always necessary for first paint,
+    // so we always include those CPU nodes.
+    const firstLayout = cpuNodes.find(node => node.didPerformLayout());
+    if (firstLayout) renderBlockingCpuNodeIds.add(firstLayout.id);
+    const firstPaint = cpuNodes.find(node => node.childEvents.some(e => e.name === 'Paint'));
+    if (firstPaint) renderBlockingCpuNodeIds.add(firstPaint.id);
+    const firstParse = cpuNodes.find(node => node.childEvents.some(e => e.name === 'ParseHTML'));
+    if (firstParse) renderBlockingCpuNodeIds.add(firstParse.id);
+
+    // If a CPU filter was passed in, we also want to include those extra nodes.
+    if (additionalCpuNodesToTreatAsRenderBlocking) {
+      cpuNodes
+        .filter(additionalCpuNodesToTreatAsRenderBlocking)
+        .forEach(node => renderBlockingCpuNodeIds.add(node.id));
+    }
+
+    return {
+      definitelyNotRenderBlockingScriptUrls,
+      renderBlockingCpuNodeIds,
+    };
+  }
+
+  /**
+   * This function computes the graph required for the first paint of interest.
+   *
+   * @template [T=unknown]
+   * @param {Node} dependencyGraph
+   * @param {FirstPaintBasedGraphOpts<T>} opts
+   * @return {Node}
+   */
+  static getFirstPaintBasedGraph(
+      dependencyGraph,
+      {cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking}
+  ) {
+    const rbData = this.getRenderBlockingNodeData(dependencyGraph, {
+      cutoffTimestamp,
+      treatNodeAsRenderBlocking,
+      additionalCpuNodesToTreatAsRenderBlocking,
+    });
+    const {definitelyNotRenderBlockingScriptUrls, renderBlockingCpuNodeIds} = rbData;
+
+    return dependencyGraph.cloneWithRelationships(node => {
+      if (node.type === BaseNode.TYPES.NETWORK) {
+        // Exclude all nodes that ended after cutoffTimestamp (except for the main document which we always consider necessary)
+        // endTime is negative if request does not finish, make sure startTime isn't after cutoffTimestamp in this case.
+        const endedAfterPaint = node.endTime > cutoffTimestamp || node.startTime > cutoffTimestamp;
+        if (endedAfterPaint && !node.isMainDocument()) return false;
+
+        const url = node.record.url;
+        // If the URL definitely wasn't render-blocking then we filter it out.
+        if (definitelyNotRenderBlockingScriptUrls.has(url)) {
+          return false;
+        }
+
+        // Lastly, build up the FCP graph of all nodes we consider render blocking
+        return treatNodeAsRenderBlocking(node);
+      } else {
+        // If it's a CPU node, just check if it was blocking.
+        return renderBlockingCpuNodeIds.has(node.id);
+      }
+    });
+  }
+
+  /**
+   * @param {Node} dependencyGraph
+   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+   * @return {Node}
+   */
+  static getOptimisticGraph(dependencyGraph, processedNavigation) {
+    return this.getFirstPaintBasedGraph(dependencyGraph, {
+      cutoffTimestamp: processedNavigation.timestamps.firstContentfulPaint,
+      // In the optimistic graph we exclude resources that appeared to be render blocking but were
+      // initiated by a script. While they typically have a very high importance and tend to have a
+      // significant impact on the page's content, these resources don't technically block rendering.
+      treatNodeAsRenderBlocking: node =>
+        node.hasRenderBlockingPriority() && node.initiatorType !== 'script',
+    });
+  }
+
+  /**
+   * @param {Node} dependencyGraph
+   * @param {LH.Artifacts.ProcessedNavigation} processedNavigation
+   * @return {Node}
+   */
+  static getPessimisticGraph(dependencyGraph, processedNavigation) {
+    return this.getFirstPaintBasedGraph(dependencyGraph, {
+      cutoffTimestamp: processedNavigation.timestamps.firstContentfulPaint,
+      treatNodeAsRenderBlocking: node => node.hasRenderBlockingPriority(),
+    });
+  }
+}
+
+export {FirstContentfulPaint};

package/core/lib/lantern/metrics/first-meaningful-paint.d.ts

@@ -0,0 +1,6 @@
+export type Node = import('../base-node.js').Node;
+/** @typedef {import('../base-node.js').Node} Node */
+export class FirstMeaningfulPaint extends Metric {
+}
+import { Metric } from '../metric.js';
+//# sourceMappingURL=first-meaningful-paint.d.ts.map