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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @atlaskit/editor-plugin-collab-edit
 
+## 13.1.0
+
+### Minor Changes
+
+- [`895ac23f1a3be`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/895ac23f1a3be) -
+  Agent edit presence: surface agent-authored collaborative edits to other users.
+  - `collab-provider` detects agent-authored remote steps (`agentType`/`agentId`) and registers a
+    synthetic agent participant in the AI-provider (`agent:`) partition so the agent appears in
+    presence, with a 30s sliding inactivity window (CCI-18030). `editor-common` gains optional
+    `agentId`/`agentType` on the collab step types.
+  - `editor-plugin-collab-edit` + `editor-core` add the in-editor shimmer (CCI-18033): when an
+    agent-authored step lands, the top-level block(s) it touched are covered by a skeleton-loader
+    shimmer (grey skeleton with a moving highlight) with a Rovo agent telepointer/cursor — labelled
+    with the agent's type — at the end of the range, then removed on a timer to reveal the content.
+    Gated behind the default-OFF `platform_editor_agent_be_streaming` experiment; the `durationMs`
+    dynamic-config param controls how long the shimmer stays (0 disables it) and
+    `telepointerDisabled` hides the telepointer. `tmp-editor-statsig` registers the experiment.
+  - `ratcheting` excludes the new `agentShimmerStyles.ts` from the "No unsafe typography" rule (the
+    agent telepointer label mirrors the existing AI in-editor telepointer's sub-token 10px/9px
+    sizing, matching its already-excluded Compiled counterpart).
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 13.0.30
 
 ### Patch Changes

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

