devtools-tracing 1.2.1 → 1.3.0

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

@@ -0,0 +1,59 @@
+import * as Types from '../types/types.js';
+export declare const milliToMicro: (value: Types.Timing.Milli) => Types.Timing.Micro;
+export declare const secondsToMilli: (value: Types.Timing.Seconds) => Types.Timing.Milli;
+export declare const secondsToMicro: (value: Types.Timing.Seconds) => Types.Timing.Micro;
+export declare const microToMilli: (value: Types.Timing.Micro) => Types.Timing.Milli;
+export declare const microToSeconds: (value: Types.Timing.Micro) => Types.Timing.Seconds;
+export declare function timeStampForEventAdjustedByClosestNavigation(event: Types.Events.Event, traceBounds: Types.Timing.TraceWindowMicro, navigationsByNavigationId: Map<string, Types.Events.NavigationStart>, softNavigationsById: Map<number, Types.Events.SoftNavigationStart>, navigationsByFrameId: Map<string, Types.Events.NavigationStart[]>): Types.Timing.Micro;
+/**
+ * Expands the trace window by a provided percentage or, if it the expanded window is smaller than 1 millisecond, expands it to 1 millisecond.
+ * If the expanded window is outside of the max trace window, cut the overflowing bound to the max trace window bound.
+ **/
+export declare function expandWindowByPercentOrToOneMillisecond(annotationWindow: Types.Timing.TraceWindowMicro, maxTraceWindow: Types.Timing.TraceWindowMicro, percentage: number): Types.Timing.TraceWindowMicro;
+export interface EventTimingsData<ValueType extends Types.Timing.Micro | Types.Timing.Milli | Types.Timing.Seconds> {
+    startTime: ValueType;
+    endTime: ValueType;
+    duration: ValueType;
+}
+export declare function eventTimingsMicroSeconds(event: Types.Events.Event): EventTimingsData<Types.Timing.Micro>;
+export declare function eventTimingsMilliSeconds(event: Types.Events.Event): EventTimingsData<Types.Timing.Milli>;
+export declare function traceWindowMilliSeconds(bounds: Types.Timing.TraceWindowMicro): Types.Timing.TraceWindowMilli;
+export declare function traceWindowMicroSecondsToMilliSeconds(bounds: Types.Timing.TraceWindowMicro): Types.Timing.TraceWindowMilli;
+export declare function traceWindowFromMilliSeconds(min: Types.Timing.Milli, max: Types.Timing.Milli): Types.Timing.TraceWindowMicro;
+export declare function traceWindowFromMicroSeconds(min: Types.Timing.Micro, max: Types.Timing.Micro): Types.Timing.TraceWindowMicro;
+export declare function traceWindowFromEvent(event: Types.Events.Event): Types.Timing.TraceWindowMicro;
+export declare function traceWindowFromOverlay(overlay: Types.Overlays.Overlay): Types.Timing.TraceWindowMicro | null;
+/**
+ * Combines (as in a union) multiple windows into one.
+ */
+export declare function combineTraceWindowsMicro(windows: Types.Timing.TraceWindowMicro[]): Types.Timing.TraceWindowMicro | null;
+export interface BoundsIncludeTimeRange {
+    timeRange: Types.Timing.TraceWindowMicro;
+    bounds: Types.Timing.TraceWindowMicro;
+}
+/**
+ * Checks to see if the timeRange is within the bounds. By "within" we mean
+ * "has any overlap":
+ *         |------------------------|
+ *      ==                                     no overlap (entirely before)
+ *       =========                             overlap
+ *            =========                        overlap
+ *                             =========       overlap
+ *                                     ====    no overlap (entirely after)
+ *        ==============================       overlap (time range is larger than bounds)
+ *         |------------------------|
+ */
+export declare function boundsIncludeTimeRange(data: BoundsIncludeTimeRange): boolean;
+/** Checks to see if the event is within or overlaps the bounds */
+export declare function eventIsInBounds(event: Types.Events.Event, bounds: Types.Timing.TraceWindowMicro): boolean;
+export declare function timestampIsInBounds(bounds: Types.Timing.TraceWindowMicro, timestamp: Types.Timing.Micro): boolean;
+export interface WindowFitsInsideBounds {
+    window: Types.Timing.TraceWindowMicro;
+    bounds: Types.Timing.TraceWindowMicro;
+}
+/**
+ * Returns true if the window fits entirely within the bounds.
+ * Note that if the window is equivalent to the bounds, that is considered to fit
+ */
+export declare function windowFitsInsideBounds(data: WindowFitsInsideBounds): boolean;
+export declare function windowsEqual(w1: Types.Timing.TraceWindowMicro, w2: Types.Timing.TraceWindowMicro): boolean;

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

