lighthouse 11.7.0-dev.20240326 → 11.7.0-dev.20240328

package/core/computed/metrics/lantern-total-blocking-time.d.ts

@@ -1,37 +1,25 @@
 export { LanternTotalBlockingTimeComputed as LanternTotalBlockingTime };
-export type Node = import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>;
+export type Extras = import('../../lib/lantern/metric.js').Extras;
 declare const LanternTotalBlockingTimeComputed: typeof LanternTotalBlockingTime & {
     request: (dependencies: import("../../index.js").Artifacts.MetricComputationDataInput, context: import("../../../types/utility-types.js").default.ImmutableObject<{
         computedCache: Map<string, import("../../lib/arbitrary-equality-map.js").ArbitraryEqualityMap>;
     }>) => Promise<import("../../index.js").Artifacts.LanternMetric>;
 };
-/** @typedef {import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>} Node */
-declare class LanternTotalBlockingTime extends LanternMetric {
+/** @typedef {import('../../lib/lantern/metric.js').Extras} Extras */
+declare class LanternTotalBlockingTime extends TotalBlockingTime {
     /**
-     * @param {Node} dependencyGraph
-     * @return {Node}
+     * @param {LH.Artifacts.MetricComputationDataInput} data
+     * @param {LH.Artifacts.ComputedContext} context
+     * @param {Omit<Extras, 'optimistic'>=} extras
+     * @return {Promise<LH.Artifacts.LanternMetric>}
      */
-    static getOptimisticGraph(dependencyGraph: Node): Node;
+    static computeMetricWithGraphs(data: LH.Artifacts.MetricComputationDataInput, context: LH.Artifacts.ComputedContext, extras?: Omit<Extras, 'optimistic'> | undefined): Promise<LH.Artifacts.LanternMetric>;
     /**
-     * @param {Node} dependencyGraph
-     * @return {Node}
+     * @param {LH.Artifacts.MetricComputationDataInput} data
+     * @param {LH.Artifacts.ComputedContext} context
+     * @return {Promise<LH.Artifacts.LanternMetric>}
      */
-    static getPessimisticGraph(dependencyGraph: Node): Node;
-    /**
-     * @param {LH.Gatherer.Simulation.Result} simulation
-     * @param {import('../../lib/lantern/metric.js').Extras} extras
-     * @return {LH.Gatherer.Simulation.Result}
-     */
-    static getEstimateFromSimulation(simulation: LH.Gatherer.Simulation.Result, extras: import('../../lib/lantern/metric.js').Extras): LH.Gatherer.Simulation.Result;
-    /**
-     * @param {LH.Gatherer.Simulation.Result['nodeTimings']} nodeTimings
-     * @param {number} minDurationMs
-     */
-    static getTopLevelEvents(nodeTimings: LH.Gatherer.Simulation.Result['nodeTimings'], minDurationMs: number): {
-        start: number;
-        end: number;
-        duration: number;
-    }[];
+    static compute_(data: LH.Artifacts.MetricComputationDataInput, context: LH.Artifacts.ComputedContext): Promise<LH.Artifacts.LanternMetric>;
 }
-import { LanternMetric } from './lantern-metric.js';
+import { TotalBlockingTime } from '../../lib/lantern/metrics/total-blocking-time.js';
 //# sourceMappingURL=lantern-total-blocking-time.d.ts.map

package/core/computed/metrics/lantern-total-blocking-time.js

@@ -4,83 +4,23 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import {TotalBlockingTime} from '../../lib/lantern/metrics/total-blocking-time.js';
 import {makeComputedArtifact} from '../computed-artifact.js';
-import {LanternMetric} from './lantern-metric.js';
-import {BaseNode} from '../../lib/lantern/base-node.js';
 import {LanternFirstContentfulPaint} from './lantern-first-contentful-paint.js';
 import {LanternInteractive} from './lantern-interactive.js';
-import {BLOCKING_TIME_THRESHOLD, calculateSumOfBlockingTime} from './tbt-utils.js';
+import {getComputationDataParams} from './lantern-metric.js';
 
-/** @typedef {import('../../lib/lantern/base-node.js').Node<LH.Artifacts.NetworkRequest>} Node */
+/** @typedef {import('../../lib/lantern/metric.js').Extras} Extras */
 
-class LanternTotalBlockingTime extends LanternMetric {
+class LanternTotalBlockingTime extends TotalBlockingTime {
   /**
-   * @return {LH.Gatherer.Simulation.MetricCoefficients}
-   */
-  static get COEFFICIENTS() {
-    return {
-      intercept: 0,
-      optimistic: 0.5,
-      pessimistic: 0.5,
-    };
-  }
-
-  /**
-   * @param {Node} dependencyGraph
-   * @return {Node}
-   */
-  static getOptimisticGraph(dependencyGraph) {
-    return dependencyGraph;
-  }
-
-  /**
-   * @param {Node} dependencyGraph
-   * @return {Node}
-   */
-  static getPessimisticGraph(dependencyGraph) {
-    return dependencyGraph;
-  }
-
-  /**
-   * @param {LH.Gatherer.Simulation.Result} simulation
-   * @param {import('../../lib/lantern/metric.js').Extras} extras
-   * @return {LH.Gatherer.Simulation.Result}
+   * @param {LH.Artifacts.MetricComputationDataInput} data
+   * @param {LH.Artifacts.ComputedContext} context
+   * @param {Omit<Extras, 'optimistic'>=} extras
+   * @return {Promise<LH.Artifacts.LanternMetric>}
    */
-  static getEstimateFromSimulation(simulation, extras) {
-    if (!extras.fcpResult) throw new Error('missing fcpResult');
-    if (!extras.interactiveResult) throw new Error('missing interactiveResult');
-
-    // Intentionally use the opposite FCP estimate. A pessimistic FCP is higher than equal to an
-    // optimistic FCP, which means potentially more tasks are excluded from the Total Blocking Time
-    // computation. So a more pessimistic FCP gives a more optimistic Total Blocking Time for the
-    // same work.
-    const fcpTimeInMs = extras.optimistic
-      ? extras.fcpResult.pessimisticEstimate.timeInMs
-      : extras.fcpResult.optimisticEstimate.timeInMs;
-
-    // Similarly, we always have pessimistic TTI >= optimistic TTI. Therefore, picking optimistic
-    // TTI means our window of interest is smaller and thus potentially more tasks are excluded from
-    // Total Blocking Time computation, yielding a lower (more optimistic) Total Blocking Time value
-    // for the same work.
-    const interactiveTimeMs = extras.optimistic
-      ? extras.interactiveResult.optimisticEstimate.timeInMs
-      : extras.interactiveResult.pessimisticEstimate.timeInMs;
-
-    const minDurationMs = BLOCKING_TIME_THRESHOLD;
-
-    const events = LanternTotalBlockingTime.getTopLevelEvents(
-      simulation.nodeTimings,
-      minDurationMs
-    );
-
-    return {
-      timeInMs: calculateSumOfBlockingTime(
-        events,
-        fcpTimeInMs,
-        interactiveTimeMs
-      ),
-      nodeTimings: simulation.nodeTimings,
-    };
+  static async computeMetricWithGraphs(data, context, extras) {
+    return this.compute(await getComputationDataParams(data, context), extras);
   }
 
   /**
@@ -93,30 +33,6 @@ class LanternTotalBlockingTime extends LanternMetric {
     const interactiveResult = await LanternInteractive.request(data, context);
     return this.computeMetricWithGraphs(data, context, {fcpResult, interactiveResult});
   }
-
-  /**
-   * @param {LH.Gatherer.Simulation.Result['nodeTimings']} nodeTimings
-   * @param {number} minDurationMs
-   */
-  static getTopLevelEvents(nodeTimings, minDurationMs) {
-    /** @type {Array<{start: number, end: number, duration: number}>}
-     */
-    const events = [];
-
-    for (const [node, timing] of nodeTimings.entries()) {
-      if (node.type !== BaseNode.TYPES.CPU) continue;
-      // Filtering out events below minimum duration.
-      if (timing.duration < minDurationMs) continue;
-
-      events.push({
-        start: timing.startTime,
-        end: timing.endTime,
-        duration: timing.duration,
-      });
-    }
-
-    return events;
-  }
 }
 
 const LanternTotalBlockingTimeComputed = makeComputedArtifact(

package/core/computed/metrics/metric.js

@@ -61,9 +61,7 @@ class Metric {
    * @return {Promise<LH.Artifacts.LanternMetric|LH.Artifacts.Metric>}
    */
   static async compute_(data, context) {
-    // TODO: remove this fallback when lighthouse-pub-ads plugin can update.
-    const gatherContext = data.gatherContext || {gatherMode: 'navigation'};
-    const {trace, devtoolsLog, settings} = data;
+    const {trace, devtoolsLog, settings, gatherContext} = data;
     if (!trace || !devtoolsLog || !settings) {
       throw new Error('Did not provide necessary metric computation data');
     }

package/core/config/default-config.js

@@ -9,7 +9,6 @@
 import * as LH from '../../types/lh.js';
 import * as constants from './constants.js';
 import * as i18n from '../lib/i18n/i18n.js';
-import {metricsToAudits} from './metrics-to-audits.js';
 
 const UIStrings = {
   /** Title of the Performance category of audits. Equivalent to 'Web performance', this term is inclusive of all web page speed and loading optimization topics. Also used as a label of a score gauge; try to limit to 20 characters. */
@@ -20,10 +19,6 @@ const UIStrings = {
   budgetsGroupDescription: 'Performance budgets set standards for the performance of your site.',
   /** 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 opportunity section of the Performance category. Within this section are audits with imperative titles that suggest actions the user can take to improve the loading performance of their web page. 'Suggestion'/'Optimization'/'Recommendation' are reasonable synonyms for 'opportunity' in this case. */
-  loadOpportunitiesGroupTitle: 'Opportunities',
-  /** Description of the opportunity section of the Performance category. 'Suggestions' could also be 'recommendations'. Within this section are audits with imperative titles that suggest actions the user can take to improve the loading performance of their web page. */
-  loadOpportunitiesGroupDescription: 'These suggestions can help your page load faster. They don\'t [directly affect](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring/) the Performance score.',
   /** 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. */
@@ -141,7 +136,6 @@ const defaultConfig = {
     {id: 'EmbeddedContent', gatherer: 'seo/embedded-content'},
     {id: 'FontSize', gatherer: 'seo/font-size'},
     {id: 'Inputs', gatherer: 'inputs'},
-    {id: 'GlobalListeners', gatherer: 'global-listeners'},
     {id: 'IFrameElements', gatherer: 'iframe-elements'},
     {id: 'ImageElements', gatherer: 'image-elements'},
     {id: 'InstallabilityErrors', gatherer: 'installability-errors'},
@@ -222,7 +216,6 @@ const defaultConfig = {
     'layout-shift-elements',
     'layout-shifts',
     'long-tasks',
-    'no-unload-listeners',
     'non-composited-animations',
     'unsized-images',
     'valid-source-maps',
@@ -349,10 +342,6 @@ const defaultConfig = {
     'metrics': {
       title: str_(UIStrings.metricGroupTitle),
     },
-    'load-opportunities': {
-      title: str_(UIStrings.loadOpportunitiesGroupTitle),
-      description: str_(UIStrings.loadOpportunitiesGroupDescription),
-    },
     'budgets': {
       title: str_(UIStrings.budgetsGroupTitle),
       description: str_(UIStrings.budgetsGroupDescription),
@@ -431,59 +420,58 @@ const defaultConfig = {
       title: str_(UIStrings.performanceCategoryTitle),
       supportedModes: ['navigation', 'timespan', 'snapshot'],
       auditRefs: [
-        {id: 'first-contentful-paint', weight: 10, group: 'metrics', acronym: 'FCP', relevantAudits: metricsToAudits.fcpRelevantAudits},
-        {id: 'largest-contentful-paint', weight: 25, group: 'metrics', acronym: 'LCP', relevantAudits: metricsToAudits.lcpRelevantAudits},
-        {id: 'total-blocking-time', weight: 30, group: 'metrics', acronym: 'TBT', relevantAudits: metricsToAudits.tbtRelevantAudits},
-        {id: 'cumulative-layout-shift', weight: 25, group: 'metrics', acronym: 'CLS', relevantAudits: metricsToAudits.clsRelevantAudits},
+        {id: 'first-contentful-paint', weight: 10, group: 'metrics', acronym: 'FCP'},
+        {id: 'largest-contentful-paint', weight: 25, group: 'metrics', acronym: 'LCP'},
+        {id: 'total-blocking-time', weight: 30, group: 'metrics', acronym: 'TBT'},
+        {id: 'cumulative-layout-shift', weight: 25, group: 'metrics', acronym: 'CLS'},
         {id: 'speed-index', weight: 10, group: 'metrics', acronym: 'SI'},
-        {id: 'interaction-to-next-paint', weight: 0, group: 'metrics', acronym: 'INP', relevantAudits: metricsToAudits.inpRelevantAudits},
+        {id: 'interaction-to-next-paint', weight: 0, group: 'metrics', acronym: 'INP'},
 
         // 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'},
         {id: 'first-meaningful-paint', weight: 0, acronym: 'FMP', group: 'hidden'},
 
-        // These audits will be put in "load-opportunities" or "diagnostics" based on their details type.
-        {id: 'render-blocking-resources', weight: 0},
-        {id: 'uses-responsive-images', weight: 0},
-        {id: 'offscreen-images', weight: 0},
-        {id: 'unminified-css', weight: 0},
-        {id: 'unminified-javascript', weight: 0},
-        {id: 'unused-css-rules', weight: 0},
-        {id: 'unused-javascript', weight: 0},
-        {id: 'uses-optimized-images', weight: 0},
-        {id: 'modern-image-formats', weight: 0},
-        {id: 'uses-text-compression', weight: 0},
-        {id: 'uses-rel-preconnect', weight: 0},
-        {id: 'server-response-time', weight: 0},
-        {id: 'redirects', weight: 0},
-        {id: 'uses-http2', weight: 0},
-        {id: 'efficient-animated-content', weight: 0},
-        {id: 'duplicated-javascript', weight: 0},
-        {id: 'legacy-javascript', weight: 0},
-        {id: 'prioritize-lcp-image', weight: 0},
-        {id: 'total-byte-weight', weight: 0},
-        {id: 'uses-long-cache-ttl', weight: 0},
-        {id: 'dom-size', weight: 0},
-        {id: 'critical-request-chains', weight: 0},
-        {id: 'user-timings', weight: 0},
-        {id: 'bootup-time', weight: 0},
-        {id: 'mainthread-work-breakdown', weight: 0},
-        {id: 'font-display', weight: 0},
-        {id: 'third-party-summary', weight: 0},
-        {id: 'third-party-facades', weight: 0},
-        {id: 'largest-contentful-paint-element', weight: 0},
-        {id: 'lcp-lazy-loaded', 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},
-        {id: 'non-composited-animations', weight: 0},
-        {id: 'unsized-images', weight: 0},
-        {id: 'viewport', weight: 0},
-        {id: 'uses-responsive-images-snapshot', weight: 0},
-        {id: 'work-during-interaction', weight: 0},
-        {id: 'bf-cache', weight: 0},
+        {id: 'render-blocking-resources', weight: 0, group: 'diagnostics'},
+        {id: 'uses-responsive-images', weight: 0, group: 'diagnostics'},
+        {id: 'offscreen-images', weight: 0, group: 'diagnostics'},
+        {id: 'unminified-css', weight: 0, group: 'diagnostics'},
+        {id: 'unminified-javascript', weight: 0, group: 'diagnostics'},
+        {id: 'unused-css-rules', weight: 0, group: 'diagnostics'},
+        {id: 'unused-javascript', weight: 0, group: 'diagnostics'},
+        {id: 'uses-optimized-images', weight: 0, group: 'diagnostics'},
+        {id: 'modern-image-formats', weight: 0, group: 'diagnostics'},
+        {id: 'uses-text-compression', weight: 0, group: 'diagnostics'},
+        {id: 'uses-rel-preconnect', weight: 0, group: 'diagnostics'},
+        {id: 'server-response-time', weight: 0, group: 'diagnostics'},
+        {id: 'redirects', weight: 0, group: 'diagnostics'},
+        {id: 'uses-http2', weight: 0, group: 'diagnostics'},
+        {id: 'efficient-animated-content', weight: 0, group: 'diagnostics'},
+        {id: 'duplicated-javascript', weight: 0, group: 'diagnostics'},
+        {id: 'legacy-javascript', weight: 0, group: 'diagnostics'},
+        {id: 'prioritize-lcp-image', weight: 0, group: 'diagnostics'},
+        {id: 'total-byte-weight', weight: 0, group: 'diagnostics'},
+        {id: 'uses-long-cache-ttl', weight: 0, group: 'diagnostics'},
+        {id: 'dom-size', weight: 0, group: 'diagnostics'},
+        {id: 'critical-request-chains', weight: 0, group: 'diagnostics'},
+        {id: 'user-timings', weight: 0, group: 'diagnostics'},
+        {id: 'bootup-time', weight: 0, group: 'diagnostics'},
+        {id: 'mainthread-work-breakdown', weight: 0, group: 'diagnostics'},
+        {id: 'font-display', weight: 0, group: 'diagnostics'},
+        {id: 'third-party-summary', weight: 0, group: 'diagnostics'},
+        {id: 'third-party-facades', weight: 0, group: 'diagnostics'},
+        {id: 'largest-contentful-paint-element', weight: 0, group: 'diagnostics'},
+        {id: 'lcp-lazy-loaded', weight: 0, group: 'diagnostics'},
+        {id: 'layout-shifts', weight: 0, group: 'diagnostics'},
+        {id: 'uses-passive-event-listeners', weight: 0, group: 'diagnostics'},
+        {id: 'no-document-write', weight: 0, group: 'diagnostics'},
+        {id: 'long-tasks', weight: 0, group: 'diagnostics'},
+        {id: 'non-composited-animations', weight: 0, group: 'diagnostics'},
+        {id: 'unsized-images', weight: 0, group: 'diagnostics'},
+        {id: 'viewport', weight: 0, group: 'diagnostics'},
+        {id: 'uses-responsive-images-snapshot', weight: 0, group: 'diagnostics'},
+        {id: 'work-during-interaction', weight: 0, group: 'diagnostics'},
+        {id: 'bf-cache', weight: 0, group: 'diagnostics'},
 
         // Budget audits.
         {id: 'performance-budget', weight: 0, group: 'budgets'},
@@ -605,7 +593,6 @@ const defaultConfig = {
         {id: 'doctype', weight: 1, group: 'best-practices-browser-compat'},
         {id: 'charset', weight: 1, group: 'best-practices-browser-compat'},
         // General Group
-        {id: 'no-unload-listeners', weight: 1, group: 'best-practices-general'},
         {id: 'js-libraries', weight: 0, group: 'best-practices-general'},
         {id: 'deprecations', weight: 5, group: 'best-practices-general'},
         {id: 'third-party-cookies', weight: 5, group: 'best-practices-general'},

package/core/config/experimental-config.js

@@ -23,7 +23,7 @@ const config = {
     // config is awkward - easier to omit the property here. Will defer to default config.
     'performance': {
       auditRefs: [
-        {id: 'uses-rel-preload', weight: 0},
+        {id: 'uses-rel-preload', weight: 0, group: 'diagnostics'},
       ],
     },
     // @ts-ignore: `title` is required in CategoryJson. setting to the same value as the default

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