@mcp-b/chrome-devtools-mcp 1.1.0 → 1.1.2

package/build/node_modules/chrome-devtools-frontend/front_end/models/trace/insights/LCPBreakdown.js

@@ -0,0 +1,199 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as Handlers from '../handlers/handlers.js';
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+import { calculateDocFirstByteTs } from './Common.js';
+import { InsightCategory, InsightWarning, } from './types.js';
+export const UIStrings = {
+    /**
+     * @description Title of an insight that provides details about the LCP metric, broken down by parts.
+     */
+    title: 'LCP breakdown',
+    /**
+     * @description Description of a DevTools insight that presents a breakdown for the LCP metric by subparts.
+     * This is displayed after a user expands the section to see more. No character length limits.
+     */
+    description: 'Each [subpart has specific improvement strategies](https://developer.chrome.com/docs/performance/insights/lcp-breakdown). Ideally, most of the LCP time should be spent on loading the resources, not within delays.',
+    /**
+     * @description Time to first byte title for the Largest Contentful Paint's subparts timespan breakdown.
+     */
+    timeToFirstByte: 'Time to first byte',
+    /**
+     * @description Resource load delay title for the Largest Contentful Paint subparts timespan breakdown.
+     */
+    resourceLoadDelay: 'Resource load delay',
+    /**
+     * @description Resource load duration title for the Largest Contentful Paint subparts timespan breakdown.
+     */
+    resourceLoadDuration: 'Resource load duration',
+    /**
+     * @description Element render delay title for the Largest Contentful Paint subparts timespan breakdown.
+     */
+    elementRenderDelay: 'Element render delay',
+    /**
+     * @description Label used for the subpart (section) of a larger duration.
+     */
+    subpart: 'Subpart',
+    /**
+     * @description Label used for the duration a single subpart (section) takes up of a larger duration.
+     */
+    duration: 'Duration',
+    /**
+     * @description Label used for the duration a single subpart (section) takes up of a larger duration. The value will be the 75th percentile of aggregate data. "Field" means that the data was collected from real users in the field as opposed to the developers local environment. "Field" is synonymous with "Real user data".
+     */
+    fieldDuration: 'Field p75',
+    /**
+     * @description Text status indicating that the the Largest Contentful Paint (LCP) metric timing was not found. "LCP" is an acronym and should not be translated.
+     */
+    noLcp: 'No LCP detected',
+};
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/LCPBreakdown.ts', UIStrings);
+export const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+export function isLCPBreakdownInsight(model) {
+    return model.insightKey === 'LCPBreakdown';
+}
+function anyValuesNaN(...values) {
+    return values.some(v => Number.isNaN(v));
+}
+/**
+ * Calculates the 2–4 subparts of an LCP as bounds.
+ * Will return `null` if any required values were missing. We don't ever expect
+ * them to be missing on newer traces, but old trace files may lack some of the
+ * data we rely on, so we want to handle that case.
+ */
+function determineSubparts(nav, docRequest, lcpEvent, lcpRequest) {
+    const firstDocByteTs = calculateDocFirstByteTs(docRequest);
+    if (firstDocByteTs === null) {
+        return null;
+    }
+    const ttfb = Helpers.Timing.traceWindowFromMicroSeconds(nav.ts, firstDocByteTs);
+    ttfb.label = i18nString(UIStrings.timeToFirstByte);
+    let renderDelay = Helpers.Timing.traceWindowFromMicroSeconds(ttfb.max, lcpEvent.ts);
+    renderDelay.label = i18nString(UIStrings.elementRenderDelay);
+    // If the LCP is text, we don't have a request, so just 2 subparts.
+    if (!lcpRequest) {
+        /**
+         * Text LCP. 2 subparts, thus 3 timestamps
+         *
+         *       |          ttfb           |             renderDelay              |
+         *                                                                        ^ lcpEvent.ts
+         *                                 ^ firstDocByteTs
+         *       ^ navStartTs
+         */
+        if (anyValuesNaN(ttfb.range, renderDelay.range)) {
+            return null;
+        }
+        return { ttfb, renderDelay };
+    }
+    /**
+     * Image LCP. 4 subparts means 5 timestamps
+     *
+     *       |  ttfb   |    loadDelay     |     loadTime    |    renderDelay    |
+     *                                                                          ^ lcpEvent.ts
+     *                                                      ^ lcpReqEndTs
+     *                                    ^ lcpStartTs
+     *                 ^ ttfbTs
+     *       ^ navStartTs
+     */
+    const lcpStartTs = lcpRequest.ts;
+    const lcpReqEndTs = lcpRequest.args.data.syntheticData.finishTime;
+    const loadDelay = Helpers.Timing.traceWindowFromMicroSeconds(ttfb.max, lcpStartTs);
+    const loadDuration = Helpers.Timing.traceWindowFromMicroSeconds(lcpStartTs, lcpReqEndTs);
+    renderDelay = Helpers.Timing.traceWindowFromMicroSeconds(lcpReqEndTs, lcpEvent.ts);
+    loadDelay.label = i18nString(UIStrings.resourceLoadDelay);
+    loadDuration.label = i18nString(UIStrings.resourceLoadDuration);
+    renderDelay.label = i18nString(UIStrings.elementRenderDelay);
+    if (anyValuesNaN(ttfb.range, loadDelay.range, loadDuration.range, renderDelay.range)) {
+        return null;
+    }
+    return {
+        ttfb,
+        loadDelay,
+        loadDuration,
+        renderDelay,
+    };
+}
+function finalize(partialModel) {
+    const relatedEvents = [];
+    if (partialModel.lcpEvent) {
+        relatedEvents.push(partialModel.lcpEvent);
+    }
+    if (partialModel.lcpRequest) {
+        relatedEvents.push(partialModel.lcpRequest);
+    }
+    let state = 'pass';
+    if (partialModel.lcpMs !== undefined) {
+        const classification = Handlers.ModelHandlers.PageLoadMetrics.scoreClassificationForLargestContentfulPaint(Helpers.Timing.milliToMicro(partialModel.lcpMs));
+        if (classification === "good" /* Handlers.ModelHandlers.PageLoadMetrics.ScoreClassification.GOOD */) {
+            state = 'informative';
+        }
+        else {
+            state = 'fail';
+        }
+    }
+    return {
+        insightKey: "LCPBreakdown" /* InsightKeys.LCP_BREAKDOWN */,
+        strings: UIStrings,
+        title: i18nString(UIStrings.title),
+        description: i18nString(UIStrings.description),
+        docs: 'https://developer.chrome.com/docs/performance/insights/lcp-breakdown',
+        category: InsightCategory.LCP,
+        state,
+        ...partialModel,
+        relatedEvents,
+    };
+}
+export function generateInsight(data, context) {
+    if (!context.navigation) {
+        return finalize({});
+    }
+    const networkRequests = data.NetworkRequests;
+    const frameMetrics = data.PageLoadMetrics.metricScoresByFrameId.get(context.frameId);
+    if (!frameMetrics) {
+        throw new Error('no frame metrics');
+    }
+    const navMetrics = frameMetrics.get(context.navigationId);
+    if (!navMetrics) {
+        throw new Error('no navigation metrics');
+    }
+    const metricScore = navMetrics.get("LCP" /* Handlers.ModelHandlers.PageLoadMetrics.MetricName.LCP */);
+    const lcpEvent = metricScore?.event;
+    if (!lcpEvent || !Types.Events.isLargestContentfulPaintCandidate(lcpEvent)) {
+        return finalize({ warnings: [InsightWarning.NO_LCP] });
+    }
+    // This helps calculate the subparts.
+    const lcpMs = Helpers.Timing.microToMilli(metricScore.timing);
+    // This helps position things on the timeline's UI accurately for a trace.
+    const lcpTs = metricScore.event?.ts ? Helpers.Timing.microToMilli(metricScore.event?.ts) : undefined;
+    const lcpRequest = data.LargestImagePaint.lcpRequestByNavigationId.get(context.navigationId);
+    const docRequest = networkRequests.byId.get(context.navigationId);
+    if (!docRequest) {
+        return finalize({ lcpMs, lcpTs, lcpEvent, lcpRequest, warnings: [InsightWarning.NO_DOCUMENT_REQUEST] });
+    }
+    return finalize({
+        lcpMs,
+        lcpTs,
+        lcpEvent,
+        lcpRequest,
+        subparts: determineSubparts(context.navigation, docRequest, lcpEvent, lcpRequest) ?? undefined,
+    });
+}
+export function createOverlays(model) {
+    if (!model.subparts || !model.lcpTs) {
+        return [];
+    }
+    const overlays = [
+        {
+            type: 'TIMESPAN_BREAKDOWN',
+            sections: Object.values(model.subparts)
+                .map((subpart) => ({ bounds: subpart, label: subpart.label, showDuration: true })),
+        },
+    ];
+    if (model.lcpRequest) {
+        overlays.push({ type: 'ENTRY_OUTLINE', entry: model.lcpRequest, outlineReason: 'INFO' });
+    }
+    return overlays;
+}

