@paulirish/trace_engine 0.0.25 → 0.0.27

package/models/trace/lantern/metrics/Metric.d.ts

@@ -0,0 +1,44 @@
+import * as Graph from '../graph/graph.js';
+import type * as Simulation from '../simulation/simulation.js';
+import type * as Types from '../types/types.js';
+export interface MetricComputationDataInput {
+    simulator: Simulation.Simulator;
+    graph: Graph.Node<unknown>;
+    processedNavigation: Types.Simulation.ProcessedNavigation;
+}
+export interface MetricCoefficients {
+    intercept: number;
+    optimistic: number;
+    pessimistic: number;
+}
+export interface MetricResult<T = Types.AnyNetworkObject> {
+    timing: number;
+    timestamp?: never;
+    optimisticEstimate: Simulation.Result<T>;
+    pessimisticEstimate: Simulation.Result<T>;
+    optimisticGraph: Graph.Node<T>;
+    pessimisticGraph: Graph.Node;
+}
+export interface Extras {
+    optimistic: boolean;
+    fcpResult?: MetricResult;
+    lcpResult?: MetricResult;
+    interactiveResult?: MetricResult;
+    observedSpeedIndex?: number;
+}
+declare class Metric {
+    static getScriptUrls(dependencyGraph: Graph.Node, treatNodeAsRenderBlocking?: (node: Graph.NetworkNode) => boolean): Set<string>;
+    static get coefficients(): MetricCoefficients;
+    /**
+     * Returns the coefficients, scaled by the throttling settings if needed by the metric.
+     * Some lantern metrics (speed-index) use components in their estimate that are not
+     * from the simulator. In this case, we need to adjust the coefficients as the target throttling
+     * settings change.
+     */
+    static getScaledCoefficients(rttMs: number): MetricCoefficients;
+    static getOptimisticGraph(dependencyGraph: Graph.Node, processedNavigation: Types.Simulation.ProcessedNavigation): Graph.Node;
+    static getPessimisticGraph(dependencyGraph: Graph.Node, processedNavigation: Types.Simulation.ProcessedNavigation): Graph.Node;
+    static getEstimateFromSimulation(simulationResult: Simulation.Result, extras: Extras): Simulation.Result;
+    static compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): Promise<MetricResult>;
+}
+export { Metric };

package/models/trace/lantern/metrics/Metric.js

@@ -0,0 +1,70 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Graph from '../graph/graph.js';
+class Metric {
+    static getScriptUrls(dependencyGraph, treatNodeAsRenderBlocking) {
+        const scriptUrls = new Set();
+        dependencyGraph.traverse(node => {
+            if (node.type !== Graph.BaseNode.types.NETWORK) {
+                return;
+            }
+            if (node.request.resourceType !== 'Script') {
+                return;
+            }
+            if (treatNodeAsRenderBlocking?.(node)) {
+                scriptUrls.add(node.request.url);
+            }
+        });
+        return scriptUrls;
+    }
+    static get coefficients() {
+        throw new Error('coefficients unimplemented!');
+    }
+    /* eslint-disable @typescript-eslint/no-unused-vars */
+    /**
+     * Returns the coefficients, scaled by the throttling settings if needed by the metric.
+     * Some lantern metrics (speed-index) use components in their estimate that are not
+     * from the simulator. In this case, we need to adjust the coefficients as the target throttling
+     * settings change.
+     */
+    static getScaledCoefficients(rttMs) {
+        return this.coefficients;
+    }
+    static getOptimisticGraph(dependencyGraph, processedNavigation) {
+        throw new Error('Optimistic graph unimplemented!');
+    }
+    static getPessimisticGraph(dependencyGraph, processedNavigation) {
+        throw new Error('Pessmistic graph unimplemented!');
+    }
+    static getEstimateFromSimulation(simulationResult, extras) {
+        return simulationResult;
+    }
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    static async compute(data, extras) {
+        const { simulator, graph, processedNavigation } = data;
+        const metricName = this.name.replace('Lantern', '');
+        const optimisticGraph = this.getOptimisticGraph(graph, processedNavigation);
+        const pessimisticGraph = this.getPessimisticGraph(graph, processedNavigation);
+        let simulateOptions = { label: `optimistic${metricName}` };
+        const optimisticSimulation = simulator.simulate(optimisticGraph, simulateOptions);
+        simulateOptions = { label: `pessimistic${metricName}` };
+        const pessimisticSimulation = simulator.simulate(pessimisticGraph, simulateOptions);
+        const optimisticEstimate = this.getEstimateFromSimulation(optimisticSimulation, { ...extras, optimistic: true });
+        const pessimisticEstimate = this.getEstimateFromSimulation(pessimisticSimulation, { ...extras, optimistic: false });
+        const coefficients = this.getScaledCoefficients(simulator.rtt);
+        // Estimates under 1s don't really follow the normal curve fit, minimize the impact of the intercept
+        const interceptMultiplier = coefficients.intercept > 0 ? Math.min(1, optimisticEstimate.timeInMs / 1000) : 1;
+        const timing = coefficients.intercept * interceptMultiplier +
+            coefficients.optimistic * optimisticEstimate.timeInMs + coefficients.pessimistic * pessimisticEstimate.timeInMs;
+        return {
+            timing,
+            optimisticEstimate,
+            pessimisticEstimate,
+            optimisticGraph,
+            pessimisticGraph,
+        };
+    }
+}
+export { Metric };
+//# sourceMappingURL=Metric.js.map

