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

package/dist/esm/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.
 var agentShimmerIdCounter = 0;
 
 // A step is position-neutral when its StepMap changes no range's length — i.e. it shifts no
@@ -20,6 +21,26 @@ export var isPositionNeutralStep = function 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.
+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
@@ -36,15 +57,20 @@ export var isPositionNeutralStep = function 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 var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, tr, view, durationMs, telepointerEnabled) {
+export var getAgentShimmerRanges = function 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).
+  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.
@@ -52,7 +78,11 @@ export var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, t
   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
@@ -63,6 +93,7 @@ export var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, t
     if (unconfirmed.some(function (entry) {
       return !isPositionNeutralStep(entry.step);
     })) {
+      onNotShown === null || onNotShown === void 0 || onNotShown('rebasedConcurrentEdit', agentType);
       return [];
     }
   }
@@ -102,6 +133,7 @@ export var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, t
       });
     });
     if (!infos.length) {
+      onNotShown === null || onNotShown === void 0 || onNotShown('nothingToShow', agentType);
       return [];
     }
 
@@ -113,28 +145,12 @@ export var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, t
     // 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);
@@ -150,14 +166,17 @@ export var getAgentShimmerRanges = function getAgentShimmerRanges(json, steps, t
     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/esm/pm-plugins/main/plugin-state.js

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

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

@@ -7,7 +7,7 @@ export declare const registerAllCustomSteps: () => void;
 export declare const handleInit: (initData: CollabEventInitData, view: EditorView, options?: PrivateCollabEditOptions, editorAnalyticsApi?: EditorAnalyticsAPI) => void;
 export declare const handleConnection: (connectionData: CollabEventConnectionData, view: EditorView) => void;
 export declare const handlePresence: (presenceData: CollabEventPresenceData, view: EditorView) => void;
-export declare const applyRemoteData: (remoteData: CollabEventRemoteData, view: EditorView, options: PrivateCollabEditOptions) => void;
-export declare const applyRemoteSteps: (json: any[], view: EditorView, userIds?: (number | string)[], options?: PrivateCollabEditOptions) => void;
+export declare const applyRemoteData: (remoteData: CollabEventRemoteData, view: EditorView, options: PrivateCollabEditOptions, editorAnalyticsApi?: EditorAnalyticsAPI) => void;
+export declare const applyRemoteSteps: (json: any[], view: EditorView, userIds?: (number | string)[], options?: PrivateCollabEditOptions, editorAnalyticsApi?: EditorAnalyticsAPI) => void;
 export declare const handleTelePointer: (telepointerData: CollabTelepointerPayload, view: EditorView) => void;
 export declare const getSendableSelection: (selection: Selection) => CollabSendableSelection;

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

@@ -1,6 +1,14 @@
-import type { EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics';
+import type { AnalyticsEventPayload, EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics';
+import type { AgentEditShimmerNotShownReason } from '@atlaskit/editor-common/analytics/types/agent-edit-shimmer-events';
 import type { FeatureFlags } from '@atlaskit/editor-common/types';
 import type { EditorState, Transaction } from '@atlaskit/editor-prosemirror/state';
 export declare const addSynchronyErrorAnalytics: (state: EditorState, tr: Transaction, featureFlags: FeatureFlags, editorAnalyticsApi: EditorAnalyticsAPI | undefined) => (error: Error) => Transaction;
+/**
+ * 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 declare const getAgentEditShimmerNotShownPayload: (reason: AgentEditShimmerNotShownReason, agentType?: string, error?: Error) => AnalyticsEventPayload;
 export type EntityEventType = 'error' | 'disconnected';
 export declare const addSynchronyEntityAnalytics: (state: EditorState, tr: Transaction) => (type: EntityEventType, editorAnalyticsApi: EditorAnalyticsAPI | undefined) => Transaction;

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

@@ -2,13 +2,23 @@ import type { ReadonlyTransaction } from '@atlaskit/editor-prosemirror/state';
 import { Decoration } from '@atlaskit/editor-prosemirror/view';
 /** Default time the skeleton shimmer stays on the agent-authored content (ms). */
 export declare const AGENT_SHIMMER_DEFAULT_DURATION_MS = 3000;
+/**
+ * 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 declare const AGENT_EDIT_HIGHLIGHT_DEFAULT_DURATION_MS = 2000;
 export declare const AGENT_SHIMMER_CLASS = "collab-agent-shimmer";
+export declare const AGENT_EDIT_HIGHLIGHT_CLASS = "collab-agent-edit-highlight";
 export declare const ROVO_AGENT_TELEPOINTER_CLASS = "ai-in-editor-telepointer";
 export declare const ROVO_AGENT_TELEPOINTER_LABEL_CLASS = "ai-in-editor-telepointer-label";
 export declare const ADD_AGENT_SHIMMER_META = "addAgentShimmer";
+export declare const HIGHLIGHT_AGENT_SHIMMER_META = "highlightAgentShimmer";
 export declare const REMOVE_AGENT_SHIMMER_META = "removeAgentShimmer";
+export type AgentShimmerPhase = 'skeleton' | 'highlight';
 export type AgentShimmerRange = {
     from: number;
+    highlightDurationMs: number;
+    phase: AgentShimmerPhase;
     shimmerId: string;
     telepointerLabel?: string;
     to: number;
@@ -19,13 +29,14 @@ export type AgentShimmerRange = {
  * supersedes any still-in-flight shimmer), and drops a range when its removal timer fires. Returns a
  * fresh array (never mutates in place) plus whether anything changed.
  */
-export declare const reduceAgentShimmers: (current: AgentShimmerRange[], tr: ReadonlyTransaction, added: AgentShimmerRange[] | undefined, removedShimmerId: string | undefined) => {
+export declare const reduceAgentShimmers: (current: AgentShimmerRange[], tr: ReadonlyTransaction, added: AgentShimmerRange[] | undefined, removedShimmerId: string | undefined, highlightShimmerId: string | undefined) => {
     changed: boolean;
     next: AgentShimmerRange[];
 };
 /**
- * Builds the inline skeleton-bar + trailing telepointer decorations for the active shimmer ranges.
- * `getValidPos` clamps a raw position to a valid decoration position (owned by `plugin-state`).
- * One bad range is isolated via `onError` so it can't kill the others.
+ * 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 declare const buildAgentShimmerDecorations: (tr: ReadonlyTransaction, shimmers: AgentShimmerRange[], getValidPos: (tr: ReadonlyTransaction, pos: number) => number, onError: (err: Error) => void) => Decoration[];

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

@@ -1,3 +1,4 @@
+import type { AgentEditShimmerNotShownReason } from '@atlaskit/editor-common/analytics/types/agent-edit-shimmer-events';
 import type { Transaction } from '@atlaskit/editor-prosemirror/state';
 import type { Step } from '@atlaskit/editor-prosemirror/transform';
 import type { EditorView } from '@atlaskit/editor-prosemirror/view';
@@ -19,4 +20,4 @@ export declare const isPositionNeutralStep: (step: Step) => boolean;
  * rebased local step changed sizes (a rare, safe degrade). Any unexpected error also degrades to no
  * shimmer, so this never throws into the shared remote-step handler.
  */
-export declare const getAgentShimmerRanges: (json: any[], steps: Step[], tr: Transaction, view: EditorView, durationMs: number, telepointerEnabled: boolean) => AgentShimmerRange[];
+export declare const getAgentShimmerRanges: (json: any[], steps: Step[], tr: Transaction, view: EditorView, shimmerDurationMs: number, highlightDurationMs: number, telepointerEnabled: boolean, onNotShown?: (reason: AgentEditShimmerNotShownReason, agentType?: string, error?: Error) => void) => AgentShimmerRange[];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-collab-edit",
-	"version": "13.1.3",
+	"version": "13.2.0",
 	"description": "Collab Edit plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -37,7 +37,7 @@
 		"memoize-one": "^6.0.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^116.41.0",
+		"@atlaskit/editor-common": "^116.42.0",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0"
 	},