@@ -0,0 +1,148 @@
+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';
+/**
+ * Extracts the raw stack trace in known trace events. Most likely than
+ * not you want to use `getZeroIndexedStackTraceForEvent`, which returns
+ * the stack with zero based numbering. Since some trace events are
+ * one based this function can yield unexpected results when used
+ * indiscriminately.
+ *
+ * Note: this only returns the stack trace contained in the payload of
+ * an event, which only contains the synchronous portion of the call
+ * stack. If you want to obtain the whole stack trace you might need to
+ * use the @see Trace.Extras.StackTraceForEvent util.
+ */
+export declare function stackTraceInEvent(event: Types.Events.Event): Types.Events.CallFrame[] | null;
+export declare function extractOriginFromTrace(firstNavigationURL: string): string | null;
+export type EventsInThread<T extends Types.Events.Event> = Map<Types.Events.ThreadID, T[]>;
+/**
+ * Each thread contains events. Events indicate the thread and process IDs, which are
+ * used to store the event in the correct process thread entry below.
+ **/
+export declare function addEventToProcessThread<T extends Types.Events.Event>(event: T, eventsInProcessThread: Map<Types.Events.ProcessID, EventsInThread<T>>): void;
+export declare function compareBeginAndEnd(aBeginTime: number, bBeginTime: number, aEndTime: number, bEndTime: number): -1 | 0 | 1;
+export declare function eventTimeComparator(a: Types.Events.Event, b: Types.Events.Event): -1 | 0 | 1;
+/**
+ * Sorts all the events in place, in order, by their start time. If they have
+ * the same start time, orders them by longest first.
+ */
+export declare function sortTraceEventsInPlace(events: Types.Events.Event[]): void;
+/**
+ * Returns an array of ordered events that results after merging the two
+ * ordered input arrays.
+ */
+export declare function mergeEventsInOrder<T1 extends Types.Events.Event, T2 extends Types.Events.Event>(eventsArray1: readonly T1[], eventsArray2: readonly T2[]): Array<T1 | T2>;
+export declare function parseDevtoolsDetails(timingDetail: string, key: string): Types.Extensions.DevToolsObj | Types.Extensions.ExtensionTrackEntryPayloadDeeplink | null;
+export declare function getNavigationForTraceEvent(event: Types.Events.Event, eventFrameId: string, navigationsByFrameId: Map<string, Types.Events.NavigationStart[]>): Types.Events.NavigationStart | null;
+export declare function extractId(event: Types.Events.PairableAsync | Types.Events.SyntheticEventPair<Types.Events.PairableAsync>): string | undefined;
+export declare function activeURLForFrameAtTime(frameId: string, time: Types.Timing.Micro, rendererProcessesByFrame: Map<string, Map<Types.Events.ProcessID, Array<{
+    frame: Types.Events.TraceFrame;
+    window: Types.Timing.TraceWindowMicro;
+}>>>): string | null;
+/**
+ * @param node the node attached to the profile call. Here a node represents a function in the call tree.
+ * @param profileId the profile ID that the sample came from that backs this call.
+ * @param sampleIndex the index of the sample in the given profile that this call was created from
+ * @param ts the timestamp of the profile call
+ * @param pid the process ID of the profile call
+ * @param tid the thread ID of the profile call
+ *
+ * See `panels/timeline/docs/profile_calls.md` for more context on how these events are created.
+ */
+export declare function makeProfileCall(node: CPUProfile.ProfileTreeModel.ProfileNode, profileId: Types.Events.ProfileID, sampleIndex: number, ts: Types.Timing.Micro, pid: Types.Events.ProcessID, tid: Types.Events.ThreadID): Types.Events.SyntheticProfileCall;
+export declare function getSyntheticId(event: Types.Events.PairableAsync): string | undefined;
+/**
+ * Groups up sets of async events into synthetic events.
+ * @param unpairedAsyncEvents the raw array of begin, end and async instant
+ * events. These MUST be sorted in timestamp ASC order.
+ */
+export declare function createMatchedSortedSyntheticEvents<T extends Types.Events.PairableAsync>(unpairedAsyncEvents: T[]): Array<Types.Events.SyntheticEventPair<T>>;
+/**
+ * Different trace events return line/column numbers that are 1 or 0 indexed.
+ * This function knows which events return 1 indexed numbers and normalizes
+ * them. The UI expects 0 indexed line numbers, so that is what we return.
+ */
+export declare function getZeroIndexedLineAndColumnForEvent(event: Types.Events.Event): {
+    lineNumber?: number;
+    columnNumber?: number;
+};
+/**
+ * Different trace events contain stack traces with line/column numbers
+ * that are 1 or 0 indexed.
+ * This function knows which events return 1 indexed numbers and normalizes
+ * them. The UI expects 0 indexed line numbers, so that is what we return.
+ *
+ * Note: this only returns the stack trace contained in the payload of
+ * an event, which only contains the synchronous portion of the call
+ * stack. If you want to obtain the whole stack trace you might need to
+ * use the @see Trace.Extras.StackTraceForEvent util.
+ */
+export declare function getZeroIndexedStackTraceInEventPayload(event: Types.Events.Event): Types.Events.CallFrame[] | null;
+/**
+ * Same as getZeroIndexedStackTraceInEventPayload, but only returns the top call frame.
+ */
+export declare function getStackTraceTopCallFrameInEventPayload(event: Types.Events.Event): Types.Events.CallFrame | null;
+export declare function rawCallFrameForEntry(entry: Types.Events.Event): Protocol.Runtime.CallFrame | null;
+/**
+ * Given a 1-based call frame creates a 0-based one.
+ */
+export declare function makeZeroBasedCallFrame(callFrame: Types.Events.CallFrame): Types.Events.CallFrame;
+export declare function frameIDForEvent(event: Types.Events.Event): string | null;
+export declare function isTopLevelEvent(event: Types.Events.Event): boolean;
+export declare function isExtensionUrl(url: string): boolean;
+export declare function findRecalcStyleEvents(events: Types.Events.Event[], startTime: Types.Timing.Micro, endTime?: Types.Timing.Micro): Types.Events.RecalcStyle[];
+export declare function findNextEventAfterTimestamp<T extends Types.Events.Event>(candidates: T[], ts: Types.Timing.Micro): T | null;
+export declare function findPreviousEventBeforeTimestamp<T extends Types.Events.Event>(candidates: T[], ts: Types.Timing.Micro): T | null;
+export interface ForEachEventConfig {
+    onStartEvent: (event: Types.Events.Event) => void;
+    onEndEvent: (event: Types.Events.Event) => void;
+    onInstantEvent?: (event: Types.Events.Event) => void;
+    eventFilter?: (event: Types.Events.Event) => boolean;
+    startTime?: Types.Timing.Micro;
+    endTime?: Types.Timing.Micro;
+    ignoreAsyncEvents?: boolean;
+}
+/**
+ * Iterates events in a tree hierarchically, from top to bottom,
+ * calling back on every event's start and end in the order
+ * dictated by the corresponding timestamp.
+ *
+ * Events are assumed to be in ascendent order by timestamp.
+ *
+ * Events with 0 duration are treated as instant events. These do not have a
+ * begin and end, but will be passed to the config.onInstantEvent callback as
+ * they are discovered. Do not provide this callback if you are not interested
+ * in them.
+ *
+ * For example, given this tree, the following callbacks
+ * are expected to be made in the following order
+ * |---------------A---------------|
+ *  |------B------||-------D------|
+ *    |---C---|
+ *
+ * 1. Start A
+ * 3. Start B
+ * 4. Start C
+ * 5. End C
+ * 6. End B
+ * 7. Start D
+ * 8. End D
+ * 9. End A
+ *
+ * By default, async events are skipped. This behaviour can be
+ * overridden making use of the config.ignoreAsyncEvents parameter.
+ */
+export declare function forEachEvent(events: Types.Events.Event[], config: ForEachEventConfig): void;
+export declare function eventHasCategory(event: Types.Events.Event, category: string): boolean;
+/**
+ * This compares Types.Events.CallFrame with Protocol.Runtime.CallFrame and checks for equality.
+ */
+export declare function isMatchingCallFrame(eventFrame: Types.Events.CallFrame, nodeFrame: Protocol.Runtime.CallFrame): boolean;
+export declare function eventContainsTimestamp(event: Types.Events.Event, ts: Types.Timing.Micro): boolean;
+export declare function extractSampleTraceId(event: Types.Events.Event): number | null;
+/**
+ * This exactly matches Trace.Styles.visibleTypes. See the runtime verification in maybeInitStylesMap.
+ * TODO(crbug.com/410884528)
+ **/
+export declare const VISIBLE_TRACE_EVENT_TYPES: Set<Types.Events.Name>;

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

