@atlaskit/editor-plugin-collab-edit 9.0.20 → 9.0.22

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @atlaskit/editor-plugin-collab-edit
 
+## 9.0.22
+
+### Patch Changes
+
+- Updated dependencies
+
+## 9.0.21
+
+### Patch Changes
+
+- [`f8922537e5ec8`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f8922537e5ec8) -
+  Preserve node referential identity in replaceDocument to prevent ProseMirror view reconciliation
+  from unnecessarily destroying and recreating mark wrappers (and their React nodeviews), which
+  caused visible flicker on sync blocks and other wrapped nodeviews during collab initialization.
+
+  Fixes EDITOR-5277.
+
+- Updated dependencies
+
 ## 9.0.20
 
 ### Patch Changes

package/dist/cjs/pm-plugins/preserve-node-identity.js

@@ -0,0 +1,91 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.preserveNodeIdentity = preserveNodeIdentity;
+var _model = require("@atlaskit/editor-prosemirror/model");
+var _expValEquals = require("@atlaskit/tmp-editor-statsig/exp-val-equals");
+/**
+ * Walk two Fragments (old and new) and return a Fragment that reuses old node
+ * references wherever structurally equal (`node.eq()` returns true).
+ *
+ * This preserves referential identity (`===`) for unchanged subtrees, which is
+ * critical for ProseMirror's view reconciliation performance. The `preMatch`
+ * optimisation in `prosemirror-view/src/viewdesc.ts` uses `===` to fast-match
+ * nodes against existing view descriptors. When all nodes are fresh objects
+ * (e.g. after `Node.fromJSON` in `replaceDocument`), `preMatch` fails for
+ * everything, and the fallback scan in `syncToMarks` is limited to 3
+ * positions — causing mark wrappers to be destroyed and recreated when widget
+ * decorations (gap cursor, telepointers, block controls) shift indices beyond
+ * that window. The destroyed mark wrappers take their React nodeviews with
+ * them, causing visible flicker.
+ *
+ * By preserving identity here, we ensure `preMatch` succeeds for unchanged
+ * subtrees, preventing unnecessary mark wrapper destruction and React nodeview
+ * re-mounting.
+ *
+ * @param oldFragment - Fragment from the current editor state (holds existing node references)
+ * @param newFragment - Fragment parsed from incoming document (fresh node objects)
+ * @returns A Fragment that reuses old node references where possible
+ *
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-5277
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-4424
+ */
+function preserveNodeIdentity(oldFragment, newFragment) {
+  // Fast path: referentially identical — nothing to do
+  if (oldFragment === newFragment) {
+    return oldFragment;
+  }
+
+  // Fast path: structurally equal — reuse old fragment entirely.
+  // This covers the common SSR case where collab init sends the same doc.
+  if (oldFragment.eq(newFragment)) {
+    return oldFragment;
+  }
+
+  // Walk children position-by-position and preserve what we can
+  var oldCount = oldFragment.childCount;
+  var newCount = newFragment.childCount;
+  var changed = false;
+  var children = [];
+  for (var i = 0; i < newCount; i++) {
+    var newChild = newFragment.child(i);
+    if (i < oldCount) {
+      var oldChild = oldFragment.child(i);
+      if (oldChild === newChild) {
+        // Already referentially identical
+        children.push(newChild);
+      } else if (oldChild.eq(newChild)) {
+        // Structurally equal — reuse old reference (THE KEY OPERATION)
+        children.push(oldChild);
+      } else if (oldChild.type === newChild.type && oldChild.sameMarkup(newChild) && oldChild.content.childCount > 0 && newChild.content.childCount > 0 && (0, _expValEquals.expValEquals)('platform_editor_preserve_node_identity', 'isRecursive', true)) {
+        // Same type and markup but different content — recurse into children
+        var preservedContent = preserveNodeIdentity(oldChild.content, newChild.content);
+        if (preservedContent === oldChild.content) {
+          // All content was preserved — reuse old node entirely
+          children.push(oldChild);
+        } else {
+          // Partially changed — create node with preserved content
+          children.push(oldChild.copy(preservedContent));
+          changed = true;
+        }
+      } else {
+        // Completely different node — use new
+        children.push(newChild);
+        changed = true;
+      }
+    } else {
+      // New child beyond old count — use as-is (insertion)
+      children.push(newChild);
+      changed = true;
+    }
+  }
+
+  // If nothing changed and counts match, return old fragment directly
+  // (avoids creating a new Fragment object)
+  if (!changed && oldCount === newCount) {
+    return oldFragment;
+  }
+  return _model.Fragment.from(children);
+}

