@atlaskit/editor-plugin-collab-edit 13.1.3 → 13.3.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @atlaskit/editor-plugin-collab-edit
 
+## 13.3.0
+
+### Minor Changes
+
+- [`51c33ef5349b6`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/51c33ef5349b6) -
+  Enable compatibility with React 19.2.0
+
+### Patch Changes
+
+- Updated dependencies
+
+## 13.2.0
+
+### Minor Changes
+
+- [`782360c1111dc`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/782360c1111dc) -
+  Agent-edit shimmer review follow-ups (behind the default-OFF `platform_editor_agent_be_streaming`
+  experiment):
+  - Add a second shimmer phase: after the skeleton loader clears, the changed range shows a purple
+    "just edited" highlight (same colours as the editor AI "improve writing" in-editor highlight)
+    that eases in and out over its lifetime. The Rovo telepointer stays through both phases.
+  - The two phases are sized by independent experiment params: `shimmerDurationMs` (skeleton,
+    renamed from `durationMs`) and `highlightDurationMs` (highlight). `0` on either skips just that
+    phase, `0` on both shows nothing.
+  - Gate the agent-edit shimmer styles behind the experiment in both the emotion and compiled
+    `EditorContentContainer` style entries, using the no-exposure check on the hot render path.
+  - Add an `agentEditReceived` collab-provider analytics event, fired once per received transaction
+    that contains agent-authored steps, with non-PII attributes (agent ids, count, kinds,
+    agent/total step counts).
+  - Add an `agentEditShimmerNotShown` COLLAB operational analytics event for agent edits that apply
+    without the shimmer (`rebasedConcurrentEdit`, `nothingToShow`, `captureThrew`,
+    `tornDownMidAnimation`); neutral action + `reason`, non-PII attributes.
+  - Hoist the top-level block/position helpers in `agent-shimmer-ranges` to reusable module scope,
+    drop the redundant upper-bound clamp in `agent-shimmer-decorations`, and remove the empty
+    `@example` JSDoc tags added in the original PR.
+
+  `@atlaskit/editor-common` gains a new subpath export,
+  `@atlaskit/editor-common/analytics/types/agent-edit-shimmer-events`, exposing the
+  `agentEditShimmerNotShown` operational event types. Usage:
+
+  ```ts
+  import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
+  import type { AgentEditShimmerNotShownReason } from '@atlaskit/editor-common/analytics/types/agent-edit-shimmer-events';
+
+  const reason: AgentEditShimmerNotShownReason = 'captureThrew';
+  editorAnalyticsApi?.fireAnalyticsEvent({
+  	action: ACTION.AGENT_EDIT_SHIMMER_NOT_SHOWN,
+  	actionSubject: ACTION_SUBJECT.COLLAB,
+  	eventType: EVENT_TYPE.OPERATIONAL,
+  	attributes: { reason },
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 13.1.3
 
 ### Patch Changes

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

@@ -12,6 +12,7 @@ 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 _analytics = require("./analytics");
 var _agentShimmerDecorations = require("./main/agent-shimmer-decorations");
 var _agentShimmerRanges = require("./main/agent-shimmer-ranges");
 var _utils = require("./utils");
@@ -40,7 +41,7 @@ var handleInit = exports.handleInit = function handleInit(initData, view, option
     tr.setMeta('isRemote', true);
     view.dispatch(tr);
   } else if (json) {
-    applyRemoteSteps(json, view);
+    applyRemoteSteps(json, view, undefined, options, editorAnalyticsApi);
   }
 };
 var handleConnection = exports.handleConnection = function handleConnection(connectionData, view) {
@@ -51,15 +52,15 @@ var handlePresence = exports.handlePresence = function handlePresence(presenceDa
   var tr = view.state.tr;
   view.dispatch(tr.setMeta('presence', presenceData));
 };
-var applyRemoteData = exports.applyRemoteData = function applyRemoteData(remoteData, view, options) {
+var applyRemoteData = exports.applyRemoteData = function applyRemoteData(remoteData, view, options, editorAnalyticsApi) {
   var json = remoteData.json,
     _remoteData$userIds = remoteData.userIds,
     userIds = _remoteData$userIds === void 0 ? [] : _remoteData$userIds;
   if (json) {
-    applyRemoteSteps(json, view, userIds, options);
+    applyRemoteSteps(json, view, userIds, options, editorAnalyticsApi);
   }
 };
-var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json, view, userIds, options) {
+var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json, view, userIds, options, editorAnalyticsApi) {
   if (!json || !json.length) {
     return;
   }
@@ -84,16 +85,28 @@ var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json
     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;
+    // skeleton loader, then (optionally) a purple "just edited" highlight. Gated as a whole so no
+    // experiment reads run off-experiment; off-path leaves `agentShimmers` empty and everything below
+    // is a no-op.
+    var shimmerDurationMs = 0;
+    var highlightDurationMs = 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);
+      // The skeleton and purple-highlight phases toggle independently. `shimmerDurationMs` is the
+      // skeleton lifetime; `0` skips the skeleton (an edit can still get the purple highlight).
+      shimmerDurationMs = (0, _expVal.expVal)('platform_editor_agent_be_streaming', 'shimmerDurationMs', _agentShimmerDecorations.AGENT_SHIMMER_DEFAULT_DURATION_MS);
+      // `highlightDurationMs` is the purple "just edited" highlight lifetime; `0` skips the highlight
+      // (the skeleton still shows). `0` on both shows nothing.
+      highlightDurationMs = (0, _expVal.expVal)('platform_editor_agent_be_streaming', 'highlightDurationMs', _agentShimmerDecorations.AGENT_EDIT_HIGHLIGHT_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);
+      agentShimmers = (0, _agentShimmerRanges.getAgentShimmerRanges)(json, steps, tr, view, shimmerDurationMs, highlightDurationMs, telepointerEnabled,
+      // An agent edit that applied without the shimmer fires the operational event on the same
+      // transaction, so success stays event-free and only degrades are reported.
+      function (reason, agentType, error) {
+        return editorAnalyticsApi === null || editorAnalyticsApi === void 0 ? void 0 : editorAnalyticsApi.attachAnalyticsEvent((0, _analytics.getAgentEditShimmerNotShownPayload)(reason, agentType, error))(tr);
+      });
       if (agentShimmers.length) {
         tr.setMeta(_agentShimmerDecorations.ADD_AGENT_SHIMMER_META, agentShimmers);
       }
@@ -109,22 +122,45 @@ var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json
     }
     view.dispatch(tr);
 
-    // Remove each shimmer after `durationMs`. `dispatchMeta` is guarded so a timer firing after
+    // Schedule each shimmer's phase changes. `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 tornDownReported = false;
       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.
