devtools-tracing 1.2.1 → 1.3.0

package/dist/lib/front_end/models/trace/handlers/RendererHandler.d.ts

@@ -0,0 +1,100 @@
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+import * as HandlerHelpers from './helpers.js';
+import { type FrameProcessData } from './MetaHandler.js';
+import type { HandlerName } from './types.js';
+export declare function handleUserConfig(userConfig: Types.Configuration.Configuration): void;
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function finalize(): Promise<void>;
+export declare function data(): RendererHandlerData;
+/**
+ * Steps through all the renderer processes we've located so far in the meta
+ * handler, obtaining their URL, checking whether they are the main frame, and
+ * collecting each one of their threads' name. This meta handler's data is
+ * assigned to the renderer handler's data.
+ */
+export declare function assignMeta(processes: Map<Types.Events.ProcessID, RendererProcess>, mainFrameId: string, rendererProcessesByFrame: FrameProcessData, threadsInProcess: Map<Types.Events.ProcessID, Map<Types.Events.ThreadID, Types.Events.ThreadName>>): void;
+/**
+ * Assigns origins to all threads in all processes.
+ * @see assignMeta
+ */
+export declare function assignOrigin(processes: Map<Types.Events.ProcessID, RendererProcess>, rendererProcessesByFrame: FrameProcessData): void;
+/**
+ * Assigns whether or not a thread is the main frame to all threads in all processes.
+ * @see assignMeta
+ */
+export declare function assignIsMainFrame(processes: Map<Types.Events.ProcessID, RendererProcess>, mainFrameId: string, rendererProcessesByFrame: FrameProcessData): void;
+/**
+ * Assigns the thread name to all threads in all processes.
+ * @see assignMeta
+ */
+export declare function assignThreadName(processes: Map<Types.Events.ProcessID, RendererProcess>, threadsInProcess: Map<Types.Events.ProcessID, Map<Types.Events.ThreadID, Types.Events.ThreadName>>): void;
+/**
+ * Removes unneeded trace data opportunistically stored while handling events.
+ * This currently does the following:
+ *  - Deletes processes with an unknown origin.
+ */
+export declare function sanitizeProcesses(processes: Map<Types.Events.ProcessID, RendererProcess>): void;
+/**
+ * Removes unneeded trace data opportunistically stored while handling events.
+ * This currently does the following:
+ *  - Deletes threads with no roots.
+ */
+export declare function sanitizeThreads(processes: Map<Types.Events.ProcessID, RendererProcess>): void;
+/**
+ * Creates a hierarchical structure from the trace events. Each thread in each
+ * process will contribute to their own individual hierarchy.
+ *
+ * The trace data comes in as a contiguous array of events, against which we
+ * make a couple of assumptions:
+ *
+ *  1. Events are temporally-ordered in terms of start time (though they're
+ *     not necessarily ordered as such in the data stream).
+ *  2. If event B's start and end times are within event A's time boundaries
+ *     we assume that A is the parent of B.
+ *
+ * Therefore we expect to reformulate something like:
+ *
+ * [ Task A ][ Task B ][ Task C ][ Task D ][ Task E ]
+ *
+ * Into something hierarchically-arranged like below:
+ *
+ * |------------- Task A -------------||-- Task E --|
+ *  |-- Task B --||-- Task D --|
+ *   |- Task C -|
+ */
+export declare function buildHierarchy(processes: Map<Types.Events.ProcessID, RendererProcess>, options?: {
+    filter: {
+        has: (name: Types.Events.Name) => boolean;
+    };
+}): void;
+export declare function makeCompleteEvent(event: Types.Events.Begin | Types.Events.End): Types.Events.SyntheticComplete | null;
+export declare function deps(): HandlerName[];
+export interface RendererHandlerData {
+    processes: Map<Types.Events.ProcessID, RendererProcess>;
+    /**
+     * A map of all compositor workers (which we show in the UI as Rasterizers)
+     * by the process ID.
+     */
+    compositorTileWorkers: Map<Types.Events.ProcessID, Types.Events.ThreadID[]>;
+    entryToNode: Map<Types.Events.Event, Helpers.TreeHelpers.TraceEntryNode>;
+    entityMappings: HandlerHelpers.EntityMappings;
+}
+export interface RendererProcess {
+    url: string | null;
+    isOnMainFrame: boolean;
+    threads: Map<Types.Events.ThreadID, RendererThread>;
+}
+export interface RendererThread {
+    name: string | null;
+    /**
+     * Contains trace events and synthetic profile calls made from
+     * samples.
+     */
+    entries: Types.Events.Event[];
+    profileCalls: Types.Events.SyntheticProfileCall[];
+    layoutEvents: Types.Events.Layout[];
+    recalcStyleEvents: Types.Events.RecalcStyle[];
+    tree?: Helpers.TreeHelpers.TraceEntryTree;
+}

