@atlaskit/editor-plugin-collab-edit 13.3.1 → 13.4.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @atlaskit/editor-plugin-collab-edit
 
+## 13.4.1
+
+### Patch Changes
+
+- Updated dependencies
+
+## 13.4.0
+
+### Minor Changes
+
+- [`95e5e100318c4`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/95e5e100318c4) -
+  Review moment (Post Stream Review) for BE streaming — record remote agent edits into
+  aiContentPositions and open/append the Review moment (hybrid completion signal + idle debounce).
+  - New `@atlaskit/editor-common/collab/agent-remote-edit-review` subpath export for the neutral
+    agent-edit review contract (AGENT_REMOTE_EDIT_REVIEW_DATA, AgentRemoteEditReviewSegment,
+    AgentRemoteEditReviewData).
+  - Fix chimera delete diffs in agent-review-segments: per-step backward StepMap mapping replaces
+    the previous group-then-invert approach that produced blended original text when multiple
+    discrete operations (delete + insert) interacted in the same region.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 13.3.1
 
 ### Patch Changes

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

@@ -7,12 +7,14 @@ Object.defineProperty(exports, "__esModule", {
 exports.registerAllCustomSteps = exports.handleTelePointer = exports.handlePresence = exports.handleInit = exports.handleConnection = exports.getSendableSelection = exports.applyRemoteSteps = exports.applyRemoteData = void 0;
 var allAdfSchemaSteps = _interopRequireWildcard(require("@atlaskit/adf-schema/steps"));
 var allAtlaskitCustomSteps = _interopRequireWildcard(require("@atlaskit/custom-steps"));
+var _collabAgentRemoteEditReview = require("@atlaskit/editor-common/collab-agent-remote-edit-review");
 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 _analytics = require("./analytics");
+var _agentReviewSegments = require("./main/agent-review-segments");
 var _agentShimmerDecorations = require("./main/agent-shimmer-decorations");
 var _agentShimmerRanges = require("./main/agent-shimmer-ranges");
 var _utils = require("./utils");
@@ -112,6 +114,21 @@ var applyRemoteSteps = exports.applyRemoteSteps = function applyRemoteSteps(json
       }
     }
 
+    // [CCI-17994] Post Stream Review ("Review moment") for BE streaming. Record what
+    // the agent just wrote (original + new slice per contiguous change) onto this same
+    // transaction. `editor-plugin-ai` consumes this neutral meta to populate
+    // `aiContentPositions` and — only on the requester's client — open the Review
+    // moment once the edit settles. Gated on `platform_editor_agent_be_streaming`
+    // alongside shimmer; `getAgentEditSegments` also self-gates by returning null
+    // unless the batch contains agent-authored steps (and never throws), so this is
+    // a no-op for ordinary collaborator edits and can't affect step application.
+    if ((0, _expValEquals.expValEquals)('platform_editor_agent_be_streaming', 'isEnabled', true)) {
+      var reviewData = (0, _agentReviewSegments.getAgentEditSegments)(json, steps, tr, view);
+      if (reviewData) {
+        tr.setMeta(_collabAgentRemoteEditReview.AGENT_REMOTE_EDIT_REVIEW_DATA, reviewData);
+      }
+    }
+
     /*
      * Persist marks across transactions. Fixes an issue where
      * marks are lost if remote transactions are dispatched

package/dist/cjs/pm-plugins/main/agent-review-segments.js

@@ -0,0 +1,178 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAgentEditSegments = void 0;
+var _prosemirrorCollab = require("@atlaskit/prosemirror-collab");
+var _agentShimmerRanges = require("./agent-shimmer-ranges");
+// [CCI-17994] Post Stream Review ("Review moment") recording for BE streaming.
+//
+// Sibling to `getAgentShimmerRanges`: same idea of deriving what the agent wrote
+// from a received remote-step batch, but for a DIFFERENT consumer. The shimmer
+// only needs the NEW extent of added content (to draw a skeleton), so it drops
+// pure deletions and expands to whole blocks. The Review moment instead needs, per
+// contiguous change, BOTH the original slice (pre-edit, for undo / "compare with
+// original") and the new slice (for redo), AND it must keep deletions (a removed
+// paragraph is a reviewable change). So this derives the actual changed extents
+// and reconstructs the pre-edit slice from `tr.before`.
+//
+// The output is a neutral `AgentRemoteEditReviewData` (contract in editor-common);
+// `editor-plugin-ai`'s session-context plugin turns each segment into a coarse
+// `aiContentPositions` entry, reusing the entire FE Review moment pipeline.
+
+var clampToDoc = function clampToDoc(doc, pos) {
+  return Math.min(Math.max(pos, 0), doc.content.size);
+};
+
+// Map a position in doc_{i+1} forward through the remaining steps to final-doc
+// coords. Mirrors the shimmer's `mapToFinalDoc` — a later step's own inserted
+// content starts at its `from`; only subsequent steps shift it.
+var mapToFinalDoc = function mapToFinalDoc(steps, 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 per-change Review moment segments from an agent-authored remote-step
+ * batch. Returns `null` when there is nothing to record (no agent steps, or a
+ * rebase invalidated our index math, or derivation threw) so the caller can no-op
+ * safely — this must never throw into the shared remote-step handler.
+ *
+ * @param json  the raw received step JSON (carries `agentType` / `agentId` / `userId`)
+ * @param steps the parsed PM steps (index-aligned with `json`)
+ * @param tr    the transaction that applied `steps` (so `tr.before`/`tr.doc`/`tr.mapping` are available)
+ * @param view  the editor view (for the collab rebase guard)
+ */
+var getAgentEditSegments = exports.getAgentEditSegments = function getAgentEditSegments(json, steps, tr, view) {
+  // `agentType` present ⇒ agent-authored (per the NCS↔Editor steps contract). Read
+  // from the first agent step; it is identical across a batch.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  var agentStep = json.find(function (step) {
+    return typeof (step === null || step === void 0 ? void 0 : step.agentType) === 'string';
+  });
+  var agentType = agentStep === null || agentStep === void 0 ? void 0 : agentStep.agentType;
+  if (agentType === undefined) {
+    return null;
+  }
+  // The user the agent acted on behalf of (the requester). Optional/additive on the
+  // step contract, so it may be absent.
+  var actorUserId = typeof (agentStep === null || agentStep === void 0 ? void 0 : agentStep.userId) === 'string' ? agentStep.userId : undefined;
+  // Which agent instance wrote the batch. Additive on the step contract like
+  // `userId`, so treat it as optional. Carried for contract clarity / future
+  // per-agent attribution; nothing consumes it yet.
+  var agentId = typeof (agentStep === null || agentStep === void 0 ? void 0 : agentStep.agentId) === 'string' ? agentStep.agentId : undefined;
+  // Hybrid end-of-edit seam: if the BE/NCS flags a batch as the terminal one, carry
+  // it so the AI plugin can open review immediately instead of waiting for the
+  // debounce. Additive marker; absent for streaming (non-final) batches.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  var complete = json.some(function (step) {
+    return (step === null || step === void 0 ? void 0 : step.agentEditComplete) === true;
+  });
+
+  // Same rebase guard as the shimmer: index-based range math is only valid if any
+  // rebased-over local steps shifted no positions. Degrade to no recording otherwise.
+  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 !(0, _agentShimmerRanges.isPositionNeutralStep)(entry.step);
+    })) {
+      return null;
+    }
+  }
+  try {
+    // Compute one segment per step-level StepMap range. Each agent step's changed
+    // extent is taken from its StepMap (the canonical, step-type-agnostic source).
+    // Unlike the shimmer we KEEP zero-width new extents — a pure deletion has
+    // `newEnd === newStart` but is a reviewable `remove`.
+    //
+    // We derive the originalSlice/newSlice PER RANGE (per step) rather than
+    // grouping ranges first and then inverting over a merged range. Grouping
+    // before slicing corrupts the invert-mapping: when multiple discrete
+    // operations (e.g. two deleteNode + one insertNodeAfter) are merged into one
+    // range, mapping that merged range back through the inverted mapping produces
+    // a chimera — a blend of old and new text that never existed in the document.
+    //
+    // The downstream PSR pipeline (mergeOverlappingSegments +
+    // calculateTopLevelNodeSegments) already handles overlapping/adjacent coarse
+    // entries correctly, so grouping here is unnecessary.
+
+    var segments = [];
+    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) {
+        try {
+          // NEW-doc coordinates: map this step's newStart/newEnd forward
+          // through all subsequent steps to get final-doc positions.
+          var finalFrom = mapToFinalDoc(steps, newStart, index, -1);
+          var finalTo = mapToFinalDoc(steps, newEnd, index, 1);
+          var newFrom = clampToDoc(tr.doc, Math.min(finalFrom, finalTo));
+          var newTo = clampToDoc(tr.doc, Math.max(finalFrom, finalTo));
+
+          // ORIGINAL-doc coordinates: map this step's oldStart/oldEnd
+          // BACKWARD through all preceding steps to get pre-batch
+          // (`tr.before`) positions. Each preceding step's StepMap tells
+          // us how positions shifted; we invert that shift by mapping
+          // through the inverted StepMap.
+          //
+          // This is the key difference from using `tr.mapping.invert()`
+          // which inverts ALL steps at once — that produces chimera text
+          // when multiple discrete operations (delete + delete + insert)
+          // interact in the same region. Per-step backward mapping keeps
+          // each operation's original range isolated.
+          var origStart = oldStart;
+          var origEnd = oldEnd;
+          for (var j = index - 1; j >= 0; j--) {
+            var prevMap = steps[j].getMap().invert();
+            origStart = prevMap.map(origStart, -1);
+            origEnd = prevMap.map(origEnd, 1);
+          }
+          var origFrom = clampToDoc(tr.before, Math.min(origStart, origEnd));
+          var origTo = clampToDoc(tr.before, Math.max(origStart, origEnd));
+          var originalSlice = tr.before.slice(origFrom, origTo);
+          var newSlice = tr.doc.slice(newFrom, newTo);
+          var originalEmpty = originalSlice.content.size === 0;
+          var newEmpty = newSlice.content.size === 0;
+          // A truly empty-to-empty region is not a change — skip it.
+          if (originalEmpty && newEmpty) {
+            return;
+          }
+          var kind = originalEmpty ? 'add' : newEmpty ? 'remove' : 'update';
+          segments.push({
+            startPos: newFrom,
+            endPos: newTo,
+            originalSlice: originalSlice,
+            newSlice: newSlice,
+            kind: kind
+          });
+        } catch (_unused) {
+          // One bad range must not drop the others.
+        }
+      });
+    });
+    if (!segments.length) {
+      return null;
+    }
+    return {
+      actorUserId: actorUserId,
+      agentId: agentId,
+      agentType: agentType,
+      complete: complete,
+      segments: segments
+    };
+  } catch (_unused2) {
+    // Never throw into the shared remote-step handler; degrade to no recording.
+    return null;
+  }
+};

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

