devtools-tracing 1.2.1 → 1.2.2

package/dist/lib/front_end/models/trace/lantern/graph/BaseNode.d.ts

@@ -0,0 +1,98 @@
+import type * as Lantern from '../types/types.js';
+import type { CPUNode } from './CPUNode.js';
+import type { NetworkNode } from './NetworkNode.js';
+/**
+ * A union of all types derived from BaseNode, allowing type check discrimination
+ * based on `node.type`. If a new node type is created, it should be added here.
+ */
+export type Node<T = Lantern.AnyNetworkObject> = CPUNode<T> | NetworkNode<T>;
+/**
+ * @file This class encapsulates logic for handling resources and tasks used to model the
+ * execution dependency graph of the page. A node has a unique identifier and can depend on other
+ * nodes/be depended on. The construction of the graph maintains some important invariants that are
+ * inherent to the model:
+ *
+ *    1. The graph is a DAG, there are no cycles.
+ *    2. There is always a root node upon which all other nodes eventually depend.
+ *
+ * This allows particular optimizations in this class so that we do no need to check for cycles as
+ * these methods are called and we can always start traversal at the root node.
+ */
+declare class BaseNode<T = Lantern.AnyNetworkObject> {
+    static types: {
+        readonly NETWORK: "network";
+        readonly CPU: "cpu";
+    };
+    _id: string;
+    _isMainDocument: boolean;
+    dependents: Node[];
+    dependencies: Node[];
+    constructor(id: string);
+    get id(): string;
+    get type(): 'network' | 'cpu';
+    /**
+     * In microseconds
+     */
+    get startTime(): number;
+    /**
+     * In microseconds
+     */
+    get endTime(): number;
+    setIsMainDocument(value: boolean): void;
+    isMainDocument(): boolean;
+    getDependents(): Node[];
+    getNumberOfDependents(): number;
+    getDependencies(): Node[];
+    getNumberOfDependencies(): number;
+    getRootNode(): Node<T>;
+    addDependent(node: Node): void;
+    addDependency(node: Node): void;
+    removeDependent(node: Node): void;
+    removeDependency(node: Node): void;
+    removeAllDependencies(): void;
+    /**
+     * Computes whether the given node is anywhere in the dependency graph of this node.
+     * While this method can prevent cycles, it walks the graph and should be used sparingly.
+     * Nodes are always considered dependent on themselves for the purposes of cycle detection.
+     */
+    isDependentOn(node: BaseNode<T>): boolean;
+    /**
+     * Clones the node's information without adding any dependencies/dependents.
+     */
+    cloneWithoutRelationships(): Node<T>;
+    /**
+     * Clones the entire graph connected to this node filtered by the optional predicate. If a node is
+     * included by the predicate, all nodes along the paths between the node and the root will be included. If the
+     * node this was called on is not included in the resulting filtered graph, the method will throw.
+     *
+     * This does not clone NetworkNode's `record` or `rawRecord` fields. It may be reasonable to clone the former,
+     * to assist in graph construction, but the latter should never be cloned as one constraint of Lantern is that
+     * the underlying data records are accessible for plain object reference equality checks.
+     */
+    cloneWithRelationships(predicate?: (arg0: Node) => boolean): Node;
+    /**
+     * Traverses all connected nodes in BFS order, calling `callback` exactly once
+     * on each. `traversalPath` is the shortest (though not necessarily unique)
+     * path from `node` to the root of the iteration.
+     *
+     * The `getNextNodes` function takes a visited node and returns which nodes to
+     * visit next. It defaults to returning the node's dependents.
+     */
+    traverse(callback: (node: Node<T>, traversalPath: Array<Node<T>>) => void, getNextNodes?: (arg0: Node<T>) => Array<Node<T>>): void;
+    /**
+     * @see BaseNode.traverse
+     */
+    traverseGenerator(getNextNodes?: (arg0: Node) => Node[]): Generator<{
+        node: Node;
+        traversalPath: Node[];
+    }, void, unknown>;
+    /**
+     * If the given node has a cycle, returns a path representing that cycle.
+     * Else returns null.
+     *
+     * Does a DFS on in its dependent graph.
+     */
+    static findCycle(node: Node, direction?: 'dependents' | 'dependencies' | 'both'): BaseNode[] | null;
+    canDependOn(node: Node): boolean;
+}
+export { BaseNode };