package/models/trace/lantern/metrics/Metric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Metric.js","sourceRoot":"","sources":["../../../../../../../../front_end/models/trace/lantern/metrics/Metric.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nimport * as Graph from '../graph/graph.js';\nimport type * as Simulation from '../simulation/simulation.js';\nimport type * as Types from '../types/types.js';\n\nexport interface MetricComputationDataInput {\n  simulator: Simulation.Simulator;\n  graph: Graph.Node<unknown>;\n  processedNavigation: Types.Simulation.ProcessedNavigation;\n}\n\nexport interface MetricCoefficients {\n  intercept: number;\n  optimistic: number;\n  pessimistic: number;\n}\n\nexport interface MetricResult<T = Types.AnyNetworkObject> {\n  timing: number;\n  timestamp?: never;\n  optimisticEstimate: Simulation.Result<T>;\n  pessimisticEstimate: Simulation.Result<T>;\n  optimisticGraph: Graph.Node<T>;\n  pessimisticGraph: Graph.Node;\n}\n\nexport interface Extras {\n  optimistic: boolean;\n  fcpResult?: MetricResult;\n  lcpResult?: MetricResult;\n  interactiveResult?: MetricResult;\n  observedSpeedIndex?: number;\n}\n\nclass Metric {\n  static getScriptUrls(dependencyGraph: Graph.Node, treatNodeAsRenderBlocking?: (node: Graph.NetworkNode) => boolean):\n      Set<string> {\n    const scriptUrls: Set<string> = new Set();\n\n    dependencyGraph.traverse(node => {\n      if (node.type !== Graph.BaseNode.types.NETWORK) {\n        return;\n      }\n      if (node.request.resourceType !== 'Script') {\n        return;\n      }\n      if (treatNodeAsRenderBlocking?.(node)) {\n        scriptUrls.add(node.request.url);\n      }\n    });\n\n    return scriptUrls;\n  }\n\n  static get coefficients(): MetricCoefficients {\n    throw new Error('coefficients unimplemented!');\n  }\n\n  /* eslint-disable @typescript-eslint/no-unused-vars */\n\n  /**\n   * Returns the coefficients, scaled by the throttling settings if needed by the metric.\n   * Some lantern metrics (speed-index) use components in their estimate that are not\n   * from the simulator. In this case, we need to adjust the coefficients as the target throttling\n   * settings change.\n   */\n  static getScaledCoefficients(rttMs: number): MetricCoefficients {\n    return this.coefficients;\n  }\n\n  static getOptimisticGraph(dependencyGraph: Graph.Node, processedNavigation: Types.Simulation.ProcessedNavigation):\n      Graph.Node {\n    throw new Error('Optimistic graph unimplemented!');\n  }\n\n  static getPessimisticGraph(dependencyGraph: Graph.Node, processedNavigation: Types.Simulation.ProcessedNavigation):\n      Graph.Node {\n    throw new Error('Pessmistic graph unimplemented!');\n  }\n\n  static getEstimateFromSimulation(simulationResult: Simulation.Result, extras: Extras): Simulation.Result {\n    return simulationResult;\n  }\n\n  /* eslint-enable @typescript-eslint/no-unused-vars */\n\n  static async compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): Promise<MetricResult> {\n    const {simulator, graph, processedNavigation} = data;\n\n    const metricName = this.name.replace('Lantern', '');\n    const optimisticGraph = this.getOptimisticGraph(graph, processedNavigation);\n    const pessimisticGraph = this.getPessimisticGraph(graph, processedNavigation);\n\n    let simulateOptions = {label: `optimistic${metricName}`};\n    const optimisticSimulation = simulator.simulate(optimisticGraph, simulateOptions);\n\n    simulateOptions = {label: `pessimistic${metricName}`};\n    const pessimisticSimulation = simulator.simulate(pessimisticGraph, simulateOptions);\n\n    const optimisticEstimate = this.getEstimateFromSimulation(\n        optimisticSimulation,\n        {...extras, optimistic: true},\n    );\n\n    const pessimisticEstimate = this.getEstimateFromSimulation(\n        pessimisticSimulation,\n        {...extras, optimistic: false},\n    );\n\n    const coefficients = this.getScaledCoefficients(simulator.rtt);\n    // Estimates under 1s don't really follow the normal curve fit, minimize the impact of the intercept\n    const interceptMultiplier = coefficients.intercept > 0 ? Math.min(1, optimisticEstimate.timeInMs / 1000) : 1;\n    const timing = coefficients.intercept * interceptMultiplier +\n        coefficients.optimistic * optimisticEstimate.timeInMs + coefficients.pessimistic * pessimisticEstimate.timeInMs;\n\n    return {\n      timing,\n      optimisticEstimate,\n      pessimisticEstimate,\n      optimisticGraph,\n      pessimisticGraph,\n    };\n  }\n}\n\nexport {Metric};\n"]}

package/models/trace/lantern/metrics/SpeedIndex.d.ts

@@ -0,0 +1,25 @@
+import * as Graph from '../graph/graph.js';
+import type * as Simulation from '../simulation/simulation.js';
+import { type Extras, Metric, type MetricCoefficients, type MetricComputationDataInput, type MetricResult } from './Metric.js';
+declare class SpeedIndex extends Metric {
+    static get coefficients(): MetricCoefficients;
+    static getScaledCoefficients(rttMs: number): MetricCoefficients;
+    static getOptimisticGraph(dependencyGraph: Graph.Node): Graph.Node;
+    static getPessimisticGraph(dependencyGraph: Graph.Node): Graph.Node;
+    static getEstimateFromSimulation(simulationResult: Simulation.Result, extras: Extras): Simulation.Result;
+    static compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): Promise<MetricResult>;
+    /**
+     * Approximate speed index using layout events from the simulated node timings.
+     * The layout-based speed index is the weighted average of the endTime of CPU nodes that contained
+     * a 'Layout' task. log(duration) is used as the weight to stand for "significance" to the page.
+     *
+     * If no layout events can be found or the endTime of a CPU task is too early, FCP is used instead.
+     *
+     * This approach was determined after evaluating the accuracy/complexity tradeoff of many
+     * different methods. Read more in the evaluation doc.
+     *
+     * @see https://docs.google.com/document/d/1qJWXwxoyVLVadezIp_Tgdk867G3tDNkkVRvUJSH3K1E/edit#
+     */
+    static computeLayoutBasedSpeedIndex(nodeTimings: Simulation.Result['nodeTimings'], fcpTimeInMs: number): number;
+}
+export { SpeedIndex };