package/dist/lib/front_end/models/trace/handlers/SamplesHandler.d.ts

@@ -0,0 +1,46 @@
+import * as CPUProfile from '../../cpu_profile/cpu_profile.js';
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+declare let profilesInProcess: Map<Types.Events.ProcessID, Map<Types.Events.ThreadID, ProfileData>>;
+declare let entryToNode: Map<Types.Events.Event, Helpers.TreeHelpers.TraceEntryNode>;
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function finalize(parseOptions?: Types.Configuration.ParseOptions): Promise<void>;
+export declare function data(): SamplesHandlerData;
+export interface SamplesHandlerData {
+    profilesInProcess: typeof profilesInProcess;
+    entryToNode: typeof entryToNode;
+}
+export interface ProfileData {
+    profileId: Types.Events.ProfileID;
+    rawProfile: CPUProfile.CPUProfileDataModel.ExtendedProfile;
+    parsedProfile: CPUProfile.CPUProfileDataModel.CPUProfileDataModel;
+    /**
+     * Contains the calls built from the CPU profile samples.
+     * Note: This doesn't contain real trace events coming from the
+     * browser, only calls synthetically typed as trace events for
+     * compatibility, as such it only makes sense to use them in pure CPU
+     * profiles.
+     *
+     * If you need the profile calls from a CPU profile obtained from a
+     * web trace, use the data exported by the RendererHandler instead.
+     */
+    profileCalls: Types.Events.SyntheticProfileCall[];
+    /**
+     * Contains the call tree built from the CPU profile samples.
+     * Similar to the profileCalls field, this tree does not contain nor
+     * take into account trace events, as such it only makes sense to use
+     * them in pure CPU profiles.
+     */
+    profileTree?: Helpers.TreeHelpers.TraceEntryTree;
+}
+/**
+ * Returns the name of a function for a given synthetic profile call.
+ * We first look to find the ProfileNode representing this call, and use its
+ * function name. This is preferred (and should always exist) because if we
+ * resolve sourcemaps, we will update this name. If that name is not present,
+ * we fall back to the function name that was in the callframe that we got
+ * when parsing the profile's trace data.
+ */
+export declare function getProfileCallFunctionName(data: SamplesHandlerData, entry: Types.Events.SyntheticProfileCall): string;
+export {};

package/dist/lib/front_end/models/trace/handlers/ScreenshotsHandler.d.ts

@@ -0,0 +1,12 @@
+import * as Types from '../types/types.js';
+import type { HandlerName } from './types.js';
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function finalize(): Promise<void>;
+export declare function screenshotImageDataUri(event: Types.Events.LegacySyntheticScreenshot | Types.Events.Screenshot): string;
+export interface Data {
+    legacySyntheticScreenshots: Types.Events.LegacySyntheticScreenshot[] | null;
+    screenshots: Types.Events.Screenshot[] | null;
+}
+export declare function data(): Data;
+export declare function deps(): HandlerName[];

package/dist/lib/front_end/models/trace/handlers/ScriptsHandler.d.ts