package/dist/lib/front_end/models/trace/lantern/graph/CPUNode.d.ts

@@ -0,0 +1,24 @@
+import type * as Lantern from '../types/types.js';
+import { BaseNode } from './BaseNode.js';
+declare class CPUNode<T = Lantern.AnyNetworkObject> extends BaseNode<T> {
+    _event: Lantern.TraceEvent;
+    _childEvents: Lantern.TraceEvent[];
+    correctedEndTs: number | undefined;
+    constructor(parentEvent: Lantern.TraceEvent, childEvents?: Lantern.TraceEvent[], correctedEndTs?: number);
+    get type(): 'cpu';
+    get startTime(): number;
+    get endTime(): number;
+    get duration(): number;
+    get event(): Lantern.TraceEvent;
+    get childEvents(): Lantern.TraceEvent[];
+    /**
+     * Returns true if this node contains a Layout task.
+     */
+    didPerformLayout(): boolean;
+    /**
+     * Returns the script URLs that had their EvaluateScript events occur in this task.
+     */
+    getEvaluateScriptURLs(): Set<string>;
+    cloneWithoutRelationships(): CPUNode;
+}
+export { CPUNode };

package/dist/lib/front_end/models/trace/lantern/graph/NetworkNode.d.ts

@@ -0,0 +1,22 @@
+import type * as Lantern from '../types/types.js';
+import { BaseNode } from './BaseNode.js';
+declare class NetworkNode<T = Lantern.AnyNetworkObject> extends BaseNode<T> {
+    _request: Lantern.NetworkRequest<T>;
+    constructor(networkRequest: Lantern.NetworkRequest<T>);
+    get type(): 'network';
+    get startTime(): number;
+    get endTime(): number;
+    get rawRequest(): Readonly<T>;
+    get request(): Lantern.NetworkRequest<T>;
+    get initiatorType(): string;
+    get fromDiskCache(): boolean;
+    get isNonNetworkProtocol(): boolean;
+    /**
+     * Returns whether this network request can be downloaded without a TCP connection.
+     * During simulation we treat data coming in over a network connection separately from on-device data.
+     */
+    get isConnectionless(): boolean;
+    hasRenderBlockingPriority(): boolean;
+    cloneWithoutRelationships(): NetworkNode<T>;
+}
+export { NetworkNode };

package/dist/lib/front_end/models/trace/lantern/graph/PageDependencyGraph.d.ts

@@ -0,0 +1,43 @@
+import type * as Lantern from '../types/types.js';
+import type { Node } from './BaseNode.js';
+import { CPUNode } from './CPUNode.js';
+import { NetworkNode } from './NetworkNode.js';
+interface NetworkNodeOutput {
+    nodes: NetworkNode[];
+    idToNodeMap: Map<string, NetworkNode>;
+    urlToNodeMap: Map<string, NetworkNode[]>;
+    frameIdToNodeMap: Map<string, NetworkNode | null>;
+}
+declare class PageDependencyGraph {
+    static getNetworkInitiators(request: Lantern.NetworkRequest): string[];
+    static getNetworkNodeOutput(networkRequests: Lantern.NetworkRequest[]): NetworkNodeOutput;
+    static isScheduleableTask(evt: Lantern.TraceEvent): boolean;
+    /**
+     * There should *always* be at least one top level event, having 0 typically means something is
+     * drastically wrong with the trace and we should just give up early and loudly.
+     */
+    static assertHasToplevelEvents(events: Lantern.TraceEvent[]): void;
+    static getCPUNodes(mainThreadEvents: Lantern.TraceEvent[]): CPUNode[];
+    static linkNetworkNodes(rootNode: NetworkNode, networkNodeOutput: NetworkNodeOutput): void;
+    static linkCPUNodes(rootNode: Node, networkNodeOutput: NetworkNodeOutput, cpuNodes: CPUNode[]): void;
+    /**
+     * Removes the given node from the graph, but retains all paths between its dependencies and
+     * dependents.
+     */
+    static pruneNode(node: Node): void;
+    /**
+     * TODO: remove when CDT backend in Lighthouse is gone. Until then, this is a useful debugging tool
+     * to find delta between using CDP or the trace to create the network requests.
+     *
+     * When a test fails using the trace backend, I enabled this debug method and copied the network
+     * requests when CDP was used, then when trace is used, and diff'd them. This method helped
+     * remove non-logical differences from the comparison (order of properties, slight rounding
+     * discrepancies, removing object cycles, etc).
+     *
+     * When using for a unit test, make sure to do `.only` so you are getting what you expect.
+     */
+    static debugNormalizeRequests(lanternRequests: Lantern.NetworkRequest[]): void;
+    static createGraph(mainThreadEvents: Lantern.TraceEvent[], networkRequests: Lantern.NetworkRequest[], url: Lantern.Simulation.URL): Node;
+    static printGraph(rootNode: Node, widthInCharacters?: number): void;
+}
+export { PageDependencyGraph };