package/models/trace/lantern/metrics/SpeedIndex.js

@@ -0,0 +1,101 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Graph from '../graph/graph.js';
+import { Metric, } from './Metric.js';
+const mobileSlow4GRtt = 150;
+class SpeedIndex extends Metric {
+    static get coefficients() {
+        return {
+            // Note that the optimistic estimate is based on the real observed speed index rather than a
+            // real lantern graph (and the final estimate will be Math.max(FCP, Speed Index)).
+            intercept: 0,
+            optimistic: 1.4,
+            pessimistic: 0.4,
+        };
+    }
+    static getScaledCoefficients(rttMs) {
+        // We want to scale our default coefficients based on the speed of the connection.
+        // We will linearly interpolate coefficients for the passed-in rttMs based on two pre-determined points:
+        //   1. Baseline point of 30 ms RTT where Speed Index should be a ~50/50 blend of optimistic/pessimistic.
+        //      30 ms was based on a typical home WiFi connection's actual RTT.
+        //      Coefficients here follow from the fact that the optimistic estimate should be very close
+        //      to reality at this connection speed and the pessimistic estimate compensates for minor
+        //      connection speed differences.
+        //   2. Default throttled point of 150 ms RTT where the default coefficients have been determined to be most accurate.
+        //      Coefficients here were determined through thorough analysis and linear regression on the
+        //      lantern test data set. See core/scripts/test-lantern.sh for more detail.
+        // While the coefficients haven't been analyzed at the interpolated points, it's our current best effort.
+        const defaultCoefficients = this.coefficients;
+        const defaultRttExcess = mobileSlow4GRtt - 30;
+        const multiplier = Math.max((rttMs - 30) / defaultRttExcess, 0);
+        return {
+            intercept: defaultCoefficients.intercept * multiplier,
+            optimistic: 0.5 + (defaultCoefficients.optimistic - 0.5) * multiplier,
+            pessimistic: 0.5 + (defaultCoefficients.pessimistic - 0.5) * multiplier,
+        };
+    }
+    static getOptimisticGraph(dependencyGraph) {
+        return dependencyGraph;
+    }
+    static getPessimisticGraph(dependencyGraph) {
+        return dependencyGraph;
+    }
+    static getEstimateFromSimulation(simulationResult, extras) {
+        if (!extras.fcpResult) {
+            throw new Error('missing fcpResult');
+        }
+        if (extras.observedSpeedIndex === undefined) {
+            throw new Error('missing observedSpeedIndex');
+        }
+        const fcpTimeInMs = extras.fcpResult.pessimisticEstimate.timeInMs;
+        const estimate = extras.optimistic ?
+            extras.observedSpeedIndex :
+            SpeedIndex.computeLayoutBasedSpeedIndex(simulationResult.nodeTimings, fcpTimeInMs);
+        return {
+            timeInMs: estimate,
+            nodeTimings: simulationResult.nodeTimings,
+        };
+    }
+    static async compute(data, extras) {
+        const fcpResult = extras?.fcpResult;
+        if (!fcpResult) {
+            throw new Error('FCP is required to calculate the SpeedIndex metric');
+        }
+        const metricResult = await super.compute(data, extras);
+        metricResult.timing = Math.max(metricResult.timing, fcpResult.timing);
+        return metricResult;
+    }
+    /**
+     * Approximate speed index using layout events from the simulated node timings.
+     * The layout-based speed index is the weighted average of the endTime of CPU nodes that contained
+     * a 'Layout' task. log(duration) is used as the weight to stand for "significance" to the page.
+     *
+     * If no layout events can be found or the endTime of a CPU task is too early, FCP is used instead.
+     *
+     * This approach was determined after evaluating the accuracy/complexity tradeoff of many
+     * different methods. Read more in the evaluation doc.
+     *
+     * @see https://docs.google.com/document/d/1qJWXwxoyVLVadezIp_Tgdk867G3tDNkkVRvUJSH3K1E/edit#
+     */
+    static computeLayoutBasedSpeedIndex(nodeTimings, fcpTimeInMs) {
+        const layoutWeights = [];
+        for (const [node, timing] of nodeTimings.entries()) {
+            if (node.type !== Graph.BaseNode.types.CPU) {
+                continue;
+            }
+            if (node.childEvents.some(x => x.name === 'Layout')) {
+                const timingWeight = Math.max(Math.log2(timing.endTime - timing.startTime), 0);
+                layoutWeights.push({ time: timing.endTime, weight: timingWeight });
+            }
+        }
+        const totalWeightedTime = layoutWeights.map(evt => evt.weight * Math.max(evt.time, fcpTimeInMs)).reduce((a, b) => a + b, 0);
+        const totalWeight = layoutWeights.map(evt => evt.weight).reduce((a, b) => a + b, 0);
+        if (!totalWeight) {
+            return fcpTimeInMs;
+        }
+        return totalWeightedTime / totalWeight;
+    }
+}
+export { SpeedIndex };
+//# sourceMappingURL=SpeedIndex.js.map