@@ -0,0 +1,43 @@
+import type * as SDK from '../../../core/sdk/sdk.js';
+import type * as Protocol from '../../../generated/protocol.js';
+import * as Types from '../types/types.js';
+import type { FinalizeOptions, HandlerName } from './types.js';
+export interface ScriptsData {
+    /** Note: this is only populated when the "Enhanced Traces" feature is enabled. */
+    scripts: Script[];
+}
+export interface Script {
+    isolate: string;
+    scriptId: Protocol.Runtime.ScriptId;
+    frame: string;
+    ts: Types.Timing.Micro;
+    inline: boolean;
+    url?: string;
+    sourceUrl?: string;
+    content?: string;
+    /**
+     * Note: this is the literal text given as the sourceMappingURL value. It has not been resolved relative to the script url.
+     * Since M138, data urls are never set here.
+     */
+    sourceMapUrl?: string;
+    /** If true, the source map url was a data URL, so it got removed from the trace event. */
+    sourceMapUrlElided?: boolean;
+    sourceMap?: SDK.SourceMap.SourceMap;
+    request?: Types.Events.SyntheticNetworkRequest;
+    /** Lazily generated - use getScriptGeneratedSizes to access. */
+    sizes?: GeneratedFileSizes;
+}
+type GeneratedFileSizes = {
+    errorMessage: string;
+} | {
+    files: Record<string, number>;
+    unmappedBytes: number;
+    totalBytes: number;
+};
+export declare function deps(): HandlerName[];
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function getScriptGeneratedSizes(script: Script): GeneratedFileSizes | null;
+export declare function finalize(options: FinalizeOptions): Promise<void>;
+export declare function data(): ScriptsData;
+export {};

package/dist/lib/front_end/models/trace/handlers/SelectorStatsHandler.d.ts

@@ -0,0 +1,27 @@
+import type * as Protocol from '../../../generated/protocol.js';
+import * as Types from '../types/types.js';
+interface SelectorWithStyleSheedId {
+    selector: string;
+    styleSheetId: string;
+}
+interface InvalidatedNode {
+    frame: string;
+    backendNodeId: Protocol.DOM.BackendNodeId;
+    type: Types.Events.InvalidationEventType;
+    selectorList: SelectorWithStyleSheedId[];
+    ts: Types.Timing.Micro;
+    tts?: Types.Timing.Micro;
+    subtree: boolean;
+    lastRecalcStyleEventTs: Types.Timing.Micro;
+}
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function finalize(): Promise<void>;
+export interface SelectorStatsData {
+    dataForRecalcStyleEvent: Map<Types.Events.RecalcStyle, {
+        timings: Types.Events.SelectorTiming[];
+    }>;
+    invalidatedNodeList: InvalidatedNode[];
+}
+export declare function data(): SelectorStatsData;
+export {};

package/dist/lib/front_end/models/trace/handlers/Threads.d.ts

@@ -0,0 +1,34 @@
+import type * as Helpers from '../helpers/helpers.js';
+import type * as Types from '../types/types.js';
+import type { AuctionWorkletsData } from './AuctionWorkletsHandler.js';
+import type * as Renderer from './RendererHandler.js';
+import type { HandlerData } from './types.js';
+export interface ThreadData {
+    pid: Types.Events.ProcessID;
+    tid: Types.Events.ThreadID;
+    entries: readonly Types.Events.Event[];
+    processIsOnMainFrame: boolean;
+    tree: Helpers.TreeHelpers.TraceEntryTree;
+    type: ThreadType;
+    name: string | null;
+    entryToNode: Map<Types.Events.Event, Helpers.TreeHelpers.TraceEntryNode>;
+}
+export declare const enum ThreadType {
+    MAIN_THREAD = "MAIN_THREAD",
+    WORKER = "WORKER",
+    RASTERIZER = "RASTERIZER",
+    AUCTION_WORKLET = "AUCTION_WORKLET",
+    OTHER = "OTHER",
+    CPU_PROFILE = "CPU_PROFILE",
+    THREAD_POOL = "THREAD_POOL"
+}
+export declare function threadsInRenderer(rendererData: Renderer.RendererHandlerData, auctionWorkletsData: AuctionWorkletsData): readonly ThreadData[];
+/**
+ * Given trace parsed data, this helper will return a high level array of
+ * ThreadData. This is useful because it allows you to get a list of threads
+ * regardless of if the trace is a CPU Profile or a Tracing profile. Thus you
+ * can use this helper to iterate over threads in confidence that it will work
+ * for both trace types.
+ * The resulting data is cached per-trace, so you can safely call this multiple times.
+ */
+export declare function threadsInTrace(handlerData: HandlerData): readonly ThreadData[];