@@ -0,0 +1,109 @@
+import type * as Platform from '../../../core/platform/platform.js';
+import * as Types from '../types/types.js';
+export declare const makeTraceEntryNodeId: () => TraceEntryNodeId;
+export declare const makeEmptyTraceEntryTree: () => TraceEntryTree;
+export declare const makeEmptyTraceEntryNode: (entry: Types.Events.Event, id: TraceEntryNodeId) => TraceEntryNode;
+export interface TraceEntryTree {
+    roots: Set<TraceEntryNode>;
+    maxDepth: number;
+}
+/** Node in the graph that defines all parent/child relationships. */
+export interface TraceEntryNode {
+    entry: Types.Events.Event;
+    depth: number;
+    selfTime?: Types.Timing.Micro;
+    id: TraceEntryNodeId;
+    parent: TraceEntryNode | null;
+    children: TraceEntryNode[];
+}
+export type TraceEntryNodeId = Platform.Brand.Brand<number, 'traceEntryNodeIdTag'>;
+/**
+ * Builds a hierarchy of the entries (trace events and profile calls) in
+ * a particular thread of a particular process, assuming that they're
+ * sorted, by iterating through all of the events in order.
+ *
+ * The approach is analogous to how a parser would be implemented. A
+ * stack maintains local context. A scanner peeks and pops from the data
+ * stream. Various "tokens" (events) are treated as "whitespace"
+ * (ignored).
+ *
+ * The tree starts out empty and is populated as the hierarchy is built.
+ * The nodes are also assumed to be created empty, with no known parent
+ * or children.
+ *
+ * Complexity: O(n), where n = number of events
+ */
+export declare function treify(entries: readonly Types.Events.Event[], options?: {
+    filter: {
+        has: (name: Types.Events.Name) => boolean;
+    };
+}): {
+    tree: TraceEntryTree;
+    entryToNode: Map<Types.Events.Event, TraceEntryNode>;
+};
+/**
+ * Iterates events in a tree hierarchically, from top to bottom,
+ * calling back on every event's start and end in the order
+ * as it traverses down and then up the tree.
+ *
+ * For example, given this tree, the following callbacks
+ * are expected to be made in the following order
+ * |---------------A---------------|
+ *  |------B------||-------D------|
+ *    |---C---|
+ *
+ * 1. Start A
+ * 3. Start B
+ * 4. Start C
+ * 5. End C
+ * 6. End B
+ * 7. Start D
+ * 8. End D
+ * 9. End A
+ *
+ */
+export declare function walkTreeFromEntry(entryToNode: Map<Types.Events.Event, TraceEntryNode>, rootEntry: Types.Events.Event, onEntryStart: (entry: Types.Events.Event) => void, onEntryEnd: (entry: Types.Events.Event) => void): void;
+/**
+ * Given a Helpers.TreeHelpers.RendererTree, this will iterates events in hierarchically, visiting
+ * each root node and working from top to bottom, calling back on every event's
+ * start and end in the order as it traverses down and then up the tree.
+ *
+ * For example, given this tree, the following callbacks
+ * are expected to be made in the following order
+ * |------------- Task A -------------||-- Task E --|
+ *  |-- Task B --||-- Task D --|
+ *   |- Task C -|
+ *
+ * 1. Start A
+ * 3. Start B
+ * 4. Start C
+ * 5. End C
+ * 6. End B
+ * 7. Start D
+ * 8. End D
+ * 9. End A
+ * 10. Start E
+ * 11. End E
+ *
+ */
+export declare function walkEntireTree(entryToNode: Map<Types.Events.Event, TraceEntryNode>, tree: TraceEntryTree, onEntryStart: (entry: Types.Events.Event) => void, onEntryEnd: (entry: Types.Events.Event) => void, traceWindowToInclude?: Types.Timing.TraceWindowMicro, minDuration?: Types.Timing.Micro): void;
+/**
+ * Determines if the given events, which are assumed to be ordered can
+ * be organized into tree structures.
+ * This condition is met if there is *not* a pair of async events
+ * e1 and e2 where:
+ *
+ * e1.startTime < e2.startTime && e1.endTime > e2.startTime && e1.endTime < e2.endTime.
+ * or, graphically:
+ * |------- e1 ------|
+ *   |------- e2 --------|
+ *
+ * Because a parent-child relationship cannot be made from the example
+ * above, a tree cannot be made from the set of events.
+ *
+ * Sync events from the same thread are tree-able by definition.
+ *
+ * Note that this will also return true if multiple trees can be
+ * built, for example if none of the events overlap with each other.
+ */
+export declare function canBuildTreesFromEvents(events: readonly Types.Events.Event[]): boolean;

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

