@atlaskit/editor-plugin-collab-edit 13.0.30 → 13.1.0

package/dist/esm/pm-plugins/main/agent-shimmer-ranges.js

@@ -0,0 +1,163 @@
+import { getCollabState } from '@atlaskit/prosemirror-collab';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
+// When an agent step lands we cover the top-level block(s) it wrote with a skeleton-loader shimmer
+// (plus a Rovo agent telepointer at the end of the range), then remove it on a timer to reveal the
+// content. Gated behind the `platform_editor_agent_be_streaming` experiment; `durationMs` sets how
+// long the shimmer stays and a 0 duration disables it.
+var agentShimmerIdCounter = 0;
+
+// A step is position-neutral when its StepMap changes no range's length — i.e. it shifts no
+// positions. Attribute-only steps (e.g. `localId` assignment) produce an empty StepMap, and
+// same-size replacements preserve lengths, so both are position-neutral. Used to decide whether a
+// rebase over local unconfirmed steps could have invalidated our index-based range math.
+export var isPositionNeutralStep = function isPositionNeutralStep(step) {
+  var neutral = true;
+  step.getMap().forEach(function (oldStart, oldEnd, newStart, newEnd) {
+    if (oldEnd - oldStart !== newEnd - newStart) {
+      neutral = false;
+    }
+  });
+  return neutral;
+};
+
+/**
+ * Derive the shimmer ranges for the agent-authored steps in a received batch, in final-doc
+ * coordinates. `agentType` present ⇒ agent-authored (per the NCS↔Editor steps contract). Each
+ * emitted range is expanded to the whole top-level block(s) the agent touched, which the plugin
+ * covers with the skeleton shimmer. Ranges with no new content (pure deletions) are dropped.
+ *
+ * Steps whose new content is in the same or directly-adjacent top-level block are coalesced into one
+ * range, so an edit that arrives as several steps in a region shimmers as a single unit. Edits
+ * separated by an untouched block stay independent.
+ *
+ * Correctness: the range math assumes `tr` is a linear 1:1 apply of `steps`. Under the native collab
+ * plugin, `receiveTransaction` rebases incoming steps over unconfirmed local steps when they exist;
+ * that only invalidates our positions if a local step shifted positions, so we skip solely when a
+ * rebased local step changed sizes (a rare, safe degrade). Any unexpected error also degrades to no
+ * shimmer, so this never throws into the shared remote-step handler.
+ */
+export var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, tr, view, durationMs, telepointerEnabled) {
+  var _json$find;
+  if (!expValEquals('platform_editor_agent_be_streaming', 'isEnabled', true)) {
+    return [];
+  }
+  // Nothing to reveal if the shimmer is disabled.
+  if (durationMs <= 0) {
+    return [];
+  }
+  // Telepointer label = the agent's type upper-cased (e.g. `mcp` → "MCP"), falling back to a generic
+  // "Agent"; `undefined` when the telepointer is disabled, so the plugin skips it. `agentType` is the
+  // same on every step of an agent batch, so read it from the first agent-authored step.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  var agentType = (_json$find = json.find(function (step) {
+    return typeof (step === null || step === void 0 ? void 0 : step.agentType) === 'string';
+  })) === null || _json$find === void 0 ? void 0 : _json$find.agentType;
+  var telepointerLabel = telepointerEnabled ? (agentType === null || agentType === void 0 ? void 0 : agentType.toUpperCase()) || 'Agent' : undefined;
+  // When the batch was rebased over local unconfirmed steps, our index-based range math is only
+  // valid if those local steps shifted no positions. Attribute-only steps (e.g. `localId`) and
+  // same-size replacements are position-neutral, so the shimmer stays correct. Skip only when a
+  // local step actually changed sizes (a genuine concurrent content edit).
+  if (Number(tr.getMeta('rebased')) > 0) {
+    var _getCollabState$uncon, _getCollabState;
+    var unconfirmed = (_getCollabState$uncon = (_getCollabState = getCollabState(view.state)) === null || _getCollabState === void 0 ? void 0 : _getCollabState.unconfirmed) !== null && _getCollabState$uncon !== void 0 ? _getCollabState$uncon : [];
+    if (unconfirmed.some(function (entry) {
+      return !isPositionNeutralStep(entry.step);
+    })) {
+      return [];
+    }
+  }
+  try {
+    // Map an inserted range in doc_{i+1} forward through the remaining steps to final-doc coords.
+    // (A later step's own inserted content starts at its `from`; only subsequent steps shift it.)
+    var mapToFinalDoc = function mapToFinalDoc(pos, stepIndex, bias) {
+      var p = pos;
+      for (var j = stepIndex + 1; j < steps.length; j++) {
+        p = steps[j].getMap().map(p, bias);
+      }
+      return p;
+    };
+
+    // Derive each agent step's changed ranges from its StepMap — the canonical, step-type-agnostic
+    // source of what a step wrote. We only need the NEW extent (the content now in the document), in
+    // final-doc coords, since the highlight decorates content that is already present.
+
+    var infos = [];
+    json.forEach(function (rawStep, index) {
+      if (typeof (rawStep === null || rawStep === void 0 ? void 0 : rawStep.agentType) !== 'string') {
+        return;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      var pmStep = steps[index];
+      if (typeof (pmStep === null || pmStep === void 0 ? void 0 : pmStep.getMap) !== 'function') {
+        return;
+      }
+      pmStep.getMap().forEach(function (_oldStart, _oldEnd, newStart, newEnd) {
+        if (newEnd <= newStart) {
+          return; // pure deletion / attribute-only — no new content to highlight
+        }
+        infos.push({
+          from: mapToFinalDoc(newStart, index, -1),
+          to: mapToFinalDoc(newEnd, index, 1)
+        });
+      });
+    });
+    if (!infos.length) {
+      return [];
+    }
+
+    // Group the changed ranges by the TOP-LEVEL block they landed in, then highlight each touched
+    // block IN FULL. NCS emits a single agent edit as many small replace fragments and often keeps a
+    // common prefix/suffix untouched, so the changed sub-ranges cover only part of a block (e.g. half
+    // a rewritten heading). Expanding to the whole block's content makes the entire heading/paragraph
+    // shimmer as one unit rather than leaving the unchanged half undecorated. Directly-adjacent
+    // touched blocks (index n and n+1) merge into one group so a multi-block rewrite reveals together;
+    // a genuinely untouched block in between (index gap > 1) splits the run, so far-apart edits stay
+    // independent.
+    var docSize = tr.doc.content.size;
+    var clampPos = function clampPos(pos) {
+      return Math.min(Math.max(pos, 1), docSize);
+    };
+    var blockIndexAt = function blockIndexAt(pos) {
+      return tr.doc.resolve(clampPos(pos)).index(0);
+    };
+    // Start/end of the content of the top-level block containing `pos`, so the whole block is covered.
+    var blockContentStart = function blockContentStart(pos) {
+      var $pos = tr.doc.resolve(clampPos(pos));
+      return $pos.depth >= 1 ? $pos.start(1) : pos;
+    };
+    var blockContentEnd = function blockContentEnd(pos) {
+      var $pos = tr.doc.resolve(clampPos(pos));
+      return $pos.depth >= 1 ? $pos.end(1) : pos;
+    };
+    var sorted = [].concat(infos).sort(function (a, b) {
+      return a.from - b.from || a.to - b.to;
+    });
+    var groups = [];
+    sorted.forEach(function (info) {
+      var block = blockIndexAt(info.from);
+      var current = groups[groups.length - 1];
+      if (current && block <= current.maxBlock + 1) {
+        current.to = Math.max(current.to, info.to);
+        current.maxBlock = Math.max(current.maxBlock, block);
+      } else {
+        groups.push({
+          from: info.from,
+          to: info.to,
+          maxBlock: block
+        });
+      }
+    });
+    return groups.map(function (group) {
+      return {
+        shimmerId: "agent-shimmer-".concat(agentShimmerIdCounter++),
+        from: blockContentStart(group.from),
+        to: blockContentEnd(group.to),
+        telepointerLabel: telepointerLabel
+      };
+    });
+  } catch (_unused) {
+    // Never let shimmer range derivation throw into the shared remote-step handler; degrade to no
+    // shimmer.
+    return [];
+  }
+};