@@ -10,6 +10,10 @@ var allAtlaskitCustomSteps = _interopRequireWildcard(require("@atlaskit/custom-s
 var _state = require("@atlaskit/editor-prosemirror/state");
 var _transform = require("@atlaskit/editor-prosemirror/transform");
 var _prosemirrorCollab = require("@atlaskit/prosemirror-collab");
+var _expValEquals = require("@atlaskit/tmp-editor-statsig/exp-val-equals");
+var _expVal = require("@atlaskit/tmp-editor-statsig/expVal");
+var _agentShimmerDecorations = require("./main/agent-shimmer-decorations");
+var _agentShimmerRanges = require("./main/agent-shimmer-ranges");
 var _utils = require("./utils");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 // Ignored via go/ees005
@@ -79,6 +83,22 @@ var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json
     tr.setMeta('addToHistory', false);
     tr.setMeta('isRemote', true);
 
+    // Agent edit shimmer: mark the ranges agent steps just wrote so the plugin reveals them with the
+    // gloss-sweep → purple-highlight sequence. Gated as a whole so no experiment reads run
+    // off-experiment; off-path leaves `agentShimmers` empty and everything below is a no-op.
+    var durationMs = 0;
+    var agentShimmers = [];
+    if ((0, _expValEquals.expValEquals)('platform_editor_agent_be_streaming', 'isEnabled', true)) {
+      durationMs = (0, _expVal.expVal)('platform_editor_agent_be_streaming', 'durationMs', _agentShimmerDecorations.AGENT_SHIMMER_DEFAULT_DURATION_MS);
+      // Telepointer shown by default; `telepointerDisabled` hides it (inverted because `expVal`
+      // only permits `false` as a boolean default).
+      var telepointerEnabled = !(0, _expVal.expVal)('platform_editor_agent_be_streaming', 'telepointerDisabled', false);
+      agentShimmers = (0, _agentShimmerRanges.getAgentShimmerRanges)(json, steps, tr, view, durationMs, telepointerEnabled);
+      if (agentShimmers.length) {
+        tr.setMeta(_agentShimmerDecorations.ADD_AGENT_SHIMMER_META, agentShimmers);
+      }
+    }
+
     /*
      * Persist marks across transactions. Fixes an issue where
      * marks are lost if remote transactions are dispatched
@@ -88,6 +108,25 @@ var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json
       tr.setStoredMarks(state.tr.storedMarks);
     }
     view.dispatch(tr);
+
+    // Remove each shimmer after `durationMs`. `dispatchMeta` is guarded so a timer firing after
+    // teardown is a harmless no-op. Only reached when the gated block above produced ranges, so this
+    // whole path is off-experiment-safe.
+    if (agentShimmers.length) {
+      var dispatchMeta = function dispatchMeta(metaKey, value) {
+        try {
+          view.dispatch(view.state.tr.setMeta(metaKey, value));
+        } catch (_unused) {
+          // View torn down before the timer fired — nothing to clean up.
+        }
+      };
+      agentShimmers.forEach(function (_ref) {
+        var shimmerId = _ref.shimmerId;
+        setTimeout(function () {
+          dispatchMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META, shimmerId);
+        }, durationMs);
+      });
+    }
   }
 };
 var handleTelePointer = exports.handleTelePointer = function handleTelePointer(telepointerData, view) {

package/dist/cjs/pm-plugins/main/agent-shimmer-decorations.js

@@ -0,0 +1,126 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.reduceAgentShimmers = exports.buildAgentShimmerDecorations = exports.ROVO_AGENT_TELEPOINTER_LABEL_CLASS = exports.ROVO_AGENT_TELEPOINTER_CLASS = exports.REMOVE_AGENT_SHIMMER_META = exports.AGENT_SHIMMER_DEFAULT_DURATION_MS = exports.AGENT_SHIMMER_CLASS = exports.ADD_AGENT_SHIMMER_META = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _view = require("@atlaskit/editor-prosemirror/view");
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+// Kept out of `plugin-state.ts` so all the agent-shimmer plumbing lives together and is easy to
+// remove if the approach changes. `plugin-state` just reduces the active ranges and asks this module
+// to build the decorations.
+
+/** Default time the skeleton shimmer stays on the agent-authored content (ms). */
+var AGENT_SHIMMER_DEFAULT_DURATION_MS = exports.AGENT_SHIMMER_DEFAULT_DURATION_MS = 3000;
+
+// Skeleton-loader bar over the agent-authored range, plus a Rovo AI telepointer at the end.
+var AGENT_SHIMMER_CLASS = exports.AGENT_SHIMMER_CLASS = 'collab-agent-shimmer';
+var ROVO_AGENT_TELEPOINTER_CLASS = exports.ROVO_AGENT_TELEPOINTER_CLASS = 'ai-in-editor-telepointer';
+var ROVO_AGENT_TELEPOINTER_LABEL_CLASS = exports.ROVO_AGENT_TELEPOINTER_LABEL_CLASS = 'ai-in-editor-telepointer-label';
+var ADD_AGENT_SHIMMER_META = exports.ADD_AGENT_SHIMMER_META = 'addAgentShimmer'; // register the shimmer decorations
+var REMOVE_AGENT_SHIMMER_META = exports.REMOVE_AGENT_SHIMMER_META = 'removeAgentShimmer'; // remove them once the shimmer ends
+
+// A range an agent step wrote; the skeleton + telepointer decorations are drawn over `from`..`to`
+// and kept until removal (so positions can be re-mapped). Pure data only. `telepointerLabel` is the
+// label for the trailing agent telepointer (the agent's type); when absent, no telepointer is shown.
+
+// Rovo AI in-editor telepointer/cursor shown at the end of an agent-authored range (same DOM/style
+// pattern as editor-plugin-ai's in-editor direct-streaming telepointer).
+var createRovoAgentTelepointer = function createRovoAgentTelepointer(label) {
+  var element = document.createElement('span');
+  element.setAttribute('data-testid', 'ai-in-editor-telepointer-widget');
+  element.className = ROVO_AGENT_TELEPOINTER_CLASS;
+  var labelElement = document.createElement('span');
+  labelElement.setAttribute('data-testid', 'ai-in-editor-telepointer-widget-label');
+  labelElement.className = ROVO_AGENT_TELEPOINTER_LABEL_CLASS;
+  labelElement.append(label);
+  element.appendChild(labelElement);
+  return element;
+};
+
+/**
+ * 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.
+ */
+var reduceAgentShimmers = exports.reduceAgentShimmers = function reduceAgentShimmers(current, tr, added, removedShimmerId) {
+  var next = current;
+  var changed = false;
+
+  // Ranges added in THIS transaction are already in post-change coords, so map the pre-existing
+  // ones BEFORE replacing with any new batch.
+  if (tr.docChanged && next.length) {
+    next = next.map(function (shimmer) {
+      return _objectSpread(_objectSpread({}, shimmer), {}, {
+        from: tr.mapping.map(shimmer.from, -1),
+        to: tr.mapping.map(shimmer.to, 1)
+      });
+    });
+    changed = true;
+  }
+  if (added !== null && added !== void 0 && added.length) {
+    next = added.map(function (shimmer) {
+      return _objectSpread({}, shimmer);
+    });
+    changed = true;
+  }
+  if (removedShimmerId) {
+    next = next.filter(function (shimmer) {
+      return shimmer.shimmerId !== removedShimmerId;
+    });
+    changed = true;
+  }
+  return {
+    changed: changed,
+    next: next
+  };
+};
+
+/**
+ * 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.
+ */
+var buildAgentShimmerDecorations = exports.buildAgentShimmerDecorations = function buildAgentShimmerDecorations(tr, shimmers, getValidPos, onError) {
+  var decorations = [];
+  var docEnd = tr.doc.nodeSize - 2;
+  shimmers.forEach(function (_ref) {
+    var shimmerId = _ref.shimmerId,
+      from = _ref.from,
+      to = _ref.to,
+      telepointerLabel = _ref.telepointerLabel;
+    try {
+      var validFrom = getValidPos(tr, Math.max(from, 1));
+      var validTo = getValidPos(tr, Math.min(to, docEnd));
+      if (validTo <= validFrom) {
+        return;
+      }
+      // Skeleton-loader bar over the whole agent-authored range...
+      decorations.push(_view.Decoration.inline(validFrom, validTo, {
+        class: AGENT_SHIMMER_CLASS
+      }, {
+        isAgentShimmer: true,
+        shimmerId: shimmerId
+      }));
+      // ...and, when enabled, a Rovo AI telepointer/cursor (labelled with the agent's type) at the
+      // end of the range.
+      if (telepointerLabel) {
+        decorations.push(_view.Decoration.widget(validTo, createRovoAgentTelepointer(telepointerLabel), {
+          isAgentShimmer: true,
+          shimmerId: shimmerId,
+          class: ROVO_AGENT_TELEPOINTER_CLASS,
+          key: "agent-telepointer-".concat(shimmerId),
+          side: 1
+        }));
+      }
+    } catch (err) {
+      // One bad range must not kill the others.
+      onError(err);
+    }
+  });
+  return decorations;
+};

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

@@ -0,0 +1,169 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isPositionNeutralStep = exports.getAgentShimmerRanges = void 0;
+var _prosemirrorCollab = require("@atlaskit/prosemirror-collab");
+var _expValEquals = require("@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.
+var isPositionNeutralStep = exports.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.
+ */
+var getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, tr, view, durationMs, telepointerEnabled) {
+  var _json$find;
+  if (!(0, _expValEquals.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 = (0, _prosemirrorCollab.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/cjs/pm-plugins/main/plugin-state.js

@@ -14,6 +14,7 @@ var _state = require("@atlaskit/editor-prosemirror/state");
 var _view = require("@atlaskit/editor-prosemirror/view");
 var _participants = require("../participants");
 var _utils = require("../utils");
+var _agentShimmerDecorations = require("./agent-shimmer-decorations");
 /**
  * Returns position where it's possible to place a decoration.
  */
@@ -33,7 +34,10 @@ var PluginState = exports.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] : [];
     (0, _classCallCheck2.default)(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
     (0, _defineProperty2.default)(this, "onError", function (error) {
       return console.error(error);
@@ -44,6 +48,7 @@ var PluginState = exports.PluginState = /*#__PURE__*/function () {
     this.isReady = collabInitalised;
     this.onError = onError || this.onError;
     this.nudgeAnimations = nudgeAnimations;
+    this.agentShimmers = agentShimmers;
   }
   return (0, _createClass2.default)(PluginState, [{
     key: "decorations",
@@ -90,6 +95,8 @@ var PluginState = exports.PluginState = /*#__PURE__*/function () {
       var presenceData = tr.getMeta('presence');
       var telepointerData = tr.getMeta('telepointer');
       var nudgeTelepointerData = tr.getMeta('nudgeTelepointer');
+      var agentShimmerData = tr.getMeta(_agentShimmerDecorations.ADD_AGENT_SHIMMER_META);
+      var removeAgentShimmerId = tr.getMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META);
       var sessionIdData = tr.getMeta('sessionId');
       var collabInitialised = tr.getMeta('collabInitialised');
       if (typeof collabInitialised !== 'boolean') {
@@ -177,6 +184,11 @@ var PluginState = exports.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(_collab.TELEPOINTER_DIM_CLASS);
           var browser = (0, _browser.getBrowserInfo)();
@@ -205,8 +217,12 @@ var PluginState = exports.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(_collab.TELEPOINTER_PULSE_DURING_TR_CLASS);
             deco.type.toDOM.classList.remove(_collab.TELEPOINTER_PULSE_CLASS);
@@ -216,6 +232,41 @@ var PluginState = exports.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 = (0, _agentShimmerDecorations.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 = (0, _agentShimmerDecorations.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);
       }
@@ -234,7 +285,7 @@ var PluginState = exports.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/cjs/pm-plugins/utils.js

@@ -19,8 +19,12 @@ var _view = require("@atlaskit/editor-prosemirror/view");
 var _editorSharedStyles = require("@atlaskit/editor-shared-styles");
 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;
+  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/es2019/pm-plugins/actions.js

@@ -7,6 +7,10 @@ import * as allAtlaskitCustomSteps from '@atlaskit/custom-steps';
 import { AllSelection, NodeSelection } from '@atlaskit/editor-prosemirror/state';
 import { Step } from '@atlaskit/editor-prosemirror/transform';
 import { receiveTransaction } from '@atlaskit/prosemirror-collab';
+import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
+import { expVal } from '@atlaskit/tmp-editor-statsig/expVal';
+import { ADD_AGENT_SHIMMER_META, AGENT_SHIMMER_DEFAULT_DURATION_MS, REMOVE_AGENT_SHIMMER_META } from './main/agent-shimmer-decorations';
+import { getAgentShimmerRanges } from './main/agent-shimmer-ranges';
 import { replaceDocument } from './utils';
 
 /*
@@ -83,6 +87,22 @@ export const applyRemoteSteps = (json, view, userIds, options) => {
     tr.setMeta('addToHistory', false);
     tr.setMeta('isRemote', true);
 
+    // Agent edit shimmer: mark the ranges agent steps just wrote so the plugin reveals them with the
+    // gloss-sweep → purple-highlight sequence. Gated as a whole so no experiment reads run
+    // off-experiment; off-path leaves `agentShimmers` empty and everything below is a no-op.
+    let durationMs = 0;
+    let agentShimmers = [];
+    if (expValEquals('platform_editor_agent_be_streaming', 'isEnabled', true)) {
+      durationMs = expVal('platform_editor_agent_be_streaming', 'durationMs', AGENT_SHIMMER_DEFAULT_DURATION_MS);
+      // Telepointer shown by default; `telepointerDisabled` hides it (inverted because `expVal`
+      // only permits `false` as a boolean default).
+      const telepointerEnabled = !expVal('platform_editor_agent_be_streaming', 'telepointerDisabled', false);
+      agentShimmers = getAgentShimmerRanges(json, steps, tr, view, durationMs, telepointerEnabled);
+      if (agentShimmers.length) {
+        tr.setMeta(ADD_AGENT_SHIMMER_META, agentShimmers);
+      }
+    }
+
     /*
      * Persist marks across transactions. Fixes an issue where
      * marks are lost if remote transactions are dispatched
@@ -92,6 +112,26 @@ export const applyRemoteSteps = (json, view, userIds, options) => {
       tr.setStoredMarks(state.tr.storedMarks);
     }
     view.dispatch(tr);
+
+    // Remove each shimmer after `durationMs`. `dispatchMeta` is guarded so a timer firing after
+    // teardown is a harmless no-op. Only reached when the gated block above produced ranges, so this
+    // whole path is off-experiment-safe.
+    if (agentShimmers.length) {
+      const dispatchMeta = (metaKey, value) => {
+        try {
+          view.dispatch(view.state.tr.setMeta(metaKey, value));
+        } catch {
+          // View torn down before the timer fired — nothing to clean up.
+        }
+      };
+      agentShimmers.forEach(({
+        shimmerId
+      }) => {
+        setTimeout(() => {
+          dispatchMeta(REMOVE_AGENT_SHIMMER_META, shimmerId);
+        }, durationMs);
+      });
+    }
   }
 };
 export const handleTelePointer = (telepointerData, view) => {