@atlaskit/editor-plugin-interactivity 0.1.0 → 0.3.0

package/dist/esm/collector/lifecycle-observer.js

@@ -0,0 +1,59 @@
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+import { bind } from 'bind-event-listener';
+import { getDocument } from '@atlaskit/browser-apis';
+/**
+ * Reports the page lifecycle signals that force an extra snapshot: the tab being hidden or
+ * shown again, and the page being unloaded or restored from the back/forward cache.
+ *
+ * None of them is guaranteed to arrive — a mobile browser being killed raises nothing at all.
+ * Snapshots carry session-to-date values, so losing the last one costs only the tail of that
+ * session.
+ */
+export var LifecycleObserver = /*#__PURE__*/function () {
+  function LifecycleObserver(handlers) {
+    _classCallCheck(this, LifecycleObserver);
+    this.handlers = handlers;
+  }
+  return _createClass(LifecycleObserver, [{
+    key: "start",
+    value: function start() {
+      var _this = this;
+      var doc = getDocument();
+      var unbindVisibilityChange = doc ? bind(doc, {
+        type: 'visibilitychange',
+        listener: function listener() {
+          if (doc.visibilityState === 'hidden') {
+            _this.handlers.onHidden();
+          } else {
+            _this.handlers.onVisible();
+          }
+        }
+      }) : undefined;
+      var unbindPageHide = bind(window, {
+        type: 'pagehide',
+        listener: function listener() {
+          return _this.handlers.onPageHide();
+        }
+      });
+      var unbindPageShow = bind(window, {
+        type: 'pageshow',
+        listener: function listener() {
+          return _this.handlers.onPageShow();
+        }
+      });
+      this.unbind = function () {
+        unbindVisibilityChange === null || unbindVisibilityChange === void 0 || unbindVisibilityChange();
+        unbindPageHide();
+        unbindPageShow();
+      };
+    }
+  }, {
+    key: "stop",
+    value: function stop() {
+      var _this$unbind;
+      (_this$unbind = this.unbind) === null || _this$unbind === void 0 || _this$unbind.call(this);
+      this.unbind = undefined;
+    }
+  }]);
+}();

package/dist/esm/collector/snapshot-scheduler.js

@@ -0,0 +1,63 @@
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _createClass from "@babel/runtime/helpers/createClass";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+/**
+ * Snapshots are taken 10 s, 30 s and 60 s after the session starts, then every 60 s. The
+ * first three come close together so that short sessions, which are the common case, are
+ * still reported.
+ */
+var INITIAL_OFFSETS_MS = [10000, 30000, 60000];
+var INTERVAL_MS = 60000;
+
+/**
+ * Fires `onTick` on the snapshot cadence. Timings are offsets from `start()`, so a
+ * restart (a new session in the same editor) restarts the cadence too.
+ */
+export var SnapshotScheduler = /*#__PURE__*/function () {
+  function SnapshotScheduler(onTick) {
+    _classCallCheck(this, SnapshotScheduler);
+    _defineProperty(this, "tickIndex", 0);
+    this.onTick = onTick;
+  }
+  return _createClass(SnapshotScheduler, [{
+    key: "start",
+    value: function start() {
+      this.tickIndex = 0;
+      this.scheduleNext();
+    }
+  }, {
+    key: "restart",
+    value: function restart() {
+      this.stop();
+      this.start();
+    }
+  }, {
+    key: "stop",
+    value: function stop() {
+      if (this.timeoutId !== undefined) {
+        window.clearTimeout(this.timeoutId);
+        this.timeoutId = undefined;
+      }
+    }
+  }, {
+    key: "scheduleNext",
+    value: function scheduleNext() {
+      var _this = this;
+      this.timeoutId = window.setTimeout(function () {
+        _this.tickIndex += 1;
+        _this.onTick();
+        _this.scheduleNext();
+      }, this.delayForNextTick());
+    }
+  }, {
+    key: "delayForNextTick",
+    value: function delayForNextTick() {
+      var offset = INITIAL_OFFSETS_MS[this.tickIndex];
+      if (offset === undefined) {
+        return INTERVAL_MS;
+      }
+      var previousOffset = this.tickIndex === 0 ? 0 : INITIAL_OFFSETS_MS[this.tickIndex - 1];
+      return offset - previousOffset;
+    }
+  }]);
+}();

package/dist/esm/interactivityPlugin.js