@@ -0,0 +1,7 @@
+export * as Extensions from './Extensions.js';
+export * as Network from './Network.js';
+export * as SamplesIntegrator from './SamplesIntegrator.js';
+export * as SyntheticEvents from './SyntheticEvents.js';
+export * as Timing from './Timing.js';
+export * as Trace from './Trace.js';
+export * as TreeHelpers from './TreeHelpers.js';

package/dist/lib/front_end/models/trace/insights/CLSCulprits.d.ts

@@ -0,0 +1,137 @@
+import * as Platform from '../../../core/platform/platform.js';
+import type * as Protocol from '../../../generated/protocol.js';
+import * as Handlers from '../handlers/handlers.js';
+import * as Types from '../types/types.js';
+import { type InsightModel, type InsightSetContext } from './types.js';
+export declare const UIStrings: {
+    /** Title of an insight that provides details about why elements shift/move on the page. The causes for these shifts are referred to as culprits ("reasons"). */
+    readonly title: "Layout shift culprits";
+    /**
+     * @description Description of a DevTools insight that identifies the reasons that elements shift on the page.
+     * This is displayed after a user expands the section to see more. No character length limits.
+     */
+    readonly description: "Layout shifts occur when elements move absent any user interaction. [Investigate the causes of layout shifts](https://developer.chrome.com/docs/performance/insights/cls-culprit), such as elements being added, removed, or their fonts changing as the page loads.";
+    /**
+     * @description Text indicating the worst layout shift cluster.
+     */
+    readonly worstLayoutShiftCluster: "Worst layout shift cluster";
+    /**
+     * @description Text indicating the worst layout shift cluster.
+     */
+    readonly worstCluster: "Worst cluster";
+    /**
+     * @description Text indicating a layout shift cluster and its start time.
+     * @example {32 ms} PH1
+     */
+    readonly layoutShiftCluster: "Layout shift cluster @ {PH1}";
+    /**
+     * @description Text indicating the biggest reasons for the layout shifts.
+     */
+    readonly topCulprits: "Top layout shift culprits";
+    /**
+     * @description Text for a culprit type of Injected iframe.
+     */
+    readonly injectedIframe: "Injected iframe";
+    /**
+     * @description Text for a culprit type of web font request.
+     */
+    readonly webFont: "Web font";
+    /**
+     * @description Text for a culprit type of Animation.
+     */
+    readonly animation: "Animation";
+    /**
+     * @description Text for a culprit type of Unsized image.
+     */
+    readonly unsizedImage: "Unsized image element";
+    /**
+     * @description Text status when there were no layout shifts detected.
+     */
+    readonly noLayoutShifts: "No layout shifts";
+    /**
+     * @description Text status when there no layout shifts culprits/root causes were found.
+     */
+    readonly noCulprits: "Could not detect any layout shift culprits";
+};
+export declare const i18nString: any;
+export type CLSCulpritsInsightModel = InsightModel<typeof UIStrings, {
+    animationFailures: readonly NoncompositedAnimationFailure[];
+    shifts: Map<Types.Events.SyntheticLayoutShift, LayoutShiftRootCausesData>;
+    clusters: Types.Events.SyntheticLayoutShiftCluster[];
+    worstCluster: Types.Events.SyntheticLayoutShiftCluster | undefined;
+    /** The top 3 shift root causes for each cluster. */
+    topCulpritsByCluster: Map<Types.Events.SyntheticLayoutShiftCluster, LayoutShiftItem[]>;
+}>;
+export declare const enum AnimationFailureReasons {
+    ACCELERATED_ANIMATIONS_DISABLED = "ACCELERATED_ANIMATIONS_DISABLED",
+    EFFECT_SUPPRESSED_BY_DEVTOOLS = "EFFECT_SUPPRESSED_BY_DEVTOOLS",
+    INVALID_ANIMATION_OR_EFFECT = "INVALID_ANIMATION_OR_EFFECT",
+    EFFECT_HAS_UNSUPPORTED_TIMING_PARAMS = "EFFECT_HAS_UNSUPPORTED_TIMING_PARAMS",
+    EFFECT_HAS_NON_REPLACE_COMPOSITE_MODE = "EFFECT_HAS_NON_REPLACE_COMPOSITE_MODE",
+    TARGET_HAS_INVALID_COMPOSITING_STATE = "TARGET_HAS_INVALID_COMPOSITING_STATE",
+    TARGET_HAS_INCOMPATIBLE_ANIMATIONS = "TARGET_HAS_INCOMPATIBLE_ANIMATIONS",
+    TARGET_HAS_CSS_OFFSET = "TARGET_HAS_CSS_OFFSET",
+    ANIMATION_AFFECTS_NON_CSS_PROPERTIES = "ANIMATION_AFFECTS_NON_CSS_PROPERTIES",
+    TRANSFORM_RELATED_PROPERTY_CANNOT_BE_ACCELERATED_ON_TARGET = "TRANSFORM_RELATED_PROPERTY_CANNOT_BE_ACCELERATED_ON_TARGET",
+    TRANSFROM_BOX_SIZE_DEPENDENT = "TRANSFROM_BOX_SIZE_DEPENDENT",
+    FILTER_RELATED_PROPERTY_MAY_MOVE_PIXELS = "FILTER_RELATED_PROPERTY_MAY_MOVE_PIXELS",
+    UNSUPPORTED_CSS_PROPERTY = "UNSUPPORTED_CSS_PROPERTY",
+    MIXED_KEYFRAME_VALUE_TYPES = "MIXED_KEYFRAME_VALUE_TYPES",
+    TIMELINE_SOURCE_HAS_INVALID_COMPOSITING_STATE = "TIMELINE_SOURCE_HAS_INVALID_COMPOSITING_STATE",
+    ANIMATION_HAS_NO_VISIBLE_CHANGE = "ANIMATION_HAS_NO_VISIBLE_CHANGE",
+    AFFECTS_IMPORTANT_PROPERTY = "AFFECTS_IMPORTANT_PROPERTY",
+    SVG_TARGET_HAS_INDEPENDENT_TRANSFORM_PROPERTY = "SVG_TARGET_HAS_INDEPENDENT_TRANSFORM_PROPERTY"
+}
+export declare const enum LayoutShiftType {
+    WEB_FONT = 0,
+    IFRAMES = 1,
+    ANIMATIONS = 2,
+    UNSIZED_IMAGE = 3
+}
+export type LayoutShiftItem = {
+    type: LayoutShiftType.UNSIZED_IMAGE;
+    description: Platform.UIString.LocalizedString;
+    url: string;
+    backendNodeId: Protocol.DOM.BackendNodeId;
+    frame: string;
+} | {
+    type: Exclude<LayoutShiftType, LayoutShiftType.UNSIZED_IMAGE>;
+    description: Platform.UIString.LocalizedString;
+};
+export interface NoncompositedAnimationFailure {
+    /**
+     * Animation name.
+     */
+    name?: string;
+    /**
+     * Failure reason based on mask number defined in
+     * https://source.chromium.org/search?q=f:compositor_animations.h%20%22enum%20FailureReason%22.
+     */
+    failureReasons: AnimationFailureReasons[];
+    /**
+     * Unsupported properties.
+     */
+    unsupportedProperties?: Types.Events.Animation['args']['data']['unsupportedProperties'];
+    /**
+     * Animation event.
+     */
+    animation?: Types.Events.SyntheticAnimationPair;
+}
+export interface UnsizedImage {
+    backendNodeId: Protocol.DOM.BackendNodeId;
+    paintImageEvent: Types.Events.PaintImage;
+}
+export interface IframeRootCause {
+    frame: string;
+    url?: string;
+}
+export interface LayoutShiftRootCausesData {
+    iframes: IframeRootCause[];
+    webFonts: Types.Events.SyntheticNetworkRequest[];
+    nonCompositedAnimations: NoncompositedAnimationFailure[];
+    unsizedImages: UnsizedImage[];
+}
+export declare function getNonCompositedFailure(animationEvent: Types.Events.SyntheticAnimationPair): NoncompositedAnimationFailure[];
+export declare function isCLSCulpritsInsight(insight: InsightModel): insight is CLSCulpritsInsightModel;
+export declare function generateInsight(data: Handlers.Types.HandlerData, context: InsightSetContext): CLSCulpritsInsightModel;
+export declare function createOverlays(model: CLSCulpritsInsightModel): Types.Overlays.Overlay[];

