@atlaskit/editor-plugin-collab-edit 13.1.2 → 13.2.0

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

@@ -9,7 +9,8 @@ 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 { getAgentEditShimmerNotShownPayload } from './analytics';
+import { ADD_AGENT_SHIMMER_META, AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS, AGENT_SHIMMER_DEFAULT_DURATION_MS, HIGHLIGHT_AGENT_SHIMMER_META, REMOVE_AGENT_SHIMMER_META } from './main/agent-shimmer-decorations';
 import { getAgentShimmerRanges } from './main/agent-shimmer-ranges';
 import { replaceDocument } from './utils';
 
@@ -35,7 +36,7 @@ export const handleInit = (initData, view, options, editorAnalyticsApi) => {
     tr.setMeta('isRemote', true);
     view.dispatch(tr);
   } else if (json) {
-    applyRemoteSteps(json, view);
+    applyRemoteSteps(json, view, undefined, options, editorAnalyticsApi);
   }
 };
 export const handleConnection = (connectionData, view) => {
@@ -54,16 +55,16 @@ export const handlePresence = (presenceData, view) => {
   } = view;
   view.dispatch(tr.setMeta('presence', presenceData));
 };
-export const applyRemoteData = (remoteData, view, options) => {
+export const applyRemoteData = (remoteData, view, options, editorAnalyticsApi) => {
   const {
     json,
     userIds = []
   } = remoteData;
   if (json) {
-    applyRemoteSteps(json, view, userIds, options);
+    applyRemoteSteps(json, view, userIds, options, editorAnalyticsApi);
   }
 };
-export const applyRemoteSteps = (json, view, userIds, options) => {
+export const applyRemoteSteps = (json, view, userIds, options, editorAnalyticsApi) => {
   if (!json || !json.length) {
     return;
   }
@@ -88,16 +89,26 @@ export const applyRemoteSteps = (json, view, userIds, options) => {
     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;
+    // 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.
+    let shimmerDurationMs = 0;
+    let highlightDurationMs = 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);
+      // 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 = expVal('platform_editor_agent_be_streaming', 'shimmerDurationMs', 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 = expVal('platform_editor_agent_be_streaming', 'highlightDurationMs', AGENT_EDIT_HIGHLIGHT_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);
+      agentShimmers = 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.
+      (reason, agentType, error) => editorAnalyticsApi === null || editorAnalyticsApi === void 0 ? void 0 : editorAnalyticsApi.attachAnalyticsEvent(getAgentEditShimmerNotShownPayload(reason, agentType, error))(tr));
       if (agentShimmers.length) {
         tr.setMeta(ADD_AGENT_SHIMMER_META, agentShimmers);
       }
@@ -113,23 +124,46 @@ export const applyRemoteSteps = (json, view, userIds, options) => {
     }
     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) {
+      let tornDownReported = false;
       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.
+          // 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 ? void 0 : editorAnalyticsApi.fireAnalyticsEvent(getAgentEditShimmerNotShownPayload('tornDownMidAnimation'));
+          }
         }
       };
       agentShimmers.forEach(({
         shimmerId
       }) => {
-        setTimeout(() => {
-          dispatchMeta(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(() => {
+            if (highlightDurationMs > 0) {
+              dispatchMeta(HIGHLIGHT_AGENT_SHIMMER_META, shimmerId);
+              setTimeout(() => {
+                dispatchMeta(REMOVE_AGENT_SHIMMER_META, shimmerId);
+              }, highlightDurationMs);
+            } else {
+              dispatchMeta(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(() => {
+            dispatchMeta(REMOVE_AGENT_SHIMMER_META, shimmerId);
+          }, highlightDurationMs);
+        }
       });
     }
   }

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

@@ -26,6 +26,29 @@ export const addSynchronyErrorAnalytics = (state, tr, featureFlags, editorAnalyt
     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).
+ */
+export const getAgentEditShimmerNotShownPayload = (reason, agentType, error) => ({
+  action: ACTION.AGENT_EDIT_SHIMMER_NOT_SHOWN,
+  actionSubject: ACTION_SUBJECT.COLLAB,
+  eventType: EVENT_TYPE.OPERATIONAL,
+  attributes: {
+    reason,
+    // Spread conditionally so absent context isn't emitted as `undefined` (the teardown path has no
+    // single agent, and non-throw reasons have no error).
+    ...(agentType ? {
+      agentType
+    } : {}),
+    ...(error ? {
+      error: `${error.name}: ${error.message}`
+    } : {})
+  }
+});
 export const addSynchronyEntityAnalytics = (state, tr) => {
   return (type, editorAnalyticsApi) => {
     editorAnalyticsApi === null || editorAnalyticsApi === void 0 ? void 0 : editorAnalyticsApi.attachAnalyticsEvent({

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

@@ -44,7 +44,7 @@ export const subscribe = effect((view, provider, options, featureFlags, _provide
       handleInit(data, view, options, editorAnalyticsApi);
     },
     connectedHandler: data => handleConnection(data, view),
-    dataHandler: data => applyRemoteData(data, view, options),
+    dataHandler: data => applyRemoteData(data, view, options, editorAnalyticsApi),
     presenceHandler: data => handlePresence(data, view),
     telepointerHandler: data => handleTelePointer(data, view),
     localStepsHandler: data => {

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

@@ -6,17 +6,31 @@ import { Decoration } from '@atlaskit/editor-prosemirror/view';
 
 /** Default time the skeleton shimmer stays on the agent-authored content (ms). */
 export const 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.
+ */
+export const AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS = 2000;
 
 // Skeleton-loader bar over the agent-authored range, plus a Rovo AI telepointer at the end.
 export const 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).
+export const AGENT_EDIT_HIGHLIGHT_CLASS = 'collab-agent-edit-highlight';
 export const ROVO_AGENT_TELEPOINTER_CLASS = 'ai-in-editor-telepointer';
 export const ROVO_AGENT_TELEPOINTER_LABEL_CLASS = 'ai-in-editor-telepointer-label';
 export const ADD_AGENT_SHIMMER_META = 'addAgentShimmer'; // register the shimmer decorations
+export const HIGHLIGHT_AGENT_SHIMMER_META = 'highlightAgentShimmer'; // skeleton → purple highlight phase
 export const 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).
@@ -38,7 +52,7 @@ const 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.
  */
-export const reduceAgentShimmers = (current, tr, added, removedShimmerId) => {
+export const reduceAgentShimmers = (current, tr, added, removedShimmerId, highlightShimmerId) => {
   let next = current;
   let changed = false;
 
@@ -58,6 +72,16 @@ export const reduceAgentShimmers = (current, tr, added, removedShimmerId) => {
     }));
     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(shimmer => shimmer.shimmerId === highlightShimmerId)) {
+    next = next.map(shimmer => shimmer.shimmerId === highlightShimmerId ? {
+      ...shimmer,
+      phase: 'highlight'
+    } : shimmer);
+    changed = true;
+  }
   if (removedShimmerId) {
     next = next.filter(shimmer => shimmer.shimmerId !== removedShimmerId);
     changed = true;
@@ -69,34 +93,46 @@ export const reduceAgentShimmers = (current, tr, added, removedShimmerId) => {
 };
 
 /**
- * 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.
  */
 export const buildAgentShimmerDecorations = (tr, shimmers, getValidPos, onError) => {
   const decorations = [];
-  const docEnd = tr.doc.nodeSize - 2;
   shimmers.forEach(({
     shimmerId,
     from,
     to,
-    telepointerLabel
+    telepointerLabel,
+    phase,
+    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`).
       const validFrom = getValidPos(tr, Math.max(from, 1));
-      const validTo = getValidPos(tr, Math.min(to, docEnd));
+      const validTo = getValidPos(tr, to);
       if (validTo <= validFrom) {
         return;
       }
-      // Skeleton-loader bar over the whole agent-authored range...
-      decorations.push(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.
+      const isHighlight = phase === 'highlight';
+      const inlineAttrs = {
+        class: isHighlight ? AGENT_EDIT_HIGHLIGHT_CLASS : AGENT_SHIMMER_CLASS
+      };
+      if (isHighlight && highlightDurationMs > 0) {
+        inlineAttrs.style = `animation-duration: ${highlightDurationMs}ms`;
+      }
+      decorations.push(Decoration.inline(validFrom, validTo, inlineAttrs, {
         isAgentShimmer: true,
         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(Decoration.widget(validTo, createRovoAgentTelepointer(telepointerLabel), {
           isAgentShimmer: true,

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

@@ -2,8 +2,9 @@ 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.
+// 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.
 let agentShimmerIdCounter = 0;
 
 // A step is position-neutral when its StepMap changes no range's length — i.e. it shifts no
@@ -20,6 +21,22 @@ export const isPositionNeutralStep = step => {
   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.
+const clampToDoc = (doc, pos) => Math.min(Math.max(pos, 1), doc.content.size);
+const topLevelBlockIndexAt = (doc, pos) => doc.resolve(clampToDoc(doc, pos)).index(0);
+// Start of the content of the top-level block containing `pos`, so the whole block is covered.
+const topLevelBlockContentStart = (doc, pos) => {
+  const $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.
+const topLevelBlockContentEnd = (doc, pos) => {
+  const $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
@@ -36,21 +53,30 @@ export const isPositionNeutralStep = step => {
  * 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 const getAgentShimmerRanges = (json, steps, tr, view, durationMs, telepointerEnabled) => {
+export const getAgentShimmerRanges = (json, steps, tr, view, shimmerDurationMs, highlightDurationMs, telepointerEnabled, onNotShown) => {
   var _json$find;
   if (!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).
+  const 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.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const agentType = (_json$find = json.find(step => typeof (step === null || step === void 0 ? void 0 : step.agentType) === 'string')) === null || _json$find === void 0 ? void 0 : _json$find.agentType;
-  const 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 [];
+  }
+  const 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
@@ -59,6 +85,7 @@ export const getAgentShimmerRanges = (json, steps, tr, view, durationMs, telepoi
     var _getCollabState$uncon, _getCollabState;
     const 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(entry => !isPositionNeutralStep(entry.step))) {
+      onNotShown === null || onNotShown === void 0 ? void 0 : onNotShown('rebasedConcurrentEdit', agentType);
       return [];
     }
   }
@@ -98,6 +125,7 @@ export const getAgentShimmerRanges = (json, steps, tr, view, durationMs, telepoi
       });
     });
     if (!infos.length) {
+      onNotShown === null || onNotShown === void 0 ? void 0 : onNotShown('nothingToShow', agentType);
       return [];
     }
 
@@ -109,22 +137,10 @@ export const getAgentShimmerRanges = (json, steps, tr, view, durationMs, telepoi
     // 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.
-    const docSize = tr.doc.content.size;
-    const clampPos = pos => Math.min(Math.max(pos, 1), docSize);
-    const blockIndexAt = pos => 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.
-    const blockContentStart = pos => {
-      const $pos = tr.doc.resolve(clampPos(pos));
-      return $pos.depth >= 1 ? $pos.start(1) : pos;
-    };
-    const blockContentEnd = pos => {
-      const $pos = tr.doc.resolve(clampPos(pos));
-      return $pos.depth >= 1 ? $pos.end(1) : pos;
-    };
     const sorted = [...infos].sort((a, b) => a.from - b.from || a.to - b.to);
     const groups = [];
     sorted.forEach(info => {
-      const block = blockIndexAt(info.from);
+      const block = topLevelBlockIndexAt(tr.doc, info.from);
       const current = groups[groups.length - 1];
       if (current && block <= current.maxBlock + 1) {
         current.to = Math.max(current.to, info.to);
@@ -139,13 +155,16 @@ export const getAgentShimmerRanges = (json, steps, tr, view, durationMs, telepoi
     });
     return groups.map(group => ({
       shimmerId: `agent-shimmer-${agentShimmerIdCounter++}`,
-      from: blockContentStart(group.from),
-      to: blockContentEnd(group.to),
-      telepointerLabel
+      from: topLevelBlockContentStart(tr.doc, group.from),
+      to: topLevelBlockContentEnd(tr.doc, group.to),
+      telepointerLabel,
+      phase: initialPhase,
+      highlightDurationMs
     }));
-  } catch {
+  } catch (err) {
     // Never let shimmer range derivation throw into the shared remote-step handler; degrade to no
     // shimmer.
+    onNotShown === null || onNotShown === void 0 ? void 0 : onNotShown('captureThrew', agentType, err);
     return [];
   }
 };

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

@@ -5,7 +5,7 @@ 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';
+import { ADD_AGENT_SHIMMER_META, buildAgentShimmerDecorations, HIGHLIGHT_AGENT_SHIMMER_META, reduceAgentShimmers, REMOVE_AGENT_SHIMMER_META } from './agent-shimmer-decorations';
 
 /**
  * Returns position where it's possible to place a decoration.
@@ -69,6 +69,7 @@ export class PluginState {
     const nudgeTelepointerData = tr.getMeta('nudgeTelepointer');
     const agentShimmerData = tr.getMeta(ADD_AGENT_SHIMMER_META);
     const removeAgentShimmerId = tr.getMeta(REMOVE_AGENT_SHIMMER_META);
+    const highlightAgentShimmerId = tr.getMeta(HIGHLIGHT_AGENT_SHIMMER_META);
     const sessionIdData = tr.getMeta('sessionId');
     let collabInitialised = tr.getMeta('collabInitialised');
     if (typeof collabInitialised !== 'boolean') {
@@ -224,7 +225,7 @@ export class PluginState {
       const {
         changed,
         next
-      } = reduceAgentShimmers(this.agentShimmers, tr, agentShimmerData, removeAgentShimmerId);
+      } = reduceAgentShimmers(this.agentShimmers, tr, agentShimmerData, removeAgentShimmerId, highlightAgentShimmerId);
       if (changed) {
         // Build into local arrays; only merge into the shared add/remove once the block succeeds.
         const agentRemove = this.decorationSet.find(undefined, undefined, spec => spec.isAgentShimmer);

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

@@ -9,7 +9,8 @@ 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 { getAgentEditShimmerNotShownPayload } from './analytics';
+import { ADD_AGENT_SHIMMER_META, AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS, AGENT_SHIMMER_DEFAULT_DURATION_MS, HIGHLIGHT_AGENT_SHIMMER_META, REMOVE_AGENT_SHIMMER_META } from './main/agent-shimmer-decorations';
 import { getAgentShimmerRanges } from './main/agent-shimmer-ranges';
 import { replaceDocument } from './utils';
 
@@ -31,7 +32,7 @@ export var handleInit = function handleInit(initData, view, options, editorAnaly
     tr.setMeta('isRemote', true);
     view.dispatch(tr);
   } else if (json) {
-    applyRemoteSteps(json, view);
+    applyRemoteSteps(json, view, undefined, options, editorAnalyticsApi);
   }
 };
 export var handleConnection = function handleConnection(connectionData, view) {
@@ -42,15 +43,15 @@ export var handlePresence = function handlePresence(presenceData, view) {
   var tr = view.state.tr;
   view.dispatch(tr.setMeta('presence', presenceData));
 };
-export var applyRemoteData = function applyRemoteData(remoteData, view, options) {
+export var 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);
   }
 };
-export var applyRemoteSteps = function applyRemoteSteps(json, view, userIds, options) {
+export var applyRemoteSteps = function applyRemoteSteps(json, view, userIds, options, editorAnalyticsApi) {
   if (!json || !json.length) {
     return;
   }
@@ -75,16 +76,28 @@ export var applyRemoteSteps = function applyRemoteSteps(json, view, userIds, opt
     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 (expValEquals('platform_editor_agent_be_streaming', 'isEnabled', true)) {
-      durationMs = expVal('platform_editor_agent_be_streaming', 'durationMs', 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 = expVal('platform_editor_agent_be_streaming', 'shimmerDurationMs', 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 = expVal('platform_editor_agent_be_streaming', 'highlightDurationMs', 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 = !expVal('platform_editor_agent_be_streaming', 'telepointerDisabled', false);
-      agentShimmers = getAgentShimmerRanges(json, steps, tr, view, durationMs, telepointerEnabled);
+      agentShimmers = 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(getAgentEditShimmerNotShownPayload(reason, agentType, error))(tr);
+      });
       if (agentShimmers.length) {
         tr.setMeta(ADD_AGENT_SHIMMER_META, agentShimmers);
       }
@@ -100,22 +113,45 @@ export var applyRemoteSteps = function applyRemoteSteps(json, view, userIds, opt
     }
     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(getAgentEditShimmerNotShownPayload('tornDownMidAnimation'));
+          }
         }
       };
       agentShimmers.forEach(function (_ref) {
         var shimmerId = _ref.shimmerId;
-        setTimeout(function () {
-          dispatchMeta(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(HIGHLIGHT_AGENT_SHIMMER_META, shimmerId);
+              setTimeout(function () {
+                dispatchMeta(REMOVE_AGENT_SHIMMER_META, shimmerId);
+              }, highlightDurationMs);
+            } else {
+              dispatchMeta(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(REMOVE_AGENT_SHIMMER_META, shimmerId);
+          }, highlightDurationMs);
+        }
       });
     }
   }

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

@@ -1,3 +1,6 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+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) { _defineProperty(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; }
 import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
 import { getDocStructure } from '@atlaskit/editor-common/core-utils';
 import { sniffUserBrowserExtensions } from '@atlaskit/editor-common/utils';
@@ -26,6 +29,27 @@ export var addSynchronyErrorAnalytics = function addSynchronyErrorAnalytics(stat
     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).
+ */
+export var getAgentEditShimmerNotShownPayload = function getAgentEditShimmerNotShownPayload(reason, agentType, error) {
+  return {
+    action: ACTION.AGENT_EDIT_SHIMMER_NOT_SHOWN,
+    actionSubject: ACTION_SUBJECT.COLLAB,
+    eventType: EVENT_TYPE.OPERATIONAL,
+    attributes: _objectSpread(_objectSpread({
+      reason: reason
+    }, agentType ? {
+      agentType: agentType
+    } : {}), error ? {
+      error: "".concat(error.name, ": ").concat(error.message)
+    } : {})
+  };
+};
 export var addSynchronyEntityAnalytics = function addSynchronyEntityAnalytics(state, tr) {
   return function (type, editorAnalyticsApi) {
     editorAnalyticsApi === null || editorAnalyticsApi === void 0 || editorAnalyticsApi.attachAnalyticsEvent({

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

@@ -50,7 +50,7 @@ export var subscribe = effect(function (view, provider, options, featureFlags, _
       return handleConnection(data, view);
     },
     dataHandler: function dataHandler(data) {
-      return applyRemoteData(data, view, options);
+      return applyRemoteData(data, view, options, editorAnalyticsApi);
     },
     presenceHandler: function presenceHandler(data) {
       return handlePresence(data, view);