package/dist/lib/front_end/models/trace/lantern/graph/graph.d.ts

@@ -0,0 +1,4 @@
+export * from './BaseNode.js';
+export * from './CPUNode.js';
+export * from './NetworkNode.js';
+export * from './PageDependencyGraph.js';

package/dist/lib/front_end/models/trace/lantern/lantern.d.ts

@@ -0,0 +1,6 @@
+import * as Core from './core/core.js';
+import * as Graph from './graph/graph.js';
+import * as Metrics from './metrics/metrics.js';
+import * as Simulation from './simulation/simulation.js';
+import * as Types from './types/types.js';
+export { Core, Graph, Metrics, Simulation, Types, };

package/dist/lib/front_end/models/trace/lantern/metrics/FirstContentfulPaint.d.ts

@@ -0,0 +1,40 @@
+import * as Graph from '../graph/graph.js';
+import type * as Types from '../types/types.js';
+import { Metric, type MetricCoefficients } from './Metric.js';
+interface FirstPaintBasedGraphOpts<T> {
+    /**
+     * The timestamp used to filter out tasks that occurred 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: (node: Graph.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?: (node: Graph.CPUNode) => boolean;
+}
+declare class FirstContentfulPaint extends Metric {
+    static get coefficients(): MetricCoefficients;
+    /**
+     * 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.
+     */
+    static getRenderBlockingNodeData<T = unknown>(graph: Graph.Node, { cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking }: FirstPaintBasedGraphOpts<T>): {
+        definitelyNotRenderBlockingScriptUrls: Set<string>;
+        renderBlockingCpuNodeIds: Set<string>;
+    };
+    /**
+     * Computes the graph required for the first paint of interest.
+     */
+    static getFirstPaintBasedGraph<T>(dependencyGraph: Graph.Node, { cutoffTimestamp, treatNodeAsRenderBlocking, additionalCpuNodesToTreatAsRenderBlocking }: FirstPaintBasedGraphOpts<T>): Graph.Node<T>;
+    static getOptimisticGraph<T>(dependencyGraph: Graph.Node<T>, processedNavigation: Types.Simulation.ProcessedNavigation): Graph.Node<T>;
+    static getPessimisticGraph<T>(dependencyGraph: Graph.Node<T>, processedNavigation: Types.Simulation.ProcessedNavigation): Graph.Node<T>;
+}
+export { FirstContentfulPaint };

package/dist/lib/front_end/models/trace/lantern/metrics/Interactive.d.ts

@@ -0,0 +1,12 @@
+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 Interactive extends Metric {
+    static get coefficients(): MetricCoefficients;
+    static getOptimisticGraph<T>(dependencyGraph: Graph.Node<T>): Graph.Node<T>;
+    static getPessimisticGraph<T>(dependencyGraph: Graph.Node<T>): Graph.Node<T>;
+    static getEstimateFromSimulation(simulationResult: Simulation.Result, extras: Extras): Simulation.Result;
+    static compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): MetricResult;
+    static getLastLongTaskEndTime(nodeTimings: Simulation.Result['nodeTimings'], duration?: number): number;
+}
+export { Interactive };

package/dist/lib/front_end/models/trace/lantern/metrics/LargestContentfulPaint.d.ts

@@ -0,0 +1,17 @@
+import type * as Graph from '../graph/graph.js';
+import type * as Simulation from '../simulation/simulation.js';
+import type * as Types from '../types/types.js';
+import { type Extras, Metric, type MetricCoefficients, type MetricComputationDataInput, type MetricResult } from './Metric.js';
+declare class LargestContentfulPaint extends Metric {
+    static get coefficients(): MetricCoefficients;
+    /**
+     * Low priority image nodes are usually offscreen and very unlikely to be the
+     * resource that is required for LCP. Our LCP graphs include everything except for these images.
+     */
+    static isNotLowPriorityImageNode(node: Graph.Node): boolean;
+    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): Simulation.Result;
+    static compute(data: MetricComputationDataInput, extras?: Omit<Extras, 'optimistic'>): MetricResult;
+}
+export { LargestContentfulPaint };