package/dist/lib/front_end/models/trace/insights/Cache.d.ts

@@ -0,0 +1,71 @@
+import type * as Handlers from '../handlers/handlers.js';
+import * as Helpers from '../helpers/helpers.js';
+import type * as Types from '../types/types.js';
+import { type InsightModel, type InsightSetContext } from './types.js';
+export declare const UIStrings: {
+    /**
+     * @description Title of an insight that provides information and suggestions of resources that could improve their caching.
+     */
+    readonly title: "Use efficient cache lifetimes";
+    /**
+     * @description Text to tell the user about how caching can help improve performance.
+     */
+    readonly description: "A long cache lifetime can speed up repeat visits to your page. [Learn more about caching](https://developer.chrome.com/docs/performance/insights/cache).";
+    /**
+     * @description Column for a font loaded by the page to render text.
+     */
+    readonly requestColumn: "Request";
+    /**
+     * @description Column for a resource cache's Time To Live.
+     */
+    readonly cacheTTL: "Cache TTL";
+    /**
+     * @description Text describing that there were no requests found that need caching.
+     */
+    readonly noRequestsToCache: "No requests with inefficient cache policies";
+    /**
+     * @description Table row value representing the remaining items not shown in the table due to size constraints. This row will always represent at least 2 items.
+     * @example {5} PH1
+     */
+    readonly others: "{PH1} others";
+};
+export declare const i18nString: any;
+export type CacheInsightModel = InsightModel<typeof UIStrings, {
+    requests: Array<{
+        request: Types.Events.SyntheticNetworkRequest;
+        ttl: number;
+        wastedBytes: number;
+    }>;
+}>;
+/**
+ * Determines if a request is "cacheable".
+ * A request is "cacheable" if it is of the appropriate protocol and resource type
+ * (see Helpers.Network.NON_NETWORK_SCHEMES and Helpers.Network.STATIC_RESOURCE_TYPE)
+ * and has the appropriate statusCodes.
+ */
+export declare function isCacheable(request: Types.Events.SyntheticNetworkRequest): boolean;
+/**
+ * Returns max-age if defined, otherwise expires header if defined, and null if not.
+ */
+export declare function computeCacheLifetimeInSeconds(headers: Array<{
+    name: string;
+    value: string;
+}>, cacheControl: Helpers.Network.CacheControl | null): number | null;
+export declare function getCombinedHeaders(responseHeaders: Array<{
+    name: string;
+    value: string;
+}>): Map<string, string>;
+/**
+ * Returns whether a request contains headers that disable caching.
+ * Disabled caching is checked on the 'cache-control' and 'pragma' headers.
+ */
+export declare function cachingDisabled(headers: Map<string, string> | null, parsedCacheControl: Helpers.Network.CacheControl | null): boolean;
+export interface CacheableRequest {
+    request: Types.Events.SyntheticNetworkRequest;
+    ttl: number;
+    wastedBytes: number;
+}
+export declare function isCacheInsight(model: InsightModel): model is CacheInsightModel;
+export declare function generateInsight(data: Handlers.Types.HandlerData, context: InsightSetContext): CacheInsightModel;
+export declare function createOverlayForRequest(request: Types.Events.SyntheticNetworkRequest): Types.Overlays.EntryOutline;
+export declare function createOverlays(model: CacheInsightModel): Types.Overlays.Overlay[];