+          // View torn down before the timer fired — nothing to clean up. Report once (not once
+          // per shimmer) so we can see how often shimmers are interrupted by teardown.
+          if (!tornDownReported) {
+            tornDownReported = true;
+            editorAnalyticsApi === null || editorAnalyticsApi === void 0 || editorAnalyticsApi.fireAnalyticsEvent((0, _analytics.getAgentEditShimmerNotShownPayload)('tornDownMidAnimation'));
+          }
         }
       };
       agentShimmers.forEach(function (_ref) {
         var shimmerId = _ref.shimmerId;
-        setTimeout(function () {
-          dispatchMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META, shimmerId);
-        }, durationMs);
+        if (shimmerDurationMs > 0) {
+          // Skeleton first. When it clears, show the purple highlight (if enabled) then remove;
+          // otherwise remove straight away.
+          setTimeout(function () {
+            if (highlightDurationMs > 0) {
+              dispatchMeta(_agentShimmerDecorations.HIGHLIGHT_AGENT_SHIMMER_META, shimmerId);
+              setTimeout(function () {
+                dispatchMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META, shimmerId);
+              }, highlightDurationMs);
+            } else {
+              dispatchMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META, shimmerId);
+            }
+          }, shimmerDurationMs);
+        } else {
+          // Skeleton disabled: the range already starts in the highlight phase, so just time its
+          // removal. (Reached only when `highlightDurationMs > 0`, else no ranges were produced.)
+          setTimeout(function () {
+            dispatchMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META, shimmerId);
+          }, highlightDurationMs);
+        }
       });
     }
   }

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

@@ -1,12 +1,16 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.addSynchronyErrorAnalytics = exports.addSynchronyEntityAnalytics = void 0;
+exports.getAgentEditShimmerNotShownPayload = exports.addSynchronyErrorAnalytics = exports.addSynchronyEntityAnalytics = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _analytics = require("@atlaskit/editor-common/analytics");
 var _coreUtils = require("@atlaskit/editor-common/core-utils");
 var _utils = require("@atlaskit/editor-common/utils");