package/dist/lib/front_end/models/trace/lantern/metrics/MaxPotentialFID.d.ts

@@ -0,0 +1,14 @@
+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 MaxPotentialFID 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'>): MetricResult;
+    static getTimingsAfterFCP(nodeTimings: Simulation.Result['nodeTimings'], fcpTimeInMs: number): Array<{
+        duration: number;
+    }>;
+}
+export { MaxPotentialFID };

package/dist/lib/front_end/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'>): MetricResult;
+}
+export { Metric };

package/dist/lib/front_end/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'>): 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/dist/lib/front_end/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/dist/lib/front_end/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'>): MetricResult;
+    static getTopLevelEvents(nodeTimings: Simulation.Result['nodeTimings'], minDurationMs: number): Array<{
+        start: number;
+        end: number;
+        duration: number;
+    }>;
+}
+export { TotalBlockingTime };

package/dist/lib/front_end/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/dist/lib/front_end/models/trace/lantern/simulation/ConnectionPool.d.ts

@@ -0,0 +1,26 @@
+import type * as Lantern from '../types/types.js';
+import { TCPConnection } from './TCPConnection.js';
+export declare class ConnectionPool {
+    options: Required<Lantern.Simulation.Options>;
+    records: Lantern.NetworkRequest[];
+    connectionsByOrigin: Map<string, TCPConnection[]>;
+    connectionsByRequest: Map<Lantern.NetworkRequest, TCPConnection>;
+    _connectionsInUse: Set<TCPConnection>;
+    connectionReusedByRequestId: Map<string, boolean>;
+    constructor(records: Lantern.NetworkRequest[], options: Required<Lantern.Simulation.Options>);
+    connectionsInUse(): TCPConnection[];
+    initializeConnections(): void;
+    findAvailableConnectionWithLargestCongestionWindow(connections: TCPConnection[]): TCPConnection | null;
+    /**
+     * This method finds an available connection to the origin specified by the network request or null
+     * if no connection was available. If returned, connection will not be available for other network
+     * records until release is called.
+     */
+    acquire(request: Lantern.NetworkRequest): TCPConnection | null;
+    /**
+     * Return the connection currently being used to fetch a request. If no connection
+     * currently being used for this request, an error will be thrown.
+     */
+    acquireActiveConnectionFromRequest(request: Lantern.NetworkRequest): TCPConnection;
+    release(request: Lantern.NetworkRequest): void;
+}

package/dist/lib/front_end/models/trace/lantern/simulation/Constants.d.ts

@@ -0,0 +1,31 @@
+declare const Constants: {
+    throttling: {
+        DEVTOOLS_RTT_ADJUSTMENT_FACTOR: number;
+        DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR: number;
+        mobileSlow4G: {
+            rttMs: number;
+            throughputKbps: number;
+            requestLatencyMs: number;
+            downloadThroughputKbps: number;
+            uploadThroughputKbps: number;
+            cpuSlowdownMultiplier: number;
+        };
+        mobileRegular3G: {
+            rttMs: number;
+            throughputKbps: number;
+            requestLatencyMs: number;
+            downloadThroughputKbps: number;
+            uploadThroughputKbps: number;
+            cpuSlowdownMultiplier: number;
+        };
+        desktopDense4G: {
+            rttMs: number;
+            throughputKbps: number;
+            cpuSlowdownMultiplier: number;
+            requestLatencyMs: number;
+            downloadThroughputKbps: number;
+            uploadThroughputKbps: number;
+        };
+    };
+};
+export { Constants };

package/dist/lib/front_end/models/trace/lantern/simulation/DNSCache.d.ts