package/dist/lib/front_end/models/trace/insights/CharacterSet.d.ts

@@ -0,0 +1,49 @@
+import type * as Handlers from '../handlers/handlers.js';
+import type * as Types from '../types/types.js';
+import { type Checklist, type InsightModel, type InsightSetContext } from './types.js';
+export declare const UIStrings: {
+    /**
+     * @description Title of an insight that checks whether the page declares a character encoding early enough.
+     */
+    readonly title: "Declare a character encoding";
+    /**
+     * @description Description of an insight that checks whether the page has a proper character encoding declaration via HTTP header or early meta tag.
+     */
+    readonly description: "A character encoding declaration is required. It can be done with a meta charset tag in the first 1024 bytes of the HTML or in the Content-Type HTTP response header. [Learn more about declaring the character encoding](https://developer.chrome.com/docs/insights/charset/).";
+    /**
+     * @description Text to tell the user that the charset is declared in the Content-Type HTTP response header.
+     */
+    readonly passingHttpHeader: "Declares charset in HTTP header";
+    /**
+     * @description Text to tell the user that the charset is NOT declared in the Content-Type HTTP response header.
+     */
+    readonly failedHttpHeader: "Does not declare charset in HTTP header";
+    /**
+     * @description Text to tell the user that a meta charset tag was found in the first 1024 bytes of the HTML.
+     */
+    readonly passingMetaCharsetEarly: "Declares charset using a meta tag in the first 1024 bytes";
+    /**
+     * @description Text to tell the user that a meta charset tag was found, but too late in the HTML.
+     */
+    readonly failedMetaCharsetLate: "Declares charset using a meta tag after the first 1024 bytes";
+    /**
+     * @description Text to tell the user that no meta charset tag was found in the HTML.
+     */
+    readonly failedMetaCharsetMissing: "Does not declare charset using a meta tag";
+    /**
+     * @description Text to tell the user that trace data did not include the Blink signal for meta charset.
+     */
+    readonly failedMetaCharsetUnknown: "Could not determine meta charset declaration from trace";
+};
+export declare const i18nString: any;
+export type CharacterSetInsightModel = InsightModel<typeof UIStrings, {
+    data?: {
+        hasHttpCharset: boolean;
+        checklist: Checklist<'httpCharset' | 'metaCharset'>;
+        metaCharsetDisposition?: Types.Events.MetaCharsetDisposition;
+        documentRequest?: Types.Events.SyntheticNetworkRequest;
+    };
+}>;
+export declare function isCharacterSetInsight(model: InsightModel): model is CharacterSetInsightModel;
+export declare function generateInsight(data: Handlers.Types.HandlerData, context: InsightSetContext): CharacterSetInsightModel;
+export declare function createOverlays(model: CharacterSetInsightModel): Types.Overlays.Overlay[];