package/dist/cjs/pm-plugins/utils.js

@@ -17,6 +17,8 @@ var _state = require("@atlaskit/editor-prosemirror/state");
 var _transform = require("@atlaskit/editor-prosemirror/transform");
 var _view = require("@atlaskit/editor-prosemirror/view");
 var _editorSharedStyles = require("@atlaskit/editor-shared-styles");
+var _experiments = require("@atlaskit/tmp-editor-statsig/experiments");
+var _preserveNodeIdentity = require("./preserve-node-identity");
 var findPointers = exports.findPointers = function findPointers(id, decorations) {
   return decorations.find().reduce(function (arr, deco) {
     return deco.spec.pointer.presenceId === id ? arr.concat(deco) : arr;
@@ -110,15 +112,33 @@ var replaceDocument = exports.replaceDocument = function replaceDocument(doc, st
   var parsedDoc = (0, _processRawValue.processRawValueWithoutValidation)(schema, doc, editorAnalyticsAPI === null || editorAnalyticsAPI === void 0 ? void 0 : editorAnalyticsAPI.fireAnalyticsEvent);
   var hasContent = !!(parsedDoc !== null && parsedDoc !== void 0 && parsedDoc.childCount);
   var content = parsedDoc === null || parsedDoc === void 0 ? void 0 : parsedDoc.content;
-  if (hasContent) {
+  if (hasContent && content && (0, _experiments.editorExperiment)('platform_editor_preserve_node_identity', true, {
+    exposure: true
+  })) {
+    var preservedContent = (0, _preserveNodeIdentity.preserveNodeIdentity)(state.doc.content, content);
+
+    // If the entire content is identical, skip the replaceWith entirely
+    // and just update collab metadata. This avoids triggering a full
+    // document reconciliation for no-op replacements.
+    if (preservedContent === state.doc.content) {
+      tr.setMeta('addToHistory', false);
+      if (version !== undefined && options && options.useNativePlugin) {
+        var collabState = {
+          version: version,
+          unconfirmed: []
+        };
+        tr.setMeta('collab$', collabState);
+      }
+      return tr;
+    }
+
+    // Use the preserved fragment (reuses old node references for unchanged nodes)
+    // rather than the raw parsed content, so ProseMirror's view reconciliation
+    // can fast-match unchanged subtrees via referential identity (===).
     tr.setMeta('addToHistory', false);
-    // Ignored via go/ees005
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    tr.replaceWith(0, state.doc.nodeSize - 2, content);
+    tr.replaceWith(0, state.doc.nodeSize - 2, preservedContent);
     var selection = state.selection;
     if (reserveCursor) {
-      // If the cursor is still in the range of the new document,
-      // keep where it was.
       if (selection.to < tr.doc.content.size - 2) {
         var $from = tr.doc.resolve(selection.from);
         var $to = tr.doc.resolve(selection.to);
@@ -129,12 +149,40 @@ var replaceDocument = exports.replaceDocument = function replaceDocument(doc, st
       tr.setSelection(_state.Selection.atStart(tr.doc));
     }
     tr.setMeta('replaceDocument', true);
+    if (version !== undefined && options && options.useNativePlugin) {
+      var _collabState = {
+        version: version,
+        unconfirmed: []
+      };
+      tr.setMeta('collab$', _collabState);
+    }
+    return tr;
+  }
+  if (hasContent) {
+    tr.setMeta('addToHistory', false);
+    // Ignored via go/ees005
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    tr.replaceWith(0, state.doc.nodeSize - 2, content);
+    var _selection = state.selection;
+    if (reserveCursor) {
+      // If the cursor is still in the range of the new document,
+      // keep where it was.
+      if (_selection.to < tr.doc.content.size - 2) {
+        var _$from = tr.doc.resolve(_selection.from);
+        var _$to = tr.doc.resolve(_selection.to);
+        var _newselection = new _state.TextSelection(_$from, _$to);
+        tr.setSelection(_newselection);
+      }
+    } else {
+      tr.setSelection(_state.Selection.atStart(tr.doc));
+    }
+    tr.setMeta('replaceDocument', true);
     if ((0, _typeof2.default)(version) !== undefined && options && options.useNativePlugin) {
-      var collabState = {
+      var _collabState2 = {
         version: version,
         unconfirmed: []
       };
-      tr.setMeta('collab$', collabState);
+      tr.setMeta('collab$', _collabState2);
     }
   }
   return tr;

package/dist/es2019/pm-plugins/preserve-node-identity.js

@@ -0,0 +1,86 @@
+import { Fragment } from '@atlaskit/editor-prosemirror/model';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
+
+/**
+ * Walk two Fragments (old and new) and return a Fragment that reuses old node
+ * references wherever structurally equal (`node.eq()` returns true).
+ *
+ * This preserves referential identity (`===`) for unchanged subtrees, which is
+ * critical for ProseMirror's view reconciliation performance. The `preMatch`
+ * optimisation in `prosemirror-view/src/viewdesc.ts` uses `===` to fast-match
+ * nodes against existing view descriptors. When all nodes are fresh objects
+ * (e.g. after `Node.fromJSON` in `replaceDocument`), `preMatch` fails for
+ * everything, and the fallback scan in `syncToMarks` is limited to 3
+ * positions — causing mark wrappers to be destroyed and recreated when widget
+ * decorations (gap cursor, telepointers, block controls) shift indices beyond
+ * that window. The destroyed mark wrappers take their React nodeviews with
+ * them, causing visible flicker.
+ *
+ * By preserving identity here, we ensure `preMatch` succeeds for unchanged
+ * subtrees, preventing unnecessary mark wrapper destruction and React nodeview
+ * re-mounting.
+ *
+ * @param oldFragment - Fragment from the current editor state (holds existing node references)
+ * @param newFragment - Fragment parsed from incoming document (fresh node objects)
+ * @returns A Fragment that reuses old node references where possible
+ *
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-5277
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-4424
+ */
+export function preserveNodeIdentity(oldFragment, newFragment) {
+  // Fast path: referentially identical — nothing to do
+  if (oldFragment === newFragment) {
+    return oldFragment;
+  }
+
+  // Fast path: structurally equal — reuse old fragment entirely.
+  // This covers the common SSR case where collab init sends the same doc.
+  if (oldFragment.eq(newFragment)) {
+    return oldFragment;
+  }
+
+  // Walk children position-by-position and preserve what we can
+  const oldCount = oldFragment.childCount;
+  const newCount = newFragment.childCount;
+  let changed = false;
+  const children = [];
+  for (let i = 0; i < newCount; i++) {
+    const newChild = newFragment.child(i);
+    if (i < oldCount) {
+      const oldChild = oldFragment.child(i);
+      if (oldChild === newChild) {
+        // Already referentially identical
+        children.push(newChild);
+      } else if (oldChild.eq(newChild)) {
+        // Structurally equal — reuse old reference (THE KEY OPERATION)
+        children.push(oldChild);
+      } else if (oldChild.type === newChild.type && oldChild.sameMarkup(newChild) && oldChild.content.childCount > 0 && newChild.content.childCount > 0 && expValEquals('platform_editor_preserve_node_identity', 'isRecursive', true)) {
+        // Same type and markup but different content — recurse into children
+        const preservedContent = preserveNodeIdentity(oldChild.content, newChild.content);
+        if (preservedContent === oldChild.content) {
+          // All content was preserved — reuse old node entirely
+          children.push(oldChild);
+        } else {
+          // Partially changed — create node with preserved content
+          children.push(oldChild.copy(preservedContent));
+          changed = true;
+        }
+      } else {
+        // Completely different node — use new
+        children.push(newChild);
+        changed = true;
+      }
+    } else {
+      // New child beyond old count — use as-is (insertion)
+      children.push(newChild);
+      changed = true;
+    }
+  }
+
+  // If nothing changed and counts match, return old fragment directly
+  // (avoids creating a new Fragment object)
+  if (!changed && oldCount === newCount) {
+    return oldFragment;
+  }
+  return Fragment.from(children);
+}

package/dist/es2019/pm-plugins/utils.js

@@ -7,6 +7,8 @@ import { Transaction, Selection, TextSelection } from '@atlaskit/editor-prosemir
 import { AttrStep, ReplaceStep } from '@atlaskit/editor-prosemirror/transform';
 import { Decoration } from '@atlaskit/editor-prosemirror/view';
 import { getParticipantColor } from '@atlaskit/editor-shared-styles';
+import { editorExperiment } from '@atlaskit/tmp-editor-statsig/experiments';
+import { preserveNodeIdentity } from './preserve-node-identity';
 export const findPointers = (id, decorations) => decorations.find().reduce((arr, deco) => deco.spec.pointer.presenceId === id ? arr.concat(deco) : arr, []);
 function style(options) {
   const color = options && options.color || "var(--ds-border, #0B120E24)";
@@ -98,6 +100,52 @@ export const replaceDocument = (doc, state, version, options, reserveCursor, edi
   const parsedDoc = processRawValueWithoutValidation(schema, doc, editorAnalyticsAPI === null || editorAnalyticsAPI === void 0 ? void 0 : editorAnalyticsAPI.fireAnalyticsEvent);
   const hasContent = !!(parsedDoc !== null && parsedDoc !== void 0 && parsedDoc.childCount);
   const content = parsedDoc === null || parsedDoc === void 0 ? void 0 : parsedDoc.content;
+  if (hasContent && content && editorExperiment('platform_editor_preserve_node_identity', true, {
+    exposure: true
+  })) {
+    const preservedContent = preserveNodeIdentity(state.doc.content, content);
+
+    // If the entire content is identical, skip the replaceWith entirely
+    // and just update collab metadata. This avoids triggering a full
+    // document reconciliation for no-op replacements.
+    if (preservedContent === state.doc.content) {
+      tr.setMeta('addToHistory', false);
+      if (version !== undefined && options && options.useNativePlugin) {
+        const collabState = {
+          version,
+          unconfirmed: []
+        };
+        tr.setMeta('collab$', collabState);
+      }
+      return tr;
+    }
+
+    // Use the preserved fragment (reuses old node references for unchanged nodes)
+    // rather than the raw parsed content, so ProseMirror's view reconciliation
+    // can fast-match unchanged subtrees via referential identity (===).
+    tr.setMeta('addToHistory', false);
+    tr.replaceWith(0, state.doc.nodeSize - 2, preservedContent);
+    const selection = state.selection;
+    if (reserveCursor) {
+      if (selection.to < tr.doc.content.size - 2) {
+        const $from = tr.doc.resolve(selection.from);
+        const $to = tr.doc.resolve(selection.to);
+        const newselection = new TextSelection($from, $to);
+        tr.setSelection(newselection);
+      }
+    } else {
+      tr.setSelection(Selection.atStart(tr.doc));
+    }
+    tr.setMeta('replaceDocument', true);
+    if (version !== undefined && options && options.useNativePlugin) {
+      const collabState = {
+        version,
+        unconfirmed: []
+      };
+      tr.setMeta('collab$', collabState);
+    }
+    return tr;
+  }
   if (hasContent) {
     tr.setMeta('addToHistory', false);
     // Ignored via go/ees005

package/dist/esm/pm-plugins/preserve-node-identity.js

@@ -0,0 +1,86 @@
+import { Fragment } from '@atlaskit/editor-prosemirror/model';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
+
+/**
+ * Walk two Fragments (old and new) and return a Fragment that reuses old node
+ * references wherever structurally equal (`node.eq()` returns true).
+ *
+ * This preserves referential identity (`===`) for unchanged subtrees, which is
+ * critical for ProseMirror's view reconciliation performance. The `preMatch`
+ * optimisation in `prosemirror-view/src/viewdesc.ts` uses `===` to fast-match
+ * nodes against existing view descriptors. When all nodes are fresh objects
+ * (e.g. after `Node.fromJSON` in `replaceDocument`), `preMatch` fails for
+ * everything, and the fallback scan in `syncToMarks` is limited to 3
+ * positions — causing mark wrappers to be destroyed and recreated when widget
+ * decorations (gap cursor, telepointers, block controls) shift indices beyond
+ * that window. The destroyed mark wrappers take their React nodeviews with
+ * them, causing visible flicker.
+ *
+ * By preserving identity here, we ensure `preMatch` succeeds for unchanged
+ * subtrees, preventing unnecessary mark wrapper destruction and React nodeview
+ * re-mounting.
+ *
+ * @param oldFragment - Fragment from the current editor state (holds existing node references)
+ * @param newFragment - Fragment parsed from incoming document (fresh node objects)
+ * @returns A Fragment that reuses old node references where possible
+ *
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-5277
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-4424
+ */
+export function preserveNodeIdentity(oldFragment, newFragment) {
+  // Fast path: referentially identical — nothing to do
+  if (oldFragment === newFragment) {
+    return oldFragment;
+  }
+
+  // Fast path: structurally equal — reuse old fragment entirely.
+  // This covers the common SSR case where collab init sends the same doc.
+  if (oldFragment.eq(newFragment)) {
+    return oldFragment;
+  }
+
+  // Walk children position-by-position and preserve what we can
+  var oldCount = oldFragment.childCount;
+  var newCount = newFragment.childCount;
+  var changed = false;
+  var children = [];
+  for (var i = 0; i < newCount; i++) {
+    var newChild = newFragment.child(i);
+    if (i < oldCount) {
+      var oldChild = oldFragment.child(i);
+      if (oldChild === newChild) {
+        // Already referentially identical
+        children.push(newChild);
+      } else if (oldChild.eq(newChild)) {
+        // Structurally equal — reuse old reference (THE KEY OPERATION)
+        children.push(oldChild);
+      } else if (oldChild.type === newChild.type && oldChild.sameMarkup(newChild) && oldChild.content.childCount > 0 && newChild.content.childCount > 0 && expValEquals('platform_editor_preserve_node_identity', 'isRecursive', true)) {
+        // Same type and markup but different content — recurse into children
+        var preservedContent = preserveNodeIdentity(oldChild.content, newChild.content);
+        if (preservedContent === oldChild.content) {
+          // All content was preserved — reuse old node entirely
+          children.push(oldChild);
+        } else {
+          // Partially changed — create node with preserved content
+          children.push(oldChild.copy(preservedContent));
+          changed = true;
+        }
+      } else {
+        // Completely different node — use new
+        children.push(newChild);
+        changed = true;
+      }
+    } else {
+      // New child beyond old count — use as-is (insertion)
+      children.push(newChild);
+      changed = true;
+    }
+  }
+
+  // If nothing changed and counts match, return old fragment directly
+  // (avoids creating a new Fragment object)
+  if (!changed && oldCount === newCount) {
+    return oldFragment;
+  }
+  return Fragment.from(children);
+}

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

@@ -8,6 +8,8 @@ import { Transaction, Selection, TextSelection } from '@atlaskit/editor-prosemir
 import { AttrStep, ReplaceStep } from '@atlaskit/editor-prosemirror/transform';
 import { Decoration } from '@atlaskit/editor-prosemirror/view';
 import { getParticipantColor } from '@atlaskit/editor-shared-styles';
+import { editorExperiment } from '@atlaskit/tmp-editor-statsig/experiments';
+import { preserveNodeIdentity } from './preserve-node-identity';
 export var findPointers = function findPointers(id, decorations) {
   return decorations.find().reduce(function (arr, deco) {
     return deco.spec.pointer.presenceId === id ? arr.concat(deco) : arr;
@@ -101,15 +103,33 @@ export var replaceDocument = function replaceDocument(doc, state, version, optio
   var parsedDoc = processRawValueWithoutValidation(schema, doc, editorAnalyticsAPI === null || editorAnalyticsAPI === void 0 ? void 0 : editorAnalyticsAPI.fireAnalyticsEvent);
   var hasContent = !!(parsedDoc !== null && parsedDoc !== void 0 && parsedDoc.childCount);
   var content = parsedDoc === null || parsedDoc === void 0 ? void 0 : parsedDoc.content;
-  if (hasContent) {
+  if (hasContent && content && editorExperiment('platform_editor_preserve_node_identity', true, {
+    exposure: true
+  })) {
+    var preservedContent = preserveNodeIdentity(state.doc.content, content);
+
+    // If the entire content is identical, skip the replaceWith entirely
+    // and just update collab metadata. This avoids triggering a full
+    // document reconciliation for no-op replacements.
+    if (preservedContent === state.doc.content) {
+      tr.setMeta('addToHistory', false);
+      if (version !== undefined && options && options.useNativePlugin) {
+        var collabState = {
+          version: version,
+          unconfirmed: []
+        };
+        tr.setMeta('collab$', collabState);
+      }
+      return tr;
+    }
+
+    // Use the preserved fragment (reuses old node references for unchanged nodes)
+    // rather than the raw parsed content, so ProseMirror's view reconciliation
+    // can fast-match unchanged subtrees via referential identity (===).
     tr.setMeta('addToHistory', false);
-    // Ignored via go/ees005
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    tr.replaceWith(0, state.doc.nodeSize - 2, content);
+    tr.replaceWith(0, state.doc.nodeSize - 2, preservedContent);
     var selection = state.selection;
     if (reserveCursor) {
-      // If the cursor is still in the range of the new document,
-      // keep where it was.
       if (selection.to < tr.doc.content.size - 2) {
         var $from = tr.doc.resolve(selection.from);
         var $to = tr.doc.resolve(selection.to);
@@ -120,12 +140,40 @@ export var replaceDocument = function replaceDocument(doc, state, version, optio
       tr.setSelection(Selection.atStart(tr.doc));
     }
     tr.setMeta('replaceDocument', true);
+    if (version !== undefined && options && options.useNativePlugin) {
+      var _collabState = {
+        version: version,
+        unconfirmed: []
+      };
+      tr.setMeta('collab$', _collabState);
+    }
+    return tr;
+  }
+  if (hasContent) {
+    tr.setMeta('addToHistory', false);
+    // Ignored via go/ees005
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    tr.replaceWith(0, state.doc.nodeSize - 2, content);
+    var _selection = state.selection;
+    if (reserveCursor) {
+      // If the cursor is still in the range of the new document,
+      // keep where it was.
+      if (_selection.to < tr.doc.content.size - 2) {
+        var _$from = tr.doc.resolve(_selection.from);
+        var _$to = tr.doc.resolve(_selection.to);
+        var _newselection = new TextSelection(_$from, _$to);
+        tr.setSelection(_newselection);
+      }
+    } else {
+      tr.setSelection(Selection.atStart(tr.doc));
+    }
+    tr.setMeta('replaceDocument', true);
     if (_typeof(version) !== undefined && options && options.useNativePlugin) {
-      var collabState = {
+      var _collabState2 = {
         version: version,
         unconfirmed: []
       };
-      tr.setMeta('collab$', collabState);
+      tr.setMeta('collab$', _collabState2);
     }
   }
   return tr;

package/dist/types/pm-plugins/preserve-node-identity.d.ts

@@ -0,0 +1,28 @@
+import { Fragment } from '@atlaskit/editor-prosemirror/model';
+/**
+ * Walk two Fragments (old and new) and return a Fragment that reuses old node
+ * references wherever structurally equal (`node.eq()` returns true).
+ *
+ * This preserves referential identity (`===`) for unchanged subtrees, which is
+ * critical for ProseMirror's view reconciliation performance. The `preMatch`
+ * optimisation in `prosemirror-view/src/viewdesc.ts` uses `===` to fast-match
+ * nodes against existing view descriptors. When all nodes are fresh objects
+ * (e.g. after `Node.fromJSON` in `replaceDocument`), `preMatch` fails for
+ * everything, and the fallback scan in `syncToMarks` is limited to 3
+ * positions — causing mark wrappers to be destroyed and recreated when widget
+ * decorations (gap cursor, telepointers, block controls) shift indices beyond
+ * that window. The destroyed mark wrappers take their React nodeviews with
+ * them, causing visible flicker.
+ *
+ * By preserving identity here, we ensure `preMatch` succeeds for unchanged
+ * subtrees, preventing unnecessary mark wrapper destruction and React nodeview
+ * re-mounting.
+ *
+ * @param oldFragment - Fragment from the current editor state (holds existing node references)
+ * @param newFragment - Fragment parsed from incoming document (fresh node objects)
+ * @returns A Fragment that reuses old node references where possible
+ *
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-5277
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-4424
+ */
+export declare function preserveNodeIdentity(oldFragment: Fragment, newFragment: Fragment): Fragment;

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

@@ -8,8 +8,8 @@ import type { DecorationSet, EditorView } from '@atlaskit/editor-prosemirror/vie
 import { Decoration } from '@atlaskit/editor-prosemirror/view';
 export declare const findPointers: (id: string, decorations: DecorationSet) => Decoration[];
 export declare function getAvatarColor(str: string): {
-    index: number;
     backgroundColor: string;
+    index: number;
     textColor: string;
 };
 export declare const createTelepointers: (from: number, to: number, sessionId: string, isSelection: boolean, initial: string, presenceId: string, fullName: string, isNudged: boolean) => Decoration[];

package/dist/types-ts4.5/pm-plugins/preserve-node-identity.d.ts

@@ -0,0 +1,28 @@
+import { Fragment } from '@atlaskit/editor-prosemirror/model';
+/**
+ * Walk two Fragments (old and new) and return a Fragment that reuses old node
+ * references wherever structurally equal (`node.eq()` returns true).
+ *
+ * This preserves referential identity (`===`) for unchanged subtrees, which is
+ * critical for ProseMirror's view reconciliation performance. The `preMatch`
+ * optimisation in `prosemirror-view/src/viewdesc.ts` uses `===` to fast-match
+ * nodes against existing view descriptors. When all nodes are fresh objects
+ * (e.g. after `Node.fromJSON` in `replaceDocument`), `preMatch` fails for
+ * everything, and the fallback scan in `syncToMarks` is limited to 3
+ * positions — causing mark wrappers to be destroyed and recreated when widget
+ * decorations (gap cursor, telepointers, block controls) shift indices beyond
+ * that window. The destroyed mark wrappers take their React nodeviews with
+ * them, causing visible flicker.
+ *
+ * By preserving identity here, we ensure `preMatch` succeeds for unchanged
+ * subtrees, preventing unnecessary mark wrapper destruction and React nodeview
+ * re-mounting.
+ *
+ * @param oldFragment - Fragment from the current editor state (holds existing node references)
+ * @param newFragment - Fragment parsed from incoming document (fresh node objects)
+ * @returns A Fragment that reuses old node references where possible
+ *
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-5277
+ * @see https://hello.jira.atlassian.cloud/browse/EDITOR-4424
+ */
+export declare function preserveNodeIdentity(oldFragment: Fragment, newFragment: Fragment): Fragment;

package/dist/types-ts4.5/pm-plugins/utils.d.ts

@@ -8,8 +8,8 @@ import type { DecorationSet, EditorView } from '@atlaskit/editor-prosemirror/vie
 import { Decoration } from '@atlaskit/editor-prosemirror/view';
 export declare const findPointers: (id: string, decorations: DecorationSet) => Decoration[];
 export declare function getAvatarColor(str: string): {
-    index: number;
     backgroundColor: string;
+    index: number;
     textColor: string;
 };
 export declare const createTelepointers: (from: number, to: number, sessionId: string, isSelection: boolean, initial: string, presenceId: string, fullName: string, isNudged: boolean) => Decoration[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-collab-edit",
-	"version": "9.0.20",
+	"version": "9.0.22",
 	"description": "Collab Edit plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -39,13 +39,13 @@
 		"@atlaskit/frontend-utilities": "^3.2.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
 		"@atlaskit/prosemirror-collab": "^0.22.0",
-		"@atlaskit/tmp-editor-statsig": "^53.0.0",
+		"@atlaskit/tmp-editor-statsig": "^54.0.0",
 		"@atlaskit/tokens": "^11.4.0",
 		"@babel/runtime": "^7.0.0",
 		"memoize-one": "^6.0.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^112.15.0",
+		"@atlaskit/editor-common": "^112.16.0",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0"
 	},