@@ -0,0 +1,22 @@
+import type * as Lantern from '../types/types.js';
+declare class DNSCache {
+    static rttMultiplier: number;
+    rtt: number;
+    resolvedDomainNames: Map<string, {
+        resolvedAt: number;
+    }>;
+    constructor({ rtt }: {
+        rtt: number;
+    });
+    getTimeUntilResolution(request: Lantern.NetworkRequest, options?: {
+        requestedAt?: number;
+        shouldUpdateCache?: boolean;
+    }): number;
+    updateCacheResolvedAtIfNeeded(request: Lantern.NetworkRequest, resolvedAt: number): void;
+    /**
+     * Forcefully sets the DNS resolution time for a request.
+     * Useful for testing and alternate execution simulations.
+     */
+    setResolvedAt(domain: string, resolvedAt: number): void;
+}
+export { DNSCache };

package/dist/lib/front_end/models/trace/lantern/simulation/SimulationTimingMap.d.ts

@@ -0,0 +1,62 @@
+import * as Graph from '../graph/graph.js';
+interface NodeTimingComplete {
+    startTime: number;
+    endTime: number;
+    queuedTime: number;
+    estimatedTimeElapsed: number;
+    timeElapsed: number;
+    timeElapsedOvershoot: number;
+    bytesDownloaded: number;
+}
+type NodeTimingQueued = Pick<NodeTimingComplete, 'queuedTime'>;
+type CpuNodeTimingStarted = NodeTimingQueued & Pick<NodeTimingComplete, 'startTime' | 'timeElapsed'>;
+type NetworkNodeTimingStarted = CpuNodeTimingStarted & Pick<NodeTimingComplete, 'timeElapsedOvershoot' | 'bytesDownloaded'>;
+type CpuNodeTimingInProgress = CpuNodeTimingStarted & Pick<NodeTimingComplete, 'estimatedTimeElapsed'>;
+type NetworkNodeTimingInProgress = NetworkNodeTimingStarted & Pick<NodeTimingComplete, 'estimatedTimeElapsed'>;
+export type CpuNodeTimingComplete = CpuNodeTimingInProgress & Pick<NodeTimingComplete, 'endTime'>;
+export type NetworkNodeTimingComplete = NetworkNodeTimingInProgress & Pick<NodeTimingComplete, 'endTime'> & {
+    connectionTiming: ConnectionTiming;
+};
+export type CompleteNodeTiming = CpuNodeTimingComplete | NetworkNodeTimingComplete;
+type NodeTimingData = NodeTimingQueued | CpuNodeTimingStarted | NetworkNodeTimingStarted | CpuNodeTimingInProgress | NetworkNodeTimingInProgress | CpuNodeTimingComplete | NetworkNodeTimingComplete;
+export interface ConnectionTiming {
+    dnsResolutionTime?: number;
+    connectionTime?: number;
+    sslTime?: number;
+    timeToFirstByte: number;
+}
+declare class SimulatorTimingMap {
+    nodeTimings: Map<Graph.Node, NodeTimingData>;
+    constructor();
+    getNodes(): Graph.Node[];
+    setReadyToStart(node: Graph.Node, values: {
+        queuedTime: number;
+    }): void;
+    setInProgress(node: Graph.Node, values: {
+        startTime: number;
+    }): void;
+    setCompleted(node: Graph.Node, values: {
+        endTime: number;
+        connectionTiming?: ConnectionTiming;
+    }): void;
+    setCpu(node: Graph.CPUNode, values: {
+        timeElapsed: number;
+    }): void;
+    setCpuEstimated(node: Graph.CPUNode, values: {
+        estimatedTimeElapsed: number;
+    }): void;
+    setNetwork(node: Graph.NetworkNode, values: {
+        timeElapsed: number;
+        timeElapsedOvershoot: number;
+        bytesDownloaded: number;
+    }): void;
+    setNetworkEstimated(node: Graph.NetworkNode, values: {
+        estimatedTimeElapsed: number;
+    }): void;
+    getQueued(node: Graph.Node): NodeTimingData;
+    getCpuStarted(node: Graph.CPUNode): CpuNodeTimingStarted;
+    getNetworkStarted(node: Graph.NetworkNode): NetworkNodeTimingStarted;
+    getInProgress(node: Graph.Node): CpuNodeTimingInProgress | NetworkNodeTimingInProgress;
+    getCompleted(node: Graph.Node): CpuNodeTimingComplete | NetworkNodeTimingComplete;
+}
+export { SimulatorTimingMap };

package/dist/lib/front_end/models/trace/lantern/simulation/Simulator.d.ts

