@atlaskit/editor-plugin-interactivity 1.1.0 → 1.2.1

package/dist/esm/collector/slow-interaction-list.js

@@ -1,6 +1,11 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
 import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
 import _createClass from "@babel/runtime/helpers/createClass";
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+import { BoundedList } from '../collections/bounded-list';
 /** Fixed by the schema, so the event stays a bounded size. */
 var MAX_RECORDS = 5;
 
@@ -10,6 +15,12 @@ var MAX_RECORDS = 5;
  */
 var MIN_LATENCY_MS = 200;
 
+/**
+ * How many frames are kept to attribute records from. An interaction spans one paint, so a few dozen
+ * cover even a second of a janky page.
+ */
+var MAX_FRAMES = 64;
+
 /**
  * The attributes a target may be named by, all of them ours: `data-vc` for visual completion, the
  * test ids for tests. Ids, roles, class names, text and accessibility labels are left out because
@@ -20,13 +31,42 @@ var MAX_TARGET_ELEMENTS = 4;
 var MAX_ATTRIBUTE_VALUE_LENGTH = 32;
 var MAX_TARGET_LENGTH = 120;
 
-/** The id identifies an interaction across the entries measuring it. It is not reported. */
+/** How long a reported script or function name may be. */
+var MAX_NAME_LENGTH = 64;
+var QUERY_OR_HASH = /[#\?]/;
+
+/** The part of a record that only the frames the interaction ran in can fill in. */
 
-/** An interaction as the collector's two observers saw it. */
+/**
+ * Whether two attributions say the same thing. Shallow, because every field of one is a number or a
+ * string; by the field names of both, so that a field going missing counts as a change rather than
+ * as nothing to see.
+ */
+function sameAttribution(one, other) {
+  var fields = Object.keys(one);
+  return fields.length === Object.keys(other).length && fields.every(function (field) {
+    return one[field] === other[field];
+  });
+}
+
+/**
+ * One recorded interaction. The reported phases are not among its fields: they are the gaps between
+ * the boundaries, worked out when the record is reported, which is also where the latency is
+ * rounded into the `durationMs` the event carries.
+ *
+ * The attribution is kept whole rather than spread across the record, so that a record can never
+ * hold half of what one set of frames said and half of what another did.
+ *
+ * `interactionId` identifies the interaction across the entries measuring it, and `boundaries` is
+ * also what its frames are matched to it by. Neither is reported.
+ */
 
 /**
  * The slowest interactions of one session, which is what the event's `slowest` records are.
  *
+ * Interactions arrive from the tracker and frames from the Long Animation Frame observer, and this
+ * is where the two meet: a record says both how long the user waited and where that time went.
+ *
  * A record is built from the entry that measured the interaction, as that entry arrives:
  * `entry.target` is `null` once the element has left the document.
  */
@@ -35,42 +75,88 @@ export var SlowInteractionList = /*#__PURE__*/function () {
     _classCallCheck(this, SlowInteractionList);
     /** Slowest first. */
     _defineProperty(this, "records", []);
+    _defineProperty(this, "frames", new BoundedList(MAX_FRAMES));
   }
   return _createClass(SlowInteractionList, [{
-    key: "track",
-    value: function track(interaction) {
-      var interactionId = interaction.interactionId,
-        latencyMs = interaction.latencyMs;
-      var previousIndex = this.records.findIndex(function (existing) {
-        return existing.interactionId === interactionId;
+    key: "trackInteractionUpdate",
+    value:
+    /**
+     * Takes in what the tracker now says about an interaction, keeping it when it is one of the
+     * slowest of the session.
+     *
+     * @returns whether that changed what a snapshot would carry.
+     */
+    function trackInteractionUpdate(entry, update) {
+      var boundaries = update.boundaries,
+        interactionId = update.interactionId,
+        latencyMs = update.latencyMs;
+      var index = this.records.findIndex(function (record) {
+        return record.interactionId === interactionId;
       });
-      var toBeatMs = MIN_LATENCY_MS;
-      if (previousIndex !== -1) {
-        // An interaction's latency grows as later entries arrive, and it replaces itself rather
-        // than taking a second place.
-        toBeatMs = this.records[previousIndex].durationMs;
-      } else if (this.records.length === MAX_RECORDS) {
-        toBeatMs = this.records[MAX_RECORDS - 1].durationMs;
-      }
-      if (latencyMs <= toBeatMs) {
-        return;
+      var knownRecord = index === -1 ? undefined : this.records[index];
+      if (knownRecord && latencyMs <= knownRecord.latencyMs) {
+        var _knownRecord$boundari, _knownRecord$boundari2;
+        // The interaction at the latency it already had, so its name and target still come from
+        // the entry that measured it at its slowest — and so do `startedAt` and `presentedAt`,
+        // which leaves the processing as the only pair that can have moved.
+        if (((_knownRecord$boundari = knownRecord.boundaries) === null || _knownRecord$boundari === void 0 ? void 0 : _knownRecord$boundari.processingStartedAt) === (boundaries === null || boundaries === void 0 ? void 0 : boundaries.processingStartedAt) && ((_knownRecord$boundari2 = knownRecord.boundaries) === null || _knownRecord$boundari2 === void 0 ? void 0 : _knownRecord$boundari2.processingEndedAt) === (boundaries === null || boundaries === void 0 ? void 0 : boundaries.processingEndedAt)) {
+          return false;
+        }
+        knownRecord.boundaries = boundaries;
+        this.attribute(knownRecord);
+        return true;
       }
 
-      // Read only once the interaction has earned a place: naming its target walks the DOM, and
-      // this runs while the page is already slow.
-      var record = this.toRecord(interaction);
-      if (previousIndex === -1) {
-        this.records.push(record);
+      // Everything below builds a record out of `entry`, so it has to be an entry of this
+      // interaction. The tracker also reports an interaction whose boundaries moved because of an
+      // event that is no interaction of its own, and that event names something else entirely.
+      if (entry.interactionId !== interactionId) {
+        return false;
+      }
+      if (knownRecord) {
+        // An interaction measured as slower replaces itself rather than taking a second place.
+        this.records[index] = this.toRecord(entry, update);
       } else {
-        this.records[previousIndex] = record;
+        var toBeatMs = this.records.length === MAX_RECORDS ? this.records[MAX_RECORDS - 1].latencyMs : MIN_LATENCY_MS;
+        if (latencyMs <= toBeatMs) {
+          return false;
+        }
+        this.records.push(this.toRecord(entry, update));
       }
       this.records.sort(function (a, b) {
-        return b.durationMs - a.durationMs;
+        return b.latencyMs - a.latencyMs;
       });
       this.records.splice(MAX_RECORDS);
+      return true;
     }
 
-    /** @returns the records, slowest first, or nothing when no interaction was slow enough. */
+    /**
+     * Takes in the frames the browser has just reported and works out again what the frames say about
+     * every record — again, because the frames of one interaction can be reported in several batches
+     * and the first of them may hold neither its longest script nor all of its style and layout.
+     *
+     * @returns whether that changed what a snapshot would carry.
+     */
+  }, {
+    key: "trackLongAnimationFrames",
+    value: function trackLongAnimationFrames(frames) {
+      var _this$frames;
+      (_this$frames = this.frames).push.apply(_this$frames, _toConsumableArray(frames));
+      var changed = false;
+      var _iterator = _createForOfIteratorHelper(this.records),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var record = _step.value;
+          changed = this.attribute(record) || changed;
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return changed;
+    }
   }, {
     key: "snapshot",
     value: function snapshot() {
@@ -78,50 +164,205 @@ export var SlowInteractionList = /*#__PURE__*/function () {
         return undefined;
       }
       return this.records.map(function (record) {
+        var _record$attribution, _record$attribution2, _record$attribution3, _record$attribution4, _record$attribution5, _record$attribution6, _record$attribution7, _record$attribution8, _record$attribution9;
+        var boundaries = record.boundaries;
         return {
           group: record.group,
           name: record.name,
-          durationMs: record.durationMs,
-          inputDelayMs: record.inputDelayMs,
-          processingMs: record.processingMs,
-          presentationDelayMs: record.presentationDelayMs,
-          target: record.target
+          durationMs: Math.round(record.latencyMs),
+          inputDelayMs: boundaries && Math.round(boundaries.processingStartedAt - boundaries.startedAt),
+          processingMs: boundaries && Math.round(boundaries.processingEndedAt - boundaries.processingStartedAt),
+          presentationDelayMs: boundaries && Math.round(boundaries.presentedAt - boundaries.processingEndedAt),
+          target: record.target,
+          functionName: (_record$attribution = record.attribution) === null || _record$attribution === void 0 ? void 0 : _record$attribution.functionName,
+          invokerType: (_record$attribution2 = record.attribution) === null || _record$attribution2 === void 0 ? void 0 : _record$attribution2.invokerType,
+          longestScriptMs: (_record$attribution3 = record.attribution) === null || _record$attribution3 === void 0 ? void 0 : _record$attribution3.longestScriptMs,
+          scriptName: (_record$attribution4 = record.attribution) === null || _record$attribution4 === void 0 ? void 0 : _record$attribution4.scriptName,
+          scriptSubpart: (_record$attribution5 = record.attribution) === null || _record$attribution5 === void 0 ? void 0 : _record$attribution5.scriptSubpart,
+          totalPaintDurationMs: (_record$attribution6 = record.attribution) === null || _record$attribution6 === void 0 ? void 0 : _record$attribution6.totalPaintDurationMs,
+          totalScriptDurationMs: (_record$attribution7 = record.attribution) === null || _record$attribution7 === void 0 ? void 0 : _record$attribution7.totalScriptDurationMs,
+          totalStyleAndLayoutDurationMs: (_record$attribution8 = record.attribution) === null || _record$attribution8 === void 0 ? void 0 : _record$attribution8.totalStyleAndLayoutDurationMs,
+          totalUnattributedDurationMs: (_record$attribution9 = record.attribution) === null || _record$attribution9 === void 0 ? void 0 : _record$attribution9.totalUnattributedDurationMs
         };
       });
     }
+  }, {
+    key: "toRecord",
+    value: function toRecord(entry, update) {
+      var _update$group;
+      // The target is read only once the interaction has earned a place: naming it walks the DOM,
+      // and this runs while the page is already slow.
+      var record = {
+        attribution: undefined,
+        boundaries: update.boundaries,
+        interactionId: update.interactionId,
+        // An interaction the editor never reported an event for is not the editor's as far as we
+        // know.
+        group: (_update$group = update.group) !== null && _update$group !== void 0 ? _update$group : 'outsideEditor',
+        name: entry.name,
+        latencyMs: update.latencyMs,
+        target: this.describeTarget(entry.target)
+      };
+
+      // Frames reported before this entry already answer for it.
+      this.attribute(record);
+      return record;
+    }
+  }, {
+    key: "attribute",
+    value: function attribute(record) {
+      var attribution = record.boundaries && this.attributionFor(record.boundaries);
+      if (!attribution) {
+        return false;
+      }
+      if (record.attribution && sameAttribution(record.attribution, attribution)) {
+        return false;
+      }
+      record.attribution = attribution;
+      return true;
+    }
 
     /**
-     * The phases are reported together or not at all: a browser that reports one reports all three,
-     * and zeroes standing in for values we never had would read as an interaction that spent no time
-     * anywhere. Each is clamped, because they come from timestamps the browser coarsens
-     * independently, so a phase can come out just below zero.
+     * What the frames say about an interaction, attributed the way `web-vitals` attributes INP: every
+     * frame overlapping the interaction counts, the script that counts is the one with the longest
+     * part inside it, and style and layout is summed across those frames.
+     *
+     * @returns nothing when no frame overlaps the interaction — the browser reports frames above
+     * 50 ms only.
      */
   }, {
-    key: "toRecord",
-    value: function toRecord(_ref) {
-      var entry = _ref.entry,
-        group = _ref.group,
-        interactionId = _ref.interactionId,
-        latencyMs = _ref.latencyMs;
-      var processingStart = entry.processingStart,
-        processingEnd = entry.processingEnd,
-        startTime = entry.startTime;
-      var measured = typeof processingStart === 'number' && typeof processingEnd === 'number';
-      var phaseMs = function phaseMs(durationMs) {
-        return Math.max(0, Math.round(durationMs));
-      };
+    key: "attributionFor",
+    value: function attributionFor(boundaries) {
+      var _longestScript, _longestScript2, _longestScript3;
+      var overlapped = false;
+      var lastFrameEndTime = 0;
+      var totalScriptDurationMs = 0;
+      var totalStyleAndLayoutDurationMs = 0;
+      var longestScript;
+      var longestScriptMs = 0;
+      var _iterator2 = _createForOfIteratorHelper(this.frames),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _frame$scripts;
+          var frame = _step2.value;
+          // Frames come in the order they were rendered, so once one starts after the interaction,
+          // so does every frame after it.
+          if (frame.startTime > boundaries.processingEndedAt) {
+            break;
+          }
+          var frameEndTime = frame.startTime + frame.duration;
+          if (frameEndTime < boundaries.startedAt) {
+            continue;
+          }
+          overlapped = true;
+          lastFrameEndTime = frameEndTime;
+          totalStyleAndLayoutDurationMs += this.styleAndLayoutOf(frame);
+          var _iterator3 = _createForOfIteratorHelper((_frame$scripts = frame.scripts) !== null && _frame$scripts !== void 0 ? _frame$scripts : []),
+            _step3;
+          try {
+            for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+              var _script$forcedStyleAn;
+              var script = _step3.value;
+              var scriptEndTime = script.startTime + script.duration;
+              if (scriptEndTime < boundaries.startedAt) {
+                continue;
+              }
+              var insideInteractionMs = scriptEndTime - Math.max(boundaries.startedAt, script.startTime);
+              // `forcedStyleAndLayoutDuration` carries no timestamps, so the part of it inside the
+              // interaction is apportioned. It counts as style and layout rather than script time,
+              // the same split DevTools shows.
+              var forcedInsideMs = script.duration ? insideInteractionMs / script.duration * ((_script$forcedStyleAn = script.forcedStyleAndLayoutDuration) !== null && _script$forcedStyleAn !== void 0 ? _script$forcedStyleAn : 0) : 0;
+              totalScriptDurationMs += insideInteractionMs - forcedInsideMs;
+              totalStyleAndLayoutDurationMs += forcedInsideMs;
+              if (insideInteractionMs > longestScriptMs) {
+                longestScript = script;
+                longestScriptMs = insideInteractionMs;
+              }
+            }
+          } catch (err) {
+            _iterator3.e(err);
+          } finally {
+            _iterator3.f();
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+      if (!overlapped) {
+        return undefined;
+      }
+
+      // What the browser did after the last frame of the interaction, so it only counts when that
+      // frame ended no earlier than the handlers did.
+      var totalPaintDurationMs = lastFrameEndTime >= boundaries.processingEndedAt ? Math.max(0, boundaries.presentedAt - lastFrameEndTime) : 0;
+      // Every total is brought to what it is reported as before this subtraction, so that the four
+      // of them add up to the latency rather than to more than it: a frame whose render phase runs
+      // past the interaction would otherwise leave a negative here to be counted twice.
+      totalScriptDurationMs = Math.max(0, totalScriptDurationMs);
+      totalStyleAndLayoutDurationMs = Math.max(0, totalStyleAndLayoutDurationMs);
+      // Whatever is left of the latency: the thread was busy with something the frames attributed
+      // to no script, to no style and layout, and to no paint.
+      var totalUnattributedDurationMs = Math.max(0, boundaries.presentedAt - boundaries.startedAt - totalScriptDurationMs - totalStyleAndLayoutDurationMs - totalPaintDurationMs);
       return {
-        interactionId: interactionId,
-        group: group,
-        name: entry.name,
-        durationMs: Math.round(latencyMs),
-        inputDelayMs: measured ? phaseMs(processingStart - startTime) : undefined,
-        processingMs: measured ? phaseMs(processingEnd - processingStart) : undefined,
-        presentationDelayMs: measured ? phaseMs(startTime + latencyMs - processingEnd) : undefined,
-        target: this.describeTarget(entry.target)
+        functionName: this.truncated((_longestScript = longestScript) === null || _longestScript === void 0 ? void 0 : _longestScript.sourceFunctionName),
+        invokerType: this.truncated((_longestScript2 = longestScript) === null || _longestScript2 === void 0 ? void 0 : _longestScript2.invokerType),
+        longestScriptMs: longestScript && Math.round(longestScriptMs),
+        scriptName: this.truncated(this.fileName((_longestScript3 = longestScript) === null || _longestScript3 === void 0 ? void 0 : _longestScript3.sourceURL)),
+        scriptSubpart: longestScript && this.subpartOf(longestScript, boundaries),
+        totalPaintDurationMs: Math.round(totalPaintDurationMs),
+        totalScriptDurationMs: Math.round(totalScriptDurationMs),
+        totalStyleAndLayoutDurationMs: Math.round(totalStyleAndLayoutDurationMs),
+        totalUnattributedDurationMs: Math.round(totalUnattributedDurationMs)
       };
     }
 
+    /**
+     * Style, layout and paint of the frame, which the browser reports as starting at 0 when the
+     * frame did none.
+     */
+  }, {
+    key: "styleAndLayoutOf",
+    value: function styleAndLayoutOf(frame) {
+      var styleAndLayoutStart = frame.styleAndLayoutStart;
+      if (typeof styleAndLayoutStart !== 'number' || styleAndLayoutStart === 0) {
+        return 0;
+      }
+      var frameEndTime = frame.startTime + frame.duration;
+      return Math.max(0, frameEndTime - styleAndLayoutStart);
+    }
+
+    /** Which phase of the interaction the script ran in, by where it started. */
+  }, {
+    key: "subpartOf",
+    value: function subpartOf(script, boundaries) {
+      if (script.startTime < boundaries.processingStartedAt) {
+        return 'inputDelay';
+      }
+      return script.startTime >= boundaries.processingEndedAt ? 'presentationDelay' : 'processing';
+    }
+  }, {
+    key: "truncated",
+    value: function truncated(name) {
+      return name ? name.slice(0, MAX_NAME_LENGTH) : undefined;
+    }
+
+    /**
+     * The file as the browser named it, content hash and all: that is what identifies the artefact
+     * and its source map, and a query can be grouped away downstream.
+     */
+  }, {
+    key: "fileName",
+    value: function fileName(sourceURL) {
+      if (!sourceURL) {
+        return undefined;
+      }
+      var path = sourceURL.split(QUERY_OR_HASH)[0];
+      return path.slice(path.lastIndexOf('/') + 1);
+    }
+
     /**
      * Names the element an interaction happened on — `div[data-vc="x"] > p > span`, outermost first.
      * The path climbs until an element carries an allow-listed attribute, because that is what says

package/dist/types/analytics/interactivity-snapshot.d.ts

@@ -36,21 +36,52 @@ export type SlowInteractionGroup = EditorInteractionGroupName | 'outsideEditor';
  * One of the slowest interactions of the session: which target was slow, and where the time went,
  * neither of which the histograms can answer.
  *
- * The three phases divide `durationMs` and add up to it within rounding.
+ * The three phases divide `durationMs` and add up to it within rounding, and so do the four totals.
+ * Everything but the phases comes from the Long Animation Frames the interaction ran in, so all of
+ * it is absent when the browser reported none — and the fields describing one script are absent as
+ * well when no script of those frames overlapped the interaction.
  */
 export type SlowInteraction = {
     durationMs: number;
+    /** Function the interaction's slowest script ran in. */
+    functionName?: string;
     group: SlowInteractionGroup;
     /** Time between the event arriving and its handlers starting to run. */
     inputDelayMs?: number;
+    /**
+     * What ran that script, as the browser names it: `event-listener`, `user-callback`,
+     * `resolve-promise`, `classic-script` and so on.
+     */
+    invokerType?: string;
+    /** How much of the interaction's slowest script fell inside the interaction. */
+    longestScriptMs?: number;
     /** Type of the event the latency was measured on, which for a pointer press is usually `click`. */
     name: string;
     /** Time between the handlers finishing and the next frame being presented. */
     presentationDelayMs?: number;
     /** Time spent running the event's handlers. */
     processingMs?: number;
+    /** The bundle that script came from, without its origin or query. */
+    scriptName?: string;
+    /** The phase of the interaction that script ran in. */
+    scriptSubpart?: 'inputDelay' | 'presentationDelay' | 'processing';
     /** A short DOM path. Absent once the element has been removed from the document. */
     target?: string;
+    /** Time between the last frame of the interaction ending and the screen updating. */
+    totalPaintDurationMs?: number;
+    /**
+     * Script time inside the interaction across its frames, the part a script forced into style and
+     * layout excluded.
+     */
+    totalScriptDurationMs?: number;
+    /** Style and layout across the frames of the interaction, the part forced from a script included. */
+    totalStyleAndLayoutDurationMs?: number;
+    /**
+     * The part of the latency the frames account for nothing in — the main thread was busy with
+     * something no Long Animation Frame attributed to a script, to style and layout, or to paint.
+     * Not idle time: the browser reports no frame under 50 ms, so the work of those lands here too.
+     */
+    totalUnattributedDurationMs?: number;
 };
 /**
  * Session-to-date latency distribution for one group of interactions.

package/dist/types/collections/bounded-list.d.ts

@@ -0,0 +1,9 @@
+/** An array that forgets its oldest item once it holds more than `limit`. */
+export declare class BoundedList<Item> {
+    private readonly limit;
+    private readonly items;
+    constructor(limit: number);
+    push(...items: Item[]): void;
+    [Symbol.iterator](): IterableIterator<Item>;
+    findLast(matches: (item: Item) => boolean): Item | undefined;
+}

package/dist/types/collections/bounded-map.d.ts

@@ -0,0 +1,9 @@
+/** A `Map` that forgets its oldest entry once it holds more than `limit`. */
+export declare class BoundedMap<Key, Value> {
+    private readonly limit;
+    private readonly entries;
+    constructor(limit: number);
+    get(key: Key): Value | undefined;
+    forEach(visit: (value: Value, key: Key) => void): void;
+    set(key: Key, value: Value): void;
+}

package/dist/types/collector/interaction-group.d.ts

@@ -1,4 +1,5 @@
 import type { InteractionGroupSnapshot } from '../analytics/interactivity-snapshot';
+import type { InteractionUpdate } from './interaction-tracker';
 /**
  * The latencies of one set of interactions — every interaction on the page, or only the ones
  * inside the editor — reported as one object in the event.
@@ -8,21 +9,33 @@ import type { InteractionGroupSnapshot } from '../analytics/interactivity-snapsh
  * count, the sum, the maximum and the percentiles — is derived from that map when a snapshot
  * is taken. Nothing is computed while interactions arrive.
  *
- * The two counters count different populations: `add` takes the interactions Event Timing
- * measured, `countTotal` takes all of them, including the ones below the 16 ms reporting threshold
- * it never delivers. So `totalCount >= observedCount`, and the difference is how many were too
- * fast to be measured.
+ * The two counters count different populations: `trackInteractionUpdate` takes the interactions
+ * Event Timing measured, `countTotal` takes all of them, including the ones below the 16 ms
+ * reporting threshold it never delivers. So `totalCount >= observedCount`, and the difference is how
+ * many were too fast to be measured.
  */
 export declare class InteractionGroup {
     private countByLatency;
     private totalCount;
+    /**
+     * Takes in what the tracker now says about an interaction: a new one is counted, and one measured
+     * again moves the count it already has.
+     *
+     * @returns whether the group changed.
+     */
+    trackInteractionUpdate(update: InteractionUpdate): boolean;
     add(latencyMs: number): void;
     /**
      * Counts an interaction towards the group's total, measured or not. `page` has no use for it:
      * `performance.interactionCount` counts the page's interactions.
      */
     countTotal(): void;
-    remeasure(previousLatencyMs: number, latencyMs: number): void;
+    /**
+     * @returns whether the count moved, which is `false` when both latencies fall in the step the
+     * interaction is already counted in — including when the interaction was measured no slower at
+     * all and only its boundaries moved.
+     */
+    remeasure(previousLatencyMs: number, latencyMs: number): boolean;
     /**
      * @param totalCount every interaction of the group, including those below the Event Timing
      * reporting threshold. Defaults to what `countTotal` was told, which is where an editor

package/dist/types/collector/interaction-tracker.d.ts

@@ -10,21 +10,37 @@ export type InteractionEntry = PerformanceEntry & {
     processingStart?: number;
     target?: Node | null;
 };
+/**
+ * The four moments an interaction's latency divides at, in order: the user acted, its handlers
+ * started running, they finished, the screen updated.
+ */
+export type InteractionBoundaries = {
+    presentedAt: number;
+    processingEndedAt: number;
+    processingStartedAt: number;
+    startedAt: number;
+};
 /**
  * What an entry did to the interaction it belongs to: either it is the first entry of a new
- * interaction, or it measured an interaction that was already counted as slower than it was
- * known to be. Both carry the editor group of the interaction, if it is one of the editor's.
+ * interaction, or it changed an interaction already known. Both carry the editor group of the
+ * interaction, if it is one of the editor's, and the boundaries it now has.
+ *
+ * A `remeasured` where `previousLatencyMs` equals `latencyMs` is an interaction whose latency stayed
+ * as it was and whose boundaries moved: the entry ran in the same paint without being the slowest
+ * of them.
  */
 export type InteractionUpdate = {
+    boundaries: InteractionBoundaries | undefined;
     group: EditorInteractionGroupName | undefined;
     interactionId: number;
     latencyMs: number;
     type: 'new';
 } | {
-    fromMs: number;
+    boundaries: InteractionBoundaries | undefined;
     group: EditorInteractionGroupName | undefined;
     interactionId: number;
-    toMs: number;
+    latencyMs: number;
+    previousLatencyMs: number;
     type: 'remeasured';
 };
 /**
@@ -41,11 +57,15 @@ export type InteractionUpdate = {
  *
  * The editor's events answer what an entry cannot: which interactions were with the editor, and
  * how many there were, including the ones below the Event Timing reporting threshold.
+ *
+ * Every entry is also placed in the paint that presented it, which is what says how an
+ * interaction's latency divides into waiting, processing and presentation. See `Paint`.
  */
 export declare class InteractionTracker {
     private readonly startsAfterInteractionId;
     private readonly interactions;
     private readonly groupByEvent;
+    private readonly recentPaints;
     private highestInteractionId;
     /**
      * @param startsAfterInteractionId interactions up to and including this one belong to the
@@ -60,11 +80,40 @@ export declare class InteractionTracker {
     /**
      * Merges an entry into the interaction it belongs to.
      *
-     * @returns what that did to the interaction's latency, or nothing when the entry is not
-     * part of an interaction, belongs to a previous tracker, or does not change one.
+     * @returns what that changed about the interactions this tracker knows, the entry's own first.
+     * More than one of them when the paint the entry ran in presented several.
      */
-    merge(entry: InteractionEntry): InteractionUpdate | undefined;
-    /** @returns the group of an interaction to count, when this is the event its group counts on. */
+    merge(entry: InteractionEntry): InteractionUpdate[];
     recordEditorEvent(event: Event): EditorInteractionGroupName | undefined;
-    private prune;
+    /**
+     * Every interaction whose boundaries are read from this paint, reported as measured again at the
+     * latency it already had.
+     *
+     * @param except the interaction the entry measured, which the caller reports itself. `0` or
+     * nothing when the entry measured none, and then no interaction is left out.
+     */
+    private remeasuredUpdatesIn;
+    private newUpdate;
+    private remeasuredUpdate;
+    /**
+     * The four moments of an interaction, read from the paint as it stands now.
+     *
+     * Limited the way `web-vitals` limits its INP attribution, so the four stay in order: the paint's
+     * handlers can have started before the event arrived, and can have finished after the paint the
+     * event's rounded-down `duration` points at.
+     *
+     * @returns nothing when the browser reported no processing timestamps for the interaction, which
+     * leaves it in no paint.
+     */
+    private boundariesOf;
+    /**
+     * The paint that presented this entry, grown to cover this entry's own processing.
+     *
+     * The moment being matched is always the one the first entry of the paint reported, so that a
+     * run of entries 8 ms apart cannot walk one paint across the next.
+     *
+     * @returns nothing when the browser reported no processing timestamps for the entry, which
+     * leaves nothing to place it by.
+     */
+    private paintOf;
 }