package/dist/lib/front_end/models/trace/insights/Common.d.ts

@@ -0,0 +1,77 @@
+import * as Protocol from '../../../generated/protocol.js';
+import type * as CrUXManager from '../../crux-manager/crux-manager.js';
+import type * as Handlers from '../handlers/handlers.js';
+import * as Types from '../types/types.js';
+import { type InsightModel, type InsightModels, type InsightSet, type InsightSetContext, type MetricSavings } from './types.js';
+export declare function getInsight<InsightName extends keyof InsightModels>(insightName: InsightName, insightSet: InsightSet): InsightModels[InsightName];
+export declare function getLCP(insightSet: InsightSet): {
+    value: Types.Timing.Micro;
+    event: Types.Events.AnyLargestContentfulPaintCandidate;
+} | null;
+export declare function getINP(insightSet: InsightSet): {
+    value: Types.Timing.Micro;
+    event: Types.Events.SyntheticInteractionPair;
+} | null;
+export declare function getCLS(insightSet: InsightSet): {
+    value: number;
+    worstClusterEvent: Types.Events.Event | null;
+};
+export declare function evaluateLCPMetricScore(value: Types.Timing.Milli): number;
+export declare function evaluateINPMetricScore(value: Types.Timing.Milli): number;
+export declare function evaluateCLSMetricScore(value: number): number;
+export interface CrUXFieldMetricTimingResult {
+    value: Types.Timing.Micro;
+    pageScope: CrUXManager.PageScope;
+}
+export interface CrUXFieldMetricNumberResult {
+    value: number;
+    pageScope: CrUXManager.PageScope;
+}
+export interface CrUXFieldMetricResults {
+    fcp: CrUXFieldMetricTimingResult | null;
+    lcp: CrUXFieldMetricTimingResult | null;
+    inp: CrUXFieldMetricTimingResult | null;
+    cls: CrUXFieldMetricNumberResult | null;
+    lcpBreakdown: {
+        ttfb: CrUXFieldMetricTimingResult | null;
+        loadDelay: CrUXFieldMetricTimingResult | null;
+        loadDuration: CrUXFieldMetricTimingResult | null;
+        renderDelay: CrUXFieldMetricTimingResult | null;
+    };
+}
+export declare function getFieldMetricsForInsightSet(insightSet: InsightSet, metadata: Types.File.MetaData | null, scope?: CrUXManager.Scope | null): CrUXFieldMetricResults | null;
+export declare function calculateMetricWeightsForSorting(insightSet: InsightSet, metadata: Types.File.MetaData | null): {
+    lcp: number;
+    inp: number;
+    cls: number;
+};
+/**
+ * Estimates the FCP & LCP savings for wasted bytes in `wastedBytesByRequestId`.
+ */
+export declare function metricSavingsForWastedBytes(wastedBytesByRequestId: Map<string, number>, context: InsightSetContext): MetricSavings | undefined;
+/**
+ * Returns whether the network request was sent encoded.
+ */
+export declare function isRequestCompressed(request: Types.Events.SyntheticNetworkRequest): boolean;
+export declare function isRequestServedFromBrowserCache(request: Types.Events.SyntheticNetworkRequest): boolean;
+/**
+ * Estimates the number of bytes the content of this network record would have consumed on the network based on the
+ * uncompressed size (totalBytes). Uses the actual transfer size from the network record if applicable,
+ * minus the size of the response headers.
+ *
+ * @param totalBytes Uncompressed size of the resource
+ */
+export declare function estimateCompressedContentSize(request: Types.Events.SyntheticNetworkRequest | undefined, totalBytes: number, resourceType: Protocol.Network.ResourceType): number;
+/**
+ * Utility function to estimate the ratio of the compression of a script.
+ * This excludes the size of the response headers.
+ */
+export declare function estimateCompressionRatioForScript(script: Handlers.ModelHandlers.Scripts.Script): number;
+export declare function calculateDocFirstByteTs(docRequest: Types.Events.SyntheticNetworkRequest): Types.Timing.Micro | null;
+/**
+ * Calculates the trace bounds for the given insight that are relevant.
+ *
+ * Uses the insight's overlays to determine the relevant trace bounds. If there are
+ * no overlays, falls back to the insight set's navigation bounds.
+ */
+export declare function insightBounds(insight: InsightModel, insightSetBounds: Types.Timing.TraceWindowMicro): Types.Timing.TraceWindowMicro;