package/dist/lib/front_end/models/trace/handlers/UserInteractionsHandler.d.ts

@@ -0,0 +1,78 @@
+import * as Types from '../types/types.js';
+import { ScoreClassification } from './PageLoadMetricsHandler.js';
+import type { HandlerName } from './types.js';
+export declare const LONG_INTERACTION_THRESHOLD: Types.Timing.Micro;
+export interface UserInteractionsData {
+    /** All the BeginCommitCompositorFrame events we found in the trace */
+    beginCommitCompositorFrameEvents: readonly Types.Events.BeginCommitCompositorFrame[];
+    /** All the ParseMetaViewport events we found in the trace */
+    parseMetaViewportEvents: readonly Types.Events.ParseMetaViewport[];
+    /**
+     * All the interaction events we found in the trace that had an
+     * interactionId and a duration > 0
+     **/
+    interactionEvents: readonly Types.Events.SyntheticInteractionPair[];
+    /**
+     * If the user rapidly generates interaction events (think typing into a
+     * text box), in the UI we only really want to show the user the longest
+     * interaction in that set.
+     * For example picture interactions like this:
+     * ===[interaction A]==========
+     *       =[interaction B]======
+     *            =[interaction C]=
+     *
+     * These events all end at the same time, and so in this instance we only want
+     * to show the first interaction A on the timeline, as that is the longest one
+     * and the one the developer should be focusing on. So this array of events is
+     * all the interaction events filtered down, removing any nested interactions
+     * entirely.
+     **/
+    interactionEventsWithNoNesting: readonly Types.Events.SyntheticInteractionPair[];
+    longestInteractionEvent: Readonly<Types.Events.SyntheticInteractionPair> | null;
+    interactionsOverThreshold: Readonly<Set<Types.Events.SyntheticInteractionPair>>;
+}
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export type InteractionCategory = 'KEYBOARD' | 'POINTER' | 'OTHER';
+export declare function categoryOfInteraction(interaction: Types.Events.SyntheticInteractionPair): InteractionCategory;
+/**
+ * We define a set of interactions as nested where:
+ * 1. Their end times align.
+ * 2. The longest interaction's start time is earlier than all other
+ * interactions with the same end time.
+ * 3. The interactions are of the same category [each interaction is either
+ * categorised as keyboard, or pointer.]
+ *
+ * =============A=[pointerup]=
+ *        ====B=[pointerdown]=
+ *        ===C=[pointerdown]==
+ *         ===D=[pointerup]===
+ *
+ * In this example, B, C and D are all nested and therefore should not be
+ * returned from this function.
+ *
+ * However, in this example we would only consider B nested (under A) and D
+ * nested (under C). A and C both stay because they are of different types.
+ * ========A=[keydown]====
+ *   =======B=[keyup]=====
+ *    ====C=[pointerdown]=
+ *         =D=[pointerup]=
+ *
+ * Additionally, this method will also maximise the processing duration of the
+ * events that we keep as non-nested. We want to make sure we give an accurate
+ * representation of main thread activity, so if we keep an event + hide its
+ * nested children, we set the top level event's processing start &
+ * processing end to be the earliest processing start & the latest processing
+ * end of its children. This ensures we report a more accurate main thread
+ * activity time which is important as we want developers to focus on fixing
+ * this.
+ **/
+export declare function removeNestedInteractionsAndSetProcessingTime(interactions: readonly Types.Events.SyntheticInteractionPair[]): readonly Types.Events.SyntheticInteractionPair[];
+export declare function finalize(): Promise<void>;
+export declare function data(): UserInteractionsData;
+export declare function deps(): HandlerName[];
+/**
+ * Classifications sourced from
+ * https://web.dev/articles/inp#good-score
+ */
+export declare function scoreClassificationForInteractionToNextPaint(timing: Types.Timing.Micro): ScoreClassification;

