core(cumulative-layout-shift): introduce CDT's trace processor for CLS

build/build-cdt-lib.js

@@ -25,10 +25,12 @@ import {LH_ROOT} from '../root.js';
 
 const outDir = `${LH_ROOT}/core/lib/cdt/generated`;
 
+const frontEndPath = 'node_modules/chrome-devtools-frontend/front_end';
+
 /** @type {Modification[]} */
 const modifications = [
   {
-    input: 'node_modules/chrome-devtools-frontend/front_end/core/sdk/SourceMap.ts',
+    input: `${frontEndPath}/core/sdk/SourceMap.ts`,
     output: `${outDir}/SourceMap.js`,
     template: [
       'const Common = require(\'../Common.js\');',
@@ -62,7 +64,7 @@ const modifications = [
     ],
   },
   {
-    input: 'node_modules/chrome-devtools-frontend/front_end/core/common/ParsedURL.ts',
+    input: `${frontEndPath}/core/common/ParsedURL.ts`,
     output: `${outDir}/ParsedURL.js`,
     template: '%sourceFilePrinted%',
     rawCodeToReplace: {},
@@ -113,6 +115,122 @@ const modifications = [
       'Platform',
     ],
   },
+  {
+    input: `${frontEndPath}/models/trace/types/types.ts`,
+    output: `${outDir}/models/trace/types/types.js`,
+    template: '%sourceFilePrinted%',
+    rawCodeToReplace: {},
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [],
+  },
+  {
+    input: `${frontEndPath}/models/trace/types/TraceEvents.ts`,
+    output: `${outDir}/models/trace/types/TraceEvents.js`,
+    template: '%sourceFilePrinted%',
+    rawCodeToReplace: {},
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [],
+  },
+  {
+    input: `${frontEndPath}/models/trace/types/Timing.ts`,
+    output: `${outDir}/models/trace/types/Timing.js`,
+    template: '%sourceFilePrinted%',
+    rawCodeToReplace: {},
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [],
+  },
+  {
+    input: `${frontEndPath}/models/trace/helpers/helpers.ts`,
+    output: `${outDir}/models/trace/helpers/helpers.js`,
+    template: '%sourceFilePrinted%',
+    rawCodeToReplace: {},
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [],
+  },
+  {
+    input: `${frontEndPath}/models/trace/helpers/Timing.ts`,
+    output: `${outDir}/models/trace/helpers/Timing.js`,
+    template: [
+      'const Platform = require(\'../../../../Platform.js\');',
+      '%sourceFilePrinted%',
+    ].join('\n'),
+    rawCodeToReplace: {
+      'navigator.language': `'en'`,
+    },
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [
+      'Platform',
+    ],
+  },
+  {
+    input: `${frontEndPath}/models/trace/helpers/Trace.ts`,
+    output: `${outDir}/models/trace/helpers/Trace.js`,
+    template: [
+      'const Platform = require(\'../../../../Platform.js\');',
+      'const Common = require(\'../../../../Common.js\');',
+      '%sourceFilePrinted%',
+    ].join('\n'),
+    rawCodeToReplace: {},
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [
+      'Platform',
+      'Common',
+    ],
+  },
+  {
+    input: `${frontEndPath}/models/trace/handlers/types.ts`,
+    output: `${outDir}/models/trace/handlers/types.js`,
+    template: '%sourceFilePrinted%',
+    rawCodeToReplace: {},
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [],
+  },
+  {
+    input: `${frontEndPath}/models/trace/handlers/MetaHandler.ts`,
+    output: `${outDir}/models/trace/handlers/MetaHandler.js`,
+    template: [
+      'const Platform = require(\'../../../../Platform.js\');',
+      '%sourceFilePrinted%',
+    ].join('\n'),
+    rawCodeToReplace: {
+      'new DOMRect(viewportX, viewportY, viewportWidth, viewportHeight)': 'null',
+    },
+    classesToRemove: [],
+    methodsToRemove: [],
+    variablesToRemove: [
+      'Platform',
+    ],
+  },
+  {
+    input: `${frontEndPath}/models/trace/handlers/LayoutShiftsHandler.ts`,
+    output: `${outDir}/models/trace/handlers/LayoutShiftsHandler.js`,
+    template: [
+      'const Platform = require(\'../../../../Platform.js\');',
+      '%sourceFilePrinted%',
+    ].join('\n'),
+    rawCodeToReplace: {
+      'findNextScreenshotSource(event.ts)': 'null',
+      [`['Screenshots', 'Meta']`]: `['Meta']`,
+      '!event.args.data?.had_recent_input': 'true',
+    },
+    classesToRemove: [],
+    methodsToRemove: [
+      'findNextScreenshotSource',
+      'stateForLayoutShiftScore',
+    ],
+    variablesToRemove: [
+      'Platform',
+      'PageLoadMetricsHandler_js_1',
+      'ScreenshotsHandler_js_1',
+    ],
+  },
 ];
 
 /**
@@ -220,3 +338,9 @@ function writeGeneratedFile(outputPath, contents) {
 }
 
 modifications.forEach(doModification);
+writeGeneratedFile(`${outDir}/models/trace/handlers/handlers.js`, `
+  module.exports.ModelHandlers = {
+    Meta: require('./MetaHandler.js'),
+    LayoutShiftsHandler: require('./LayoutShiftsHandler.js'),
+  };
+`);

core/computed/metrics/cumulative-layout-shift.js

@@ -4,10 +4,13 @@
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
 
+import log from 'lighthouse-logger';
+
+import SDK from '../../lib/cdt/SDK.js';
 import {makeComputedArtifact} from '../computed-artifact.js';
 import {ProcessedTrace} from '../processed-trace.js';
 
-/** @typedef {{ts: number, isMainFrame: boolean, weightedScore: number, impactedNodes?: LH.Artifacts.TraceImpactedNode[]}} LayoutShiftEvent */
+/** @typedef {{ts: number, isMainFrame: boolean, weightedScore: number, impactedNodes?: LH.Artifacts.TraceImpactedNode[], event: LH.TraceEvent}} LayoutShiftEvent */
 
 const RECENT_INPUT_WINDOW = 500;
 
@@ -66,6 +69,7 @@
         isMainFrame: event.args.data.is_main_frame,
         weightedScore: event.args.data.weighted_score_delta,
         impactedNodes: event.args.data.impacted_nodes,
+        event,
       });
     }
 