@@ -4,12 +4,14 @@ import * as allAdfSchemaSteps from '@atlaskit/adf-schema/steps';
 // Ignored via go/ees005
 // eslint-disable-next-line import/no-namespace
 import * as allAtlaskitCustomSteps from '@atlaskit/custom-steps';
+import { AGENT_REMOTE_EDIT_REVIEW_DATA } from '@atlaskit/editor-common/collab-agent-remote-edit-review';
 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 { getAgentEditShimmerNotShownPayload } from './analytics';
+import { getAgentEditSegments } from './main/agent-review-segments';
 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';
@@ -114,6 +116,21 @@ export const applyRemoteSteps = (json, view, userIds, options, editorAnalyticsAp
       }
     }
 
+    // [CCI-17994] Post Stream Review ("Review moment") for BE streaming. Record what
+    // the agent just wrote (original + new slice per contiguous change) onto this same
+    // transaction. `editor-plugin-ai` consumes this neutral meta to populate
+    // `aiContentPositions` and — only on the requester's client — open the Review
+    // moment once the edit settles. Gated on `platform_editor_agent_be_streaming`
+    // alongside shimmer; `getAgentEditSegments` also self-gates by returning null
+    // unless the batch contains agent-authored steps (and never throws), so this is
+    // a no-op for ordinary collaborator edits and can't affect step application.
+    if (expValEquals('platform_editor_agent_be_streaming', 'isEnabled', true)) {
+      const reviewData = getAgentEditSegments(json, steps, tr, view);
+      if (reviewData) {
+        tr.setMeta(AGENT_REMOTE_EDIT_REVIEW_DATA, reviewData);
+      }
+    }
+
     /*
      * Persist marks across transactions. Fixes an issue where
      * marks are lost if remote transactions are dispatched

package/dist/es2019/pm-plugins/main/agent-review-segments.js

@@ -0,0 +1,165 @@
+import { getCollabState } from '@atlaskit/prosemirror-collab';
+import { isPositionNeutralStep } from './agent-shimmer-ranges';
+
+// [CCI-17994] Post Stream Review ("Review moment") recording for BE streaming.
+//
+// Sibling to `getAgentShimmerRanges`: same idea of deriving what the agent wrote
+// from a received remote-step batch, but for a DIFFERENT consumer. The shimmer
+// only needs the NEW extent of added content (to draw a skeleton), so it drops
+// pure deletions and expands to whole blocks. The Review moment instead needs, per
+// contiguous change, BOTH the original slice (pre-edit, for undo / "compare with
+// original") and the new slice (for redo), AND it must keep deletions (a removed
+// paragraph is a reviewable change). So this derives the actual changed extents
+// and reconstructs the pre-edit slice from `tr.before`.
+//
+// The output is a neutral `AgentRemoteEditReviewData` (contract in editor-common);
+// `editor-plugin-ai`'s session-context plugin turns each segment into a coarse
+// `aiContentPositions` entry, reusing the entire FE Review moment pipeline.
+
+const clampToDoc = (doc, pos) => Math.min(Math.max(pos, 0), doc.content.size);
+
+// Map a position in doc_{i+1} forward through the remaining steps to final-doc
+// coords. Mirrors the shimmer's `mapToFinalDoc` — a later step's own inserted
+// content starts at its `from`; only subsequent steps shift it.
+const mapToFinalDoc = (steps, pos, stepIndex, bias) => {
+  let p = pos;
+  for (let j = stepIndex + 1; j < steps.length; j++) {
+    p = steps[j].getMap().map(p, bias);
+  }
+  return p;
+};
+
+/**
+ * Derive per-change Review moment segments from an agent-authored remote-step
+ * batch. Returns `null` when there is nothing to record (no agent steps, or a
+ * rebase invalidated our index math, or derivation threw) so the caller can no-op
+ * safely — this must never throw into the shared remote-step handler.
+ *
+ * @param json  the raw received step JSON (carries `agentType` / `agentId` / `userId`)
+ * @param steps the parsed PM steps (index-aligned with `json`)
+ * @param tr    the transaction that applied `steps` (so `tr.before`/`tr.doc`/`tr.mapping` are available)
+ * @param view  the editor view (for the collab rebase guard)
+ */
+export const getAgentEditSegments = (json, steps, tr, view) => {
+  // `agentType` present ⇒ agent-authored (per the NCS↔Editor steps contract). Read
+  // from the first agent step; it is identical across a batch.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const agentStep = json.find(step => typeof (step === null || step === void 0 ? void 0 : step.agentType) === 'string');
+  const agentType = agentStep === null || agentStep === void 0 ? void 0 : agentStep.agentType;
+  if (agentType === undefined) {
+    return null;
+  }
+  // The user the agent acted on behalf of (the requester). Optional/additive on the
+  // step contract, so it may be absent.
+  const actorUserId = typeof (agentStep === null || agentStep === void 0 ? void 0 : agentStep.userId) === 'string' ? agentStep.userId : undefined;
+  // Which agent instance wrote the batch. Additive on the step contract like
+  // `userId`, so treat it as optional. Carried for contract clarity / future
+  // per-agent attribution; nothing consumes it yet.
+  const agentId = typeof (agentStep === null || agentStep === void 0 ? void 0 : agentStep.agentId) === 'string' ? agentStep.agentId : undefined;
+  // Hybrid end-of-edit seam: if the BE/NCS flags a batch as the terminal one, carry
+  // it so the AI plugin can open review immediately instead of waiting for the
+  // debounce. Additive marker; absent for streaming (non-final) batches.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const complete = json.some(step => (step === null || step === void 0 ? void 0 : step.agentEditComplete) === true);
+
+  // Same rebase guard as the shimmer: index-based range math is only valid if any
+  // rebased-over local steps shifted no positions. Degrade to no recording otherwise.
+  if (Number(tr.getMeta('rebased')) > 0) {
+    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))) {
+      return null;
+    }
+  }
+  try {
+    // Compute one segment per step-level StepMap range. Each agent step's changed
+    // extent is taken from its StepMap (the canonical, step-type-agnostic source).
+    // Unlike the shimmer we KEEP zero-width new extents — a pure deletion has
+    // `newEnd === newStart` but is a reviewable `remove`.
+    //
+    // We derive the originalSlice/newSlice PER RANGE (per step) rather than
+    // grouping ranges first and then inverting over a merged range. Grouping
+    // before slicing corrupts the invert-mapping: when multiple discrete
+    // operations (e.g. two deleteNode + one insertNodeAfter) are merged into one
+    // range, mapping that merged range back through the inverted mapping produces
+    // a chimera — a blend of old and new text that never existed in the document.
+    //
+    // The downstream PSR pipeline (mergeOverlappingSegments +
+    // calculateTopLevelNodeSegments) already handles overlapping/adjacent coarse
+    // entries correctly, so grouping here is unnecessary.
+
+    const segments = [];
+    json.forEach((rawStep, index) => {
+      if (typeof (rawStep === null || rawStep === void 0 ? void 0 : rawStep.agentType) !== 'string') {
+        return;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const pmStep = steps[index];
+      if (typeof (pmStep === null || pmStep === void 0 ? void 0 : pmStep.getMap) !== 'function') {
+        return;
+      }
+      pmStep.getMap().forEach((oldStart, oldEnd, newStart, newEnd) => {
+        try {
+          // NEW-doc coordinates: map this step's newStart/newEnd forward
+          // through all subsequent steps to get final-doc positions.
+          const finalFrom = mapToFinalDoc(steps, newStart, index, -1);
+          const finalTo = mapToFinalDoc(steps, newEnd, index, 1);
+          const newFrom = clampToDoc(tr.doc, Math.min(finalFrom, finalTo));
+          const newTo = clampToDoc(tr.doc, Math.max(finalFrom, finalTo));
+
+          // ORIGINAL-doc coordinates: map this step's oldStart/oldEnd
+          // BACKWARD through all preceding steps to get pre-batch
+          // (`tr.before`) positions. Each preceding step's StepMap tells
+          // us how positions shifted; we invert that shift by mapping
+          // through the inverted StepMap.
+          //
+          // This is the key difference from using `tr.mapping.invert()`
+          // which inverts ALL steps at once — that produces chimera text
+          // when multiple discrete operations (delete + delete + insert)
+          // interact in the same region. Per-step backward mapping keeps
+          // each operation's original range isolated.
+          let origStart = oldStart;
+          let origEnd = oldEnd;
+          for (let j = index - 1; j >= 0; j--) {
+            const prevMap = steps[j].getMap().invert();
+            origStart = prevMap.map(origStart, -1);
+            origEnd = prevMap.map(origEnd, 1);
+          }
+          const origFrom = clampToDoc(tr.before, Math.min(origStart, origEnd));
+          const origTo = clampToDoc(tr.before, Math.max(origStart, origEnd));
+          const originalSlice = tr.before.slice(origFrom, origTo);
+          const newSlice = tr.doc.slice(newFrom, newTo);
+          const originalEmpty = originalSlice.content.size === 0;
+          const newEmpty = newSlice.content.size === 0;
+          // A truly empty-to-empty region is not a change — skip it.
+          if (originalEmpty && newEmpty) {
+            return;
+          }
+          const kind = originalEmpty ? 'add' : newEmpty ? 'remove' : 'update';
+          segments.push({
+            startPos: newFrom,
+            endPos: newTo,
+            originalSlice,
+            newSlice,
+            kind
+          });
+        } catch {
+          // One bad range must not drop the others.
+        }
+      });
+    });
+    if (!segments.length) {
+      return null;
+    }
+    return {
+      actorUserId,
+      agentId,
+      agentType,
+      complete,
+      segments
+    };
+  } catch {
+    // Never throw into the shared remote-step handler; degrade to no recording.
+    return null;
+  }
+};

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

