@atlaskit/editor-plugin-collab-edit 23.0.0 → 23.0.2

package/dist/esm/pm-plugins/collabSendHold.js

@@ -0,0 +1,70 @@
+import { DEFER_COLLAB_SEND } from '@atlaskit/editor-common/collab-defer-collab-send';
+/**
+ * Upper bound on how long the send may stay held, measured from the transaction that *started* the
+ * hold rather than the most recent one.
+ *
+ * This is the only time bound on the hold. Producers decide when to release on semantic grounds —
+ * a completed block, the end of a stream — and this bounds how long that can take. It therefore
+ * doubles as the guarantee that a producer which never releases, because it aborted or threw
+ * between hold and release, cannot stop the editor sending for the rest of the session.
+ */
+export var MAX_SEND_HOLD_MS = 2000;
+/**
+ * Tracks whether sending to the collab service is currently held back.
+ *
+ * A producer that streams into the document needs several of its transactions to accumulate in the
+ * unconfirmed queue before anything is sent, so they can be composed into one step. Marking only
+ * the producer's own transactions is not enough: `sendTransaction` runs for *every* state update,
+ * and `provider.send` flushes and locks the entire queue regardless of which transaction triggered
+ * it. Acknowledgements from previous commits, remote steps, selection changes and the user's own
+ * typing all trigger it.
+ *
+ * So the hold has to be a state that spans transactions rather than a flag on one:
+ *
+ * - `tr.setMeta(DEFER_COLLAB_SEND, true)` starts the hold, and does *not* extend one already in
+ *   progress
+ * - `tr.setMeta(DEFER_COLLAB_SEND, false)` releases it
+ * - anything else leaves it as it is
+ *
+ * Not extending matters. A producer marks every frame it wants held, so re-arming on each one
+ * would push the deadline back indefinitely and the bound would never be reached during an active
+ * stream. Measuring from the first held transaction instead makes the hold flush at least every
+ * {@link MAX_SEND_HOLD_MS}, with the next held frame starting a fresh window.
+ *
+ * While held, nothing is sent. Note this includes the local user's own edits: `sendableSteps`
+ * returns the queue in version order, so there is no way to send a step that sits behind held
+ * steps. Producers should keep hold windows short for that reason.
+ */
+export var createCollabSendHold = function createCollabSendHold() {
+  var heldSince;
+  return {
+    observe: function observe(transaction) {
+      var now = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : Date.now();
+      var meta = transaction.getMeta(DEFER_COLLAB_SEND);
+      if (meta === true) {
+        // Only start a window, never extend one, so a continuous stream of held frames
+        // still reaches the bound. See the note on this type about why.
+        if (heldSince === undefined) {
+          heldSince = now;
+        }
+        return;
+      }
+      if (meta === false) {
+        heldSince = undefined;
+      }
+    },
+    isHeld: function isHeld() {
+      var now = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : Date.now();
+      if (heldSince === undefined) {
+        return false;
+      }
+      if (now - heldSince >= MAX_SEND_HOLD_MS) {
+        // Clear as well as report, so the next held frame opens a fresh window instead of
+        // being judged against the expired one.
+        heldSince = undefined;
+        return false;
+      }
+      return true;
+    }
+  };
+};

package/dist/esm/pm-plugins/collapseStreamingSteps.js

