chrome-devtools-frontend 1.0.1376716 → 1.0.1380117

package/front_end/models/trace/insights/LCPDiscovery.test.ts

@@ -0,0 +1,58 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import {describeWithEnvironment} from '../../../testing/EnvironmentHelpers.js';
+import {getFirstOrError, getInsightOrError} from '../../../testing/InsightHelpers.js';
+import {TraceLoader} from '../../../testing/TraceLoader.js';
+
+export async function processTrace(testContext: Mocha.Suite|Mocha.Context|null, traceFile: string) {
+  const {parsedTrace, insights} = await TraceLoader.traceEngine(testContext, traceFile);
+  if (!insights) {
+    throw new Error('No insights');
+  }
+
+  return {data: parsedTrace, insights};
+}
+
+describeWithEnvironment('LCPDiscovery', function() {
+  it('calculates image lcp attributes', async () => {
+    const {data, insights} = await processTrace(this, 'lcp-images.json.gz');
+    const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
+    const insight = getInsightOrError('LCPDiscovery', insights, firstNav);
+    const {shouldIncreasePriorityHint, shouldPreloadImage, shouldRemoveLazyLoading} = insight;
+
+    assert.strictEqual(shouldRemoveLazyLoading, false);
+    assert.strictEqual(shouldPreloadImage, false);
+    assert.strictEqual(shouldIncreasePriorityHint, true);
+  });
+
+  it('calculates the LCP optimal time as the document request download start time', async () => {
+    const {data, insights} = await processTrace(this, 'web-dev-with-commit.json.gz');
+    const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
+    const insight = getInsightOrError('LCPDiscovery', insights, firstNav);
+    assert.strictEqual(
+        insight.earliestDiscoveryTimeTs,
+        // this is the TTFB for the document request
+        122411004828,
+    );
+  });
+
+  describe('warnings', function() {
+    it('warns when there is no lcp', async () => {
+      const {data, insights} = await processTrace(this, 'user-timings.json.gz');
+      const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
+      const insight = getInsightOrError('LCPDiscovery', insights, firstNav);
+
+      assert.strictEqual(insight.warnings?.[0], 'NO_LCP');
+    });
+
+    it('no main document url', async () => {
+      const {data, insights} = await processTrace(this, 'about-blank-first.json.gz');
+      const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
+      const insight = getInsightOrError('LCPDiscovery', insights, firstNav);
+
+      assert.strictEqual(insight.warnings?.[0], 'NO_DOCUMENT_REQUEST');
+    });
+  });
+});

package/front_end/models/trace/insights/LCPDiscovery.ts

@@ -0,0 +1,101 @@
+// Copyright 2024 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as 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 {type InsightModel, type InsightSetContext, InsightWarning, type RequiredData} from './types.js';
+
+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 by making the LCP image [discoverable](https://web.dev/articles/optimize-lcp#1_eliminate_resource_load_delay) from the HTML immediately, and [avoiding lazy-loading](https://web.dev/articles/lcp-lazy-loading)',
+};
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/LCPDiscovery.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+export function deps(): ['NetworkRequests', 'PageLoadMetrics', 'LargestImagePaint', 'Meta'] {
+  return ['NetworkRequests', 'PageLoadMetrics', 'LargestImagePaint', 'Meta'];
+}
+
+export type LCPDiscoveryInsightModel = InsightModel<{
+  lcpEvent?: Types.Events.LargestContentfulPaintCandidate,
+  shouldRemoveLazyLoading?: boolean,
+  shouldIncreasePriorityHint?: boolean,
+  shouldPreloadImage?: boolean,
+  /** The network request for the LCP image, if there was one. */
+  lcpRequest?: Types.Events.SyntheticNetworkRequest,
+  earliestDiscoveryTimeTs?: Types.Timing.MicroSeconds,
+}>;
+
+function finalize(partialModel: Omit<LCPDiscoveryInsightModel, 'title'|'description'>): LCPDiscoveryInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
+export function generateInsight(
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): LCPDiscoveryInsightModel {
+  if (!context.navigation) {
+    return finalize({});
+  }
+
+  const networkRequests = parsedTrace.NetworkRequests;
+
+  const frameMetrics = parsedTrace.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(Handlers.ModelHandlers.PageLoadMetrics.MetricName.LCP);
+  const lcpEvent = metricScore?.event;
+  if (!lcpEvent || !Types.Events.isLargestContentfulPaintCandidate(lcpEvent)) {
+    return finalize({warnings: [InsightWarning.NO_LCP]});
+  }
+
+  const docRequest = networkRequests.byTime.find(req => req.args.data.requestId === context.navigationId);
+  if (!docRequest) {
+    return finalize({lcpEvent, warnings: [InsightWarning.NO_DOCUMENT_REQUEST]});
+  }
+
+  const lcpRequest = parsedTrace.LargestImagePaint.lcpRequestByNavigation.get(context.navigation);
+  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.
+  const earliestDiscoveryTime = docRequest && docRequest.args.data.timing ?
+      Helpers.Timing.secondsToMicroseconds(docRequest.args.data.timing.requestTime) +
+          Helpers.Timing.millisecondsToMicroseconds(docRequest.args.data.timing.receiveHeadersStart) :
+      undefined;
+
+  return finalize({
+    lcpEvent,
+    shouldRemoveLazyLoading: imageLoadingAttr === 'lazy',
+    shouldIncreasePriorityHint: imageFetchPriorityHint !== 'high',
+    shouldPreloadImage: !imgPreloadedOrFoundInHTML,
+    lcpRequest,
+    earliestDiscoveryTimeTs: earliestDiscoveryTime ? Types.Timing.MicroSeconds(earliestDiscoveryTime) : undefined,
+  });
+}