@@ -1,12 +1,99 @@
+import { useEffect, useRef } from 'react';
+import { logException } from '@atlaskit/editor-common/monitoring';
+import { fireInteractivityEvent } from './analytics/fire-interactivity-event';
+import { InteractivityCollector } from './collector/interactivity-collector';
 /**
- * Reports interaction latency distributions for full page editor sessions as the
- * `editor interactivity` operational event.
+ * Reports session-to-date interaction latency distributions for full page editor sessions
+ * as the `editor interactivity` operational event.
  *
- * A stub for now: the plugin only registers itself. The collector and the event land in
- * EDITOR-8553.
+ * The session runs for as long as the plugin's hook stays mounted, which is one editor
+ * mount: `MountPluginHooks` in editor-core keys hook fibers by plugin name, so a preset
+ * reconfigure — which destroys and recreates ProseMirror plugin views — leaves this hook,
+ * and the session, in place.
  */
-export var interactivityPlugin = function interactivityPlugin() {
+export var interactivityPlugin = function interactivityPlugin(_ref) {
+  var api = _ref.api;
   return {
-    name: 'interactivity'
+    name: 'interactivity',
+    usePluginHook: function usePluginHook(_ref2) {
+      var editorView = _ref2.editorView,
+        wrapperElement = _ref2.wrapperElement;
+      var collectorRef = useRef(undefined);
+      useEffect(function () {
+        try {
+          var _api$contextIdentifie2, _api$editorViewMode2;
+          var collector = new InteractivityCollector({
+            emit: function emit(snapshot) {
+              var _api$analytics;
+              return fireInteractivityEvent(api === null || api === void 0 || (_api$analytics = api.analytics) === null || _api$analytics === void 0 ? void 0 : _api$analytics.actions, snapshot);
+            },
+            getObjectId: function getObjectId() {
+              var _api$contextIdentifie;
+              return api === null || api === void 0 || (_api$contextIdentifie = api.contextIdentifier) === null || _api$contextIdentifie === void 0 || (_api$contextIdentifie = _api$contextIdentifie.sharedState.currentState()) === null || _api$contextIdentifie === void 0 || (_api$contextIdentifie = _api$contextIdentifie.contextIdentifierProvider) === null || _api$contextIdentifie === void 0 ? void 0 : _api$contextIdentifie.objectId;
+            },
+            getSessionMode: function getSessionMode() {
+              var _api$editorViewMode;
+              var mode = api === null || api === void 0 || (_api$editorViewMode = api.editorViewMode) === null || _api$editorViewMode === void 0 || (_api$editorViewMode = _api$editorViewMode.sharedState.currentState()) === null || _api$editorViewMode === void 0 ? void 0 : _api$editorViewMode.mode;
+              if (mode === undefined) {
+                return undefined;
+              }
+              return mode === 'view' ? 'reading' : 'editing';
+            },
+            // A destroyed view still answers, with the document it was destroyed with, so
+            // both report nothing rather than a size the editor no longer has.
+            getNodeSize: function getNodeSize() {
+              return editorView.isDestroyed ? undefined : editorView.state.doc.nodeSize;
+            },
+            // `getElementsByTagName` counts descendants in the browser engine, so this
+            // cannot overflow the stack on very large documents.
+            getEditorDomSize: function getEditorDomSize() {
+              return editorView.isDestroyed ? undefined : editorView.dom.getElementsByTagName('*').length;
+            }
+          });
+
+          // Effects run in declaration order, so the one below always finds it.
+          collectorRef.current = collector;
+          if (!collector.start()) {
+            return;
+          }
+
+          // Confluence live pages navigate and switch between reading and editing without
+          // remounting the editor. A session covers one document in one mode, so either
+          // change ends it and starts the next.
+          var unsubscribeFromObjectId = api === null || api === void 0 || (_api$contextIdentifie2 = api.contextIdentifier) === null || _api$contextIdentifie2 === void 0 ? void 0 : _api$contextIdentifie2.sharedState.onChange(function () {
+            return collector.onObjectIdChanged();
+          });
+          var unsubscribeFromViewMode = api === null || api === void 0 || (_api$editorViewMode2 = api.editorViewMode) === null || _api$editorViewMode2 === void 0 ? void 0 : _api$editorViewMode2.sharedState.onChange(function () {
+            return collector.onViewModeChanged();
+          });
+          return function () {
+            unsubscribeFromObjectId === null || unsubscribeFromObjectId === void 0 || unsubscribeFromObjectId();
+            unsubscribeFromViewMode === null || unsubscribeFromViewMode === void 0 || unsubscribeFromViewMode();
+            collector.stop();
+          };
+        } catch (error) {
+          // Instrumentation must not fail the editor around it, but a failure that hits every
+          // browser of one engine would be invisible without this.
+          void logException(error, {
+            location: 'editor-plugin-interactivity/start'
+          });
+          return;
+        }
+        // `api` is deliberately not a dependency: a preset reconfigure hands out a new
+        // proxy object, but the one captured here keeps resolving plugins from the same
+        // live registry, and restarting the session on a reconfigure would split one
+        // editor session in two.
+      }, [editorView]);
+      useEffect(function () {
+        try {
+          var _collectorRef$current;
+          (_collectorRef$current = collectorRef.current) === null || _collectorRef$current === void 0 || _collectorRef$current.setEditorRoot(wrapperElement);
+        } catch (error) {
+          void logException(error, {
+            location: 'editor-plugin-interactivity/observe'
+          });
+        }
+      }, [wrapperElement]);
+    }
   };
 };

package/dist/types/analytics/fire-interactivity-event.d.ts

@@ -0,0 +1,9 @@
+import type { EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics/api';
+import type { InteractivitySnapshot } from './interactivity-snapshot';
+/**
+ * Sends a snapshot as the `editor interactivity` event.
+ *
+ * Does nothing without the analytics plugin: an editor without it has nowhere to send events,
+ * and the collector keeps measuring either way.
+ */
+export declare function fireInteractivityEvent(analytics: EditorAnalyticsAPI | undefined, snapshot: InteractivitySnapshot): void;

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

@@ -0,0 +1,66 @@
+/**
+ * The shape of what the `editor interactivity` event carries: one snapshot, the groups inside
+ * it, and the values its fields can take.
+ *
+ * This is the contract with the analytics pipeline, which the collector fills in and the
+ * payload wraps, and the one place in the package where types are shared. A type serving a
+ * single module stays with that module.
+ */
+/**
+ * What produced a snapshot.
+ *
+ * `navigation` and `modeChange` end a session while the editor stays mounted: Confluence
+ * live pages keep one editor across page transitions and switch between reading and
+ * editing with a command. A session covers one document in one mode, so either change
+ * closes it and opens the next.
+ */
+export type SnapshotReason = 'timer' | 'hidden' | 'pagehide' | 'unmount' | 'navigation' | 'modeChange';
+/**
+ * What the editor was being used for at the time of the snapshot: `editing` is the
+ * editable editor, `reading` is a live page being viewed with the editor still mounted.
+ */
+export type SessionMode = 'editing' | 'reading';
+/**
+ * Session-to-date latency distribution for one group of interactions.
+ *
+ * `totalCount` counts every interaction, including those below the Event Timing reporting
+ * threshold, so `totalCount - observedCount` is the sub-threshold count. `buckets` is keyed by
+ * each bucket's upper boundary in milliseconds and is not cumulative; empty buckets are
+ * omitted, so a missing bucket means zero.
+ */
+export type InteractionGroupSnapshot = {
+    buckets: Record<string, number>;
+    maxMs: number;
+    observedCount: number;
+    /**
+     * Temporary. Percentiles of the same interactions, keyed by percentile and exact to the 8 ms
+     * Event Timing reports durations at, to confirm that a percentile read off `buckets` lands
+     * where the latencies actually are. Goes once that is established.
+     */
+    percentilesMs: Record<string, number>;
+    sumMs: number;
+    totalCount: number;
+};
+/**
+ * One session-to-date snapshot. Consumers take the highest `seq` per
+ * `interactivitySessionId` and then sum bucket counts across sessions.
+ */
+export type InteractivitySnapshot = {
+    activeMs: number;
+    editorDomSize?: number;
+    /** Interactions inside the editor that are neither typing nor pointing. */
+    editorOther: InteractionGroupSnapshot;
+    editorPointer: InteractionGroupSnapshot;
+    editorTyping: InteractionGroupSnapshot;
+    hiddenMs: number;
+    interactivitySessionId: string;
+    nodeSize?: number;
+    objectId?: string;
+    /** Every interaction on the page, the editor groups included. */
+    page: InteractionGroupSnapshot;
+    reason: SnapshotReason;
+    schema: number;
+    seq: number;
+    /** Fixed for the whole session: a mode change closes it and opens the next. */
+    sessionMode?: SessionMode;
+};

package/dist/types/collector/bucket-boundaries.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bucket boundaries for the interaction latency buckets, version 1.
+ *
+ * Two ranges:
+ * - 16 ms to 200 ms — a boundary every 8 ms: 16, 24, 32, … 200. Event Timing rounds
+ *   durations to 8 ms, so nothing finer is measurable.
+ * - above 200 ms — each boundary ~15% above the previous one, five of them per doubling:
+ *   222, 256, 294, 337, 388, 445, 512, … A 40 ms difference matters at 100 ms and is
+ *   noise at 4 seconds, so buckets grow with the latency instead of staying 8 ms wide.
+ *
+ * 500 ms — the Google INP "poor" threshold — falls inside the 445…512 bucket, so that one
+ * bucket is split at 500 to count the threshold instead of interpolating it. 200 ms, the
+ * "good" threshold, is already a boundary.
+ *
+ * Bump SCHEMA_VERSION whenever any boundary moves; queries group by it.
+ */
+export declare const SCHEMA_VERSION = 1;
+/**
+ * Event Timing reporting threshold. Faster interactions are never delivered to the
+ * observer, so they reach no bucket at all — `performance.interactionCount` is what counts
+ * them, as `totalCount - observedCount`. This bucket holds the interactions reported at
+ * exactly the threshold.
+ */
+export declare const REPORTING_THRESHOLD_MS = 16;
+/**
+ * The bucket a latency belongs to, identified by the bucket's upper boundary in whole
+ * milliseconds — which is also its key in the reported buckets.
+ *
+ * Every latency gets a bucket, however slow: the boundaries continue upwards, so there is no
+ * overflow bucket. Expects the whole-millisecond durations Event Timing reports; boundaries
+ * are floored, so a fractional latency can land in a bucket whose key reads up to a
+ * millisecond below it. Non-finite latencies never reach here — `InteractionTracker` drops
+ * them as it reads the entry.
+ */
+export declare function bucketKeyForMs(latencyMs: number): number;

package/dist/types/collector/editor-event-observer.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reports the events the interactions with the editor are made of, as the browser dispatched
+ * them. What they mean is the tracker's business.
+ *
+ * Event Timing cannot answer which interactions were with the editor, because it observes the
+ * whole document, nor how many there were, because it reports none below 16 ms.
+ */
+export declare class EditorEventObserver {
+    private readonly onEvent;
+    private root;
+    private unbind;
+    constructor(onEvent: (event: Event) => void);
+    /**
+     * Called as the element the editor renders itself into changes: the editor only knows it after
+     * its first render, and can replace it.
+     */
+    observe(root: Element | null | undefined): void;
+    stop(): void;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The editor group an interaction belongs to, which is also the field the event reports it in.
+ *
+ * `editorOther` is the remainder — an interaction the browser counts that is neither typing nor
+ * pointing — so the three groups together cover whatever the browser calls an interaction.
+ */
+export type EditorInteractionGroupName = 'editorOther' | 'editorPointer' | 'editorTyping';
+export type InteractionEventKind = {
+    /**
+     * Whether an interaction is counted when this event arrives. One event of each group has it,
+     * because an interaction is several events — `keydown`, what the key produced, `keyup`, or
+     * `pointerdown`, `pointerup`, `click` — and counting each would count it three times.
+     */
+    counts?: boolean;
+    group: EditorInteractionGroupName;
+};
+/** Derived, so the types listened for cannot drift from the table. */
+export declare const INTERACTION_EVENT_TYPES: string[];
+export declare function interactionEventKind(type: string): InteractionEventKind | undefined;

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

@@ -0,0 +1,37 @@
+import type { InteractionGroupSnapshot } from '../analytics/interactivity-snapshot';
+/**
+ * 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.
+ *
+ * The whole state is a count per distinct latency, so an interaction only costs a counter
+ * whatever its latency was, and everything the event carries — the reported buckets, the
+ * 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.
+ */
+export declare class InteractionGroup {
+    private countByLatency;
+    private totalCount;
+    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;
+    /**
+     * @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
+     * group's total comes from; `page` passes `performance.interactionCount` instead.
+     */
+    snapshot(totalCount?: number): InteractionGroupSnapshot;
+    private observedCount;
+    /** Rounding lives here so that every count goes through the same step, in or out. */
+    private roundLatencyUp;
+    private increment;
+    private decrement;
+}

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

@@ -0,0 +1,39 @@
+import type { InteractionEntry } from './interaction-tracker';
+/**
+ * Reports the interactions the browser observes to `onEntries`.
+ *
+ * `drain` and `stop` are safe to call before `start` and after each other, so a session
+ * that never started collecting needs no special handling.
+ */
+export declare class InteractionObserver {
+    /**
+     * Whether the browser reports both things a session needs: `interactionId`, which groups
+     * entries into interactions, and `performance.interactionCount`, which counts the ones
+     * below the reporting threshold. Both are Chromium-only, and without the count
+     * `totalCount` would be indistinguishable from `observedCount`.
+     */
+    static isSupported(): boolean;
+    /**
+     * Total interactions on the page since page load, including those below the reporting
+     * threshold that no observer ever sees. A property of the page, not of an observer.
+     */
+    static readPageInteractionCount(): number;
+    private readonly onEntries;
+    private observer;
+    constructor(onEntries: (entries: InteractionEntry[]) => void);
+    /**
+     * Starts reporting interactions from this point on. Does nothing when already started, so
+     * a second call cannot leave an observer running with nobody to disconnect it.
+     *
+     * `buffered` is `false`: the entries the browser collected earlier are interactions with
+     * the page while the editor was still loading, and they belong to no session of ours.
+     */
+    start(): void;
+    /**
+     * Synchronously reports the entries the browser has produced but not yet dispatched to
+     * the callback. A snapshot taken because the page is going away has to include them,
+     * because there is no later chance to.
+     */
+    drain(): void;
+    stop(): void;
+}

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

@@ -0,0 +1,65 @@
+import type { EditorInteractionGroupName } from './interaction-events';
+/**
+ * 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.
+ */
+export type InteractionEntry = PerformanceEntry & {
+    interactionId?: 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.
+ */
+export type InteractionUpdate = {
+    group: EditorInteractionGroupName | undefined;
+    latencyMs: number;
+    type: 'new';
+} | {
+    fromMs: number;
+    group: EditorInteractionGroupName | undefined;
+    toMs: number;
+    type: 'remeasured';
+};
+/**
+ * Makes interactions out of what the two observers report, for one session.
+ *
+ * Entries sharing a non-zero `interactionId` are one interaction whose latency is the
+ * maximum `duration` among them. Entries arrive incrementally, so an interaction's latency
+ * can grow after it was first reported — callers apply that to what they already counted
+ * rather than counting the interaction twice.
+ *
+ * A non-zero `interactionId` is the browser's own definition of an interaction, which is
+ * also what INP filters on: it is assigned to the pointer and keyboard events that make one
+ * up, and never to scrolling or pointer movement.
+ *
+ * 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.
+ */
+export declare class InteractionTracker {
+    private readonly startsAfterInteractionId;
+    private readonly interactions;
+    private readonly groupByEvent;
+    private highestInteractionId;
+    /**
+     * @param startsAfterInteractionId interactions up to and including this one belong to the
+     * previous tracker and are ignored. `interactionId` counts up over the life of the page, so
+     * a session opening mid-page passes the highest id the one before it saw; without that, an
+     * entry still arriving for an interaction from the previous session would look new here and
+     * be counted in both.
+     */
+    constructor(startsAfterInteractionId?: number);
+    /** The highest `interactionId` this tracker has seen. */
+    get lastInteractionId(): number;
+    /**
+     * 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.
+     */
+    merge(entry: InteractionEntry): InteractionUpdate | undefined;
+    /** @returns the group of an interaction to count, when this is the event its group counts on. */
+    recordEditorEvent(event: Event): EditorInteractionGroupName | undefined;
+    private prune;
+}

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

@@ -0,0 +1,90 @@
+import type { InteractivitySnapshot, SessionMode } from '../analytics/interactivity-snapshot';
+export type InteractivityCollectorOptions = {
+    emit: (snapshot: InteractivitySnapshot) => void;
+    /** Elements inside the editor's content DOM. Read at snapshot time. */
+    getEditorDomSize: () => number | undefined;
+    /** Size of the ProseMirror document. Read at snapshot time. */
+    getNodeSize: () => number | undefined;
+    getObjectId: () => string | undefined;
+    getSessionMode: () => SessionMode | undefined;
+};
+/**
+ * Collects interaction latencies for one editor mount and emits session-to-date snapshots.
+ *
+ * Every interaction is counted in `page`, and the ones with the editor again in one of the editor
+ * groups, which is what tells a slow editor apart from a slow page around it.
+ *
+ * `start` and `stop` bound the collecting, which happens once. Within it there can be several
+ * sessions, because a session covers one document in one mode: a Confluence live page
+ * navigates and switches between reading and editing without ever remounting the editor, and
+ * each of those closes the current session and opens the next.
+ */
+export declare class InteractivityCollector {
+    private readonly emit;
+    private readonly getEditorDomSize;
+    private readonly getNodeSize;
+    private readonly getObjectId;
+    private readonly getSessionMode;
+    private readonly interactionObserver;
+    private readonly editorEvents;
+    private readonly snapshotScheduler;
+    private readonly lifecycleObserver;
+    private session;
+    private editorRoot;
+    private started;
+    private stopped;
+    constructor(options: InteractivityCollectorOptions);
+    /**
+     * Starts collecting. Calling it again while collecting changes nothing.
+     *
+     * @returns whether collecting is running; `false` when the browser cannot support it, or
+     * when it has already been stopped.
+     */
+    start(): boolean;
+    /** Reports the session as ended by the editor unmounting, and stops collecting. */
+    stop(): void;
+    /**
+     * The element the editor renders itself into is what makes an interaction one of the editor's.
+     * The session is not tied to it: interactions from before it arrives are counted in `page`.
+     */
+    setEditorRoot(root: Element | null | undefined): void;
+    /**
+     * Rotates the session when the editor is pointed at different content.
+     *
+     * An unknown object id is no information, never a change. The provider resolves
+     * asynchronously after mount, and `contextIdentifierPlugin` resets its state to the
+     * configured provider on transactions that do not carry a new one, so the id read here goes
+     * missing for a moment on a document that never changed.
+     */
+    onObjectIdChanged(): void;
+    /**
+     * Rotates the session when the editor switches between reading and editing. Interactions
+     * with a read-only page are a different population from interactions while editing, so one
+     * session never covers both.
+     */
+    onViewModeChanged(): void;
+    /**
+     * @param startsAfterInteractionId the highest interaction the previous session saw, so
+     * entries still arriving for it are not counted here as well.
+     */
+    private createSession;
+    /** Reports the current session as ended by `reason` and puts a new one in its place. */
+    private rotateSession;
+    private onTimer;
+    private onHidden;
+    private onVisible;
+    private onPageHide;
+    /**
+     * The page came back from the back/forward cache, which never raises a visibility change.
+     * The session continues, and the signal that suspended it has been reported, so the next
+     * one is due.
+     */
+    private onPageShow;
+    /**
+     * Counts an interaction with the editor, including the ones Event Timing never reports because
+     * they were faster than its threshold — which is why a count alone moves the session on.
+     */
+    private recordEditorEvent;
+    private recordEntries;
+    private takeSnapshot;
+}

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

@@ -0,0 +1,42 @@
+import type { SessionMode } from '../analytics/interactivity-snapshot';
+import { InteractionTracker } from './interaction-tracker';
+import { InteractionGroup } from './interaction-group';
+export type InteractivitySessionStart = {
+    hidden: boolean;
+    mode: SessionMode | undefined;
+    objectId: string | undefined;
+    startsAfterInteractionId: number;
+};
+/**
+ * Everything that belongs to one session.
+ *
+ * Nothing here is reset — the next session is a new instance — so a field added here cannot
+ * be left carrying the previous session's value.
+ */
+export declare class InteractivitySession {
+    readonly id: string;
+    readonly startedAt: number;
+    /** Page interaction count when the session opened, subtracted to get its own total. */
+    readonly interactionCountAtStart: number;
+    readonly tracker: InteractionTracker;
+    readonly page: InteractionGroup;
+    readonly editorTyping: InteractionGroup;
+    readonly editorPointer: InteractionGroup;
+    readonly editorOther: InteractionGroup;
+    /** 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. */
+    objectId: string | undefined;
+    mode: SessionMode | undefined;
+    hiddenMs: number;
+    hiddenSince: number | undefined;
+    /**
+     * Bumped on every change to the accumulated data. A snapshot is emitted only when this
+     * has moved past `emittedRevision`, so identical snapshots are never sent twice.
+     */
+    revision: number;
+    emittedRevision: number;
+    /** One lifecycle snapshot per hidden episode; cleared when the page comes back. */
+    lifecycleSnapshotEmitted: boolean;
+    constructor(start: InteractivitySessionStart);
+}