package/models/trace/lantern/metrics/SpeedIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpeedIndex.js","sourceRoot":"","sources":["../../../../../../../../front_end/models/trace/lantern/metrics/SpeedIndex.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAE7B,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAEL,MAAM,GAIP,MAAM,aAAa,CAAC;AAErB,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,MAAM,UAAW,SAAQ,MAAM;IAC7B,MAAM,KAAc,YAAY;QAC9B,OAAO;YACL,4FAA4F;YAC5F,kFAAkF;YAClF,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,GAAG;YACf,WAAW,EAAE,GAAG;SACjB,CAAC;IACJ,CAAC;IAED,MAAM,CAAU,qBAAqB,CAAC,KAAa;QACjD,kFAAkF;QAClF,wGAAwG;QACxG,yGAAyG;QACzG,uEAAuE;QACvE,gGAAgG;QAChG,8FAA8F;QAC9F,qCAAqC;QACrC,sHAAsH;QACtH,gGAAgG;QAChG,gFAAgF;QAChF,yGAAyG;QACzG,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,CAAC;QAC9C,MAAM,gBAAgB,GAAG,eAAe,GAAG,EAAE,CAAC;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,CAAC,CAAC;QAEhE,OAAO;YACL,SAAS,EAAE,mBAAmB,CAAC,SAAS,GAAG,UAAU;YACrD,UAAU,EAAE,GAAG,GAAG,CAAC,mBAAmB,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,UAAU;YACrE,WAAW,EAAE,GAAG,GAAG,CAAC,mBAAmB,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,UAAU;SACxE,CAAC;IACJ,CAAC;IAED,MAAM,CAAU,kBAAkB,CAAC,eAA2B;QAC5D,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,MAAM,CAAU,mBAAmB,CAAC,eAA2B;QAC7D,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,MAAM,CAAU,yBAAyB,CAAC,gBAAmC,EAAE,MAAc;QAC3F,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,MAAM,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,mBAAmB,CAAC,QAAQ,CAAC;QAClE,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;YAChC,MAAM,CAAC,kBAAkB,CAAC,CAAC;YAC3B,UAAU,CAAC,4BAA4B,CAAC,gBAAgB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACvF,OAAO;YACL,QAAQ,EAAE,QAAQ;YAClB,WAAW,EAAE,gBAAgB,CAAC,WAAW;SAC1C,CAAC;IACJ,CAAC;IAED,MAAM,CAAU,KAAK,CAAC,OAAO,CAAC,IAAgC,EAAE,MAAmC;QAEjG,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,CAAC;QACpC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,YAAY,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACvD,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QACtE,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,4BAA4B,CAAC,WAA6C,EAAE,WAAmB;QACpG,MAAM,aAAa,GAA0C,EAAE,CAAC;QAChE,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;YACnD,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;gBAC3C,SAAS;YACX,CAAC;YAED,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACpD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC/E,aAAa,CAAC,IAAI,CAAC,EAAC,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAC,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;QAED,MAAM,iBAAiB,GACnB,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACtG,MAAM,WAAW,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QAEpF,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,OAAO,iBAAiB,GAAG,WAAW,CAAC;IACzC,CAAC;CACF;AAED,OAAO,EAAC,UAAU,EAAC,CAAC","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nimport * as Graph from '../graph/graph.js';\nimport type * as Simulation from '../simulation/simulation.js';\n\nimport {\n  type Extras,\n  Metric,\n  type MetricCoefficients,\n  type MetricComputationDataInput,\n  type MetricResult,\n} from './Metric.js';\n\nconst mobileSlow4GRtt = 150;\n\nclass SpeedIndex extends Metric {\n  static override get coefficients(): MetricCoefficients {\n    return {\n      // Note that the optimistic estimate is based on the real observed speed index rather than a\n      // real lantern graph (and the final estimate will be Math.max(FCP, Speed Index)).\n      intercept: 0,\n      optimistic: 1.4,\n      pessimistic: 0.4,\n    };\n  }\n\n  static override getScaledCoefficients(rttMs: number): MetricCoefficients {\n    // We want to scale our default coefficients based on the speed of the connection.\n    // We will linearly interpolate coefficients for the passed-in rttMs based on two pre-determined points:\n    //   1. Baseline point of 30 ms RTT where Speed Index should be a ~50/50 blend of optimistic/pessimistic.\n    //      30 ms was based on a typical home WiFi connection's actual RTT.\n    //      Coefficients here follow from the fact that the optimistic estimate should be very close\n    //      to reality at this connection speed and the pessimistic estimate compensates for minor\n    //      connection speed differences.\n    //   2. Default throttled point of 150 ms RTT where the default coefficients have been determined to be most accurate.\n    //      Coefficients here were determined through thorough analysis and linear regression on the\n    //      lantern test data set. See core/scripts/test-lantern.sh for more detail.\n    // While the coefficients haven't been analyzed at the interpolated points, it's our current best effort.\n    const defaultCoefficients = this.coefficients;\n    const defaultRttExcess = mobileSlow4GRtt - 30;\n    const multiplier = Math.max((rttMs - 30) / defaultRttExcess, 0);\n\n    return {\n      intercept: defaultCoefficients.intercept * multiplier,\n      optimistic: 0.5 + (defaultCoefficients.optimistic - 0.5) * multiplier,\n      pessimistic: 0.5 + (defaultCoefficients.pessimistic - 0.5) * multiplier,\n    };\n  }\n\n  static override getOptimisticGraph(dependencyGraph: Graph.Node): Graph.Node {\n    return dependencyGraph;\n  }\n\n  static override getPessimisticGraph(dependencyGraph: Graph.Node): Graph.Node {\n    return dependencyGraph;\n  }\n\n  static override getEstimateFromSimulation(simulationResult: Simulation.Result, extras: Extras): Simulation.Result {\n    if (!extras.fcpResult) {\n      throw new Error('missing fcpResult');\n    }\n    if (extras.observedSpeedIndex === undefined) {\n      throw new Error('missing observedSpeedIndex');\n    }\n\n    const fcpTimeInMs = extras.fcpResult.pessimisticEstimate.timeInMs;\n    const estimate = extras.optimistic ?\n        extras.observedSpeedIndex :\n        SpeedIndex.computeLayoutBasedSpeedIndex(simulationResult.nodeTimings, fcpTimeInMs);\n    return {\n      timeInMs: estimate,\n      nodeTimings: simulationResult.nodeTimings,\n    };\n  }\n\n  static override async compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>):\n      Promise<MetricResult> {\n    const fcpResult = extras?.fcpResult;\n    if (!fcpResult) {\n      throw new Error('FCP is required to calculate the SpeedIndex metric');\n    }\n\n    const metricResult = await super.compute(data, extras);\n    metricResult.timing = Math.max(metricResult.timing, fcpResult.timing);\n    return metricResult;\n  }\n\n  /**\n   * Approximate speed index using layout events from the simulated node timings.\n   * The layout-based speed index is the weighted average of the endTime of CPU nodes that contained\n   * a 'Layout' task. log(duration) is used as the weight to stand for \"significance\" to the page.\n   *\n   * If no layout events can be found or the endTime of a CPU task is too early, FCP is used instead.\n   *\n   * This approach was determined after evaluating the accuracy/complexity tradeoff of many\n   * different methods. Read more in the evaluation doc.\n   *\n   * @see https://docs.google.com/document/d/1qJWXwxoyVLVadezIp_Tgdk867G3tDNkkVRvUJSH3K1E/edit#\n   */\n  static computeLayoutBasedSpeedIndex(nodeTimings: Simulation.Result['nodeTimings'], fcpTimeInMs: number): number {\n    const layoutWeights: Array<{time: number, weight: number}> = [];\n    for (const [node, timing] of nodeTimings.entries()) {\n      if (node.type !== Graph.BaseNode.types.CPU) {\n        continue;\n      }\n\n      if (node.childEvents.some(x => x.name === 'Layout')) {\n        const timingWeight = Math.max(Math.log2(timing.endTime - timing.startTime), 0);\n        layoutWeights.push({time: timing.endTime, weight: timingWeight});\n      }\n    }\n\n    const totalWeightedTime =\n        layoutWeights.map(evt => evt.weight * Math.max(evt.time, fcpTimeInMs)).reduce((a, b) => a + b, 0);\n    const totalWeight = layoutWeights.map(evt => evt.weight).reduce((a, b) => a + b, 0);\n\n    if (!totalWeight) {\n      return fcpTimeInMs;\n    }\n    return totalWeightedTime / totalWeight;\n  }\n}\n\nexport {SpeedIndex};\n"]}

package/models/trace/lantern/metrics/TBTUtils.d.ts

@@ -0,0 +1,31 @@
+declare const BLOCKING_TIME_THRESHOLD = 50;
+/**
+ * For TBT, We only want to consider tasks that fall in our time range
+ * - FCP and TTI for navigation mode
+ * - Trace start and trace end for timespan mode
+ *
+ * FCP is picked as `startTimeMs` because there is little risk of user input happening
+ * before FCP so Long Queuing Qelay regions do not harm user experience. Developers should be
+ * optimizing to reach FCP as fast as possible without having to worry about task lengths.
+ *
+ * TTI is picked as `endTimeMs` because we want a well defined end point for page load.
+ *
+ * @param startTimeMs Should be FCP in navigation mode and the trace start time in timespan mode
+ * @param endTimeMs Should be TTI in navigation mode and the trace end time in timespan mode
+ * @param topLevelEvent Leave unset if `event` is top level. Has no effect if `event` has the same duration as `topLevelEvent`.
+ */
+declare function calculateTbtImpactForEvent(event: {
+    start: number;
+    end: number;
+    duration: number;
+}, startTimeMs: number, endTimeMs: number, topLevelEvent?: {
+    start: number;
+    end: number;
+    duration: number;
+}): number;
+declare function calculateSumOfBlockingTime(topLevelEvents: Array<{
+    start: number;
+    end: number;
+    duration: number;
+}>, startTimeMs: number, endTimeMs: number): number;
+export { BLOCKING_TIME_THRESHOLD, calculateSumOfBlockingTime, calculateTbtImpactForEvent, };

package/models/trace/lantern/metrics/TBTUtils.js

@@ -0,0 +1,65 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+const BLOCKING_TIME_THRESHOLD = 50;
+/**
+ * For TBT, We only want to consider tasks that fall in our time range
+ * - FCP and TTI for navigation mode
+ * - Trace start and trace end for timespan mode
+ *
+ * FCP is picked as `startTimeMs` because there is little risk of user input happening
+ * before FCP so Long Queuing Qelay regions do not harm user experience. Developers should be
+ * optimizing to reach FCP as fast as possible without having to worry about task lengths.
+ *
+ * TTI is picked as `endTimeMs` because we want a well defined end point for page load.
+ *
+ * @param startTimeMs Should be FCP in navigation mode and the trace start time in timespan mode
+ * @param endTimeMs Should be TTI in navigation mode and the trace end time in timespan mode
+ * @param topLevelEvent Leave unset if `event` is top level. Has no effect if `event` has the same duration as `topLevelEvent`.
+ */
+function calculateTbtImpactForEvent(event, startTimeMs, endTimeMs, topLevelEvent) {
+    let threshold = BLOCKING_TIME_THRESHOLD;
+    // If a task is not top level, it doesn't make sense to subtract the entire 50ms
+    // blocking threshold from the event.
+    //
+    // e.g. A 80ms top level task with two 40ms children should attribute some blocking
+    // time to the 40ms tasks even though they do not meet the 50ms threshold.
+    //
+    // The solution is to scale the threshold for child events to be considered blocking.
+    if (topLevelEvent) {
+        threshold *= (event.duration / topLevelEvent.duration);
+    }
+    if (event.duration < threshold) {
+        return 0;
+    }
+    if (event.end < startTimeMs) {
+        return 0;
+    }
+    if (event.start > endTimeMs) {
+        return 0;
+    }
+    // Perform the clipping and then calculate Blocking Region. So if we have a 150ms task
+    // [0, 150] and `startTimeMs` is at 50ms, we first clip the task to [50, 150], and then
+    // calculate the Blocking Region to be [100, 150]. The rational here is that tasks before
+    // the start time are unimportant, so we care whether the main thread is busy more than
+    // 50ms at a time only after the start time.
+    const clippedStart = Math.max(event.start, startTimeMs);
+    const clippedEnd = Math.min(event.end, endTimeMs);
+    const clippedDuration = clippedEnd - clippedStart;
+    if (clippedDuration < threshold) {
+        return 0;
+    }
+    return clippedDuration - threshold;
+}
+function calculateSumOfBlockingTime(topLevelEvents, startTimeMs, endTimeMs) {
+    if (endTimeMs <= startTimeMs) {
+        return 0;
+    }
+    let sumBlockingTime = 0;
+    for (const event of topLevelEvents) {
+        sumBlockingTime += calculateTbtImpactForEvent(event, startTimeMs, endTimeMs);
+    }
+    return sumBlockingTime;
+}
+export { BLOCKING_TIME_THRESHOLD, calculateSumOfBlockingTime, calculateTbtImpactForEvent, };
+//# sourceMappingURL=TBTUtils.js.map

package/models/trace/lantern/metrics/TBTUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TBTUtils.js","sourceRoot":"","sources":["../../../../../../../../front_end/models/trace/lantern/metrics/TBTUtils.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAE7B,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,SAAS,0BAA0B,CAC/B,KAAqD,EAAE,WAAmB,EAAE,SAAiB,EAC7F,aAA8D;IAChE,IAAI,SAAS,GAAG,uBAAuB,CAAC;IAExC,gFAAgF;IAChF,qCAAqC;IACrC,EAAE;IACF,mFAAmF;IACnF,0EAA0E;IAC1E,EAAE;IACF,qFAAqF;IACrF,IAAI,aAAa,EAAE,CAAC;QAClB,SAAS,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,KAAK,CAAC,QAAQ,GAAG,SAAS,EAAE,CAAC;QAC/B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,CAAC,GAAG,GAAG,WAAW,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,sFAAsF;IACtF,uFAAuF;IACvF,yFAAyF;IACzF,uFAAuF;IACvF,4CAA4C;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACxD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAClD,MAAM,eAAe,GAAG,UAAU,GAAG,YAAY,CAAC;IAClD,IAAI,eAAe,GAAG,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,eAAe,GAAG,SAAS,CAAC;AACrC,CAAC;AAED,SAAS,0BAA0B,CAC/B,cAAqE,EAAE,WAAmB,EAC1F,SAAiB;IACnB,IAAI,SAAS,IAAI,WAAW,EAAE,CAAC;QAC7B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,eAAe,IAAI,0BAA0B,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,0BAA0B,GAC3B,CAAC","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nconst BLOCKING_TIME_THRESHOLD = 50;\n\n/**\n * For TBT, We only want to consider tasks that fall in our time range\n * - FCP and TTI for navigation mode\n * - Trace start and trace end for timespan mode\n *\n * FCP is picked as `startTimeMs` because there is little risk of user input happening\n * before FCP so Long Queuing Qelay regions do not harm user experience. Developers should be\n * optimizing to reach FCP as fast as possible without having to worry about task lengths.\n *\n * TTI is picked as `endTimeMs` because we want a well defined end point for page load.\n *\n * @param startTimeMs Should be FCP in navigation mode and the trace start time in timespan mode\n * @param endTimeMs Should be TTI in navigation mode and the trace end time in timespan mode\n * @param topLevelEvent Leave unset if `event` is top level. Has no effect if `event` has the same duration as `topLevelEvent`.\n */\nfunction calculateTbtImpactForEvent(\n    event: {start: number, end: number, duration: number}, startTimeMs: number, endTimeMs: number,\n    topLevelEvent?: {start: number, end: number, duration: number}): number {\n  let threshold = BLOCKING_TIME_THRESHOLD;\n\n  // If a task is not top level, it doesn't make sense to subtract the entire 50ms\n  // blocking threshold from the event.\n  //\n  // e.g. A 80ms top level task with two 40ms children should attribute some blocking\n  // time to the 40ms tasks even though they do not meet the 50ms threshold.\n  //\n  // The solution is to scale the threshold for child events to be considered blocking.\n  if (topLevelEvent) {\n    threshold *= (event.duration / topLevelEvent.duration);\n  }\n\n  if (event.duration < threshold) {\n    return 0;\n  }\n  if (event.end < startTimeMs) {\n    return 0;\n  }\n  if (event.start > endTimeMs) {\n    return 0;\n  }\n\n  // Perform the clipping and then calculate Blocking Region. So if we have a 150ms task\n  // [0, 150] and `startTimeMs` is at 50ms, we first clip the task to [50, 150], and then\n  // calculate the Blocking Region to be [100, 150]. The rational here is that tasks before\n  // the start time are unimportant, so we care whether the main thread is busy more than\n  // 50ms at a time only after the start time.\n  const clippedStart = Math.max(event.start, startTimeMs);\n  const clippedEnd = Math.min(event.end, endTimeMs);\n  const clippedDuration = clippedEnd - clippedStart;\n  if (clippedDuration < threshold) {\n    return 0;\n  }\n\n  return clippedDuration - threshold;\n}\n\nfunction calculateSumOfBlockingTime(\n    topLevelEvents: Array<{start: number, end: number, duration: number}>, startTimeMs: number,\n    endTimeMs: number): number {\n  if (endTimeMs <= startTimeMs) {\n    return 0;\n  }\n\n  let sumBlockingTime = 0;\n  for (const event of topLevelEvents) {\n    sumBlockingTime += calculateTbtImpactForEvent(event, startTimeMs, endTimeMs);\n  }\n\n  return sumBlockingTime;\n}\n\nexport {\n  BLOCKING_TIME_THRESHOLD,\n  calculateSumOfBlockingTime,\n  calculateTbtImpactForEvent,\n};\n"]}

package/models/trace/lantern/metrics/TotalBlockingTime.d.ts

@@ -0,0 +1,16 @@
+import * as Graph from '../graph/graph.js';
+import type * as Simulation from '../simulation/simulation.js';
+import { type Extras, Metric, type MetricCoefficients, type MetricComputationDataInput, type MetricResult } from './Metric.js';
+declare class TotalBlockingTime extends Metric {
+    static get coefficients(): MetricCoefficients;
+    static getOptimisticGraph(dependencyGraph: Graph.Node): Graph.Node;
+    static getPessimisticGraph(dependencyGraph: Graph.Node): Graph.Node;
+    static getEstimateFromSimulation(simulation: Simulation.Result, extras: Extras): Simulation.Result;
+    static compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): Promise<MetricResult>;
+    static getTopLevelEvents(nodeTimings: Simulation.Result['nodeTimings'], minDurationMs: number): {
+        start: number;
+        end: number;
+        duration: number;
+    }[];
+}
+export { TotalBlockingTime };

package/models/trace/lantern/metrics/TotalBlockingTime.js

@@ -0,0 +1,78 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Graph from '../graph/graph.js';
+import { Metric, } from './Metric.js';
+import { BLOCKING_TIME_THRESHOLD, calculateSumOfBlockingTime } from './TBTUtils.js';
+class TotalBlockingTime extends Metric {
+    static get coefficients() {
+        return {
+            intercept: 0,
+            optimistic: 0.5,
+            pessimistic: 0.5,
+        };
+    }
+    static getOptimisticGraph(dependencyGraph) {
+        return dependencyGraph;
+    }
+    static getPessimisticGraph(dependencyGraph) {
+        return dependencyGraph;
+    }
+    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 = TotalBlockingTime.getTopLevelEvents(simulation.nodeTimings, minDurationMs);
+        return {
+            timeInMs: calculateSumOfBlockingTime(events, fcpTimeInMs, interactiveTimeMs),
+            nodeTimings: simulation.nodeTimings,
+        };
+    }
+    static async compute(data, extras) {
+        const fcpResult = extras?.fcpResult;
+        if (!fcpResult) {
+            throw new Error('FCP is required to calculate the TBT metric');
+        }
+        const interactiveResult = extras?.fcpResult;
+        if (!interactiveResult) {
+            throw new Error('Interactive is required to calculate the TBT metric');
+        }
+        return super.compute(data, extras);
+    }
+    static getTopLevelEvents(nodeTimings, minDurationMs) {
+        const events = [];
+        for (const [node, timing] of nodeTimings.entries()) {
+            if (node.type !== Graph.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;
+    }
+}
+export { TotalBlockingTime };
+//# sourceMappingURL=TotalBlockingTime.js.map

package/models/trace/lantern/metrics/TotalBlockingTime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TotalBlockingTime.js","sourceRoot":"","sources":["../../../../../../../../front_end/models/trace/lantern/metrics/TotalBlockingTime.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nimport * as Graph from '../graph/graph.js';\nimport type * as Simulation from '../simulation/simulation.js';\n\nimport {\n  type Extras,\n  Metric,\n  type MetricCoefficients,\n  type MetricComputationDataInput,\n  type MetricResult,\n} from './Metric.js';\nimport {BLOCKING_TIME_THRESHOLD, calculateSumOfBlockingTime} from './TBTUtils.js';\n\nclass TotalBlockingTime extends Metric {\n  static override get coefficients(): MetricCoefficients {\n    return {\n      intercept: 0,\n      optimistic: 0.5,\n      pessimistic: 0.5,\n    };\n  }\n\n  static override getOptimisticGraph(dependencyGraph: Graph.Node): Graph.Node {\n    return dependencyGraph;\n  }\n\n  static override getPessimisticGraph(dependencyGraph: Graph.Node): Graph.Node {\n    return dependencyGraph;\n  }\n\n  static override getEstimateFromSimulation(simulation: Simulation.Result, extras: Extras): Simulation.Result {\n    if (!extras.fcpResult) {\n      throw new Error('missing fcpResult');\n    }\n    if (!extras.interactiveResult) {\n      throw new Error('missing interactiveResult');\n    }\n\n    // Intentionally use the opposite FCP estimate. A pessimistic FCP is higher than equal to an\n    // optimistic FCP, which means potentially more tasks are excluded from the Total Blocking Time\n    // computation. So a more pessimistic FCP gives a more optimistic Total Blocking Time for the\n    // same work.\n    const fcpTimeInMs = extras.optimistic ? extras.fcpResult.pessimisticEstimate.timeInMs :\n                                            extras.fcpResult.optimisticEstimate.timeInMs;\n\n    // Similarly, we always have pessimistic TTI >= optimistic TTI. Therefore, picking optimistic\n    // TTI means our window of interest is smaller and thus potentially more tasks are excluded from\n    // Total Blocking Time computation, yielding a lower (more optimistic) Total Blocking Time value\n    // for the same work.\n    const interactiveTimeMs = extras.optimistic ? extras.interactiveResult.optimisticEstimate.timeInMs :\n                                                  extras.interactiveResult.pessimisticEstimate.timeInMs;\n\n    const minDurationMs = BLOCKING_TIME_THRESHOLD;\n\n    const events = TotalBlockingTime.getTopLevelEvents(\n        simulation.nodeTimings,\n        minDurationMs,\n    );\n\n    return {\n      timeInMs: calculateSumOfBlockingTime(\n          events,\n          fcpTimeInMs,\n          interactiveTimeMs,\n          ),\n      nodeTimings: simulation.nodeTimings,\n    };\n  }\n\n  static override async compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>):\n      Promise<MetricResult> {\n    const fcpResult = extras?.fcpResult;\n    if (!fcpResult) {\n      throw new Error('FCP is required to calculate the TBT metric');\n    }\n\n    const interactiveResult = extras?.fcpResult;\n    if (!interactiveResult) {\n      throw new Error('Interactive is required to calculate the TBT metric');\n    }\n\n    return super.compute(data, extras);\n  }\n\n  static getTopLevelEvents(nodeTimings: Simulation.Result['nodeTimings'], minDurationMs: number):\n      {start: number, end: number, duration: number}[] {\n    const events: Array<{start: number, end: number, duration: number}> = [];\n\n    for (const [node, timing] of nodeTimings.entries()) {\n      if (node.type !== Graph.BaseNode.types.CPU) {\n        continue;\n      }\n      // Filtering out events below minimum duration.\n      if (timing.duration < minDurationMs) {\n        continue;\n      }\n\n      events.push({\n        start: timing.startTime,\n        end: timing.endTime,\n        duration: timing.duration,\n      });\n    }\n\n    return events;\n  }\n}\n\nexport {TotalBlockingTime};\n"]}

package/models/trace/lantern/metrics/bundle-tsconfig.json

@@ -0,0 +1 @@
+{"compilerOptions":{"composite":true,"outDir":".","baseUrl":".","rootDir":"../../../../../../../../front_end/models/trace/lantern/metrics"},"files":["../../../../../../../../front_end/models/trace/lantern/metrics/metrics.ts"],"references":[{"path":"./metrics-tsconfig.json"}]}

package/models/trace/lantern/metrics/devtools_entrypoint-bundle-typescript-tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "composite": true,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "forceConsistentCasingInFileNames": true,
+    "inlineSources": true,
+    "lib": [
+      "esnext",
+      "dom",
+      "dom.iterable"
+    ],
+    "module": "esnext",
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": false,
+    "outDir": ".",
+    "rootDir": "../../../../../../../../front_end/models/trace/lantern/metrics",
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "esnext",
+    "tsBuildInfoFile": "devtools_entrypoint-bundle-typescript-tsconfig.json.tsbuildinfo",
+    "typeRoots": [],
+    "useUnknownInCatchVariables": false
+  },
+  "files": [
+    "../../../../../../../../front_end/models/trace/lantern/metrics/metrics.ts",
+    "../../../../../../../../front_end/legacy/legacy-defs.d.ts",
+    "../../../../../../../../front_end/global_typings/global_defs.d.ts",
+    "../../../../../../../../node_modules/@types/filesystem/index.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./metrics-tsconfig.json"
+    }
+  ]
+}

package/models/trace/lantern/metrics/metrics-tsconfig.json

@@ -0,0 +1,58 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "composite": true,
+    "declaration": true,
+    "experimentalDecorators": true,
+    "forceConsistentCasingInFileNames": true,
+    "inlineSources": true,
+    "lib": [
+      "esnext",
+      "dom",
+      "dom.iterable"
+    ],
+    "module": "esnext",
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": false,
+    "outDir": ".",
+    "rootDir": "../../../../../../../../front_end/models/trace/lantern/metrics",
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "esnext",
+    "tsBuildInfoFile": "metrics-tsconfig.json.tsbuildinfo",
+    "typeRoots": [],
+    "useUnknownInCatchVariables": false
+  },
+  "files": [
+    "../../../../../../../../front_end/models/trace/lantern/metrics/FirstContentfulPaint.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/Interactive.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/LargestContentfulPaint.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/MaxPotentialFID.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/Metric.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/SpeedIndex.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/TBTUtils.ts",
+    "../../../../../../../../front_end/models/trace/lantern/metrics/TotalBlockingTime.ts",
+    "../../../../../../../../front_end/legacy/legacy-defs.d.ts",
+    "../../../../../../../../front_end/global_typings/global_defs.d.ts",
+    "../../../../../../../../node_modules/@types/filesystem/index.d.ts"
+  ],
+  "references": [
+    {
+      "path": "../core/bundle-tsconfig.json"
+    },
+    {
+      "path": "../graph/bundle-tsconfig.json"
+    },
+    {
+      "path": "../simulation/bundle-tsconfig.json"
+    },
+    {
+      "path": "../types/bundle-tsconfig.json"
+    }
+  ]
+}

package/models/trace/lantern/metrics/metrics.d.ts

@@ -0,0 +1,8 @@
+export * from './FirstContentfulPaint.js';
+export * from './Interactive.js';
+export * from './LargestContentfulPaint.js';
+export * from './MaxPotentialFID.js';
+export * from './Metric.js';
+export * from './SpeedIndex.js';
+export * from './TotalBlockingTime.js';
+export * as TBTUtils from './TBTUtils.js';

package/models/trace/lantern/metrics/metrics.js

@@ -0,0 +1,12 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+export * from './FirstContentfulPaint.js';
+export * from './Interactive.js';
+export * from './LargestContentfulPaint.js';
+export * from './MaxPotentialFID.js';
+export * from './Metric.js';
+export * from './SpeedIndex.js';
+export * from './TotalBlockingTime.js';
+export * as TBTUtils from './TBTUtils.js';
+//# sourceMappingURL=metrics.js.map

package/models/trace/lantern/metrics/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../../../../../../front_end/models/trace/lantern/metrics/metrics.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,yEAAyE;AACzE,6BAA6B;AAE7B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC","sourcesContent":["// Copyright 2024 The Chromium Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style license that can be\n// found in the LICENSE file.\n\nexport * from './FirstContentfulPaint.js';\nexport * from './Interactive.js';\nexport * from './LargestContentfulPaint.js';\nexport * from './MaxPotentialFID.js';\nexport * from './Metric.js';\nexport * from './SpeedIndex.js';\nexport * from './TotalBlockingTime.js';\nexport * as TBTUtils from './TBTUtils.js';\n"]}