package/front_end/models/trace/insights/{LargestContentfulPaint.test.ts → LCPPhases.test.ts}

@@ -16,11 +16,11 @@ export async function processTrace(testContext: Mocha.Suite|Mocha.Context|null,
   return {data: parsedTrace, insights};
 }
 
-describeWithEnvironment('LargestContentfulPaint', function() {
+describeWithEnvironment('LCPPhases', function() {
   it('calculates text lcp phases', async () => {
     const {data, insights} = await processTrace(this, 'lcp-web-font.json.gz');
     const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-    const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
+    const insight = getInsightOrError('LCPPhases', insights, firstNav);
 
     assert.strictEqual(insight.lcpMs, 106.482);
 
@@ -32,7 +32,7 @@ describeWithEnvironment('LargestContentfulPaint', function() {
   it('calculates image lcp phases', async () => {
     const {data, insights} = await processTrace(this, 'lcp-images.json.gz');
     const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-    const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
+    const insight = getInsightOrError('LCPPhases', insights, firstNav);
 
     assert.strictEqual(insight.lcpMs, 109.623);
 
@@ -49,33 +49,11 @@ describeWithEnvironment('LargestContentfulPaint', function() {
     assert.deepEqual(phases, {ttfb: '6.94', loadTime: '12.09', loadDelay: '33.74', renderDelay: '56.85'});
   });
 
-  it('calculates image lcp attributes', async () => {
-    const {data, insights} = await processTrace(this, 'lcp-images.json.gz');
-    const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-    const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
-    const {shouldIncreasePriorityHint, shouldPreloadImage, shouldRemoveLazyLoading} = insight;
-
-    assert.strictEqual(shouldRemoveLazyLoading, false);
-    assert.strictEqual(shouldPreloadImage, false);
-    assert.strictEqual(shouldIncreasePriorityHint, true);
-  });
-
-  it('calculates the LCP optimal time as the document request download start time', async () => {
-    const {data, insights} = await processTrace(this, 'web-dev-with-commit.json.gz');
-    const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-    const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
-    assert.strictEqual(
-        insight.earliestDiscoveryTimeTs,
-        // this is the TTFB for the document request
-        122411004828,
-    );
-  });
-
   describe('warnings', function() {
     it('warns when there is no lcp', async () => {
       const {data, insights} = await processTrace(this, 'user-timings.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
+      const insight = getInsightOrError('LCPPhases', insights, firstNav);
 
       assert.strictEqual(insight.lcpMs, undefined);
       assert.strictEqual(insight.phases, undefined);
@@ -85,7 +63,7 @@ describeWithEnvironment('LargestContentfulPaint', function() {
     it('no main document url', async () => {
       const {data, insights} = await processTrace(this, 'about-blank-first.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
+      const insight = getInsightOrError('LCPPhases', insights, firstNav);
 
       assert.strictEqual(insight.lcpMs, 204.909);
       assert.strictEqual(insight.phases, undefined);
@@ -96,7 +74,7 @@ describeWithEnvironment('LargestContentfulPaint', function() {
   it('can handle old traces with missing data and return null for breakdowns of the phases', async () => {
     const {data, insights} = await processTrace(this, 'multiple-navigations.json.gz');
     const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-    const insight = getInsightOrError('LargestContentfulPaint', insights, firstNav);
+    const insight = getInsightOrError('LCPPhases', insights, firstNav);
     // This insight has invalid phase data, so we expect the value to be undefined.
     assert.isUndefined(insight.phases);
   });

package/front_end/models/trace/insights/{LargestContentfulPaint.ts → LCPPhases.ts}

@@ -2,12 +2,27 @@
 // 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 {findLCPRequest} from './Common.js';
-import {type InsightResult, type InsightSetContext, InsightWarning, type RequiredData} from './types.js';
+import {type InsightModel, type InsightSetContext, InsightWarning, type RequiredData} from './types.js';
+
+const UIStrings = {
+  /**
+   *@description Title of an insight that provides details about the LCP metric, broken down by phases / parts.
+   */
+  title: 'LCP by phase',
+  /**
+   * @description Description of a DevTools insight that presents a breakdown for the LCP metric by phases.
+   * This is displayed after a user expands the section to see more. No character length limits.
+   */
+  description:
+      'Each [phase has specific improvement strategies](https://web.dev/articles/optimize-lcp#lcp-breakdown). Ideally, most of the LCP time should be spent on loading the resources, not within delays.',
+};
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/LCPPhases.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 
 export function deps(): ['NetworkRequests', 'PageLoadMetrics', 'LargestImagePaint', 'Meta'] {
   return ['NetworkRequests', 'PageLoadMetrics', 'LargestImagePaint', 'Meta'];
@@ -35,17 +50,13 @@ interface LCPPhases {
   renderDelay: Types.Timing.MilliSeconds;
 }
 
-export type LCPInsightResult = InsightResult<{
+export type LCPPhasesInsightModel = InsightModel<{
   lcpMs?: Types.Timing.MilliSeconds,
   lcpTs?: Types.Timing.MilliSeconds,
   lcpEvent?: Types.Events.LargestContentfulPaintCandidate,
-  phases?: LCPPhases,
-  shouldRemoveLazyLoading?: boolean,
-  shouldIncreasePriorityHint?: boolean,
-  shouldPreloadImage?: boolean,
   /** The network request for the LCP image, if there was one. */
   lcpRequest?: Types.Events.SyntheticNetworkRequest,
-  earliestDiscoveryTimeTs?: Types.Timing.MicroSeconds,
+  phases?: LCPPhases,
 }>;
 
 function anyValuesNaN(...values: number[]): boolean {
@@ -59,7 +70,7 @@ function anyValuesNaN(...values: number[]): boolean {
  */
 function breakdownPhases(
     nav: Types.Events.NavigationStart, docRequest: Types.Events.SyntheticNetworkRequest,
-    lcpMs: Types.Timing.MilliSeconds, lcpRequest: Types.Events.SyntheticNetworkRequest|null): LCPPhases|null {
+    lcpMs: Types.Timing.MilliSeconds, lcpRequest: Types.Events.SyntheticNetworkRequest|undefined): LCPPhases|null {
   const docReqTiming = docRequest.args.data.timing;
   if (!docReqTiming) {
     throw new Error('no timing for document request');
@@ -99,9 +110,14 @@ function breakdownPhases(
   };
 }
 
-export function generateInsight(parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): LCPInsightResult {
+function finalize(partialModel: Omit<LCPPhasesInsightModel, 'title'|'description'>): LCPPhasesInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
+export function generateInsight(
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): LCPPhasesInsightModel {
   if (!context.navigation) {
-    return {};
+    return finalize({});
   }
 
   const networkRequests = parsedTrace.NetworkRequests;
@@ -118,52 +134,35 @@ export function generateInsight(parsedTrace: RequiredData<typeof deps>, context:
   const metricScore = navMetrics.get(Handlers.ModelHandlers.PageLoadMetrics.MetricName.LCP);
   const lcpEvent = metricScore?.event;
   if (!lcpEvent || !Types.Events.isLargestContentfulPaintCandidate(lcpEvent)) {
-    return {warnings: [InsightWarning.NO_LCP]};
+    return finalize({warnings: [InsightWarning.NO_LCP]});
   }
 
   // This helps calculate the phases.
   const lcpMs = Helpers.Timing.microSecondsToMilliseconds(metricScore.timing);
   // This helps position things on the timeline's UI accurately for a trace.
   const lcpTs = metricScore.event?.ts ? Helpers.Timing.microSecondsToMilliseconds(metricScore.event?.ts) : undefined;
-  const lcpRequest = findLCPRequest(parsedTrace, context, lcpEvent);
+  const lcpRequest = parsedTrace.LargestImagePaint.lcpRequestByNavigation.get(context.navigation);
+
   const docRequest = networkRequests.byTime.find(req => req.args.data.requestId === context.navigationId);
   if (!docRequest) {
-    return {lcpMs, lcpTs, lcpEvent, warnings: [InsightWarning.NO_DOCUMENT_REQUEST]};
+    return finalize({lcpMs, lcpTs, lcpEvent, lcpRequest, warnings: [InsightWarning.NO_DOCUMENT_REQUEST]});
   }
 
   if (!lcpRequest) {
-    return {
+    return finalize({
       lcpMs,
       lcpTs,
       lcpEvent,
+      lcpRequest,
       phases: breakdownPhases(context.navigation, docRequest, lcpMs, lcpRequest) ?? undefined,
-    };
+    });
   }
 
-  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.
-  const earliestDiscoveryTime = docRequest && docRequest.args.data.timing ?
-      Helpers.Timing.secondsToMicroseconds(docRequest.args.data.timing.requestTime) +
-          Helpers.Timing.millisecondsToMicroseconds(docRequest.args.data.timing.receiveHeadersStart) :
-      undefined;
-
-  return {
+  return finalize({
     lcpMs,
     lcpTs,
     lcpEvent,
-    phases: breakdownPhases(context.navigation, docRequest, lcpMs, lcpRequest) ?? undefined,
-    shouldRemoveLazyLoading: imageLoadingAttr === 'lazy',
-    shouldIncreasePriorityHint: imageFetchPriorityHint !== 'high',
-    shouldPreloadImage: !imgPreloadedOrFoundInHTML,
     lcpRequest,
-    earliestDiscoveryTimeTs: earliestDiscoveryTime ? Types.Timing.MicroSeconds(earliestDiscoveryTime) : undefined,
-  };
+    phases: breakdownPhases(context.navigation, docRequest, lcpMs, lcpRequest) ?? undefined,
+  });
 }

package/front_end/models/trace/insights/{InsightRunners.ts → Models.ts}

@@ -2,12 +2,13 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-export * as CumulativeLayoutShift from './CumulativeLayoutShift.js';
+export * as CLSCulprits from './CLSCulprits.js';
 export * as DocumentLatency from './DocumentLatency.js';
 export * as FontDisplay from './FontDisplay.js';
 export * as InteractionToNextPaint from './InteractionToNextPaint.js';
-export * as LargestContentfulPaint from './LargestContentfulPaint.js';
+export * as LCPDiscovery from './LCPDiscovery.js';
+export * as LCPPhases from './LCPPhases.js';
 export * as RenderBlocking from './RenderBlocking.js';
 export * as SlowCSSSelector from './SlowCSSSelector.js';
-export * as ThirdPartyWeb from './ThirdPartyWeb.js';
+export * as ThirdParties from './ThirdParties.js';
 export * as Viewport from './Viewport.js';

package/front_end/models/trace/insights/RenderBlocking.test.ts

@@ -16,7 +16,7 @@ export async function processTrace(testContext: Mocha.Suite|Mocha.Context|null,
   return {data: parsedTrace, insights};
 }
 
-describeWithEnvironment('RenderBlockingRequests', function() {
+describeWithEnvironment('RenderBlocking', function() {
   it('finds render blocking requests', async () => {
     const {data, insights} = await processTrace(this, 'load-simple.json.gz');
     assert.deepStrictEqual(

package/front_end/models/trace/insights/RenderBlocking.ts

@@ -2,15 +2,15 @@
 // 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 Protocol from '../../../generated/protocol.js';
 import * as Handlers from '../handlers/handlers.js';
 import * as Helpers from '../helpers/helpers.js';
 import type * as Lantern from '../lantern/lantern.js';
-import * as Types from '../types/types.js';
+import type * as Types from '../types/types.js';
 
-import {findLCPRequest} from './Common.js';
 import {
-  type InsightResult,
+  type InsightModel,
   type InsightSetContext,
   type InsightSetContextWithNavigation,
   InsightWarning,
@@ -18,7 +18,23 @@ import {
   type RequiredData,
 } from './types.js';
 
-export type RenderBlockingInsightResult = InsightResult<{
+const UIStrings = {
+  /**
+   * @description Title of an insight that provides the user with the list of network requests that blocked and therefore slowed down the page rendering and becoming visible to the user.
+   */
+  title: 'Render blocking requests',
+  /**
+   * @description Text to describe that there are requests blocking rendering, which may affect LCP.
+   */
+  description: 'Requests are blocking the page\'s initial render, which may delay LCP. ' +
+      '[Deferring or inlining](https://web.dev/learn/performance/understanding-the-critical-path#render-blocking_resources/) ' +
+      'can move these network requests out of the critical path.',
+};
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/RenderBlocking.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+export type RenderBlockingInsightModel = InsightModel<{
   renderBlockingRequests: Types.Events.SyntheticNetworkRequest[],
   requestIdToWastedMs?: Map<string, number>,
 }>;
@@ -85,28 +101,13 @@ function estimateSavingsWithGraphs(
 }
 
 function hasImageLCP(parsedTrace: RequiredData<typeof deps>, context: InsightSetContextWithNavigation): boolean {
-  const frameMetrics = parsedTrace.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(Handlers.ModelHandlers.PageLoadMetrics.MetricName.LCP);
-  const lcpEvent = metricScore?.event;
-  if (!lcpEvent || !Types.Events.isLargestContentfulPaintCandidate(lcpEvent)) {
-    return false;
-  }
-
-  return findLCPRequest(parsedTrace, context, lcpEvent) !== null;
+  return parsedTrace.LargestImagePaint.lcpRequestByNavigation.get(context.navigation) !== undefined;
 }
 
 function computeSavings(
     parsedTrace: RequiredData<typeof deps>, context: InsightSetContextWithNavigation,
     renderBlockingRequests: Types.Events.SyntheticNetworkRequest[]):
-    Pick<RenderBlockingInsightResult, 'metricSavings'|'requestIdToWastedMs'>|undefined {
+    Pick<RenderBlockingInsightModel, 'metricSavings'|'requestIdToWastedMs'>|undefined {
   if (!context.lantern) {
     return;
   }
@@ -149,12 +150,16 @@ function computeSavings(
   return {metricSavings, requestIdToWastedMs};
 }
 
+function finalize(partialModel: Omit<RenderBlockingInsightModel, 'title'|'description'>): RenderBlockingInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
 export function generateInsight(
-    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): RenderBlockingInsightResult {
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): RenderBlockingInsightModel {
   if (!context.navigation) {
-    return {
+    return finalize({
       renderBlockingRequests: [],
-    };
+    });
   }
 
   const firstPaintTs = parsedTrace.PageLoadMetrics.metricScoresByFrameId.get(context.frameId)
@@ -162,10 +167,10 @@ export function generateInsight(
                            ?.get(Handlers.ModelHandlers.PageLoadMetrics.MetricName.FP)
                            ?.event?.ts;
   if (!firstPaintTs) {
-    return {
+    return finalize({
       renderBlockingRequests: [],
       warnings: [InsightWarning.NO_FP],
-    };
+    });
   }
 
   let renderBlockingRequests: Types.Events.SyntheticNetworkRequest[] = [];
@@ -211,9 +216,9 @@ export function generateInsight(
     return b.dur - a.dur;
   });
 
-  return {
+  return finalize({
     relatedEvents: renderBlockingRequests,
     renderBlockingRequests,
     ...savings,
-  };
+  });
 }

package/front_end/models/trace/insights/SlowCSSSelector.ts

@@ -2,17 +2,34 @@
 // 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 Helpers from '../helpers/helpers.js';
 import {type SelectorTiming, SelectorTimingsKey} from '../types/TraceEvents.js';
 import * as Types from '../types/types.js';
 
-import type {InsightResult, InsightSetContext, RequiredData} from './types.js';
+import type {InsightModel, InsightSetContext, RequiredData} from './types.js';
+
+const UIStrings = {
+  /**
+   *@description Title of an insight that provides details about slow CSS selectors.
+   */
+  title: 'CSS Selector costs',
+
+  /**
+   * @description Text to describe how to improve the performance of CSS selectors.
+   */
+  description:
+      'If Recalculate Style costs remain high, selector optimization can reduce them. [Optimize the selectors](https://developer.chrome.com/docs/devtools/performance/selector-stats) with both high elapsed time and high slow-path %. Simpler selectors, fewer selectors, a smaller DOM, and a shallower DOM will all reduce matching costs.',
+};
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/SlowCSSSelector.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 
 export function deps(): ['SelectorStats'] {
   return ['SelectorStats'];
 }
 
-export type SlowCSSSelectorInsightResult = InsightResult<{
+export type SlowCSSSelectorInsightModel = InsightModel<{
   totalElapsedMs: Types.Timing.MilliSeconds,
   totalMatchAttempts: number,
   totalMatchCount: number,
@@ -51,8 +68,12 @@ function aggregateSelectorStats(
   return [...selectorMap.values()];
 }
 
+function finalize(partialModel: Omit<SlowCSSSelectorInsightModel, 'title'|'description'>): SlowCSSSelectorInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
 export function generateInsight(
-    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): SlowCSSSelectorInsightResult {
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): SlowCSSSelectorInsightModel {
   const selectorStatsData = parsedTrace.SelectorStats;
 
   if (!selectorStatsData) {
@@ -81,7 +102,7 @@ export function generateInsight(
     return b[SelectorTimingsKey.MatchAttempts] - a[SelectorTimingsKey.MatchAttempts];
   });
 
-  return {
+  return finalize({
     // TODO: should we identify UpdateLayout events as linked to this insight?
     relatedEvents: [],
     totalElapsedMs: Types.Timing.MilliSeconds(totalElapsedUs / 1000.0),
@@ -89,5 +110,5 @@ export function generateInsight(
     totalMatchCount,
     topElapsedMs: sortByElapsedMs.slice(0, 3),
     topMatchAttempts: sortByMatchAttempts.slice(0, 3),
-  };
+  });
 }

package/front_end/models/trace/insights/{ThirdPartyWeb.test.ts → ThirdParties.test.ts}

@@ -15,12 +15,12 @@ export async function processTrace(testContext: Mocha.Suite|Mocha.Context|null,
   return {data: parsedTrace, insights};
 }
 
-describeWithEnvironment('ThirdPartyWeb', function() {
+describeWithEnvironment('ThirdParties', function() {
   it('categorizes third party web requests (simple)', async () => {
     const {data, insights} = await processTrace(this, 'load-simple.json.gz');
     assert.strictEqual(insights.size, 2);
     const insight =
-        getInsightOrError('ThirdPartyWeb', insights, getFirstOrError(data.Meta.navigationsByNavigationId.values()));
+        getInsightOrError('ThirdParties', insights, getFirstOrError(data.Meta.navigationsByNavigationId.values()));
 
     const entityByRequestResult = [...insight.entityByRequest.entries()].map(([request, entity]) => {
       return [request.args.data.url, entity.name];
@@ -72,7 +72,7 @@ describeWithEnvironment('ThirdPartyWeb', function() {
     const {data, insights} = await processTrace(this, 'lantern/paul/trace.json.gz');
     assert.strictEqual(insights.size, 1);
     const insight =
-        getInsightOrError('ThirdPartyWeb', insights, getFirstOrError(data.Meta.navigationsByNavigationId.values()));
+        getInsightOrError('ThirdParties', insights, getFirstOrError(data.Meta.navigationsByNavigationId.values()));
 
     const entityNames = [...insight.entityByRequest.values()].map(entity => entity.name);
     assert.deepEqual([...new Set(entityNames)], [