package/build/node_modules/chrome-devtools-frontend/front_end/models/trace/insights/LCPDiscovery.js

@@ -0,0 +1,183 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as Handlers from '../handlers/handlers.js';
+import * as Helpers from '../helpers/helpers.js';
+import * as Types from '../types/types.js';
+import { calculateDocFirstByteTs } from './Common.js';
+import { InsightCategory, InsightWarning, } from './types.js';
+export const UIStrings = {
+    /**
+     * @description Title of an insight that provides details about the LCP metric, and the network requests necessary to load it. Details how the LCP request was discoverable - in other words, the path necessary to load it (ex: network requests, JavaScript)
+     */
+    title: 'LCP request discovery',
+    /**
+     * @description Description of an insight that provides details about the LCP metric, and the network requests necessary to load it.
+     */
+    description: '[Optimize LCP](https://developer.chrome.com/docs/performance/insights/lcp-discovery) by making the LCP image discoverable from the HTML immediately, and avoiding lazy-loading',
+    /**
+     * @description Text to tell the user how long after the earliest discovery time their LCP element loaded.
+     * @example {401ms} PH1
+     */
+    lcpLoadDelay: 'LCP image loaded {PH1} after earliest start point.',
+    /**
+     * @description Text to tell the user that a fetchpriority property value of "high" is applied to the LCP request.
+     */
+    fetchPriorityApplied: 'fetchpriority=high applied',
+    /**
+     * @description Text to tell the user that a fetchpriority property value of "high" should be applied to the LCP request.
+     */
+    fetchPriorityShouldBeApplied: 'fetchpriority=high should be applied',
+    /**
+     * @description Text to tell the user that the LCP request is discoverable in the initial document.
+     */
+    requestDiscoverable: 'Request is discoverable in initial document',
+    /**
+     * @description Text to tell the user that the LCP request does not have the lazy load property applied.
+     */
+    lazyLoadNotApplied: 'lazy load not applied',
+    /**
+     * @description Text status indicating that the the Largest Contentful Paint (LCP) metric timing was not found. "LCP" is an acronym and should not be translated.
+     */
+    noLcp: 'No LCP detected',
+    /**
+     * @description Text status indicating that the Largest Contentful Paint (LCP) metric was text rather than an image. "LCP" is an acronym and should not be translated.
+     */
+    noLcpResource: 'No LCP resource detected because the LCP is not an image',
+};
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/LCPDiscovery.ts', UIStrings);
+export const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+export function isLCPDiscoveryInsight(model) {
+    return model.insightKey === 'LCPDiscovery';
+}
+function finalize(partialModel) {
+    const relatedEvents = partialModel.lcpEvent && partialModel.lcpRequest ?
+        // TODO: add entire request initiator chain?
+        [partialModel.lcpEvent, partialModel.lcpRequest] :
+        [];
+    return {
+        insightKey: "LCPDiscovery" /* InsightKeys.LCP_DISCOVERY */,
+        strings: UIStrings,
+        title: i18nString(UIStrings.title),
+        description: i18nString(UIStrings.description),
+        docs: 'https://developer.chrome.com/docs/performance/insights/lcp-discovery',
+        category: InsightCategory.LCP,
+        state: partialModel.lcpRequest && partialModel.checklist &&
+            (!partialModel.checklist.eagerlyLoaded.value || !partialModel.checklist.requestDiscoverable.value ||
+                !partialModel.checklist.priorityHinted.value) ?
+            'fail' :
+            'pass',
+        ...partialModel,
+        relatedEvents,
+    };
+}
+export function generateInsight(data, context) {
+    if (!context.navigation) {
+        return finalize({});
+    }
+    const networkRequests = data.NetworkRequests;
+    const frameMetrics = data.PageLoadMetrics.metricScoresByFrameId.get(context.frameId);
+    if (!frameMetrics) {
+        throw new Error('no frame metrics');
+    }
+    const navMetrics = frameMetrics.get(context.navigationId);
+    if (!navMetrics) {
+        throw new Error('no navigation metrics');
+    }
+    const metricScore = navMetrics.get("LCP" /* Handlers.ModelHandlers.PageLoadMetrics.MetricName.LCP */);
+    const lcpEvent = metricScore?.event;
+    if (!lcpEvent || !Types.Events.isLargestContentfulPaintCandidate(lcpEvent)) {
+        return finalize({ warnings: [InsightWarning.NO_LCP] });
+    }
+    const docRequest = networkRequests.byId.get(context.navigationId);
+    if (!docRequest) {
+        return finalize({ warnings: [InsightWarning.NO_DOCUMENT_REQUEST] });
+    }
+    const lcpRequest = data.LargestImagePaint.lcpRequestByNavigationId.get(context.navigationId);
+    if (!lcpRequest) {
+        return finalize({ lcpEvent });
+    }
+    const initiatorUrl = lcpRequest.args.data.initiator?.url;
+    // TODO(b/372319476): Explore using trace event HTMLDocumentParser::FetchQueuedPreloads to determine if the request
+    // is discovered by the preload scanner.
+    const initiatedByMainDoc = lcpRequest?.args.data.initiator?.type === 'parser' && docRequest.args.data.url === initiatorUrl;
+    const imgPreloadedOrFoundInHTML = lcpRequest?.args.data.isLinkPreload || initiatedByMainDoc;
+    const imageLoadingAttr = lcpEvent.args.data?.loadingAttr;
+    const imageFetchPriorityHint = lcpRequest?.args.data.fetchPriorityHint;
+    // This is the earliest discovery time an LCP request could have - it's TTFB (as an absolute timestamp).
+    const earliestDiscoveryTime = calculateDocFirstByteTs(docRequest);
+    const priorityHintFound = imageFetchPriorityHint === 'high';
+    return finalize({
+        lcpEvent,
+        lcpRequest,
+        earliestDiscoveryTimeTs: earliestDiscoveryTime ? Types.Timing.Micro(earliestDiscoveryTime) : undefined,
+        checklist: {
+            priorityHinted: {
+                label: priorityHintFound ? i18nString(UIStrings.fetchPriorityApplied) :
+                    i18nString(UIStrings.fetchPriorityShouldBeApplied),
+                value: priorityHintFound
+            },
+            requestDiscoverable: { label: i18nString(UIStrings.requestDiscoverable), value: imgPreloadedOrFoundInHTML },
+            eagerlyLoaded: { label: i18nString(UIStrings.lazyLoadNotApplied), value: imageLoadingAttr !== 'lazy' },
+        },
+    });
+}
+/**
+ * TODO: this extra transformation (getImageData) should not be necessary.
+ */
+export function getImageData(model) {
+    if (!model.lcpRequest || !model.checklist) {
+        return null;
+    }
+    const shouldIncreasePriorityHint = !model.checklist.priorityHinted.value;
+    const shouldPreloadImage = !model.checklist.requestDiscoverable.value;
+    const shouldRemoveLazyLoading = !model.checklist.eagerlyLoaded.value;
+    const imageLCP = shouldIncreasePriorityHint !== undefined && shouldPreloadImage !== undefined &&
+        shouldRemoveLazyLoading !== undefined;
+    // Shouldn't render anything if lcp insight is null or lcp is text.
+    if (!imageLCP) {
+        return null;
+    }
+    const data = {
+        checklist: model.checklist,
+        request: model.lcpRequest,
+        discoveryDelay: null,
+        estimatedSavings: model.metricSavings?.LCP ?? null,
+    };
+    if (model.earliestDiscoveryTimeTs && model.lcpRequest) {
+        const discoveryDelay = model.lcpRequest.ts - model.earliestDiscoveryTimeTs;
+        data.discoveryDelay = Types.Timing.Micro(discoveryDelay);
+    }
+    return data;
+}
+export function createOverlays(model) {
+    const imageResults = getImageData(model);
+    if (!imageResults?.discoveryDelay) {
+        return [];
+    }
+    const delay = Helpers.Timing.traceWindowFromMicroSeconds(Types.Timing.Micro(imageResults.request.ts - imageResults.discoveryDelay), imageResults.request.ts);
+    return [
+        {
+            type: 'ENTRY_OUTLINE',
+            entry: imageResults.request,
+            outlineReason: 'ERROR',
+        },
+        {
+            type: 'CANDY_STRIPED_TIME_RANGE',
+            bounds: delay,
+            entry: imageResults.request,
+        },
+        {
+            type: 'TIMESPAN_BREAKDOWN',
+            sections: [{
+                    bounds: delay,
+                    // This is overridden in the component.
+                    label: `${imageResults.discoveryDelay} microseconds`,
+                    showDuration: false,
+                }],
+            entry: imageResults.request,
+            renderLocation: 'ABOVE_EVENT',
+        },
+    ];
+}