package/dist/lib/front_end/models/trace/handlers/UserTimingsHandler.d.ts

@@ -0,0 +1,54 @@
+import * as Types from '../types/types.js';
+export interface UserTimingsData {
+    /**
+     * Events triggered with the performance.measure() API.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure
+     */
+    performanceMeasures: readonly Types.Events.SyntheticUserTimingPair[];
+    /**
+     * Events triggered with the performance.mark() API.
+     * https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark
+     */
+    performanceMarks: readonly Types.Events.PerformanceMark[];
+    /**
+     * Events triggered with the console.time(), console.timeEnd() and
+     * console.timeLog() API.
+     * https://developer.mozilla.org/en-US/docs/Web/API/console/time
+     */
+    consoleTimings: readonly Types.Events.SyntheticConsoleTimingPair[];
+    /**
+     * Events triggered with the console.timeStamp() API
+     * https://developer.mozilla.org/en-US/docs/Web/API/console/timeStamp
+     */
+    timestampEvents: readonly Types.Events.ConsoleTimeStamp[];
+    /**
+     * Events triggered to trace the call to performance.measure itself,
+     * cached by trace_id.
+     */
+    measureTraceByTraceId: Map<number, Types.Events.UserTimingMeasure>;
+}
+export declare function reset(): void;
+/**
+ * Similar to the default {@link Helpers.Trace.eventTimeComparator}
+ * but with a twist:
+ * In case of equal start and end times, put the second event (within a
+ * track) first.
+ *
+ * Explanation:
+ * User timing entries come as trace events dispatched when
+ * performance.measure/mark is called. The trace events buffered in
+ * devtools frontend are sorted by the start time. If their start time
+ * is the same, then the event for the first call will appear first.
+ *
+ * When entries are meant to be stacked, the corresponding
+ * performance.measure calls usually are done in bottom-up direction:
+ * calls for children first and for parent later (because the call
+ * is usually done when the measured task is over). This means that
+ * when two user timing events have the same start and end time, usually
+ * the second event is the parent of the first. Hence the switch.
+ *
+ */
+export declare function userTimingComparator<T extends Types.Events.SyntheticEventPair | Types.Events.ConsoleTimeStamp>(a: T, b: T, originalArray: readonly T[]): number;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function finalize(): Promise<void>;
+export declare function data(): UserTimingsData;

package/dist/lib/front_end/models/trace/handlers/WarningsHandler.d.ts

@@ -0,0 +1,14 @@
+import * as Types from '../types/types.js';
+import type { HandlerName } from './types.js';
+export interface WarningsData {
+    perEvent: Map<Types.Events.Event, Warning[]>;
+    perWarning: Map<Warning, Types.Events.Event[]>;
+}
+export type Warning = 'LONG_TASK' | 'IDLE_CALLBACK_OVER_TIME' | 'FORCED_REFLOW' | 'LONG_INTERACTION';
+export declare const FORCED_REFLOW_THRESHOLD: Types.Timing.Micro;
+export declare const LONG_MAIN_THREAD_TASK_THRESHOLD: Types.Timing.Micro;
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function deps(): HandlerName[];
+export declare function finalize(): Promise<void>;
+export declare function data(): WarningsData;

package/dist/lib/front_end/models/trace/handlers/WorkersHandler.d.ts