package/dist/esm/pm-plugins/main/plugin-state.js

@@ -7,6 +7,8 @@ import { Selection } from '@atlaskit/editor-prosemirror/state';
 import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
 import { Participants } from '../participants';
 import { createTelepointers, findPointers, getPositionOfTelepointer, isReplaceStep, hasExistingNudge } from '../utils';
+import { ADD_AGENT_SHIMMER_META, buildAgentShimmerDecorations, reduceAgentShimmers, REMOVE_AGENT_SHIMMER_META } from './agent-shimmer-decorations';
+
 /**
  * Returns position where it's possible to place a decoration.
  */
@@ -26,7 +28,10 @@ export var PluginState = /*#__PURE__*/function () {
     var collabInitalised = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
     var onError = arguments.length > 4 ? arguments[4] : undefined;
     var nudgeAnimations = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : new Map();
+    var agentShimmers = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : [];
     _classCallCheck(this, PluginState);
+    // Active agent-edit shimmer ranges (pure data). Replaced with a fresh array of fresh
+    // objects whenever it changes — never mutated in place.
     // eslint-disable-next-line no-console
     _defineProperty(this, "onError", function (error) {
       return console.error(error);
@@ -37,6 +42,7 @@ export var PluginState = /*#__PURE__*/function () {
     this.isReady = collabInitalised;
     this.onError = onError || this.onError;
     this.nudgeAnimations = nudgeAnimations;
+    this.agentShimmers = agentShimmers;
   }
   return _createClass(PluginState, [{
     key: "decorations",
@@ -83,6 +89,8 @@ export var PluginState = /*#__PURE__*/function () {
       var presenceData = tr.getMeta('presence');
       var telepointerData = tr.getMeta('telepointer');
       var nudgeTelepointerData = tr.getMeta('nudgeTelepointer');
+      var agentShimmerData = tr.getMeta(ADD_AGENT_SHIMMER_META);
+      var removeAgentShimmerId = tr.getMeta(REMOVE_AGENT_SHIMMER_META);
       var sessionIdData = tr.getMeta('sessionId');
       var collabInitialised = tr.getMeta('collabInitialised');
       if (typeof collabInitialised !== 'boolean') {
@@ -170,6 +178,11 @@ export var PluginState = /*#__PURE__*/function () {
       // Ignored via go/ees005
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       this.decorationSet.find().forEach(function (deco) {
+        var _deco$spec;
+        // Never let telepointer dim/side logic touch agent-shimmer decorations.
+        if ((_deco$spec = deco.spec) !== null && _deco$spec !== void 0 && _deco$spec.isAgentShimmer) {
+          return;
+        }
         if (deco.type.toDOM) {
           var hasTelepointerDimClass = deco.type.toDOM.classList.contains(TELEPOINTER_DIM_CLASS);
           var browser = getBrowserInfo();
@@ -198,8 +211,12 @@ export var PluginState = /*#__PURE__*/function () {
         // Ignored via go/ees005
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.decorationSet.find().forEach(function (deco) {
-          var _deco$spec, _deco$spec2;
-          if (deco.type.toDOM && participants.get(nudgeSessionId) && ((_deco$spec = deco.spec) === null || _deco$spec === void 0 || (_deco$spec = _deco$spec.pointer) === null || _deco$spec === void 0 ? void 0 : _deco$spec.sessionId) === nudgeSessionId && ((_deco$spec2 = deco.spec) === null || _deco$spec2 === void 0 ? void 0 : _deco$spec2.key) === "telepointer-".concat(nudgeSessionId)) {
+          var _deco$spec2, _deco$spec3, _deco$spec4;
+          // Never let telepointer nudge logic touch agent-shimmer decorations.
+          if ((_deco$spec2 = deco.spec) !== null && _deco$spec2 !== void 0 && _deco$spec2.isAgentShimmer) {
+            return;
+          }
+          if (deco.type.toDOM && participants.get(nudgeSessionId) && ((_deco$spec3 = deco.spec) === null || _deco$spec3 === void 0 || (_deco$spec3 = _deco$spec3.pointer) === null || _deco$spec3 === void 0 ? void 0 : _deco$spec3.sessionId) === nudgeSessionId && ((_deco$spec4 = deco.spec) === null || _deco$spec4 === void 0 ? void 0 : _deco$spec4.key) === "telepointer-".concat(nudgeSessionId)) {
             // Restart animation by removing and re-adding the class
             deco.type.toDOM.classList.remove(TELEPOINTER_PULSE_DURING_TR_CLASS);
             deco.type.toDOM.classList.remove(TELEPOINTER_PULSE_CLASS);
@@ -209,6 +226,41 @@ export var PluginState = /*#__PURE__*/function () {
           }
         });
       }
+
+      // Register / keep-aligned / remove the agent-edit purple highlight
+      // decorations. Fully fault-isolated — it works on local copies and only merges into the shared
+      // `add`/`remove` (and commits `this.agentShimmers`) after the whole block succeeds, so a fault
+      // here can never corrupt telepointer decorations or the shared decoration set. Never mutates
+      // shimmer entries in place: each change produces a fresh array of fresh objects.
+      try {
+        var _reduceAgentShimmers = reduceAgentShimmers(this.agentShimmers, tr, agentShimmerData, removeAgentShimmerId),
+          changed = _reduceAgentShimmers.changed,
+          next = _reduceAgentShimmers.next;
+        if (changed) {
+          // Build into local arrays; only merge into the shared add/remove once the block succeeds.
+          var agentRemove = this.decorationSet.find(undefined, undefined, function (spec) {
+            return spec.isAgentShimmer;
+          });
+          var agentAdd = buildAgentShimmerDecorations(tr, next, getValidPos, this.onError);
+
+          // Commit only after the whole block succeeded.
+          remove = remove.concat(agentRemove);
+          add = add.concat(agentAdd);
+          this.agentShimmers = next;
+        }
+      } catch (err) {
+        this.onError(err);
+        // Degrade to no shimmer without corrupting telepointer decorations: drop all agent
+        // decorations and clear agent state, leaving the telepointer `add`/`remove` untouched.
+        this.agentShimmers = [];
+        try {
+          remove = remove.concat(this.decorationSet.find(undefined, undefined, function (spec) {
+            return spec.isAgentShimmer;
+          }));
+        } catch (_unused) {
+          // Teardown must not re-throw.
+        }
+      }
       if (remove.length) {
         this.decorationSet = this.decorationSet.remove(remove);
       }
@@ -227,7 +279,7 @@ export var PluginState = /*#__PURE__*/function () {
           }
         }
       }
-      var nextState = new PluginState(this.decorationSet, participants, sid, collabInitialised, this.onError, this.nudgeAnimations);
+      var nextState = new PluginState(this.decorationSet, participants, sid, collabInitialised, this.onError, this.nudgeAnimations, this.agentShimmers);
       return PluginState.eq(nextState, this) ? this : nextState;
     }
   }], [{

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

@@ -10,8 +10,12 @@ import { Decoration } from '@atlaskit/editor-prosemirror/view';
 import { getParticipantColor } from '@atlaskit/editor-shared-styles';
 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;
+  return decorations.find().reduce(
+  // `pointer` is absent on non-telepointer decorations (e.g. the agent-shimmer
+  // sweep decorations), so guard against it to avoid crashing this shared helper.
+  function (arr, deco) {
+    var _deco$spec$pointer;
+    return ((_deco$spec$pointer = deco.spec.pointer) === null || _deco$spec$pointer === void 0 ? void 0 : _deco$spec$pointer.presenceId) === id ? arr.concat(deco) : arr;
   }, []);
 };
 function style(options) {

package/dist/types/pm-plugins/main/agent-shimmer-decorations.d.ts

@@ -0,0 +1,31 @@
+import type { ReadonlyTransaction } from '@atlaskit/editor-prosemirror/state';
+import { Decoration } from '@atlaskit/editor-prosemirror/view';
+/** Default time the skeleton shimmer stays on the agent-authored content (ms). */
+export declare const AGENT_SHIMMER_DEFAULT_DURATION_MS = 3000;
+export declare const AGENT_SHIMMER_CLASS = "collab-agent-shimmer";
+export declare const ROVO_AGENT_TELEPOINTER_CLASS = "ai-in-editor-telepointer";
+export declare const ROVO_AGENT_TELEPOINTER_LABEL_CLASS = "ai-in-editor-telepointer-label";
+export declare const ADD_AGENT_SHIMMER_META = "addAgentShimmer";
+export declare const REMOVE_AGENT_SHIMMER_META = "removeAgentShimmer";
+export type AgentShimmerRange = {
+    from: number;
+    shimmerId: string;
+    telepointerLabel?: string;
+    to: number;
+};
+/**
+ * Pure reducer for the active shimmer ranges from a transaction's changes. Maps existing ranges
+ * forward as the doc changes, replaces them wholesale when a new agent batch lands (a new batch
+ * supersedes any still-in-flight shimmer), and drops a range when its removal timer fires. Returns a
+ * fresh array (never mutates in place) plus whether anything changed.
+ */
+export declare const reduceAgentShimmers: (current: AgentShimmerRange[], tr: ReadonlyTransaction, added: AgentShimmerRange[] | undefined, removedShimmerId: string | undefined) => {
+    changed: boolean;
+    next: AgentShimmerRange[];
+};
+/**
+ * Builds the inline skeleton-bar + trailing telepointer decorations for the active shimmer ranges.
+ * `getValidPos` clamps a raw position to a valid decoration position (owned by `plugin-state`).
+ * One bad range is isolated via `onError` so it can't kill the others.
+ */
+export declare const buildAgentShimmerDecorations: (tr: ReadonlyTransaction, shimmers: AgentShimmerRange[], getValidPos: (tr: ReadonlyTransaction, pos: number) => number, onError: (err: Error) => void) => Decoration[];

package/dist/types/pm-plugins/main/agent-shimmer-ranges.d.ts

@@ -0,0 +1,22 @@
+import type { Transaction } from '@atlaskit/editor-prosemirror/state';
+import type { Step } from '@atlaskit/editor-prosemirror/transform';
+import type { EditorView } from '@atlaskit/editor-prosemirror/view';
+import type { AgentShimmerRange } from './agent-shimmer-decorations';
+export declare const isPositionNeutralStep: (step: Step) => boolean;
+/**
+ * Derive the shimmer ranges for the agent-authored steps in a received batch, in final-doc
+ * coordinates. `agentType` present ⇒ agent-authored (per the NCS↔Editor steps contract). Each
+ * emitted range is expanded to the whole top-level block(s) the agent touched, which the plugin
+ * covers with the skeleton shimmer. Ranges with no new content (pure deletions) are dropped.
+ *
+ * Steps whose new content is in the same or directly-adjacent top-level block are coalesced into one
+ * range, so an edit that arrives as several steps in a region shimmers as a single unit. Edits
+ * separated by an untouched block stay independent.
+ *
+ * Correctness: the range math assumes `tr` is a linear 1:1 apply of `steps`. Under the native collab
+ * plugin, `receiveTransaction` rebases incoming steps over unconfirmed local steps when they exist;
+ * that only invalidates our positions if a local step shifted positions, so we skip solely when a
+ * rebased local step changed sizes (a rare, safe degrade). Any unexpected error also degrades to no
+ * shimmer, so this never throws into the shared remote-step handler.
+ */
+export declare const getAgentShimmerRanges: (json: any[], steps: Step[], tr: Transaction, view: EditorView, durationMs: number, telepointerEnabled: boolean) => AgentShimmerRange[];

package/dist/types/pm-plugins/main/plugin-state.d.ts

@@ -3,6 +3,7 @@ import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
 import type { ReadOnlyParticipants } from '../../types';
 import { Participants } from '../participants';
 import type { NudgeAnimationsMap } from '../utils';
+import { type AgentShimmerRange } from './agent-shimmer-decorations';
 /**
  * Returns position where it's possible to place a decoration.
  */
@@ -11,13 +12,14 @@ export declare class PluginState {
     private decorationSet;
     private participants;
     private nudgeAnimations;
+    private agentShimmers;
     private onError;
     private sid?;
     isReady: boolean;
     get decorations(): DecorationSet;
     get activeParticipants(): ReadOnlyParticipants;
     get sessionId(): string | undefined;
-    constructor(decorations: DecorationSet, participants: Participants, sessionId?: string, collabInitalised?: boolean, onError?: (err: Error) => void, nudgeAnimations?: NudgeAnimationsMap);
+    constructor(decorations: DecorationSet, participants: Participants, sessionId?: string, collabInitalised?: boolean, onError?: (err: Error) => void, nudgeAnimations?: NudgeAnimationsMap, agentShimmers?: AgentShimmerRange[]);
     getFullName(sessionId: string): string;
     getInitial(sessionId: string): string;
     getPresenceId(sessionId: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-collab-edit",
-	"version": "13.0.30",
+	"version": "13.1.0",
 	"description": "Collab Edit plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -31,13 +31,13 @@
 		"@atlaskit/frontend-utilities": "^4.1.0",
 		"@atlaskit/platform-feature-flags": "^2.1.0",
 		"@atlaskit/prosemirror-collab": "^1.0.0",
-		"@atlaskit/tmp-editor-statsig": "^132.0.0",
-		"@atlaskit/tokens": "^16.2.0",
+		"@atlaskit/tmp-editor-statsig": "^132.3.0",
+		"@atlaskit/tokens": "^16.3.0",
 		"@babel/runtime": "^7.0.0",
 		"memoize-one": "^6.0.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^116.35.0",
+		"@atlaskit/editor-common": "^116.36.0",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0"
 	},
@@ -86,6 +86,9 @@
 	"platform-feature-flags": {
 		"platform_editor_collab_organic_change_reporting": {
 			"type": "boolean"
+		},
+		"platform_editor_agent_be_streaming": {
+			"type": "experiment"
 		}
 	}
 }