chrome-devtools-frontend 1.0.1376716 → 1.0.1380117

package/front_end/models/trace/handlers/UserTimingsHandler.ts

@@ -5,8 +5,6 @@
 import * as Helpers from '../helpers/helpers.js';
 import * as Types from '../types/types.js';
 
-import {HandlerState} from './types.js';
-
 /**
  * IMPORTANT!
  * See UserTimings.md in this directory for some handy documentation on
@@ -43,7 +41,6 @@ export interface UserTimingsData {
    */
   timestampEvents: readonly Types.Events.TimeStamp[];
 }
-let handlerState = HandlerState.UNINITIALIZED;
 
 export function reset(): void {
   syntheticEvents.length = 0;
@@ -51,7 +48,6 @@ export function reset(): void {
   performanceMarkEvents.length = 0;
   consoleTimings.length = 0;
   timestampEvents.length = 0;
-  handlerState = HandlerState.INITIALIZED;
 }
 
 const resourceTimingNames = [
@@ -143,10 +139,6 @@ function userTimingComparator(
 }
 
 export function handleEvent(event: Types.Events.Event): void {
-  if (handlerState !== HandlerState.INITIALIZED) {
-    throw new Error('UserTimings handler is not initialized');
-  }
-
   if (ignoredNames.includes(event.name)) {
     return;
   }
@@ -167,21 +159,12 @@ export function handleEvent(event: Types.Events.Event): void {
 }
 
 export async function finalize(): Promise<void> {
-  if (handlerState !== HandlerState.INITIALIZED) {
-    throw new Error('UserTimings handler is not initialized');
-  }
-
   const asyncEvents = [...performanceMeasureEvents, ...consoleTimings];
   syntheticEvents = Helpers.Trace.createMatchedSortedSyntheticEvents(asyncEvents);
   syntheticEvents = syntheticEvents.sort((a, b) => userTimingComparator(a, b, [...syntheticEvents]));
-  handlerState = HandlerState.FINALIZED;
 }
 
 export function data(): UserTimingsData {
-  if (handlerState !== HandlerState.FINALIZED) {
-    throw new Error('UserTimings handler is not finalized');
-  }
-
   return {
     performanceMeasures: syntheticEvents.filter(e => e.cat === 'blink.user_timing') as
         Types.Events.SyntheticUserTimingPair[],

package/front_end/models/trace/handlers/WorkersHandler.test.ts

@@ -9,7 +9,6 @@ describe('WorkersHandler', () => {
   beforeEach(async function() {
     Trace.Handlers.ModelHandlers.Workers.reset();
     const events = await TraceLoader.rawEvents(this, 'two-workers.json.gz');
-    Trace.Handlers.ModelHandlers.Workers.initialize();
     for (const event of events) {
       Trace.Handlers.ModelHandlers.Workers.handleEvent(event);
     }

package/front_end/models/trace/handlers/WorkersHandler.ts

@@ -4,47 +4,29 @@
 
 import * as Types from '../types/types.js';
 
-import {HandlerState} from './types.js';
-
 export interface WorkersData {
   workerSessionIdEvents: readonly Types.Events.TracingSessionIdForWorker[];
   workerIdByThread: Map<Types.Events.ThreadID, Types.Events.WorkerId>;
   workerURLById: Map<Types.Events.WorkerId, string>;
 }
-let handlerState = HandlerState.UNINITIALIZED;
 
 const sessionIdEvents: Types.Events.TracingSessionIdForWorker[] = [];
 const workerIdByThread: Map<Types.Events.ThreadID, Types.Events.WorkerId> = new Map();
 const workerURLById: Map<Types.Events.WorkerId, string> = new Map();
 
-export function initialize(): void {
-  if (handlerState !== HandlerState.UNINITIALIZED) {
-    throw new Error('Workers Handler was not reset');
-  }
-
-  handlerState = HandlerState.INITIALIZED;
-}
-
 export function reset(): void {
   sessionIdEvents.length = 0;
   workerIdByThread.clear();
   workerURLById.clear();
-  handlerState = HandlerState.UNINITIALIZED;
 }
 
 export function handleEvent(event: Types.Events.Event): void {
-  if (handlerState !== HandlerState.INITIALIZED) {
-    throw new Error('Workers Handler is not initialized');
-  }
   if (Types.Events.isTracingSessionIdForWorker(event)) {
     sessionIdEvents.push(event);
   }
 }
 
 export async function finalize(): Promise<void> {
-  if (handlerState !== HandlerState.INITIALIZED) {
-    throw new Error('Handler is not initialized');
-  }
   for (const sessionIdEvent of sessionIdEvents) {
     if (!sessionIdEvent.args.data) {
       continue;
@@ -52,14 +34,9 @@ export async function finalize(): Promise<void> {
     workerIdByThread.set(sessionIdEvent.args.data.workerThreadId, sessionIdEvent.args.data.workerId);
     workerURLById.set(sessionIdEvent.args.data.workerId, sessionIdEvent.args.data.url);
   }
-  handlerState = HandlerState.FINALIZED;
 }
 
 export function data(): WorkersData {
-  if (handlerState !== HandlerState.FINALIZED) {
-    throw new Error('Workers Handler is not finalized');
-  }
-
   return {
     workerSessionIdEvents: sessionIdEvents,
     workerIdByThread,

package/front_end/models/trace/handlers/types.ts

@@ -7,9 +7,8 @@ import type * as ModelHandlers from './ModelHandlers.js';
 
 export interface Handler {
   reset(): void;
-  initialize?(freshRecording?: boolean): void;
   handleEvent(data: {}): void;
-  finalize?(): Promise<void>;
+  finalize(): Promise<void>;
   data(): unknown;
   deps?(): HandlerName[];
   handleUserConfig?(config: Types.Configuration.Configuration): void;
@@ -65,9 +64,3 @@ type DeepWriteable<T> = {
 export type ParsedTraceMutable = DeepWriteable<ParsedTrace>;
 
 export type Handlers = typeof ModelHandlers;
-
-export const enum HandlerState {
-  UNINITIALIZED = 1,
-  INITIALIZED = 2,
-  FINALIZED = 3,
-}

package/front_end/models/trace/insights/{CumulativeLayoutShift.test.ts → CLSCulprits.test.ts}

@@ -8,7 +8,7 @@ import {TraceLoader} from '../../../testing/TraceLoader.js';
 import * as Helpers from '../helpers/helpers.js';
 import * as Types from '../types/types.js';
 
-import {InsightRunners} from './insights.js';
+import {Models} from './insights.js';
 
 export async function processTrace(testContext: Mocha.Suite|Mocha.Context|null, traceFile: string) {
   const {parsedTrace, insights} = await TraceLoader.traceEngine(testContext, traceFile);
@@ -22,12 +22,12 @@ export async function processTrace(testContext: Mocha.Suite|Mocha.Context|null,
 // Root cause invalidation window.
 const INVALIDATION_WINDOW = Helpers.Timing.secondsToMicroseconds(Types.Timing.Seconds(0.5));
 
-describeWithEnvironment('CumulativeLayoutShift', function() {
+describeWithEnvironment('CLSCulprits', function() {
   describe('non composited animations', function() {
     it('gets the correct non composited animations', async function() {
       const {data, insights} = await processTrace(this, 'non-composited-animation.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+      const insight = getInsightOrError('CLSCulprits', insights, firstNav);
       const {animationFailures} = insight;
 
       const simpleAnimation = data.Animations.animations.find(animation => {
@@ -37,18 +37,18 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
         return animation.args.data.beginEvent.args.data.displayName === 'top';
       });
 
-      const expected: InsightRunners.CumulativeLayoutShift.NoncompositedAnimationFailure[] = [
+      const expected: Models.CLSCulprits.NoncompositedAnimationFailure[] = [
         {
           name: 'simple-animation',
-          failureReasons: [InsightRunners.CumulativeLayoutShift.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
+          failureReasons: [Models.CLSCulprits.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
           unsupportedProperties: ['color'],
           animation: simpleAnimation,
         },
         {
           name: 'top',
           failureReasons: [
-            InsightRunners.CumulativeLayoutShift.AnimationFailureReasons.TARGET_HAS_INVALID_COMPOSITING_STATE,
-            InsightRunners.CumulativeLayoutShift.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY,
+            Models.CLSCulprits.AnimationFailureReasons.TARGET_HAS_INVALID_COMPOSITING_STATE,
+            Models.CLSCulprits.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY,
           ],
           unsupportedProperties: ['top'],
           animation: top,
@@ -60,7 +60,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
     it.skip('[crbug.com/370382177]: gets the correct non composited animations for shift', async function() {
       const {data, insights} = await processTrace(this, 'non-composited-animation-shift.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+      const insight = getInsightOrError('CLSCulprits', insights, firstNav);
       const {shifts, animationFailures} = insight;
 
       const simpleAnimation = data.Animations.animations.find(animation => {
@@ -70,30 +70,30 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
         return animation.args.data.beginEvent.args.data.displayName === 'top';
       });
 
-      const shiftAnimations: InsightRunners.CumulativeLayoutShift.NoncompositedAnimationFailure[] = [];
+      const shiftAnimations: Models.CLSCulprits.NoncompositedAnimationFailure[] = [];
       shifts.forEach(entry => {
         shiftAnimations.push(...entry.nonCompositedAnimations);
       });
-      const expectedWithShift: InsightRunners.CumulativeLayoutShift.NoncompositedAnimationFailure[] = [
+      const expectedWithShift: Models.CLSCulprits.NoncompositedAnimationFailure[] = [
         {
           name: 'simple-animation',
-          failureReasons: [InsightRunners.CumulativeLayoutShift.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
+          failureReasons: [Models.CLSCulprits.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
           unsupportedProperties: ['height', 'color', 'top'],
           animation: simpleAnimation,
         },
       ];
       assert.deepStrictEqual(shiftAnimations, expectedWithShift);
 
-      const expectedAll: InsightRunners.CumulativeLayoutShift.NoncompositedAnimationFailure[] = [
+      const expectedAll: Models.CLSCulprits.NoncompositedAnimationFailure[] = [
         {
           name: 'simple-animation',
-          failureReasons: [InsightRunners.CumulativeLayoutShift.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
+          failureReasons: [Models.CLSCulprits.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
           unsupportedProperties: ['height', 'color', 'top'],
           animation: simpleAnimation,
         },
         {
           name: 'top',
-          failureReasons: [InsightRunners.CumulativeLayoutShift.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
+          failureReasons: [Models.CLSCulprits.AnimationFailureReasons.UNSUPPORTED_CSS_PROPERTY],
           unsupportedProperties: ['top'],
           animation: top,
         },
@@ -105,7 +105,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
     it('returns no insights when there are no non-composited animations', async function() {
       const {data, insights} = await processTrace(this, 'lcp-images.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+      const insight = getInsightOrError('CLSCulprits', insights, firstNav);
       const {animationFailures} = insight;
 
       assert.isEmpty(animationFailures);
@@ -115,7 +115,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
     it('returns correct layout shifts', async function() {
       const {data, insights} = await processTrace(this, 'cls-single-frame.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+      const insight = getInsightOrError('CLSCulprits', insights, firstNav);
       const {shifts} = insight;
 
       assert.exists(shifts);
@@ -127,7 +127,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
         // Trace has a single iframe that gets created before the first layout shift and causes a layout shift.
         const {data, insights} = await processTrace(this, 'iframe-shift.json.gz');
         const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-        const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+        const insight = getInsightOrError('CLSCulprits', insights, firstNav);
         const {shifts} = insight;
 
         assert.exists(shifts);
@@ -159,7 +159,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
         // Trace has font load before the second layout shift.
         const {data, insights} = await processTrace(this, 'iframe-shift.json.gz');
         const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-        const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+        const insight = getInsightOrError('CLSCulprits', insights, firstNav);
         const {shifts} = insight;
 
         assert.exists(shifts);
@@ -193,7 +193,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
       it('handles potential unsized images root cause correctly', async function() {
         const {data, insights} = await processTrace(this, 'unsized-images.json.gz');
         const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-        const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+        const insight = getInsightOrError('CLSCulprits', insights, firstNav);
         const {shifts} = insight;
         assert.exists(shifts);
         assert.strictEqual(shifts.size, 2);
@@ -217,7 +217,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
     it('returns clusters correctly', async function() {
       const {data, insights} = await processTrace(this, 'iframe-shift.json.gz');
       const firstNav = getFirstOrError(data.Meta.navigationsByNavigationId.values());
-      const insight = getInsightOrError('CumulativeLayoutShift', insights, firstNav);
+      const insight = getInsightOrError('CLSCulprits', insights, firstNav);
       const {shifts, clusters} = insight;
 
       assert.exists(clusters);
@@ -233,7 +233,7 @@ describeWithEnvironment('CumulativeLayoutShift', function() {
 
     it('returns clusters correctly for non-navigations', async function() {
       const {insights} = await processTrace(this, 'cls-no-nav.json.gz');
-      const insight = getInsightOrError('CumulativeLayoutShift', insights);
+      const insight = getInsightOrError('CLSCulprits', insights);
       const {shifts, clusters} = insight;
 
       assert.exists(clusters);

package/front_end/models/trace/insights/{CumulativeLayoutShift.ts → CLSCulprits.ts}

@@ -2,14 +2,28 @@
 // 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 Platform from '../../../core/platform/platform.js';
 import type * as Protocol from '../../../generated/protocol.js';
 import * as Helpers from '../helpers/helpers.js';
 import * as Types from '../types/types.js';
 
-import type {InsightResult, InsightSetContext, RequiredData} from './types.js';
+import type {InsightModel, InsightSetContext, RequiredData} from './types.js';
 
-export type CLSInsightResult = InsightResult<{
+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"). */
+  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.
+   */
+  description:
+      'Layout shifts occur when elements move absent any user interaction. [Investigate the causes of layout shifts](https://web.dev/articles/optimize-cls), such as elements being added, removed, or their fonts changing as the page loads.',
+};
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/CLSCulprits.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+export type CLSCulpritsInsightModel = InsightModel<{
   animationFailures: readonly NoncompositedAnimationFailure[],
   shifts: Map<Types.Events.SyntheticLayoutShift, LayoutShiftRootCausesData>,
   clusters: Types.Events.SyntheticLayoutShiftCluster[],
@@ -406,7 +420,12 @@ function getFontRootCauses(
   return rootCausesByShift;
 }
 
-export function generateInsight(parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): CLSInsightResult {
+function finalize(partialModel: Omit<CLSCulpritsInsightModel, 'title'|'description'>): CLSCulpritsInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
+export function generateInsight(
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): CLSCulpritsInsightModel {
   const isWithinContext = (event: Types.Events.Event): boolean => Helpers.Timing.eventIsInBounds(event, context.bounds);
 
   const compositeAnimationEvents = parsedTrace.Animations.animations.filter(isWithinContext);
@@ -443,11 +462,11 @@ export function generateInsight(parsedTrace: RequiredData<typeof deps>, context:
     relatedEvents.push(worstCluster);
   }
 
-  return {
+  return finalize({
     relatedEvents,
     animationFailures,
     shifts: rootCausesByShift,
     clusters,
     worstCluster,
-  };
+  });
 }

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

@@ -2,14 +2,10 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-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 {InsightModels, TraceInsightSets} from './types.js';
 
-import type {InsightResults, InsightSetContextWithNavigation, TraceInsightSets} from './types.js';
-
-export function getInsight<InsightName extends keyof InsightResults>(
-    insightName: InsightName, insights: TraceInsightSets|null, key: string|null): InsightResults[InsightName]|null {
+export function getInsight<InsightName extends keyof InsightModels>(
+    insightName: InsightName, insights: TraceInsightSets|null, key: string|null): InsightModels[InsightName]|null {
   if (!insights || !key) {
     return null;
   }
@@ -19,57 +15,11 @@ export function getInsight<InsightName extends keyof InsightResults>(
     return null;
   }
 
-  const insight = insightSets.data[insightName];
+  const insight = insightSets.model[insightName];
   if (insight instanceof Error) {
     return null;
   }
 
   // For some reason typescript won't narrow the type by removing Error, so do it manually.
-  return insight as InsightResults[InsightName];
-}
-
-/**
- * Finds a network request given a navigation context and URL.
- * Considers redirects.
- */
-export function findRequest(
-    parsedTrace: Pick<Handlers.Types.ParsedTrace, 'Meta'|'NetworkRequests'>, context: InsightSetContextWithNavigation,
-    url: string): Types.Events.SyntheticNetworkRequest|null {
-  const request = parsedTrace.NetworkRequests.byTime.find(req => {
-    const urlMatch = req.args.data.url === url || req.args.data.redirects.some(r => r.url === url);
-    if (!urlMatch) {
-      return false;
-    }
-
-    const nav = Helpers.Trace.getNavigationForTraceEvent(req, context.frameId, parsedTrace.Meta.navigationsByFrameId);
-    return nav === context.navigation;
-  });
-  return request ?? null;
-}
-
-export function findLCPRequest(
-    parsedTrace: Pick<Handlers.Types.ParsedTrace, 'Meta'|'NetworkRequests'|'LargestImagePaint'>,
-    context: InsightSetContextWithNavigation,
-    lcpEvent: Types.Events.LargestContentfulPaintCandidate): Types.Events.SyntheticNetworkRequest|null {
-  const lcpNodeId = lcpEvent.args.data?.nodeId;
-  if (!lcpNodeId) {
-    throw new Error('no lcp node id');
-  }
-
-  const imagePaint = parsedTrace.LargestImagePaint.get(lcpNodeId);
-  if (!imagePaint) {
-    return null;
-  }
-
-  const lcpUrl = imagePaint.args.data?.imageUrl;
-  if (!lcpUrl) {
-    throw new Error('no lcp url');
-  }
-  const lcpRequest = findRequest(parsedTrace, context, lcpUrl);
-
-  if (!lcpRequest) {
-    throw new Error('no lcp request found');
-  }
-
-  return lcpRequest;
+  return insight as InsightModels[InsightName];
 }

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

@@ -58,7 +58,7 @@ describeWithEnvironment('DocumentLatency', function() {
 
     const navigation = getFirstOrError(data.Meta.navigationsByNavigationId.values());
     const context = createContextForNavigation(data, navigation, data.Meta.mainFrameId);
-    const insight = Trace.Insights.InsightRunners.DocumentLatency.generateInsight(data, context);
+    const insight = Trace.Insights.Models.DocumentLatency.generateInsight(data, context);
     assert.strictEqual(insight.data?.serverResponseTime, 1043);
     assert(insight.data?.serverResponseTooSlow);
     assert.deepEqual(insight.metricSavings, {FCP: 943, LCP: 943} as Trace.Insights.Types.MetricSavings);
@@ -92,7 +92,7 @@ describeWithEnvironment('DocumentLatency', function() {
 
     const navigation = getFirstOrError(data.Meta.navigationsByNavigationId.values());
     const context = createContextForNavigation(data, navigation, data.Meta.mainFrameId);
-    const insight = Trace.Insights.InsightRunners.DocumentLatency.generateInsight(data, context);
+    const insight = Trace.Insights.Models.DocumentLatency.generateInsight(data, context);
     assert.strictEqual(insight.data?.uncompressedResponseBytes, 39799);
     assert.deepEqual(insight.metricSavings, {FCP: 0, LCP: 0} as Trace.Insights.Types.MetricSavings);
   });

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

@@ -2,10 +2,26 @@
 // 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 * 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 a breakdown for how long it took to download the main document.
+   */
+  title: 'Document request latency',
+  /**
+   *@description Description of an insight that provides a breakdown for how long it took to download the main document.
+   */
+  description:
+      'Your first network request is the most important.  Reduce its latency by avoiding redirects, ensuring a fast server response, and enabling text compression.',
+};
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/DocumentLatency.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 
 // Due to the way that DevTools throttling works we cannot see if server response took less than ~570ms.
 // We set our failure threshold to 600ms to avoid those false positives but we want devs to shoot for 100ms.
@@ -15,7 +31,7 @@ const TARGET_MS = 100;
 // Threshold for compression savings.
 const IGNORE_THRESHOLD_IN_BYTES = 1400;
 
-export type DocumentLatencyInsightResult = InsightResult<{
+export type DocumentLatencyInsightModel = InsightModel<{
   data?: {
     serverResponseTime: Types.Timing.MilliSeconds,
     serverResponseTooSlow: boolean,
@@ -103,10 +119,14 @@ function getCompressionSavings(request: Types.Events.SyntheticNetworkRequest): n
   return estimatedSavings < IGNORE_THRESHOLD_IN_BYTES ? 0 : estimatedSavings;
 }
 
+function finalize(partialModel: Omit<DocumentLatencyInsightModel, 'title'|'description'>): DocumentLatencyInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
 export function generateInsight(
-    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): DocumentLatencyInsightResult {
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): DocumentLatencyInsightModel {
   if (!context.navigation) {
-    return {};
+    return finalize({});
   }
 
   const documentRequest =
@@ -135,7 +155,7 @@ export function generateInsight(
     LCP: overallSavingsMs as Types.Timing.MilliSeconds,
   };
 
-  return {
+  return finalize({
     relatedEvents: [documentRequest],
     data: {
       serverResponseTime,
@@ -145,5 +165,5 @@ export function generateInsight(
       documentRequest,
     },
     metricSavings,
-  };
+  });
 }

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

@@ -2,17 +2,31 @@
 // 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 Platform from '../../../core/platform/platform.js';
 import * as Helpers from '../helpers/helpers.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 = {
+  /** Title of an insight that provides details about the fonts used on the page, and the value of their `font-display` properties. */
+  title: 'Font display',
+  /**
+   * @description Text to tell the user about the font-display CSS feature to help improve a the UX of a page.
+   */
+  description:
+      'Consider setting [`font-display`](https://developer.chrome.com/blog/font-display) to `swap` or `optional` to ensure text is consistently visible. `swap` can be further optimized to mitigate layout shifts with [font metric overrides](https://developer.chrome.com/blog/font-fallbacks).',
+};
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/FontDisplay.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 
 export function deps(): ['Meta', 'NetworkRequests', 'LayoutShifts'] {
   return ['Meta', 'NetworkRequests', 'LayoutShifts'];
 }
 
-export type FontDisplayResult = InsightResult<{
+export type FontDisplayInsightModel = InsightModel<{
   fonts: Array<{
     request: Types.Events.SyntheticNetworkRequest,
     display: string,
@@ -20,7 +34,12 @@ export type FontDisplayResult = InsightResult<{
   }>,
 }>;
 
-export function generateInsight(parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): FontDisplayResult {
+function finalize(partialModel: Omit<FontDisplayInsightModel, 'title'|'description'>): FontDisplayInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
+export function generateInsight(
+    parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): FontDisplayInsightModel {
   const fonts = [];
   for (const event of parsedTrace.LayoutShifts.beginRemoteFontLoadEvents) {
     if (!Helpers.Timing.eventIsInBounds(event, context.bounds)) {
@@ -57,9 +76,9 @@ export function generateInsight(parsedTrace: RequiredData<typeof deps>, context:
 
   const savings = Math.max(...fonts.map(f => f.wastedTime)) as Types.Timing.MilliSeconds;
 
-  return {
+  return finalize({
     relatedEvents: fonts.map(f => f.request),
     fonts,
     metricSavings: {FCP: savings},
-  };
+  });
 }

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

@@ -29,7 +29,7 @@ describeWithEnvironment('InteractionToNextPaint', function() {
         bounds: data.Meta.traceBounds,
         frameId: data.Meta.mainFrameId,
       };
-      const insight = Trace.Insights.InsightRunners.InteractionToNextPaint.generateInsight(data, context);
+      const insight = Trace.Insights.Models.InteractionToNextPaint.generateInsight(data, context);
       assert.strictEqual(insight.longestInteractionEvent?.dur, longest);
       assert.strictEqual(insight.highPercentileInteractionEvent?.dur, highPercentile);
     });

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

@@ -2,28 +2,48 @@
 // 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 {SyntheticInteractionPair} from '../types/TraceEvents.js';
 
-import type {InsightResult, InsightSetContext, RequiredData} from './types.js';
+import type {InsightModel, InsightSetContext, RequiredData} from './types.js';
+
+const UIStrings = {
+  /**
+   * @description Text to tell the user about the longest user interaction.
+   */
+  description:
+      'Start investigating with the longest phase. [Delays can be minimized](https://web.dev/articles/optimize-inp#optimize_interactions). To reduce processing duration, [optimize the main-thread costs](https://web.dev/articles/optimize-long-tasks), often JS.',
+  /**
+   * @description Title for the performance insight "INP by phase", which shows a breakdown of INP by phases / sections.
+   */
+  title: 'INP by phase',
+};
+
+const str_ = i18n.i18n.registerUIStrings('models/trace/insights/InteractionToNextPaint.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
 
 export function deps(): ['UserInteractions'] {
   return ['UserInteractions'];
 }
 
-export type INPInsightResult = InsightResult<{
+export type INPInsightModel = InsightModel<{
   longestInteractionEvent?: SyntheticInteractionPair,
   highPercentileInteractionEvent?: SyntheticInteractionPair,
 }>;
 
-export function generateInsight(parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): INPInsightResult {
+function finalize(partialModel: Omit<INPInsightModel, 'title'|'description'>): INPInsightModel {
+  return {title: i18nString(UIStrings.title), description: i18nString(UIStrings.description), ...partialModel};
+}
+
+export function generateInsight(parsedTrace: RequiredData<typeof deps>, context: InsightSetContext): INPInsightModel {
   const interactionEvents = parsedTrace.UserInteractions.interactionEventsWithNoNesting.filter(event => {
     return Helpers.Timing.eventIsInBounds(event, context.bounds);
   });
 
   if (!interactionEvents.length) {
     // A valid result, when there is no user interaction.
-    return {};
+    return finalize({});
   }
 
   const longestByInteractionId = new Map<number, SyntheticInteractionPair>();
@@ -43,9 +63,9 @@ export function generateInsight(parsedTrace: RequiredData<typeof deps>, context:
   // See https://source.chromium.org/chromium/chromium/src/+/main:components/page_load_metrics/browser/responsiveness_metrics_normalization.cc;l=45-59;drc=cb0f9c8b559d9c7c3cb4ca94fc1118cc015d38ad
   const highPercentileIndex = Math.min(9, Math.floor(normalizedInteractionEvents.length / 50));
 
-  return {
+  return finalize({
     relatedEvents: [normalizedInteractionEvents[0]],
     longestInteractionEvent: normalizedInteractionEvents[0],
     highPercentileInteractionEvent: normalizedInteractionEvents[highPercentileIndex],
-  };
+  });
 }