@@ -0,0 +1,10 @@
+import * as Types from '../types/types.js';
+export interface WorkersData {
+    workerSessionIdEvents: readonly Types.Events.TracingSessionIdForWorker[];
+    workerIdByThread: Map<Types.Events.ThreadID, Types.Events.WorkerId>;
+    workerURLById: Map<Types.Events.WorkerId, string>;
+}
+export declare function reset(): void;
+export declare function handleEvent(event: Types.Events.Event): void;
+export declare function finalize(): Promise<void>;
+export declare function data(): WorkersData;

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

@@ -0,0 +1,4 @@
+export * as Helpers from './helpers.js';
+export * as ModelHandlers from './ModelHandlers.js';
+export * as Threads from './Threads.js';
+export * as Types from './types.js';

package/dist/lib/front_end/models/trace/handlers/helpers.d.ts

@@ -0,0 +1,21 @@
+import type * as Platform from '../../../core/platform/platform.js';
+import * as ThirdPartyWeb from '../../../third_party/third-party-web/third-party-web.js';
+import * as Types from '../types/types.js';
+import type { TraceEventsForNetworkRequest } from './NetworkRequestsHandler.js';
+import type { HandlerData } from './types.js';
+export type Entity = typeof ThirdPartyWeb.ThirdPartyWeb.entities[number] & {
+    isUnrecognized?: boolean;
+};
+export interface EntityMappings {
+    createdEntityCache: Map<string, Entity>;
+    entityByEvent: Map<Types.Events.Event, Entity>;
+    eventsByEntity: Map<Entity, Types.Events.Event[]>;
+    entityByUrlCache: Map<string, Entity>;
+}
+export declare function getEntityForEvent(event: Types.Events.Event, entityMappings: EntityMappings): Entity | undefined;
+export declare function getEntityForUrl(url: string, entityMappings: EntityMappings): Entity | undefined;
+export declare function getNonResolvedURL(entry: Types.Events.Event, handlerData?: HandlerData): Platform.DevToolsPath.UrlString | null;
+export declare function makeUpEntity(entityCache: Map<string, Entity>, url: string): Entity | undefined;
+export declare function addEventToEntityMapping(event: Types.Events.Event, entityMappings: EntityMappings): void;
+/** A slight upgrade of addEventToEntityMapping to handle the sub-events of a network request. **/
+export declare function addNetworkRequestToEntityMapping(networkRequest: Types.Events.SyntheticNetworkRequest, entityMappings: EntityMappings, requestTraceEvents: TraceEventsForNetworkRequest): void;

package/dist/lib/front_end/models/trace/handlers/types.d.ts

@@ -0,0 +1,54 @@
+import type * as Types from './../types/types.js';
+import type * as ModelHandlers from './ModelHandlers.js';
+export type FinalizeOptions = Types.Configuration.ParseOptions & {
+    allTraceEvents: readonly Types.Events.Event[];
+};
+export interface Handler {
+    reset(): void;
+    handleEvent(data: object): void;
+    finalize(options?: FinalizeOptions): Promise<void>;
+    data(): unknown;
+    deps?(): HandlerName[];
+    handleUserConfig?(config: Types.Configuration.Configuration): void;
+}
+export type HandlerName = keyof typeof ModelHandlers;
+/**
+ * This type maps Handler names to the return type of their data
+ * function. So, for example, if we are given an object with a key of 'foo'
+ * and a value which is a TraceHandler containing a data() function that
+ * returns a string, this type will be { foo: string }.
+ *
+ * This allows us to model the behavior of the TraceProcessor in the model,
+ * which takes an object with Handlers as part of its config, and
+ * which ultimately returns an object keyed off the names of the
+ * Handlers, and with values that are derived from each
+ * Handler's data function.
+ *
+ * So, concretely, we provide a Handler for calculating the #time
+ * bounds of a trace called TraceBounds, whose data() function returns a
+ * TraceWindow. The HandlerData, therefore, would determine that the
+ * TraceProcessor would contain a key called 'TraceBounds' whose value is
+ * a TraceWindow.
+ **/
+export type EnabledHandlerDataWithMeta<T extends Record<string, Handler>> = {
+    Meta: Readonly<ReturnType<typeof ModelHandlers['Meta']['data']>>;
+} & {
+    [K in keyof T]: Readonly<ReturnType<T[K]['data']>>;
+};
+export type HandlersWithMeta<T extends Record<string, Handler>> = {
+    Meta: typeof ModelHandlers.Meta;
+} & {
+    [K in keyof T]: T[K];
+};
+/**
+ * Represents the final data from all of the handlers. If you instantiate a
+ * TraceProcessor with a subset of handlers, you should instead use
+ * `EnabledHandlerDataWithMeta<>`.
+ **/
+export type HandlerData = Readonly<EnabledHandlerDataWithMeta<typeof ModelHandlers>>;
+type DeepWriteable<T> = {
+    -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};
+export type HandlerDataMutable = DeepWriteable<HandlerData>;
+export type Handlers = typeof ModelHandlers;
+export {};