package/build/node_modules/chrome-devtools-frontend/front_end/models/trace/insights/LegacyJavaScript.js

@@ -0,0 +1,90 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as LegacyJavaScriptLib from '../../../third_party/legacy-javascript/legacy-javascript.js';
+import * as Helpers from '../helpers/helpers.js';
+import { estimateCompressionRatioForScript, metricSavingsForWastedBytes } from './Common.js';
+import { InsightCategory, } from './types.js';
+const { detectLegacyJavaScript } = LegacyJavaScriptLib.LegacyJavaScript;
+export const UIStrings = {
+    /**
+     * @description Title of an insight that identifies polyfills for modern JavaScript features, and recommends their removal.
+     */
+    title: 'Legacy JavaScript',
+    /**
+     * @description Description of an insight that identifies polyfills for modern JavaScript features, and recommends their removal.
+     */
+    description: 'Polyfills and transforms enable older browsers to use new JavaScript features. However, many aren\'t necessary for modern browsers. Consider modifying your JavaScript build process to not transpile [Baseline](https://web.dev/articles/baseline-and-polyfills) features, unless you know you must support older browsers. [Learn why most sites can deploy ES6+ code without transpiling](https://developer.chrome.com/docs/performance/insights/legacy-javascript)',
+    /** Label for a column in a data table; entries will be the individual JavaScript scripts. */
+    columnScript: 'Script',
+    /** Label for a column in a data table; entries will be the number of wasted bytes (aka the estimated savings in terms of bytes). */
+    columnWastedBytes: 'Wasted bytes',
+};
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/LegacyJavaScript.ts', UIStrings);
+export const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+const BYTE_THRESHOLD = 5000;
+function finalize(partialModel) {
+    const requests = [...partialModel.legacyJavaScriptResults.keys()].map(script => script.request).filter(e => !!e);
+    return {
+        insightKey: "LegacyJavaScript" /* InsightKeys.LEGACY_JAVASCRIPT */,
+        strings: UIStrings,
+        title: i18nString(UIStrings.title),
+        description: i18nString(UIStrings.description),
+        docs: 'https://developer.chrome.com/docs/performance/insights/legacy-javascript',
+        category: InsightCategory.ALL,
+        state: requests.length ? 'fail' : 'pass',
+        relatedEvents: [...new Set(requests)],
+        ...partialModel,
+    };
+}
+export function isLegacyJavaScript(model) {
+    return model.insightKey === "LegacyJavaScript" /* InsightKeys.LEGACY_JAVASCRIPT */;
+}
+export function generateInsight(data, context) {
+    const scripts = data.Scripts.scripts.filter(script => {
+        if (script.frame !== context.frameId) {
+            return false;
+        }
+        if (script.url?.startsWith('chrome-extension://')) {
+            return false;
+        }
+        return Helpers.Timing.timestampIsInBounds(context.bounds, script.ts) ||
+            (script.request && Helpers.Timing.eventIsInBounds(script.request, context.bounds));
+    });
+    const legacyJavaScriptResults = new Map();
+    const wastedBytesByRequestId = new Map();
+    for (const script of scripts) {
+        if (!script.content || script.content.length < BYTE_THRESHOLD) {
+            continue;
+        }
+        const result = detectLegacyJavaScript(script.content, script.sourceMap);
+        if (result.estimatedByteSavings < BYTE_THRESHOLD) {
+            continue;
+        }
+        // Translate from resource size to transfer size.
+        const compressionRatio = estimateCompressionRatioForScript(script);
+        const transferSize = Math.round(result.estimatedByteSavings * compressionRatio);
+        result.estimatedByteSavings = transferSize;
+        legacyJavaScriptResults.set(script, result);
+        if (script.request) {
+            const requestId = script.request.args.data.requestId;
+            wastedBytesByRequestId.set(requestId, transferSize);
+        }
+    }
+    const sorted = new Map([...legacyJavaScriptResults].sort((a, b) => b[1].estimatedByteSavings - a[1].estimatedByteSavings));
+    return finalize({
+        legacyJavaScriptResults: sorted,
+        metricSavings: metricSavingsForWastedBytes(wastedBytesByRequestId, context),
+        wastedBytes: wastedBytesByRequestId.values().reduce((acc, cur) => acc + cur, 0),
+    });
+}
+export function createOverlays(model) {
+    return [...model.legacyJavaScriptResults.keys()].map(script => script.request).filter(e => !!e).map(request => {
+        return {
+            type: 'ENTRY_OUTLINE',
+            entry: request,
+            outlineReason: 'ERROR',
+        };
+    });
+}

package/build/node_modules/chrome-devtools-frontend/front_end/models/trace/insights/Models.js

@@ -0,0 +1,21 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+export * as Cache from './Cache.js';
+export * as CLSCulprits from './CLSCulprits.js';
+export * as DocumentLatency from './DocumentLatency.js';
+export * as DOMSize from './DOMSize.js';
+export * as DuplicatedJavaScript from './DuplicatedJavaScript.js';
+export * as FontDisplay from './FontDisplay.js';
+export * as ForcedReflow from './ForcedReflow.js';
+export * as ImageDelivery from './ImageDelivery.js';
+export * as INPBreakdown from './INPBreakdown.js';
+export * as LCPBreakdown from './LCPBreakdown.js';
+export * as LCPDiscovery from './LCPDiscovery.js';
+export * as LegacyJavaScript from './LegacyJavaScript.js';
+export * as ModernHTTP from './ModernHTTP.js';
+export * as NetworkDependencyTree from './NetworkDependencyTree.js';
+export * as RenderBlocking from './RenderBlocking.js';
+export * as SlowCSSSelector from './SlowCSSSelector.js';
+export * as ThirdParties from './ThirdParties.js';
+export * as Viewport from './Viewport.js';