+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; }
 var addSynchronyErrorAnalytics = exports.addSynchronyErrorAnalytics = function addSynchronyErrorAnalytics(state, tr, featureFlags, editorAnalyticsApi) {
   return function (error) {
     var browserExtensions = (0, _utils.sniffUserBrowserExtensions)({
@@ -32,6 +36,27 @@ var addSynchronyErrorAnalytics = exports.addSynchronyErrorAnalytics = function a
     return tr;
   };
 };
+
+/**
+ * Builds the `agentEditShimmerNotShown` operational event fired when an agent-authored edit applied
+ * instantly without the skeleton shimmer/telepointer. Success is the ABSENCE of this event; a
+ * neutral action + `reason` keeps expected degrades out of error dashboards. Attributes are non-PII:
+ * only the agent kind and a sanitised error name/message (never the raw Error or any doc content).
+ */
+var getAgentEditShimmerNotShownPayload = exports.getAgentEditShimmerNotShownPayload = function getAgentEditShimmerNotShownPayload(reason, agentType, error) {
+  return {
+    action: _analytics.ACTION.AGENT_EDIT_SHIMMER_NOT_SHOWN,
+    actionSubject: _analytics.ACTION_SUBJECT.COLLAB,
+    eventType: _analytics.EVENT_TYPE.OPERATIONAL,
+    attributes: _objectSpread(_objectSpread({
+      reason: reason
+    }, agentType ? {
+      agentType: agentType
+    } : {}), error ? {
+      error: "".concat(error.name, ": ").concat(error.message)
+    } : {})
+  };
+};
 var addSynchronyEntityAnalytics = exports.addSynchronyEntityAnalytics = function addSynchronyEntityAnalytics(state, tr) {
   return function (type, editorAnalyticsApi) {
     editorAnalyticsApi === null || editorAnalyticsApi === void 0 || editorAnalyticsApi.attachAnalyticsEvent({

package/dist/cjs/pm-plugins/events/handlers.js

@@ -55,7 +55,7 @@ var subscribe = exports.subscribe = effect(function (view, provider, options, fe
       return (0, _actions.handleConnection)(data, view);
     },
     dataHandler: function dataHandler(data) {
-      return (0, _actions.applyRemoteData)(data, view, options);
+      return (0, _actions.applyRemoteData)(data, view, options, editorAnalyticsApi);
     },
     presenceHandler: function presenceHandler(data) {
       return (0, _actions.handlePresence)(data, view);

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

@@ -4,7 +4,7 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 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;
+exports.reduceAgentShimmers = exports.buildAgentShimmerDecorations = exports.ROVO_AGENT_TELEPOINTER_LABEL_CLASS = exports.ROVO_AGENT_TELEPOINTER_CLASS = exports.REMOVE_AGENT_SHIMMER_META = exports.HIGHLIGHT_AGENT_SHIMMER_META = exports.AGENT_SHIMMER_DEFAULT_DURATION_MS = exports.AGENT_SHIMMER_CLASS = exports.AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS = exports.AGENT_EDIT_HIGHLIGHT_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; }
@@ -15,17 +15,31 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 
 /** 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;
+/**
+ * Default time the purple "just edited" highlight stays after the skeleton clears (ms); `0` disables
+ * the highlight phase so the shimmer just reveals the content.
+ */
+var AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS = exports.AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS = 2000;
 
 // 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';
+// Purple "just edited" highlight shown over the range after the skeleton clears — same style as the
+// editor AI "improve writing" in-editor highlight (subtle purple background + dashed purple underline).
+var AGENT_EDIT_HIGHLIGHT_CLASS = exports.AGENT_EDIT_HIGHLIGHT_CLASS = 'collab-agent-edit-highlight';
 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 HIGHLIGHT_AGENT_SHIMMER_META = exports.HIGHLIGHT_AGENT_SHIMMER_META = 'highlightAgentShimmer'; // skeleton → purple highlight phase
 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.
+// A shimmer runs in two phases: the `skeleton` loader, then (optionally) the purple `highlight` over
+// the revealed content, before removal.
+
+// A range an agent step wrote; the shimmer decorations are drawn over `from`..`to` and kept until
+// removal (so positions can be re-mapped). Pure data only. `phase` selects skeleton vs purple
+// highlight. `telepointerLabel` is the label for the trailing agent telepointer (shown through both
+// phases); when absent, no telepointer is shown. `highlightDurationMs` is the purple-highlight
+// lifetime, used to size its ease in/out animation so it matches the removal timer.
 
 // 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).
@@ -47,7 +61,7 @@ var createRovoAgentTelepointer = function createRovoAgentTelepointer(label) {
  * 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 reduceAgentShimmers = exports.reduceAgentShimmers = function reduceAgentShimmers(current, tr, added, removedShimmerId, highlightShimmerId) {
   var next = current;
   var changed = false;
 
@@ -68,6 +82,19 @@ var reduceAgentShimmers = exports.reduceAgentShimmers = function reduceAgentShim
     });
     changed = true;
   }
+  // Transition a shimmer from the skeleton phase to the purple highlight phase (skeleton timer fired).
+  // Guard on an actual match so a timer firing after the shimmer was already removed (superseded by a
+  // new batch, or cleared) doesn't rebuild the array and trigger a pointless decoration rebuild.
+  if (highlightShimmerId && next.some(function (shimmer) {
+    return shimmer.shimmerId === highlightShimmerId;
+  })) {
+    next = next.map(function (shimmer) {
+      return shimmer.shimmerId === highlightShimmerId ? _objectSpread(_objectSpread({}, shimmer), {}, {
+        phase: 'highlight'
+      }) : shimmer;
+    });
+    changed = true;
+  }
   if (removedShimmerId) {
     next = next.filter(function (shimmer) {
       return shimmer.shimmerId !== removedShimmerId;
@@ -81,33 +108,45 @@ var reduceAgentShimmers = exports.reduceAgentShimmers = function reduceAgentShim
 };
 
 /**
- * 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.
+ * Builds the inline decorations (skeleton bar or purple highlight, per phase) plus the trailing
+ * telepointer 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;
+      telepointerLabel = _ref.telepointerLabel,
+      phase = _ref.phase,
+      highlightDurationMs = _ref.highlightDurationMs;
     try {
+      // `getValidPos` already clamps to the last valid position, so only the lower bound needs
+      // guarding here (a raw `from < 1` would throw in `doc.resolve`).
       var validFrom = getValidPos(tr, Math.max(from, 1));
-      var validTo = getValidPos(tr, Math.min(to, docEnd));
+      var validTo = getValidPos(tr, to);
       if (validTo <= validFrom) {
         return;
       }
-      // Skeleton-loader bar over the whole agent-authored range...
-      decorations.push(_view.Decoration.inline(validFrom, validTo, {
-        class: AGENT_SHIMMER_CLASS
-      }, {
+      // Inline decoration over the whole range: the grey skeleton loader, or (once revealed) the
+      // purple "just edited" highlight. The highlight eases in and out over its lifetime via a CSS
+      // animation whose duration is set inline so it matches the removal timer.
+      var isHighlight = phase === 'highlight';
+      var inlineAttrs = {
+        class: isHighlight ? AGENT_EDIT_HIGHLIGHT_CLASS : AGENT_SHIMMER_CLASS
+      };
+      if (isHighlight && highlightDurationMs > 0) {
+        inlineAttrs.style = "animation-duration: ".concat(highlightDurationMs, "ms");
+      }
+      decorations.push(_view.Decoration.inline(validFrom, validTo, inlineAttrs, {
         isAgentShimmer: true,
         shimmerId: shimmerId
       }));
-      // ...and, when enabled, a Rovo AI telepointer/cursor (labelled with the agent's type) at the
-      // end of the range.
+      // Rovo AI telepointer/cursor (labelled with the agent's type) at the end of the range, shown
+      // through BOTH the skeleton and purple-highlight phases so the agent's cursor stays put until
+      // the edit is fully revealed.
       if (telepointerLabel) {
         decorations.push(_view.Decoration.widget(validTo, createRovoAgentTelepointer(telepointerLabel), {
           isAgentShimmer: true,

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

@@ -8,8 +8,9 @@ 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.
+// content. Gated behind the `platform_editor_agent_be_streaming` experiment. `shimmerDurationMs` and
+// `highlightDurationMs` size the skeleton and purple-highlight phases and toggle independently: `0` on
+// either skips that phase, `0` on both shows nothing.
 var agentShimmerIdCounter = 0;
 
 // A step is position-neutral when its StepMap changes no range's length — i.e. it shifts no
@@ -26,6 +27,26 @@ var isPositionNeutralStep = exports.isPositionNeutralStep = function isPositionN
   return neutral;
 };
 
+// Top-level block/position helpers over a doc. Kept at module scope (rather than re-created as
+// closures on every call) so they are defined once, reusable, and unit-testable. Each clamps into
+// valid document coordinates before resolving.
+var clampToDoc = function clampToDoc(doc, pos) {
+  return Math.min(Math.max(pos, 1), doc.content.size);
+};
+var topLevelBlockIndexAt = function topLevelBlockIndexAt(doc, pos) {
+  return doc.resolve(clampToDoc(doc, pos)).index(0);
+};
+// Start of the content of the top-level block containing `pos`, so the whole block is covered.
+var topLevelBlockContentStart = function topLevelBlockContentStart(doc, pos) {
+  var $pos = doc.resolve(clampToDoc(doc, pos));
+  return $pos.depth >= 1 ? $pos.start(1) : pos;
+};
+// End of the content of the top-level block containing `pos`, so the whole block is covered.
+var topLevelBlockContentEnd = function topLevelBlockContentEnd(doc, pos) {
+  var $pos = doc.resolve(clampToDoc(doc, pos));
+  return $pos.depth >= 1 ? $pos.end(1) : pos;
+};
+
 /**
  * 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
@@ -42,15 +63,20 @@ var isPositionNeutralStep = exports.isPositionNeutralStep = function isPositionN
  * 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 getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, tr, view, shimmerDurationMs, highlightDurationMs, telepointerEnabled, onNotShown) {
   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) {
+  // The two phases toggle independently: `shimmerDurationMs` sizes the skeleton, `highlightDurationMs`
+  // sizes the purple highlight, and `0` on either skips just that phase. Nothing to reveal only when
+  // both are off.
+  if (shimmerDurationMs <= 0 && highlightDurationMs <= 0) {
     return [];
   }
+  // Start in the skeleton phase when it's enabled, otherwise straight into the purple highlight phase
+  // (skeleton toggled off, highlight on).
+  var initialPhase = shimmerDurationMs > 0 ? 'skeleton' : 'highlight';
   // 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.
@@ -58,7 +84,11 @@ var getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShi
   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;
+  // No agent-authored steps in this batch — nothing to shimmer, and not a "not shown" case.
+  if (agentType === undefined) {
+    return [];
+  }
+  var telepointerLabel = telepointerEnabled ? 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
@@ -69,6 +99,7 @@ var getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShi
     if (unconfirmed.some(function (entry) {
       return !isPositionNeutralStep(entry.step);
     })) {
+      onNotShown === null || onNotShown === void 0 || onNotShown('rebasedConcurrentEdit', agentType);
       return [];
     }
   }
@@ -108,6 +139,7 @@ var getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShi
       });
     });
     if (!infos.length) {
+      onNotShown === null || onNotShown === void 0 || onNotShown('nothingToShow', agentType);
       return [];
     }
 
@@ -119,28 +151,12 @@ var getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShi
     // 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 block = topLevelBlockIndexAt(tr.doc, info.from);
       var current = groups[groups.length - 1];
       if (current && block <= current.maxBlock + 1) {
         current.to = Math.max(current.to, info.to);
@@ -156,14 +172,17 @@ var getAgentShimmerRanges = exports.getAgentShimmerRanges = function getAgentShi
     return groups.map(function (group) {
       return {
         shimmerId: "agent-shimmer-".concat(agentShimmerIdCounter++),
-        from: blockContentStart(group.from),
-        to: blockContentEnd(group.to),
-        telepointerLabel: telepointerLabel
+        from: topLevelBlockContentStart(tr.doc, group.from),
+        to: topLevelBlockContentEnd(tr.doc, group.to),
+        telepointerLabel: telepointerLabel,
+        phase: initialPhase,
+        highlightDurationMs: highlightDurationMs
       };
     });
-  } catch (_unused) {
+  } catch (err) {
     // Never let shimmer range derivation throw into the shared remote-step handler; degrade to no
     // shimmer.
+    onNotShown === null || onNotShown === void 0 || onNotShown('captureThrew', agentType, err);
     return [];
   }
 };

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

@@ -97,6 +97,7 @@ var PluginState = exports.PluginState = /*#__PURE__*/function () {
       var nudgeTelepointerData = tr.getMeta('nudgeTelepointer');
       var agentShimmerData = tr.getMeta(_agentShimmerDecorations.ADD_AGENT_SHIMMER_META);
       var removeAgentShimmerId = tr.getMeta(_agentShimmerDecorations.REMOVE_AGENT_SHIMMER_META);
+      var highlightAgentShimmerId = tr.getMeta(_agentShimmerDecorations.HIGHLIGHT_AGENT_SHIMMER_META);
       var sessionIdData = tr.getMeta('sessionId');
       var collabInitialised = tr.getMeta('collabInitialised');
       if (typeof collabInitialised !== 'boolean') {
@@ -239,7 +240,7 @@ var PluginState = exports.PluginState = /*#__PURE__*/function () {
       // 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),
+        var _reduceAgentShimmers = (0, _agentShimmerDecorations.reduceAgentShimmers)(this.agentShimmers, tr, agentShimmerData, removeAgentShimmerId, highlightAgentShimmerId),
           changed = _reduceAgentShimmers.changed,
           next = _reduceAgentShimmers.next;
         if (changed) {