@@ -0,0 +1,122 @@
+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 { STREAMING_COLLAPSIBLE_STEPS } from '@atlaskit/editor-common/collab-streaming-step-collapse';
+import { Transaction } from '@atlaskit/editor-prosemirror/state';
+import { Rebaseable } from '@atlaskit/prosemirror-collab';
+import { mergeOverlappingSteps } from './mergeOverlappingSteps';
+
+/**
+ * Is this step an intermediate frame that its producer has marked as collapsible, and is it still
+ * free to be composed?
+ */
+var isCollapsibleFrame = function isCollapsibleFrame(rebaseable) {
+  var origin = rebaseable.origin;
+  if (!(origin instanceof Transaction) || origin.getMeta(STREAMING_COLLAPSIBLE_STEPS) !== true) {
+    return false;
+  }
+
+  // Already sent to (or queued for) the collab service — composing it now would change a step the
+  // backend has already seen. Mirrors the `mergeIsLocked` contract in `mergeUnconfirmedSteps`.
+  return !origin.getMeta('mergeIsLocked');
+};
+
+/**
+ * Starting document of each composed step this module has produced.
+ *
+ * A composed step is synthesised rather than taken from a transaction, so it cannot be found in
+ * `origin.steps` and its starting document cannot be recovered the way an original frame's can.
+ * `transformUnconfirmed` runs once per transaction and is handed back the steps it returned last
+ * time, so the composed step needs to carry its document forward to keep composing against later
+ * frames.
+ *
+ * Keyed on the step rather than its Rebaseable wrapper. `mergeUnconfirmedSteps` runs immediately
+ * after this module in `transformUnconfirmed` and rebuilds every wrapper it is given — merging
+ * enabled or not — so a wrapper-keyed entry would be unreachable by the very next pass. The step
+ * survives that rebuild untouched, and is still replaced whenever the association genuinely
+ * becomes stale: `rebaseSteps` maps steps into new objects, and a real merge composes a new one.
+ */
+var composedStepDocs = new WeakMap();
+
+/**
+ * The document this step was applied to.
+ *
+ * `transformUnconfirmed` is handed steps and nothing else, but a Rebaseable keeps a reference to
+ * the transaction that produced it, and a transaction records the document before each of its
+ * steps. That is enough for `mergeOverlappingSteps` to resolve merges it cannot derive from the
+ * steps alone — notably a frame that replaces more than just what the previous frame inserted.
+ *
+ * Rebasing maps a step into a new object while keeping the original transaction, so a rebased step
+ * is not found in `origin.steps` and correctly yields no document. `mergeOverlappingSteps` then
+ * falls back to the merges it can prove without one.
+ */
+var docBeforeStep = function docBeforeStep(rebaseable) {
+  var origin = rebaseable.origin,
+    step = rebaseable.step;
+  var composed = composedStepDocs.get(step);
+  if (composed) {
+    return composed;
+  }
+  var index = origin.steps.indexOf(step);
+  return index >= 0 ? origin.docs[index] : undefined;
+};
+
+/**
+ * Compose adjacent streaming frames in the unconfirmed queue so the collab service receives one
+ * step per flush instead of one step per rendered chunk.
+ *
+ * This runs in the collab plugin's `transformUnconfirmed` hook, which fires *after* each frame has
+ * already been applied to the document. Collapsing therefore has no effect on what the local user
+ * sees, on undo history, or on any other plugin state — it only changes what is sent to the collab
+ * service, and what is used as the rebase buffer when remote steps arrive.
+ *
+ * Because the unconfirmed steps double as the rebase buffer (`rebaseSteps` applies their inverses
+ * to the live document), the composition must be exact. `mergeOverlappingSteps` only returns a
+ * merge it can prove exact, and this function degrades to a no-op whenever it declines.
+ *
+ * @param steps Rebaseable steps
+ * @returns Rebaseable steps, with adjacent streaming frames composed
+ */
+export function collapseStreamingSteps(steps) {
+  // Fast path: nothing to do unless at least two frames could possibly compose.
+  if (steps.length < 2) {
+    return steps;
+  }
+  var collapsed = [];
+  // The document the run currently at the tail of `collapsed` started from. A composed step
+  // still applies to the document its first frame applied to, so this survives each merge.
+  var runDocBefore;
+  var _iterator = _createForOfIteratorHelper(steps),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var rebaseable = _step.value;
+      var previous = collapsed[collapsed.length - 1];
+      if (!previous || !isCollapsibleFrame(previous) || !isCollapsibleFrame(rebaseable)) {
+        collapsed.push(rebaseable);
+        runDocBefore = docBeforeStep(rebaseable);
+        continue;
+      }
+      var merged = mergeOverlappingSteps(previous, rebaseable, runDocBefore);
+      if (!merged) {
+        collapsed.push(rebaseable);
+        runDocBefore = docBeforeStep(rebaseable);
+        continue;
+      }
+
+      // Keep the earliest origin, matching `mergeUnconfirmedSteps`. `commitUnconfirmedSteps` in
+      // the collab provider tracks completion by origin identity, so keeping the earliest means
+      // the composed step is not considered confirmed until the whole run has been acknowledged.
+      var composed = new Rebaseable(merged.step, merged.inverted, previous.origin);
+      if (runDocBefore) {
+        composedStepDocs.set(composed.step, runDocBefore);
+      }
+      collapsed[collapsed.length - 1] = composed;
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return collapsed;
+}

package/dist/esm/pm-plugins/events/send-transaction.js