@@ -4,12 +4,14 @@ import * as allAdfSchemaSteps from '@atlaskit/adf-schema/steps';
 // Ignored via go/ees005
 // eslint-disable-next-line import/no-namespace
 import * as allAtlaskitCustomSteps from '@atlaskit/custom-steps';
+import { AGENT_REMOTE_EDIT_REVIEW_DATA } from '@atlaskit/editor-common/collab-agent-remote-edit-review';
 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 { getAgentEditShimmerNotShownPayload } from './analytics';
+import { getAgentEditSegments } from './main/agent-review-segments';
 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';
@@ -103,6 +105,21 @@ export var applyRemoteSteps = function applyRemoteSteps(json, view, userIds, opt
       }
     }
 
+    // [CCI-17994] Post Stream Review ("Review moment") for BE streaming. Record what
+    // the agent just wrote (original + new slice per contiguous change) onto this same
+    // transaction. `editor-plugin-ai` consumes this neutral meta to populate
+    // `aiContentPositions` and — only on the requester's client — open the Review
+    // moment once the edit settles. Gated on `platform_editor_agent_be_streaming`
+    // alongside shimmer; `getAgentEditSegments` also self-gates by returning null
+    // unless the batch contains agent-authored steps (and never throws), so this is
+    // a no-op for ordinary collaborator edits and can't affect step application.
+    if (expValEquals('platform_editor_agent_be_streaming', 'isEnabled', true)) {
+      var reviewData = getAgentEditSegments(json, steps, tr, view);
+      if (reviewData) {
+        tr.setMeta(AGENT_REMOTE_EDIT_REVIEW_DATA, reviewData);
+      }
+    }
+
     /*
      * Persist marks across transactions. Fixes an issue where
      * marks are lost if remote transactions are dispatched

package/dist/esm/pm-plugins/main/agent-review-segments.js

@@ -0,0 +1,173 @@
+import { getCollabState } from '@atlaskit/prosemirror-collab';
+import { isPositionNeutralStep } from './agent-shimmer-ranges';
+
+// [CCI-17994] Post Stream Review ("Review moment") recording for BE streaming.
+//
+// Sibling to `getAgentShimmerRanges`: same idea of deriving what the agent wrote
+// from a received remote-step batch, but for a DIFFERENT consumer. The shimmer
+// only needs the NEW extent of added content (to draw a skeleton), so it drops
+// pure deletions and expands to whole blocks. The Review moment instead needs, per
+// contiguous change, BOTH the original slice (pre-edit, for undo / "compare with
+// original") and the new slice (for redo), AND it must keep deletions (a removed
+// paragraph is a reviewable change). So this derives the actual changed extents
+// and reconstructs the pre-edit slice from `tr.before`.
+//
+// The output is a neutral `AgentRemoteEditReviewData` (contract in editor-common);
+// `editor-plugin-ai`'s session-context plugin turns each segment into a coarse
+// `aiContentPositions` entry, reusing the entire FE Review moment pipeline.
+
+var clampToDoc = function clampToDoc(doc, pos) {
+  return Math.min(Math.max(pos, 0), doc.content.size);
+};
+
+// Map a position in doc_{i+1} forward through the remaining steps to final-doc
+// coords. Mirrors the shimmer's `mapToFinalDoc` — a later step's own inserted
+// content starts at its `from`; only subsequent steps shift it.
+var mapToFinalDoc = function mapToFinalDoc(steps, 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 per-change Review moment segments from an agent-authored remote-step
+ * batch. Returns `null` when there is nothing to record (no agent steps, or a
+ * rebase invalidated our index math, or derivation threw) so the caller can no-op
+ * safely — this must never throw into the shared remote-step handler.
+ *
+ * @param json  the raw received step JSON (carries `agentType` / `agentId` / `userId`)
+ * @param steps the parsed PM steps (index-aligned with `json`)
+ * @param tr    the transaction that applied `steps` (so `tr.before`/`tr.doc`/`tr.mapping` are available)
+ * @param view  the editor view (for the collab rebase guard)
+ */
+export var getAgentEditSegments = function getAgentEditSegments(json, steps, tr, view) {
+  // `agentType` present ⇒ agent-authored (per the NCS↔Editor steps contract). Read
+  // from the first agent step; it is identical across a batch.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  var agentStep = json.find(function (step) {
+    return typeof (step === null || step === void 0 ? void 0 : step.agentType) === 'string';
+  });
+  var agentType = agentStep === null || agentStep === void 0 ? void 0 : agentStep.agentType;
+  if (agentType === undefined) {
+    return null;
+  }
+  // The user the agent acted on behalf of (the requester). Optional/additive on the
+  // step contract, so it may be absent.
+  var actorUserId = typeof (agentStep === null || agentStep === void 0 ? void 0 : agentStep.userId) === 'string' ? agentStep.userId : undefined;
+  // Which agent instance wrote the batch. Additive on the step contract like
+  // `userId`, so treat it as optional. Carried for contract clarity / future
+  // per-agent attribution; nothing consumes it yet.
+  var agentId = typeof (agentStep === null || agentStep === void 0 ? void 0 : agentStep.agentId) === 'string' ? agentStep.agentId : undefined;
+  // Hybrid end-of-edit seam: if the BE/NCS flags a batch as the terminal one, carry
+  // it so the AI plugin can open review immediately instead of waiting for the
+  // debounce. Additive marker; absent for streaming (non-final) batches.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  var complete = json.some(function (step) {
+    return (step === null || step === void 0 ? void 0 : step.agentEditComplete) === true;
+  });
+
+  // Same rebase guard as the shimmer: index-based range math is only valid if any
+  // rebased-over local steps shifted no positions. Degrade to no recording otherwise.
+  if (Number(tr.getMeta('rebased')) > 0) {
+    var _getCollabState$uncon, _getCollabState;
+    var unconfirmed = (_getCollabState$uncon = (_getCollabState = getCollabState(view.state)) === null || _getCollabState === void 0 ? void 0 : _getCollabState.unconfirmed) !== null && _getCollabState$uncon !== void 0 ? _getCollabState$uncon : [];
+    if (unconfirmed.some(function (entry) {
+      return !isPositionNeutralStep(entry.step);
+    })) {
+      return null;
+    }
+  }
+  try {
+    // Compute one segment per step-level StepMap range. Each agent step's changed
+    // extent is taken from its StepMap (the canonical, step-type-agnostic source).
+    // Unlike the shimmer we KEEP zero-width new extents — a pure deletion has
+    // `newEnd === newStart` but is a reviewable `remove`.
+    //
+    // We derive the originalSlice/newSlice PER RANGE (per step) rather than
+    // grouping ranges first and then inverting over a merged range. Grouping
+    // before slicing corrupts the invert-mapping: when multiple discrete
+    // operations (e.g. two deleteNode + one insertNodeAfter) are merged into one
+    // range, mapping that merged range back through the inverted mapping produces
+    // a chimera — a blend of old and new text that never existed in the document.
+    //
+    // The downstream PSR pipeline (mergeOverlappingSegments +
+    // calculateTopLevelNodeSegments) already handles overlapping/adjacent coarse
+    // entries correctly, so grouping here is unnecessary.
+
+    var segments = [];
+    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) {
+        try {
+          // NEW-doc coordinates: map this step's newStart/newEnd forward
+          // through all subsequent steps to get final-doc positions.
+          var finalFrom = mapToFinalDoc(steps, newStart, index, -1);
+          var finalTo = mapToFinalDoc(steps, newEnd, index, 1);
+          var newFrom = clampToDoc(tr.doc, Math.min(finalFrom, finalTo));
+          var newTo = clampToDoc(tr.doc, Math.max(finalFrom, finalTo));
+
+          // ORIGINAL-doc coordinates: map this step's oldStart/oldEnd
+          // BACKWARD through all preceding steps to get pre-batch
+          // (`tr.before`) positions. Each preceding step's StepMap tells
+          // us how positions shifted; we invert that shift by mapping
+          // through the inverted StepMap.
+          //
+          // This is the key difference from using `tr.mapping.invert()`
+          // which inverts ALL steps at once — that produces chimera text
+          // when multiple discrete operations (delete + delete + insert)
+          // interact in the same region. Per-step backward mapping keeps
+          // each operation's original range isolated.
+          var origStart = oldStart;
+          var origEnd = oldEnd;
+          for (var j = index - 1; j >= 0; j--) {
+            var prevMap = steps[j].getMap().invert();
+            origStart = prevMap.map(origStart, -1);
+            origEnd = prevMap.map(origEnd, 1);
+          }
+          var origFrom = clampToDoc(tr.before, Math.min(origStart, origEnd));
+          var origTo = clampToDoc(tr.before, Math.max(origStart, origEnd));
+          var originalSlice = tr.before.slice(origFrom, origTo);
+          var newSlice = tr.doc.slice(newFrom, newTo);
+          var originalEmpty = originalSlice.content.size === 0;
+          var newEmpty = newSlice.content.size === 0;
+          // A truly empty-to-empty region is not a change — skip it.
+          if (originalEmpty && newEmpty) {
+            return;
+          }
+          var kind = originalEmpty ? 'add' : newEmpty ? 'remove' : 'update';
+          segments.push({
+            startPos: newFrom,
+            endPos: newTo,
+            originalSlice: originalSlice,
+            newSlice: newSlice,
+            kind: kind
+          });
+        } catch (_unused) {
+          // One bad range must not drop the others.
+        }
+      });
+    });
+    if (!segments.length) {
+      return null;
+    }
+    return {
+      actorUserId: actorUserId,
+      agentId: agentId,
+      agentType: agentType,
+      complete: complete,
+      segments: segments
+    };
+  } catch (_unused2) {
+    // Never throw into the shared remote-step handler; degrade to no recording.
+    return null;
+  }
+};