package/dist/lib/front_end/models/trace/helpers/Extensions.d.ts

@@ -0,0 +1,6 @@
+import type * as Types from '../types/types.js';
+import { type TraceEntryNode } from './TreeHelpers.js';
+export declare function buildTrackDataFromExtensionEntries(extensionEntries: Types.Extensions.SyntheticExtensionTrackEntry[], extensionTrackData: Types.Extensions.ExtensionTrackData[], entryToNode: Map<Types.Events.Event, TraceEntryNode>): {
+    extensionTrackData: Types.Extensions.ExtensionTrackData[];
+    entryToNode?: Map<Types.Events.Event, TraceEntryNode>;
+};

package/dist/lib/front_end/models/trace/helpers/Network.d.ts

@@ -0,0 +1,26 @@
+import * as Protocol from '../../../generated/protocol.js';
+import type { SyntheticNetworkRequest } from '../types/TraceEvents.js';
+export declare function isSyntheticNetworkRequestEventRenderBlocking(event: SyntheticNetworkRequest): boolean;
+export declare function isSyntheticNetworkRequestHighPriority(event: SyntheticNetworkRequest): boolean;
+export interface CacheControl {
+    'max-age'?: number;
+    'no-cache'?: boolean;
+    'no-store'?: boolean;
+    'must-revalidate'?: boolean;
+    'private'?: boolean;
+}
+export declare const CACHEABLE_STATUS_CODES: Set<number>;
+/** @type {Set<LH.Crdp.Network.ResourceType>} */
+export declare const STATIC_RESOURCE_TYPES: Set<Protocol.Network.ResourceType>;
+export declare const NON_NETWORK_SCHEMES: string[];
+/**
+ * Parses Cache-Control directives based on https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+ * eg. 'no-cache, no-store, max-age=0, no-transform, private' will return
+ * {no-cache: true, no-store: true, max-age: 0, no-transform: true, private: true}
+ */
+export declare function parseCacheControl(header: string | null): CacheControl | null;
+/**
+ * Is the host localhost-enough to satisfy the "secure context" definition
+ * https://github.com/GoogleChrome/lighthouse/pull/11766#discussion_r582340683
+ */
+export declare function isSyntheticNetworkRequestLocalhost(event: SyntheticNetworkRequest): boolean;

package/dist/lib/front_end/models/trace/helpers/SamplesIntegrator.d.ts

