@atlaskit/editor-plugin-interactivity 0.1.0 → 0.2.0

package/dist/esm/collector/interactivity-session.js

@@ -0,0 +1,45 @@
+import _createClass from "@babel/runtime/helpers/createClass";
+import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import { InteractionObserver } from './interaction-observer';
+import { InteractionTracker } from './interaction-tracker';
+import { InteractionGroup } from './interaction-group';
+function createSessionId() {
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  var bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, function (byte) {
+    return byte.toString(16).padStart(2, '0');
+  }).join('');
+}
+/**
+ * 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 var InteractivitySession = /*#__PURE__*/_createClass(function InteractivitySession(start) {
+  _classCallCheck(this, InteractivitySession);
+  _defineProperty(this, "id", createSessionId());
+  _defineProperty(this, "startedAt", performance.now());
+  /** Page interaction count when the session opened, subtracted to get its own total. */
+  _defineProperty(this, "interactionCountAtStart", InteractionObserver.readPageInteractionCount());
+  _defineProperty(this, "page", new InteractionGroup());
+  /** Increments per snapshot; a query takes the highest one per session. */
+  _defineProperty(this, "seq", 0);
+  _defineProperty(this, "hiddenMs", 0);
+  /**
+   * 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.
+   */
+  _defineProperty(this, "revision", 0);
+  _defineProperty(this, "emittedRevision", 0);
+  /** One lifecycle snapshot per hidden episode; cleared when the page comes back. */
+  _defineProperty(this, "lifecycleSnapshotEmitted", false);
+  this.objectId = start.objectId;
+  this.mode = start.mode;
+  this.hiddenSince = start.hidden ? this.startedAt : undefined;
+  this.tracker = new InteractionTracker(start.startsAfterInteractionId);
+});

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,87 @@
+import { useEffect } 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;
+      useEffect(function () {
+        // Nothing measured here is worth an editor. This effect runs inside the plugin slot's
+        // error boundary, which also renders every plugin's content components, so a throw
+        // from instrumentation would take that UI down with it.
+        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;
+            }
+          });
+          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]);
+    }
   };
 };

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,61 @@
+/**
+ * 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;
+    hiddenMs: number;
+    interactivitySessionId: string;
+    nodeSize?: number;
+    objectId?: string;
+    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/interaction-group.d.ts

@@ -0,0 +1,25 @@
+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.
+ */
+export declare class InteractionGroup {
+    private countByLatency;
+    add(latencyMs: number): void;
+    remeasure(previousLatencyMs: number, latencyMs: number): void;
+    /**
+     * @param totalCount every interaction of the group, including those below the Event Timing
+     * reporting threshold, which this group never sees.
+     */
+    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,56 @@
+/**
+ * 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.
+ */
+export type InteractionUpdate = {
+    latencyMs: number;
+    type: 'new';
+} | {
+    fromMs: number;
+    toMs: number;
+    type: 'remeasured';
+};
+/**
+ * Groups Event Timing entries into interactions.
+ *
+ * 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.
+ */
+export declare class InteractionTracker {
+    private latencies;
+    private readonly startsAfterInteractionId;
+    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;
+    private prune;
+}

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

@@ -0,0 +1,75 @@
+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.
+ *
+ * `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 snapshotScheduler;
+    private readonly lifecycleObserver;
+    private session;
+    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;
+    /**
+     * 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;
+    private recordEntries;
+    private takeSnapshot;
+}

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

@@ -0,0 +1,39 @@
+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;
+    /** 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);
+}

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

@@ -0,0 +1,25 @@
+export type LifecycleHandlers = {
+    /** The tab became hidden. */
+    onHidden: () => void;
+    /** The page is being unloaded. May arrive right after `onHidden`. */
+    onPageHide: () => void;
+    /** The page came back from the back/forward cache. */
+    onPageShow: () => void;
+    /** The tab became visible again — the session continues. */
+    onVisible: () => void;
+};
+/**
+ * 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 declare class LifecycleObserver {
+    private readonly handlers;
+    private unbind;
+    constructor(handlers: LifecycleHandlers);
+    start(): void;
+    stop(): void;
+}

package/dist/types/collector/snapshot-scheduler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare class SnapshotScheduler {
+    private readonly onTick;
+    private timeoutId;
+    private tickIndex;
+    constructor(onTick: () => void);
+    start(): void;
+    restart(): void;
+    stop(): void;
+    private scheduleNext;
+    private delayForNextTick;
+}