@@ -0,0 +1,84 @@
+import * as Graph from '../graph/graph.js';
+import type * as Lantern from '../types/types.js';
+import { ConnectionPool } from './ConnectionPool.js';
+import { DNSCache } from './DNSCache.js';
+import { type CompleteNodeTiming, type ConnectionTiming, SimulatorTimingMap } from './SimulationTimingMap.js';
+import { TCPConnection } from './TCPConnection.js';
+export interface Result<T = Lantern.AnyNetworkObject> {
+    timeInMs: number;
+    nodeTimings: Map<Graph.Node<T>, Lantern.Simulation.NodeTiming>;
+}
+declare class Simulator<T = Lantern.AnyNetworkObject> {
+    static createSimulator(settings: Lantern.Simulation.Settings): Simulator;
+    options: Required<Lantern.Simulation.Options>;
+    _rtt: number;
+    throughput: number;
+    maximumConcurrentRequests: number;
+    cpuSlowdownMultiplier: number;
+    layoutTaskMultiplier: number;
+    cachedNodeListByStartPosition: Graph.Node[];
+    nodeTimings: SimulatorTimingMap;
+    numberInProgressByType: Map<string, number>;
+    nodes: Record<number, Set<Graph.Node>>;
+    dns: DNSCache;
+    connectionPool: ConnectionPool;
+    constructor(options?: Lantern.Simulation.Options);
+    get rtt(): number;
+    initializeConnectionPool(graph: Graph.Node): void;
+    /**
+     * Initializes the various state data structures such _nodeTimings and the _node Sets by state.
+     */
+    initializeAuxiliaryData(): void;
+    numberInProgress(type: string): number;
+    markNodeAsReadyToStart(node: Graph.Node, queuedTime: number): void;
+    markNodeAsInProgress(node: Graph.Node, startTime: number): void;
+    markNodeAsComplete(node: Graph.Node, endTime: number, connectionTiming?: ConnectionTiming): void;
+    acquireConnection(request: Lantern.NetworkRequest): TCPConnection | null;
+    getNodesSortedByStartPosition(): Graph.Node[];
+    startNodeIfPossible(node: Graph.Node, totalElapsedTime: number): void;
+    /**
+     * Updates each connection in use with the available throughput based on the number of network requests
+     * currently in flight.
+     */
+    updateNetworkCapacity(): void;
+    /**
+     * Estimates the number of milliseconds remaining given current conditions before the node is complete.
+     */
+    estimateTimeRemaining(node: Graph.Node): number;
+    estimateCPUTimeRemaining(cpuNode: Graph.CPUNode): number;
+    estimateNetworkTimeRemaining(networkNode: Graph.NetworkNode): number;
+    /**
+     * Computes and returns the minimum estimated completion time of the nodes currently in progress.
+     */
+    findNextNodeCompletionTime(): number;
+    /**
+     * Given a time period, computes the progress toward completion that the node made during that time.
+     */
+    updateProgressMadeInTimePeriod(node: Graph.Node, timePeriodLength: number, totalElapsedTime: number): void;
+    computeFinalNodeTimings(): {
+        nodeTimings: Map<Graph.Node, Lantern.Simulation.NodeTiming>;
+        completeNodeTimings: Map<Graph.Node, CompleteNodeTiming>;
+    };
+    getOptions(): Required<Lantern.Simulation.Options>;
+    /**
+     * Estimates the time taken to process all of the graph's nodes, returns the overall time along with
+     * each node annotated by start/end times.
+     *
+     * Simulator/connection pool are allowed to deviate from what was
+     * observed in the trace/devtoolsLog and start requests as soon as they are queued (i.e. do not
+     * wait around for a warm connection to be available if the original request was fetched on a warm
+     * connection).
+     */
+    simulate(graph: Graph.Node, options?: {
+        label?: string;
+    }): Result<T>;
+    computeWastedMsFromWastedBytes(wastedBytes: number): number;
+    static get allNodeTimings(): Map<string, Map<Graph.Node, CompleteNodeTiming>>;
+    /**
+     * We attempt to start nodes by their observed start time using the request priority as a tie breaker.
+     * When simulating, just because a low priority image started 5ms before a high priority image doesn't mean
+     * it would have happened like that when the network was slower.
+     */
+    static computeNodeStartPosition(node: Graph.Node): number;
+}
+export { Simulator };