@@ -108,13 +112,38 @@
    */
   static async compute_(trace, context) {
     const processedTrace = await ProcessedTrace.request(trace, context);
-
     const allFrameShiftEvents =
         CumulativeLayoutShift.getLayoutShiftEvents(processedTrace);
     const mainFrameShiftEvents = allFrameShiftEvents.filter(e => e.isMainFrame);
 
+    let cumulativeLayoutShift;
+    try {
+      // Experimental usage of CDT's trace processor.
+      const processor = new SDK.TraceProcessor.TraceProcessor({
+        LayoutShifts: SDK.TraceHandlers.LayoutShiftsHandler,
+      });
+      // We really want the logic that getLayoutShiftEvents provides for filtering out
+      // some events based on recent input.
+      // Would it make sense to upstream this to CDT?
+      const filteredTrace = processedTrace.frameTreeEvents.filter(event => {
+        if (event.name !== 'LayoutShift') {
+          return true;
+        }
+
+        return allFrameShiftEvents.some(lse => lse.event === event);
+      });
+      await processor.parse(filteredTrace);
+      const data = /** @type {import('../../lib/cdt/SDK.js').TraceProcessorResult} */ (
+        processor.data);
+      cumulativeLayoutShift = data.LayoutShifts.sessionMaxScore;
+    } catch (e) {
+      // Something failed, so fallback to our own implementation.
+      log.error('Error running SDK.TraceProcessor', e);
+      cumulativeLayoutShift = CumulativeLayoutShift.calculate(allFrameShiftEvents);
+    }
+
     return {
-      cumulativeLayoutShift: CumulativeLayoutShift.calculate(allFrameShiftEvents),
+      cumulativeLayoutShift,
       cumulativeLayoutShiftMainFrame: CumulativeLayoutShift.calculate(mainFrameShiftEvents),
     };
   }

core/lib/cdt/Platform.js

@@ -46,10 +46,124 @@
   return r;
 }
 