package/dist/types/pm-plugins/main/agent-review-segments.d.ts

@@ -0,0 +1,16 @@
+import type { AgentRemoteEditReviewData } from '@atlaskit/editor-common/collab-agent-remote-edit-review';
+import type { Transaction } from '@atlaskit/editor-prosemirror/state';
+import type { Step } from '@atlaskit/editor-prosemirror/transform';
+import type { EditorView } from '@atlaskit/editor-prosemirror/view';
+/**
+ * Derive per-change Review moment segments from an agent-authored remote-step
+ * batch. Returns `null` when there is nothing to record (no agent steps, or a
+ * rebase invalidated our index math, or derivation threw) so the caller can no-op
+ * safely — this must never throw into the shared remote-step handler.
+ *
+ * @param json  the raw received step JSON (carries `agentType` / `agentId` / `userId`)
+ * @param steps the parsed PM steps (index-aligned with `json`)
+ * @param tr    the transaction that applied `steps` (so `tr.before`/`tr.doc`/`tr.mapping` are available)
+ * @param view  the editor view (for the collab rebase guard)
+ */
+export declare const getAgentEditSegments: (json: any[], steps: Step[], tr: Transaction, view: EditorView) => AgentRemoteEditReviewData | null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-collab-edit",
-	"version": "13.3.1",
+	"version": "13.4.1",
 	"description": "Collab Edit plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
@@ -19,7 +19,7 @@
 	"sideEffects": false,
 	"atlaskit:src": "src/index.ts",
 	"dependencies": {
-		"@atlaskit/adf-schema": "^56.4.0",
+		"@atlaskit/adf-schema": "^56.5.0",
 		"@atlaskit/custom-steps": "^1.0.0",
 		"@atlaskit/editor-json-transformer": "^9.2.0",
 		"@atlaskit/editor-plugin-analytics": "^12.1.0",
@@ -31,13 +31,13 @@
 		"@atlaskit/frontend-utilities": "^4.1.0",
 		"@atlaskit/platform-feature-flags": "^2.1.0",
 		"@atlaskit/prosemirror-collab": "^1.0.0",
-		"@atlaskit/tmp-editor-statsig": "^136.0.0",
+		"@atlaskit/tmp-editor-statsig": "^137.0.0",
 		"@atlaskit/tokens": "^16.3.0",
 		"@babel/runtime": "^7.0.0",
 		"memoize-one": "^6.0.0"
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^116.48.0",
+		"@atlaskit/editor-common": "^116.51.0",
 		"react": "^18.2.0 || ^19.2.0",
 		"react-dom": "^18.2.0 || ^19.2.0"
 	},