@atlaskit/editor-plugin-interactivity 1.0.0 → 1.2.0

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

@@ -1,25 +1,46 @@
-import type { EditorInteractionGroupName } from './interaction-events';
+import type { EditorInteractionGroupName } from '../analytics/interactivity-snapshot';
 /**
- * The Event Timing fields this package reads. `interactionId` is missing from the DOM
- * typings' `PerformanceEventTiming`, so it is declared here as optional, which also makes
- * a `PerformanceEntry` from `getEntries()` assignable without a cast.
+ * The Event Timing fields this package reads, declared optional so that a `PerformanceEntry` from
+ * `getEntries()` is assignable without a cast — `interactionId` is missing from the DOM typings'
+ * `PerformanceEventTiming` altogether, and the rest are only on it.
  */
 export type InteractionEntry = PerformanceEntry & {
     interactionId?: number;
+    processingEnd?: number;
+    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;
-    toMs: number;
+    interactionId: number;
+    latencyMs: number;
+    previousLatencyMs: number;
     type: 'remeasured';
 };
 /**
@@ -36,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
@@ -55,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;
 }

package/dist/types/collector/interactivity-collector.d.ts

@@ -26,6 +26,7 @@ export declare class InteractivityCollector {
     private readonly getObjectId;
     private readonly getSessionMode;
     private readonly interactionObserver;
+    private readonly longAnimationFrameObserver;
     private readonly editorEvents;
     private readonly snapshotScheduler;
     private readonly lifecycleObserver;
@@ -85,6 +86,8 @@ export declare class InteractivityCollector {
      * they were faster than its threshold — which is why a count alone moves the session on.
      */
     private recordEditorEvent;
+    /** Long Animation Frames say where the latency of a slow interaction went. */
+    private recordFrames;
     private recordEntries;
     private takeSnapshot;
 }

package/dist/types/collector/interactivity-session.d.ts

@@ -1,6 +1,7 @@
 import type { SessionMode } from '../analytics/interactivity-snapshot';
 import { InteractionTracker } from './interaction-tracker';
 import { InteractionGroup } from './interaction-group';
+import { SlowInteractionList } from './slow-interaction-list';
 export type InteractivitySessionStart = {
     hidden: boolean;
     mode: SessionMode | undefined;
@@ -23,6 +24,7 @@ export declare class InteractivitySession {
     readonly editorTyping: InteractionGroup;
     readonly editorPointer: InteractionGroup;
     readonly editorOther: InteractionGroup;
+    readonly slowest: SlowInteractionList | undefined;
     /** Increments per snapshot; a query takes the highest one per session. */
     seq: number;
     /** Both fixed for the session: a change to either closes it and opens the next. */

package/dist/types/collector/long-animation-frame-observer.d.ts

@@ -0,0 +1,28 @@
+export type LongAnimationFrame = PerformanceEntry & {
+    scripts?: LongAnimationFrameScript[];
+    styleAndLayoutStart?: number;
+};
+export type LongAnimationFrameScript = {
+    duration: number;
+    forcedStyleAndLayoutDuration?: number;
+    invokerType?: string;
+    sourceFunctionName?: string;
+    sourceURL?: string;
+    startTime: number;
+};
+/**
+ * Reports the frames the browser took longer than 50 ms to render to `onFrames`. They are what says
+ * where the time of a slow interaction went — which script ran the longest while the user waited,
+ * and how much of the wait was style and layout — which Event Timing cannot answer.
+ *
+ * What they say about an interaction is `SlowInteractionList`'s to work out; this only observes.
+ */
+export declare class LongAnimationFrameObserver {
+    private readonly onFrames;
+    static isSupported(): boolean;
+    private observer;
+    constructor(onFrames: (frames: LongAnimationFrame[]) => void);
+    start(): void;
+    drain(): void;
+    stop(): void;
+}

package/dist/types/collector/slow-interaction-list.d.ts

@@ -0,0 +1,64 @@
+import type { SlowInteraction } from '../analytics/interactivity-snapshot';
+import type { InteractionEntry, InteractionUpdate } from './interaction-tracker';
+import type { LongAnimationFrame } from './long-animation-frame-observer';
+/**
+ * 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.
+ */
+export declare class SlowInteractionList {
+    /** Slowest first. */
+    private readonly records;
+    private readonly frames;
+    /**
+     * 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.
+     */
+    trackInteractionUpdate(entry: InteractionEntry, update: InteractionUpdate): boolean;
+    /**
+     * 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.
+     */
+    trackLongAnimationFrames(frames: LongAnimationFrame[]): boolean;
+    snapshot(): SlowInteraction[] | undefined;
+    private toRecord;
+    private attribute;
+    /**
+     * 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.
+     */
+    private attributionFor;
+    /**
+     * Style, layout and paint of the frame, which the browser reports as starting at 0 when the
+     * frame did none.
+     */
+    private styleAndLayoutOf;
+    /** Which phase of the interaction the script ran in, by where it started. */
+    private subpartOf;
+    private truncated;
+    /**
+     * 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.
+     */
+    private fileName;
+    /**
+     * 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
+     * which part of the page this was.
+     */
+    private describeTarget;
+    private identifyingAttribute;
+}

package/docs/0-intro.tsx

@@ -25,7 +25,8 @@ ${createEditorUseOnlyNotice('Editor Plugin Interactivity', [
 
   It reports the \`editor interactivity\` operational event: session-to-date interaction latency
   histograms for full page editor sessions — for the page as a whole, and for the editor's typing,
-  pointer and other interactions — per [RFC 095](https://hello.atlassian.net/wiki/spaces/EDITOR/pages/7527607488/Editor+RFC+095+Confluence+editor+responsiveness+bucketed+INP+telemetry).
+  pointer and other interactions — along with the slowest interactions of the session, per
+  [RFC 095](https://hello.atlassian.net/wiki/spaces/EDITOR/pages/7527607488/Editor+RFC+095+Confluence+editor+responsiveness+bucketed+INP+telemetry).
   See the package README for the event shape, the snapshot cadence and what ends a session.
 
   The plugin has no configuration, state, actions or commands — adding it to a preset is what turns

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-interactivity",
-	"version": "1.0.0",
+	"version": "1.2.0",
 	"description": "Interactivity plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -20,14 +20,15 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@atlaskit/browser-apis": "^1.2.0",
-		"@atlaskit/editor-plugin-analytics": "^16.0.0",
+		"@atlaskit/editor-plugin-analytics": "^16.1.0",
 		"@atlaskit/editor-plugin-context-identifier": "^16.0.0",
 		"@atlaskit/editor-plugin-editor-viewmode": "^18.0.0",
+		"@atlaskit/platform-feature-experiments": "^0.3.0",
 		"@babel/runtime": "^7.0.0",
 		"bind-event-listener": "^3.0.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^120.0.0",
+		"@atlaskit/editor-common": "^120.10.0",
 		"react": "^18.2.0 || ^19.2.0"
 	},
 	"devDependencies": {