+const NearestSearchStart = {
+  BEGINNING: 'BEGINNING',
+  END: 'END',
+};
+
+/**
+ * Obtains the first or last item in the array that satisfies the predicate function.
+ * So, for example, if the array were arr = [2, 4, 6, 8, 10], and you are looking for
+ * the last item arr[i] such that arr[i] < 5  you would be returned 1, because
+ * array[1] is 4, the last item in the array that satisfies the
+ * predicate function.
+ *
+ * If instead you were looking for the first item in the same array that satisfies
+ * arr[i] > 5 you would be returned 2 because array[2] = 6.
+ *
+ * Please note: this presupposes that the array is already ordered.
+ *
+ * @template {T}
+ * @param {T[]} arr
+ * @param {(arrayItem: T) => boolean}
+ * @param {string} searchStart
+ * @return {number|null}
+ */
+function nearestIndex(arr, predicate, searchStart) {
+  const searchFromEnd = searchStart === NearestSearchStart.END;
+  if (arr.length === 0) {
+    return null;
+  }
+
+  let left = 0;
+  let right = arr.length - 1;
+  let pivot = 0;
+  let matchesPredicate = false;
+  let moveToTheRight = false;
+  let middle = 0;
+  do {
+    middle = left + (right - left) / 2;
+    pivot = searchFromEnd ? Math.ceil(middle) : Math.floor(middle);
+    matchesPredicate = predicate(arr[pivot]);
+    moveToTheRight = matchesPredicate === searchFromEnd;
+    if (moveToTheRight) {
+      left = Math.min(right, pivot + (left === pivot ? 1 : 0));
+    } else {
+      right = Math.max(left, pivot + (right === pivot ? -1 : 0));
+    }
+  } while (right !== left);
+
+  // Special-case: the indexed item doesn't pass the predicate. This
+  // occurs when none of the items in the array are a match for the
+  // predicate.
+  if (!predicate(arr[left])) {
+    return null;
+  }
+  return left;
+}
+
+/**
+ * Obtains the first item in the array that satisfies the predicate function.
+ * So, for example, if the array was arr = [2, 4, 6, 8, 10], and you are looking for
+ * the first item arr[i] such that arr[i] > 5 you would be returned 2, because
+ * array[2] is 6, the first item in the array that satisfies the
+ * predicate function.
+ *
+ * Please note: this presupposes that the array is already ordered.
+ * @template {T}
+ * @param {T[]} arr
+ * @param {(arrayItem: T) => boolean}
+ * @return {number|null}
+ */
+function nearestIndexFromBeginning(arr, predicate) {
+  return nearestIndex(arr, predicate, NearestSearchStart.BEGINNING);
+}
+
+/**
+ * Obtains the last item in the array that satisfies the predicate function.
+ * So, for example, if the array was arr = [2, 4, 6, 8, 10], and you are looking for
+ * the last item arr[i] such that arr[i] < 5 you would be returned 1, because
+ * arr[1] is 4, the last item in the array that satisfies the
+ * predicate function.
+ *
+ * Please note: this presupposes that the array is already ordered.
+ * @template {T}
+ * @param {T[]} arr
+ * @param {(arrayItem: T) => boolean}
+ * @return {number|null}
+ */
+function nearestIndexFromEnd(arr, predicate) {
+  return nearestIndex(arr, predicate, NearestSearchStart.END);
+}
+
+/**
+ * Gets value for key, assigning a default if value is falsy.
+ * @template {K}
+ * @template {V}
+ * @param {Map<K, V>} map
+ * @param {K} key
+ * @param {(key?: K) => V} defaultValueFactory
+ * @return {V}
+ */
+function getWithDefault(map, key, defaultValueFactory) {
+  let value = map.get(key);
+  if (!value) {
+    value = defaultValueFactory(key);
+    map.set(key, value);
+  }
+
+  return value;
+}
+
 module.exports = {
   ArrayUtilities: {
     lowerBound,
     upperBound,
+    nearestIndexFromBeginning,
+    nearestIndexFromEnd,
+  },
+  MapUtilities: {
+    getWithDefault,
   },
   DevToolsPath: {
     EmptyUrlString: '',

core/lib/cdt/SDK.js

@@ -6,8 +6,13 @@
 
 const SDK = {
   SourceMap: require('./generated/SourceMap.js'),
+  TraceProcessor: require('./generated/models/trace/Processor.js'),
+  TraceHandlers: require('./generated/models/trace/handlers/handlers.js').ModelHandlers,
 };
 
+/** @typedef {{sessionMaxScore: number}} LayoutShiftsHandler */
+/** @typedef {{LayoutShifts: LayoutShiftsHandler}} TraceProcessorResult */
+
 // Add `lastColumnNumber` to mappings. This will eventually be added to CDT.
 // @ts-expect-error
 SDK.SourceMap.prototype.computeLastGeneratedColumns = function() {