@@ -0,0 +1,62 @@
+import type * as Protocol from '../../../generated/protocol.js';
+import type * as CPUProfile from '../../cpu_profile/cpu_profile.js';
+import * as Types from '../types/types.js';
+/**
+ * This is a helper that integrates CPU profiling data coming in the
+ * shape of samples, with trace events. Samples indicate what the JS
+ * stack trace looked at a given point in time, but they don't have
+ * duration. The SamplesIntegrator task is to make an approximation
+ * of what the duration of each JS call was, given the sample data and
+ * given the trace events profiled during that time. At the end of its
+ * execution, the SamplesIntegrator returns an array of ProfileCalls
+ * (under SamplesIntegrator::buildProfileCalls()), which
+ * represent JS calls, with a call frame and duration. These calls have
+ * the shape of a complete trace events and can be treated as flame
+ * chart entries in the timeline.
+ *
+ * The approach to build the profile calls consists in tracking the
+ * current stack as the following events happen (in order):
+ * 1. A sample was done.
+ * 2. A trace event started.
+ * 3. A trace event ended.
+ * Depending on the event and on the data that's coming with it the
+ * stack is updated by adding or removing JS calls to it and updating
+ * the duration of the calls in the tracking stack.
+ *
+ * note: Although this approach has been implemented since long ago, and
+ * is relatively efficient (adds a complexity over the trace parsing of
+ * O(n) where n is the number of samples) it has proven to be faulty.
+ * It might be worthwhile experimenting with improvements or with a
+ * completely different approach. Improving the approach is tracked in
+ * crbug.com/1417439
+ */
+export declare class SamplesIntegrator {
+    #private;
+    /**
+     * Keeps track of the individual samples from the CPU Profile.
+     * Only used with Debug Mode experiment enabled.
+     */
+    jsSampleEvents: Types.Events.SyntheticJSSample[];
+    constructor(profileModel: CPUProfile.CPUProfileDataModel.CPUProfileDataModel, profileId: Types.Events.ProfileID, pid: Types.Events.ProcessID, tid: Types.Events.ThreadID, configuration?: Types.Configuration.Configuration);
+    buildProfileCalls(traceEvents: Types.Events.Event[]): Types.Events.SyntheticProfileCall[];
+    /**
+     * Builds the initial calls with no duration from samples. Their
+     * purpose is to be merged with the trace event array being parsed so
+     * that they can be traversed in order with them and their duration
+     * can be updated as the SampleIntegrator callbacks are invoked.
+     */
+    callsFromProfileSamples(): Types.Events.SyntheticProfileCall[];
+    static framesAreEqual(frame1: Protocol.Runtime.CallFrame, frame2: Protocol.Runtime.CallFrame): boolean;
+    static showNativeName(name: string, runtimeCallStatsEnabled: boolean): boolean;
+    static nativeGroup(nativeName: string): SamplesIntegrator.NativeGroups | null;
+    static isNativeRuntimeFrame(frame: Protocol.Runtime.CallFrame): boolean;
+    static filterStackFrames(stack: Types.Events.SyntheticProfileCall[], engineConfig: Types.Configuration.Configuration): void;
+    static createFakeTraceFromCpuProfile(profile: Protocol.Profiler.Profile, tid: Types.Events.ThreadID): Types.File.TraceFile;
+    static extractCpuProfileFromFakeTrace(traceEvents: readonly Types.Events.Event[]): Protocol.Profiler.Profile;
+}
+export declare namespace SamplesIntegrator {
+    const enum NativeGroups {
+        COMPILE = "Compile",
+        PARSE = "Parse"
+    }
+}

package/dist/lib/front_end/models/trace/helpers/SyntheticEvents.d.ts

@@ -0,0 +1,13 @@
+import type * as Types from '../types/types.js';
+export declare class SyntheticEventsManager {
+    #private;
+    static activate(manager: SyntheticEventsManager): void;
+    static createAndActivate(rawEvents: readonly Types.Events.Event[]): SyntheticEventsManager;
+    static getActiveManager(): SyntheticEventsManager;
+    static reset(): void;
+    static registerSyntheticEvent<T extends Types.Events.SyntheticBased>(syntheticEvent: Omit<T, '_tag'>): T;
+    private constructor();
+    syntheticEventForRawEventIndex(rawEventIndex: number): Types.Events.SyntheticBased;
+    getSyntheticTraces(): Types.Events.SyntheticBased[];
+    getRawTraceEvents(): readonly Types.Events.Event[];
+}