@@ -8,7 +8,9 @@ export var sendTransaction = function sendTransaction(_ref) {
     newEditorState = _ref.newEditorState,
     useNativePlugin = _ref.useNativePlugin,
     viewMode = _ref.viewMode,
-    hideTelecursorOnLoad = _ref.hideTelecursorOnLoad;
+    hideTelecursorOnLoad = _ref.hideTelecursorOnLoad,
+    _ref$isSendHeld = _ref.isSendHeld,
+    isSendHeld = _ref$isSendHeld === void 0 ? false : _ref$isSendHeld;
   return function (provider) {
     var docChangedTransaction = transactions.find(function (tr) {
       return tr.docChanged;
@@ -27,7 +29,16 @@ export var sendTransaction = function sendTransaction(_ref) {
     // TODO: ED-8995 - We need to do this check to reduce the number of race conditions when working with tables.
     // This metadata is coming from the scaleTable command in table-resizing plugin
     !originalTransaction.getMeta('scaleTable') && trNoAnalytics.docChanged;
-    if (useNativePlugin || shouldSendStepForSynchronyCollabProvider) {
+
+    // A streaming producer can hold the flush back so several of its frames accumulate in the
+    // unconfirmed queue and collapse into one step before being sent. The steps are not
+    // dropped: `sendableSteps` returns the whole queue, so the first unheld state update sends
+    // everything that accumulated. Skipping `send` also skips `lockStepOrigins`, which is what
+    // keeps the accumulated frames composable.
+    //
+    // Telepointer messages below are intentionally left alone — holding them would freeze
+    // other participants' cursors for the length of the hold, and they carry no steps.
+    if (!isSendHeld && (useNativePlugin || shouldSendStepForSynchronyCollabProvider)) {
       provider.send(trNoAnalytics, oldEditorState, newEditorState);
     }
     var prevPluginState = pluginKey.getState(oldEditorState);

package/dist/esm/pm-plugins/mergeOverlappingSteps.js

@@ -0,0 +1,147 @@
+import { ReplaceStep, Transform } from '@atlaskit/editor-prosemirror/transform';
+
+/**
+ * A step paired with its inverse, as stored in the collab unconfirmed queue.
+ */
+
+/**
+ * `structure` is `@internal` on ReplaceStep but is part of the serialised form, so this is the
+ * supported way to read it. Structural replaces exist to stop rebased steps from overwriting
+ * content they should not, so they are never merged.
+ */
+var isStructural = function isStructural(step) {
+  return step.toJSON().structure === true;
+};
+var asPlainReplaceStep = function asPlainReplaceStep(step) {
+  return (
+    // Deliberately excludes ReplaceAroundStep — the position arithmetic below is only sound for a
+    // plain range replace.
+    step instanceof ReplaceStep && !isStructural(step) ? step : undefined
+  );
+};
+
+/**
+ * Do the two steps touch the same region of the document?
+ *
+ * `second` is expressed in the coordinate space *after* `first` has been applied, so `first`'s
+ * footprint there is the range its slice occupies: `[from, from + slice.size]`.
+ */
+var overlaps = function overlaps(first, second) {
+  var firstInsertedEnd = first.from + first.slice.size;
+  return second.from <= firstInsertedEnd && second.to >= first.from;
+};
+
+/**
+ * Merge using ProseMirror's own step merging, which handles adjacent insertions and adjacent
+ * deletions. Both the steps and their inverses have to merge for the result to be usable as a
+ * rebase buffer entry — inverses compose in reverse order.
+ */
+var mergeNatively = function mergeNatively(first, second) {
+  var step = first.step.merge(second.step);
+  if (!step) {
+    return null;
+  }
+  var inverted = second.inverted.merge(first.inverted);
+  if (!inverted) {
+    return null;
+  }
+  return {
+    step: step,
+    inverted: inverted
+  };
+};
+
+/**
+ * Merge any two overlapping steps by applying both to the document and describing the net change
+ * as a single minimal replacement.
+ *
+ * This is the general case: it copes with `second` reaching past `first` on either side, with
+ * partial overlaps, and with slices whose open depths differ — none of which can be resolved from
+ * the steps alone, because the composed slice has to be cut out of a real document.
+ */
+var mergeViaDocument = function mergeViaDocument(first, second, docBefore) {
+  var docAfter;
+  try {
+    var transform = new Transform(docBefore);
+    transform.step(first.step);
+    transform.step(second.step);
+    docAfter = transform.doc;
+  } catch (_unused) {
+    // `docBefore` did not match the steps (for example the steps have since been rebased).
+    return null;
+  }
+  var start = docBefore.content.findDiffStart(docAfter.content);
+  if (start === null) {
+    // The steps cancel each other out. There is no single step representing "no change", so
+    // leave the pair alone rather than inventing one.
+    return null;
+  }
+  var diffEnd = docBefore.content.findDiffEnd(docAfter.content);
+  if (!diffEnd) {
+    return null;
+  }
+
+  // findDiffStart and findDiffEnd can overshoot each other when the same text appears on both
+  // sides of the change; push the end out so the range stays well formed.
+  var endBefore = diffEnd.a,
+    endAfter = diffEnd.b;
+  var overshoot = start - Math.min(endBefore, endAfter);
+  if (overshoot > 0) {
+    endBefore += overshoot;
+    endAfter += overshoot;
+  }
+  var step = new ReplaceStep(start, endBefore, docAfter.slice(start, endAfter));
+
+  // Cheap guarantee that the composition is exact. If it is not, keep the original pair.
+  var applied = step.apply(docBefore);
+  if (applied.failed !== null || !applied.doc || !applied.doc.eq(docAfter)) {
+    return null;
+  }
+  return {
+    step: step,
+    inverted: step.invert(docBefore)
+  };
+};
+
+/**
+ * Merge two consecutive steps into the single step they are collectively equivalent to.
+ *
+ * `second` must be expressed in the coordinate space produced by `first` — that is, the two must be
+ * consecutive steps of the same document. The returned step maps the document from before `first`
+ * to after `second`, and the returned inverse maps it back, so the result is safe to use both on
+ * the wire and as a rebase buffer entry.
+ *
+ * Returns `null` whenever the steps do not overlap, or when the merge cannot be proven exact. A
+ * `null` result always means "keep the two steps as they are", never "the steps are equivalent to
+ * nothing".
+ *
+ * @param first The earlier step and its inverse.
+ * @param second The later step and its inverse.
+ * @param docBefore The document `first` applies to. Optional, but without it only ProseMirror's own
+ * adjacent-step merges can be resolved, because the composed slice otherwise has to be cut out of a
+ * real document. Callers lose it when the queue has been rebased over a remote step.
+ */
+export function mergeOverlappingSteps(first, second, docBefore) {
+  var firstStep = asPlainReplaceStep(first.step);
+  var secondStep = asPlainReplaceStep(second.step);
+
+  // Non-plain replaces are only ever merged by ProseMirror itself, which knows the rules for them.
+  if (!firstStep || !secondStep) {
+    return mergeNatively(first, second);
+  }
+  if (!overlaps(firstStep, secondStep)) {
+    return null;
+  }
+
+  // Try the O(1) strategy before the one that has to replay both steps against a document.
+  // `transformUnconfirmed` runs on every transaction, and adjacent insertions — which is what
+  // consecutive streaming frames often are — are exactly what ProseMirror merges natively.
+  var natively = mergeNatively(first, second);
+  if (natively) {
+    return natively;
+  }
+
+  // Anything else needs the document to cut the composed slice out of, so without one there is
+  // no merge that can be proven exact.
+  return docBefore ? mergeViaDocument(first, second, docBefore) : null;
+}

package/dist/esm/pm-plugins/track-steps.js

@@ -1,14 +1,7 @@
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
-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; }
-// delete this file when cleaning up platform_editor_remove_collab_step_metrics
-import { AnalyticsStep } from '@atlaskit/adf-schema/steps/analytics';
 import { BatchAttrsStep } from '@atlaskit/adf-schema/steps/batch-attrs-step';
 import { SetAttrsStep } from '@atlaskit/adf-schema/steps/set-attrs';
 import { AddMarkStep, AddNodeMarkStep, AttrStep, DocAttrStep, RemoveMarkStep, RemoveNodeMarkStep } from '@atlaskit/editor-prosemirror/transform';
-import { sendableSteps } from '@atlaskit/prosemirror-collab';
-import { updateNcsSessionStepMetrics } from './track-step-metrics';
 function groupBy(array, keyGetter) {
   // Check group by exists, and that it's a function. If so, use the native browser code
   if ('groupBy' in Object && typeof Object.groupBy === 'function') {
@@ -92,101 +85,4 @@ export var groupSteps = function groupSteps(sanitizedSteps) {
     acc[key] = Array.isArray(value) ? value.length : 0;
     return acc;
   }, {});
-};
-
-/**
- * Processes the steps metadata from the cache and calls the callback function with the processed data.
- *
- * @param {CacheType} cache - A cache containing steps metadata.
- * @param {(data: StepMetadataAnalytics[]) => void} onTrackDataProcessed - Callback function to be called with the processed data.
- */
-export var task = function task(cache, onTrackDataProcessed) {
-  var stepsMetadata = [];
-  var _iterator = _createForOfIteratorHelper(cache.values()),
-    _step;
-  try {
-    for (_iterator.s(); !(_step = _iterator.n()).done;) {
-      var entry = _step.value;
-      var startedAt = entry.startedAt,
-        endedAt = entry.endedAt,
-        steps = entry.steps;
-      var stepTypesAmount = groupSteps(steps.map(sanitizeStep));
-      stepsMetadata.push({
-        startedAt: startedAt,
-        endedAt: endedAt,
-        stepTypesAmount: stepTypesAmount
-      });
-    }
-  } catch (err) {
-    _iterator.e(err);
-  } finally {
-    _iterator.f();
-  }
-  cache.clear();
-  if (stepsMetadata.length > 0) {
-    onTrackDataProcessed(stepsMetadata);
-  }
-};
-var stepsSentCache = new Map();
-// Every ten seconds we will try to process the step data.
-var LOW_PRIORITY_DELAY = 10000;
-
-// See https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/
-
-var getScheduler = function getScheduler(obj) {
-  if (!obj) {
-    return null;
-  }
-  if ('scheduler' in obj) {
-    return obj.scheduler;
-  }
-  return null;
-};
-
-/**
- * Tracks the steps sent by the client by storing them in a cache and scheduling a task to process them. Once the steps are processed, the onTrackDataProcessed callabck will be called.
- *
- * This is a non-critical code. If the browser doesn't support the Scheduler API https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/
- *
- * @param {TrackProps} props - The properties required for tracking steps.
- * @param {ExtractInjectionAPI<CollabEditPlugin> | undefined} props.api - The API for the CollabEdit plugin.
- * @param {EditorState} props.newEditorState - The new editor state.
- * @param {Readonly<Transaction[]>} props.transactions - The transactions that contain the steps.
- * @param {(data: StepMetadataAnalytics[]) => void} props.onTrackDataProcessed - Callback function to be called with the processed data.
- */
-export var track = function track(_ref4) {
-  var api = _ref4.api,
-    newEditorState = _ref4.newEditorState,
-    transactions = _ref4.transactions,
-    onTrackDataProcessed = _ref4.onTrackDataProcessed;
-  var newSteps = transactions.flatMap(function (t) {
-    return t.steps;
-  });
-  var collabState = sendableSteps(newEditorState);
-  var scheduler = getScheduler(window);
-  if (!newSteps.length || !scheduler || !collabState) {
-    return;
-  }
-  var version = collabState.version;
-  var buffer = stepsSentCache.get(version);
-  var startedAt = (buffer === null || buffer === void 0 ? void 0 : buffer.startedAt) || Date.now();
-  var endedAt = Date.now();
-  var steps = ((buffer === null || buffer === void 0 ? void 0 : buffer.steps) || []).concat(newSteps);
-  stepsSentCache.set(version, {
-    startedAt: startedAt,
-    endedAt: endedAt,
-    steps: steps
-  });
-  updateNcsSessionStepMetrics({
-    api: api,
-    steps: newSteps.filter(function (step) {
-      return !(step instanceof AnalyticsStep);
-    })
-  });
-  scheduler.postTask(function () {
-    task(stepsSentCache, onTrackDataProcessed);
-  }, {
-    priority: 'background',
-    delay: LOW_PRIORITY_DELAY
-  });
 };

package/dist/types/pm-plugins/collabSendHold.d.ts

@@ -0,0 +1,51 @@
+import type { Transaction } from '@atlaskit/editor-prosemirror/state';
+/**
+ * Upper bound on how long the send may stay held, measured from the transaction that *started* the
+ * hold rather than the most recent one.
+ *
+ * This is the only time bound on the hold. Producers decide when to release on semantic grounds —
+ * a completed block, the end of a stream — and this bounds how long that can take. It therefore
+ * doubles as the guarantee that a producer which never releases, because it aborted or threw
+ * between hold and release, cannot stop the editor sending for the rest of the session.
+ */
+export declare const MAX_SEND_HOLD_MS = 2000;
+export type CollabSendHold = {
+    /**
+     * Whether the flush is currently held. Reads the clock, so a hold that has outlived
+     * {@link MAX_SEND_HOLD_MS} reports as released without needing a transaction to clear it.
+     */
+    isHeld: (now?: number) => boolean;
+    /**
+     * Feed every transaction through this. Transactions that carry no {@link DEFER_COLLAB_SEND}
+     * metadata leave the hold untouched — that is the whole point of the hold being sticky rather
+     * than per-transaction.
+     */
+    observe: (transaction: Readonly<Transaction>, now?: number) => void;
+};
+/**
+ * Tracks whether sending to the collab service is currently held back.
+ *
+ * A producer that streams into the document needs several of its transactions to accumulate in the
+ * unconfirmed queue before anything is sent, so they can be composed into one step. Marking only
+ * the producer's own transactions is not enough: `sendTransaction` runs for *every* state update,
+ * and `provider.send` flushes and locks the entire queue regardless of which transaction triggered
+ * it. Acknowledgements from previous commits, remote steps, selection changes and the user's own
+ * typing all trigger it.
+ *
+ * So the hold has to be a state that spans transactions rather than a flag on one:
+ *
+ * - `tr.setMeta(DEFER_COLLAB_SEND, true)` starts the hold, and does *not* extend one already in
+ *   progress
+ * - `tr.setMeta(DEFER_COLLAB_SEND, false)` releases it
+ * - anything else leaves it as it is
+ *
+ * Not extending matters. A producer marks every frame it wants held, so re-arming on each one
+ * would push the deadline back indefinitely and the bound would never be reached during an active
+ * stream. Measuring from the first held transaction instead makes the hold flush at least every
+ * {@link MAX_SEND_HOLD_MS}, with the next held frame starting a fresh window.
+ *
+ * While held, nothing is sent. Note this includes the local user's own edits: `sendableSteps`
+ * returns the queue in version order, so there is no way to send a step that sits behind held
+ * steps. Producers should keep hold windows short for that reason.
+ */
+export declare const createCollabSendHold: () => CollabSendHold;

package/dist/types/pm-plugins/collapseStreamingSteps.d.ts

@@ -0,0 +1,18 @@
+import { Rebaseable } from '@atlaskit/prosemirror-collab';
+/**
+ * Compose adjacent streaming frames in the unconfirmed queue so the collab service receives one
+ * step per flush instead of one step per rendered chunk.
+ *
+ * This runs in the collab plugin's `transformUnconfirmed` hook, which fires *after* each frame has
+ * already been applied to the document. Collapsing therefore has no effect on what the local user
+ * sees, on undo history, or on any other plugin state — it only changes what is sent to the collab
+ * service, and what is used as the rebase buffer when remote steps arrive.
+ *
+ * Because the unconfirmed steps double as the rebase buffer (`rebaseSteps` applies their inverses
+ * to the live document), the composition must be exact. `mergeOverlappingSteps` only returns a
+ * merge it can prove exact, and this function degrades to a no-op whenever it declines.
+ *
+ * @param steps Rebaseable steps
+ * @returns Rebaseable steps, with adjacent streaming frames composed
+ */
+export declare function collapseStreamingSteps(steps: Rebaseable[]): Rebaseable[];

package/dist/types/pm-plugins/events/send-transaction.d.ts

@@ -3,6 +3,12 @@ import type { ViewMode } from '@atlaskit/editor-plugin-editor-viewmode';
 import type { EditorState, Transaction } from '@atlaskit/editor-prosemirror/state';
 type Props = {
     hideTelecursorOnLoad: boolean;
+    /**
+     * When true the flush to the collab service is skipped for this state update. See
+     * `createCollabSendHold` — the hold spans transactions, so this is not derived from
+     * `originalTransaction` alone.
+     */
+    isSendHeld?: boolean;
     newEditorState: EditorState;
     oldEditorState: EditorState;
     originalTransaction: Readonly<Transaction>;
@@ -10,5 +16,5 @@ type Props = {
     useNativePlugin: boolean;
     viewMode?: ViewMode;
 };
-export declare const sendTransaction: ({ originalTransaction, transactions, oldEditorState, newEditorState, useNativePlugin, viewMode, hideTelecursorOnLoad, }: Props) => (provider: CollabEditProvider) => void;
+export declare const sendTransaction: ({ originalTransaction, transactions, oldEditorState, newEditorState, useNativePlugin, viewMode, hideTelecursorOnLoad, isSendHeld, }: Props) => (provider: CollabEditProvider) => void;
 export {};

package/dist/types/pm-plugins/mergeOverlappingSteps.d.ts

@@ -0,0 +1,28 @@
+import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
+import type { Step } from '@atlaskit/editor-prosemirror/transform-override';
+/**
+ * A step paired with its inverse, as stored in the collab unconfirmed queue.
+ */
+export type MergeableStep = {
+    inverted: Step;
+    step: Step;
+};
+/**
+ * Merge two consecutive steps into the single step they are collectively equivalent to.
+ *
+ * `second` must be expressed in the coordinate space produced by `first` — that is, the two must be
+ * consecutive steps of the same document. The returned step maps the document from before `first`
+ * to after `second`, and the returned inverse maps it back, so the result is safe to use both on
+ * the wire and as a rebase buffer entry.
+ *
+ * Returns `null` whenever the steps do not overlap, or when the merge cannot be proven exact. A
+ * `null` result always means "keep the two steps as they are", never "the steps are equivalent to
+ * nothing".
+ *
+ * @param first The earlier step and its inverse.
+ * @param second The later step and its inverse.
+ * @param docBefore The document `first` applies to. Optional, but without it only ProseMirror's own
+ * adjacent-step merges can be resolved, because the composed slice otherwise has to be cut out of a
+ * real document. Callers lose it when the queue has been rebased over a remote step.
+ */
+export declare function mergeOverlappingSteps(first: MergeableStep, second: MergeableStep, docBefore?: PMNode): MergeableStep | null;

package/dist/types/pm-plugins/track-steps.d.ts

@@ -1,19 +1,9 @@
-import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
-import type { EditorState, Transaction } from '@atlaskit/editor-prosemirror/state';
 import type { Step } from '@atlaskit/editor-prosemirror/transform-override';
-import type { CollabEditPlugin } from '../collabEditPluginType';
 export type SanitizedStep = {
     attr?: string;
     markType?: string;
     stepType: string;
 };
-export type StepMetadataAnalytics = {
-    endedAt: number;
-    startedAt: number;
-    stepTypesAmount: {
-        [key: string]: number;
-    };
-};
 /**
  * Sanitizes a given ProseMirror step by extracting its type and non-UCG relevant attributes.
  *
@@ -48,34 +38,3 @@ export declare const sanitizeStep: (step: Step) => SanitizedStep;
  * ```
  */
 export declare const groupSteps: (sanitizedSteps: SanitizedStep[]) => Record<string, number>;
-/**
- * Processes the steps metadata from the cache and calls the callback function with the processed data.
- *
- * @param {CacheType} cache - A cache containing steps metadata.
- * @param {(data: StepMetadataAnalytics[]) => void} onTrackDataProcessed - Callback function to be called with the processed data.
- */
-export declare const task: (cache: CacheType, onTrackDataProcessed: (data: StepMetadataAnalytics[]) => void) => void;
-export type CacheType = Map<number, {
-    endedAt: number;
-    startedAt: number;
-    steps: ReadonlyArray<Step>;
-}>;
-type TrackProps = {
-    api: ExtractInjectionAPI<CollabEditPlugin> | undefined;
-    newEditorState: EditorState;
-    onTrackDataProcessed: (data: StepMetadataAnalytics[]) => void;
-    transactions: Readonly<Transaction[]>;
-};
-/**
- * Tracks the steps sent by the client by storing them in a cache and scheduling a task to process them. Once the steps are processed, the onTrackDataProcessed callabck will be called.
- *
- * This is a non-critical code. If the browser doesn't support the Scheduler API https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/
- *
- * @param {TrackProps} props - The properties required for tracking steps.
- * @param {ExtractInjectionAPI<CollabEditPlugin> | undefined} props.api - The API for the CollabEdit plugin.
- * @param {EditorState} props.newEditorState - The new editor state.
- * @param {Readonly<Transaction[]>} props.transactions - The transactions that contain the steps.
- * @param {(data: StepMetadataAnalytics[]) => void} props.onTrackDataProcessed - Callback function to be called with the processed data.
- */
-export declare const track: ({ api, newEditorState, transactions, onTrackDataProcessed, }: TrackProps) => void;
-export {};