@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/core/commands/index.ts

@@ -0,0 +1,1879 @@
+import {
+  createSelectionSnapshot,
+  type CanonicalDocumentEnvelope,
+  type CommentThreadRecord,
+  type EditorState,
+  type EditorWarning,
+  normalizeCommentThreadRecord,
+  type SelectionSnapshot,
+} from "../state/editor-state.ts";
+import {
+  areAnchorsEqual,
+  createDetachedAnchor,
+  createEmptyMapping,
+  createNodeAnchor,
+  createRangeAnchor,
+  DEFAULT_BOUNDARY_ASSOC,
+  mapAnchor,
+  type BoundaryAssoc,
+  type EditorAnchorProjection,
+  type MappingStep,
+  type TransactionMapping,
+} from "../selection/mapping.ts";
+import {
+  createAcceptRevisionCommand,
+  createRejectRevisionCommand,
+  type ReviewCommand,
+} from "./review-commands.ts";
+import {
+  deleteSelectionOrBackward,
+  deleteSelectionOrForward,
+  insertHardBreak,
+  insertTab,
+  insertText,
+  splitParagraph,
+} from "./text-commands.ts";
+import type { RevisionRecord as CanonicalRevisionRecord } from "../../model/canonical-document.ts";
+import { remapCommentThreads } from "../../review/store/comment-remapping.ts";
+import { applyRevisionRuntimeCommand } from "../../runtime/revision-runtime.ts";
+import type { RevisionStore } from "../../review/store/revision-store.ts";
+
+export interface CommandOrigin {
+  source:
+    | "keyboard"
+    | "toolbar"
+    | "context_menu"
+    | "comment_panel"
+    | "review_panel"
+    | "api"
+    | "runtime";
+  timestamp: string;
+}
+
+export type EditorCommand =
+  | {
+      type: "selection.set";
+      selection: SelectionSnapshot;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "document.replace";
+      document: CanonicalDocumentEnvelope;
+      mapping?: TransactionMapping;
+      selection?: SelectionSnapshot;
+      protectionSelection?: SelectionSnapshot;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "text.insert";
+      text: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "text.delete-backward";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "text.delete-forward";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "text.insert-tab";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "text.insert-hard-break";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "paragraph.split";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "runtime.set-read-only";
+      readOnly: boolean;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "runtime.focus";
+      focused: boolean;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "warning.add";
+      warning: EditorWarning;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "warning.clear";
+      warningId: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "comment.add";
+      comment: CommentThreadRecord;
+      selection?: SelectionSnapshot;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "comment.open";
+      commentId: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "comment.resolve";
+      commentId: string;
+      resolvedBy?: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "comment.reopen";
+      commentId: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "comment.add-reply";
+      commentId: string;
+      body: string;
+      authorId?: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "comment.edit-body";
+      commentId: string;
+      body: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "change.accept";
+      changeId: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "change.reject";
+      changeId: string;
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "change.accept-all";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "change.reject-all";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "history.undo";
+      origin?: CommandOrigin;
+    }
+  | {
+      type: "history.redo";
+      origin?: CommandOrigin;
+    };
+
+export interface TransactionEffects {
+  warningsAdded: EditorWarning[];
+  warningsCleared: Array<{ warningId: string; code: EditorWarning["code"] }>;
+  commentAdded?: { commentId: string; anchor: EditorAnchorProjection };
+  commentResolved?: { commentId: string };
+  commentReopened?: { commentId: string };
+  commentReplyAdded?: { commentId: string };
+  commentBodyEdited?: { commentId: string };
+  changeAccepted?: { changeId: string };
+  changeRejected?: { changeId: string };
+  revisionAuthored?: { changeId: string; kind: "insertion" | "deletion" };
+  commandBlocked?: { code: string; message: string };
+}
+
+export interface EditorTransaction {
+  nextState: EditorState;
+  mapping: TransactionMapping;
+  effects: TransactionEffects;
+  historyBoundary: "push" | "skip";
+  markDirty: boolean;
+}
+
+export interface CommandExecutionContext {
+  timestamp: string;
+  documentMode?: "editing" | "suggesting" | "viewing";
+  defaultAuthorId?: string;
+}
+
+export function executeEditorCommand(
+  state: EditorState,
+  command: Exclude<EditorCommand, { type: "history.undo" } | { type: "history.redo" }>,
+  context: CommandExecutionContext,
+): EditorTransaction {
+  switch (command.type) {
+    case "selection.set":
+      return createTransaction(
+        {
+          ...state,
+          selection: normalizeSelection(command.selection),
+        },
+        {
+          historyBoundary: "skip",
+          markDirty: false,
+        },
+      );
+    case "document.replace": {
+      const mapping = command.mapping ?? createEmptyMapping();
+      const selection =
+        command.selection ?? remapSelection(state.selection, mapping);
+      const reviewState = remapReviewStateAfterContentChange(
+        state,
+        command.document,
+        mapping,
+      );
+
+      return createTransaction(
+        {
+          ...state,
+          document: reviewState.document,
+          selection,
+          warnings: reviewState.warnings,
+          runtime: {
+            ...state.runtime,
+            activeCommentId: reviewState.activeCommentId,
+          },
+          compatibility: {
+            ...state.compatibility,
+            generatedAt: context.timestamp,
+            warnings: reviewState.warnings,
+            featureEntries: state.compatibility.featureEntries.map((entry) =>
+              entry.affectedAnchor
+                ? {
+                    ...entry,
+                    affectedAnchor: mapAnchor(entry.affectedAnchor, mapping),
+                  }
+                : entry,
+            ),
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          mapping,
+          effects: reviewState.effects,
+        },
+      );
+    }
+    case "text.insert": {
+      const suggestingResult = context.documentMode === "suggesting"
+        ? applySuggestingInsert(state, command.text, context)
+        : undefined;
+      if (suggestingResult) return suggestingResult;
+      return applyTextCommand(state, context.timestamp, (document, selection) =>
+        insertText(document, selection, command.text, context),
+      );
+    }
+    case "text.delete-backward": {
+      const suggestingResult = context.documentMode === "suggesting"
+        ? applySuggestingDelete(state, "backward", context)
+        : undefined;
+      if (suggestingResult) return suggestingResult;
+      return applyTextCommand(state, context.timestamp, (document, selection) =>
+        deleteSelectionOrBackward(document, selection, context),
+      );
+    }
+    case "text.delete-forward": {
+      const suggestingResult = context.documentMode === "suggesting"
+        ? applySuggestingDelete(state, "forward", context)
+        : undefined;
+      if (suggestingResult) return suggestingResult;
+      return applyTextCommand(state, context.timestamp, (document, selection) =>
+        deleteSelectionOrForward(document, selection, context),
+      );
+    }
+    case "text.insert-tab": {
+      const suggestingResult = context.documentMode === "suggesting"
+        ? applySuggestingInsertUnit(state, "tab", context)
+        : undefined;
+      if (suggestingResult) return suggestingResult;
+      return applyTextCommand(state, context.timestamp, (document, selection) =>
+        insertTab(document, selection, context),
+      );
+    }
+    case "text.insert-hard-break": {
+      const suggestingResult = context.documentMode === "suggesting"
+        ? applySuggestingInsertUnit(state, "hard_break", context)
+        : undefined;
+      if (suggestingResult) return suggestingResult;
+      return applyTextCommand(state, context.timestamp, (document, selection) =>
+        insertHardBreak(document, selection, context),
+      );
+    }
+    case "paragraph.split":
+      if (context.documentMode === "suggesting") {
+        const suggestingResult = applySuggestingParagraphSplit(state, context);
+        if (suggestingResult) return suggestingResult;
+      }
+      return applyTextCommand(state, context.timestamp, (document, selection) =>
+        splitParagraph(document, selection, context),
+      );
+    case "runtime.set-read-only":
+      return createTransaction(
+        {
+          ...state,
+          readOnly: command.readOnly,
+        },
+        {
+          historyBoundary: "skip",
+          markDirty: false,
+        },
+      );
+    case "runtime.focus":
+      return createTransaction(
+        {
+          ...state,
+          runtime: {
+            ...state.runtime,
+            hasFocus: command.focused,
+          },
+        },
+        {
+          historyBoundary: "skip",
+          markDirty: false,
+        },
+      );
+    case "warning.add": {
+      if (state.warnings.some((warning) => warning.warningId === command.warning.warningId)) {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+        });
+      }
+
+      const warnings = [...state.warnings, command.warning];
+      return createTransaction(
+        {
+          ...state,
+          warnings,
+          compatibility: {
+            ...state.compatibility,
+            generatedAt: context.timestamp,
+            warnings,
+          },
+        },
+        {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            warningsAdded: [command.warning],
+          },
+        },
+      );
+    }
+    case "warning.clear": {
+      const existing = state.warnings.find((warning) => warning.warningId === command.warningId);
+
+      if (!existing) {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+        });
+      }
+
+      const warnings = state.warnings.filter((warning) => warning.warningId !== command.warningId);
+      return createTransaction(
+        {
+          ...state,
+          warnings,
+          compatibility: {
+            ...state.compatibility,
+            generatedAt: context.timestamp,
+            warnings,
+          },
+        },
+        {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            warningsCleared: [
+              {
+                warningId: existing.warningId,
+                code: existing.code,
+              },
+            ],
+          },
+        },
+      );
+    }
+    case "comment.add": {
+      const comments = {
+        ...state.document.review.comments,
+        [command.comment.commentId]: normalizeCommentThreadRecord(command.comment),
+      };
+
+      return createTransaction(
+        {
+          ...state,
+          document: {
+            ...state.document,
+            updatedAt: context.timestamp,
+            review: {
+              ...state.document.review,
+              comments,
+            },
+          },
+          runtime: {
+            ...state.runtime,
+            activeCommentId: command.comment.commentId,
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          effects: {
+            commentAdded: {
+              commentId: command.comment.commentId,
+              anchor: command.comment.anchor,
+            },
+          },
+        },
+      );
+    }
+    case "comment.open":
+      return createTransaction(
+        {
+          ...state,
+          runtime: {
+            ...state.runtime,
+            activeCommentId: command.commentId,
+          },
+        },
+        {
+          historyBoundary: "skip",
+          markDirty: false,
+        },
+      );
+    case "comment.resolve": {
+      const existing = state.document.review.comments[command.commentId];
+      if (!existing) {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+        });
+      }
+
+      const comments = {
+        ...state.document.review.comments,
+        [command.commentId]: {
+          ...existing,
+          status: (existing.anchor.kind === "detached" ? "detached" : "resolved") as "detached" | "resolved",
+          resolution: {
+            resolvedAt: context.timestamp,
+            resolvedBy:
+              command.resolvedBy ??
+              existing.createdBy ??
+              existing.authorId ??
+              existing.entries?.[0]?.authorId ??
+              "unknown",
+          },
+          isResolved: true,
+          resolvedAt: context.timestamp,
+        },
+      };
+
+      return createTransaction(
+        {
+          ...state,
+          document: {
+            ...state.document,
+            updatedAt: context.timestamp,
+            review: {
+              ...state.document.review,
+              comments,
+            },
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          effects: {
+            commentResolved: {
+              commentId: command.commentId,
+            },
+          },
+        },
+      );
+    }
+    case "comment.reopen": {
+      const existingThread = state.document.review.comments[command.commentId];
+      if (!existingThread || existingThread.status === "detached") {
+        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+      }
+      const reopenedComments = {
+        ...state.document.review.comments,
+        [command.commentId]: {
+          ...existingThread,
+          status: "open" as const,
+          isResolved: false,
+          resolvedAt: undefined,
+          resolution: undefined,
+        },
+      };
+      return createTransaction(
+        {
+          ...state,
+          document: {
+            ...state.document,
+            updatedAt: context.timestamp,
+            review: { ...state.document.review, comments: reopenedComments },
+          },
+          runtime: { ...state.runtime, activeCommentId: command.commentId },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          effects: { commentReopened: { commentId: command.commentId } },
+        },
+      );
+    }
+    case "comment.add-reply": {
+      const threadForReply = state.document.review.comments[command.commentId];
+      if (!threadForReply) {
+        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+      }
+      // Block reply on resolved or detached threads (must reopen first)
+      if (threadForReply.status === "resolved" || threadForReply.status === "detached") {
+        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+      }
+      const entryId = `${command.commentId}-entry-${(threadForReply.entries?.length ?? 0) + 1}`;
+      const newEntry = {
+        entryId,
+        authorId: command.authorId ?? threadForReply.createdBy ?? "unknown",
+        body: command.body,
+        createdAt: context.timestamp,
+      };
+      const updatedThread = {
+        ...threadForReply,
+        entries: [...(threadForReply.entries ?? []), newEntry],
+      };
+      const replyComments = {
+        ...state.document.review.comments,
+        [command.commentId]: updatedThread,
+      };
+      return createTransaction(
+        {
+          ...state,
+          document: {
+            ...state.document,
+            updatedAt: context.timestamp,
+            review: { ...state.document.review, comments: replyComments },
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          effects: { commentReplyAdded: { commentId: command.commentId } },
+        },
+      );
+    }
+    case "comment.edit-body": {
+      const threadToEdit = state.document.review.comments[command.commentId];
+      if (!threadToEdit || !threadToEdit.entries?.length) {
+        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+      }
+      const editedEntries = [...threadToEdit.entries];
+      editedEntries[0] = { ...editedEntries[0], body: command.body };
+      const editedThread = {
+        ...threadToEdit,
+        body: command.body,
+        entries: editedEntries,
+      };
+      const editedComments = {
+        ...state.document.review.comments,
+        [command.commentId]: editedThread,
+      };
+      return createTransaction(
+        {
+          ...state,
+          document: {
+            ...state.document,
+            updatedAt: context.timestamp,
+            review: { ...state.document.review, comments: editedComments },
+          },
+        },
+        {
+          historyBoundary: "push",
+          markDirty: true,
+          effects: { commentBodyEdited: { commentId: command.commentId } },
+        },
+      );
+    }
+    case "change.accept":
+      return applyReviewCommand(
+        state,
+        createAcceptRevisionCommand(command.changeId, command.origin),
+        context.timestamp,
+      );
+    case "change.reject":
+      return applyReviewCommand(
+        state,
+        createRejectRevisionCommand(command.changeId, command.origin),
+        context.timestamp,
+      );
+    case "change.accept-all":
+      return applyReviewCommand(
+        state,
+        {
+          type: "review.accept-all-revisions",
+          ...(command.origin ? { origin: command.origin } : {}),
+        },
+        context.timestamp,
+      );
+    case "change.reject-all":
+      return applyReviewCommand(
+        state,
+        {
+          type: "review.reject-all-revisions",
+          ...(command.origin ? { origin: command.origin } : {}),
+        },
+        context.timestamp,
+      );
+  }
+}
+
+export function remapSelection(
+  selection: SelectionSnapshot,
+  mapping: TransactionMapping,
+): SelectionSnapshot {
+  const activeRange = mapAnchor(selection.activeRange, mapping);
+
+  if (activeRange.kind === "range") {
+    return {
+      anchor: activeRange.range.from,
+      head: activeRange.range.to,
+      isCollapsed: activeRange.range.from === activeRange.range.to,
+      activeRange,
+    };
+  }
+
+  if (activeRange.kind === "node") {
+    return {
+      anchor: activeRange.at,
+      head: activeRange.at,
+      isCollapsed: true,
+      activeRange,
+    };
+  }
+
+  return {
+    anchor: selection.anchor,
+    head: selection.head,
+    isCollapsed: selection.anchor === selection.head,
+    activeRange,
+  };
+}
+
+export function selectionChanged(
+  left: SelectionSnapshot,
+  right: SelectionSnapshot,
+): boolean {
+  return (
+    left.anchor !== right.anchor ||
+    left.head !== right.head ||
+    left.isCollapsed !== right.isCollapsed ||
+    !areAnchorsEqual(left.activeRange, right.activeRange)
+  );
+}
+
+function createTransaction(
+  nextState: EditorState,
+  options: {
+    mapping?: TransactionMapping;
+    historyBoundary: "push" | "skip";
+    markDirty: boolean;
+    effects?: Partial<TransactionEffects>;
+  },
+): EditorTransaction {
+  return {
+    nextState,
+    mapping: options.mapping ?? createEmptyMapping(),
+    historyBoundary: options.historyBoundary,
+    markDirty: options.markDirty,
+    effects: {
+      warningsAdded: options.effects?.warningsAdded ?? [],
+      warningsCleared: options.effects?.warningsCleared ?? [],
+      commentAdded: options.effects?.commentAdded,
+      commentResolved: options.effects?.commentResolved,
+      changeAccepted: options.effects?.changeAccepted,
+      changeRejected: options.effects?.changeRejected,
+      revisionAuthored: options.effects?.revisionAuthored,
+      commandBlocked: options.effects?.commandBlocked,
+    },
+  };
+}
+
+function normalizeSelection(selection: SelectionSnapshot): SelectionSnapshot {
+  const activeRange = normalizeSelectionAnchor(
+    selection.activeRange,
+    selection.anchor,
+    selection.head,
+  );
+
+  if (activeRange.kind === "range") {
+    const rangeFrom = activeRange.range.from;
+    const rangeTo = activeRange.range.to;
+    const collapsed = rangeFrom === rangeTo;
+    const anchorWithinRange = selection.anchor >= rangeFrom && selection.anchor <= rangeTo;
+    const headWithinRange = selection.head >= rangeFrom && selection.head <= rangeTo;
+    const preserveDirectionalEndpoints = anchorWithinRange && headWithinRange;
+    const fallbackForward = selection.anchor <= selection.head;
+    const anchor = collapsed
+      ? rangeFrom
+      : preserveDirectionalEndpoints
+        ? selection.anchor
+        : fallbackForward
+          ? rangeFrom
+          : rangeTo;
+    const head = collapsed
+      ? rangeTo
+      : preserveDirectionalEndpoints
+        ? selection.head
+        : fallbackForward
+          ? rangeTo
+          : rangeFrom;
+    return {
+      anchor,
+      head,
+      isCollapsed: collapsed,
+      activeRange,
+    };
+  }
+
+  if (activeRange.kind === "node") {
+    return {
+      anchor: activeRange.at,
+      head: activeRange.at,
+      isCollapsed: true,
+      activeRange,
+    };
+  }
+
+  return {
+    anchor: activeRange.lastKnownRange.from,
+    head: activeRange.lastKnownRange.to,
+    isCollapsed: activeRange.lastKnownRange.from === activeRange.lastKnownRange.to,
+    activeRange,
+  };
+}
+
+function normalizeSelectionAnchor(
+  value: SelectionSnapshot["activeRange"],
+  anchor: number,
+  head: number,
+): EditorAnchorProjection {
+  if (!value || typeof value !== "object") {
+    return createRangeAnchor(anchor, head, DEFAULT_BOUNDARY_ASSOC);
+  }
+
+  const record = value as unknown as Record<string, unknown>;
+  switch (record.kind) {
+    case "range": {
+      const assoc = normalizeBoundaryAssoc(record.assoc);
+      const internalRange = record.range;
+      if (
+        internalRange &&
+        typeof internalRange === "object" &&
+        typeof (internalRange as { from?: unknown }).from === "number" &&
+        typeof (internalRange as { to?: unknown }).to === "number"
+      ) {
+        return createRangeAnchor(
+          (internalRange as { from: number }).from,
+          (internalRange as { to: number }).to,
+          assoc,
+        );
+      }
+
+      if (typeof record.from === "number" && typeof record.to === "number") {
+        return createRangeAnchor(record.from, record.to, assoc);
+      }
+
+      return createRangeAnchor(anchor, head, assoc);
+    }
+    case "node":
+      return createNodeAnchor(
+        typeof record.at === "number" ? record.at : anchor,
+        normalizeAssoc(record.assoc),
+      );
+    case "detached": {
+      const lastKnownRange = record.lastKnownRange;
+      if (
+        lastKnownRange &&
+        typeof lastKnownRange === "object" &&
+        typeof (lastKnownRange as { from?: unknown }).from === "number" &&
+        typeof (lastKnownRange as { to?: unknown }).to === "number"
+      ) {
+        return createDetachedAnchor(
+          {
+            from: (lastKnownRange as { from: number }).from,
+            to: (lastKnownRange as { to: number }).to,
+          },
+          normalizeDetachedReason(record.reason),
+        );
+      }
+
+      return createDetachedAnchor({ from: anchor, to: head }, normalizeDetachedReason(record.reason));
+    }
+    default:
+      return createRangeAnchor(anchor, head, DEFAULT_BOUNDARY_ASSOC);
+  }
+}
+
+function normalizeBoundaryAssoc(value: unknown): BoundaryAssoc {
+  if (value && typeof value === "object") {
+    const record = value as unknown as Record<string, unknown>;
+    return {
+      start: normalizeAssoc(record.start),
+      end: normalizeAssoc(record.end),
+    };
+  }
+
+  return DEFAULT_BOUNDARY_ASSOC;
+}
+
+function normalizeAssoc(value: unknown): -1 | 1 {
+  return value === -1 ? -1 : 1;
+}
+
+function normalizeDetachedReason(
+  value: unknown,
+): "deleted" | "invalidatedByStructureChange" | "importAmbiguity" {
+  if (
+    value === "deleted" ||
+    value === "invalidatedByStructureChange" ||
+    value === "importAmbiguity"
+  ) {
+    return value;
+  }
+
+  return "importAmbiguity";
+}
+
+function applyTextCommand(
+  state: EditorState,
+  timestamp: string,
+  apply: (
+    document: CanonicalDocumentEnvelope,
+    selection: SelectionSnapshot,
+  ) => {
+    document: CanonicalDocumentEnvelope;
+    selection: SelectionSnapshot;
+    mapping: TransactionMapping;
+  },
+): EditorTransaction {
+  if (state.readOnly) {
+    return createTransaction(state, {
+      historyBoundary: "skip",
+      markDirty: false,
+    });
+  }
+
+  const result = apply(state.document, state.selection);
+  const reviewState = remapReviewStateAfterContentChange(
+    state,
+    result.document,
+    result.mapping,
+  );
+
+  return createTransaction(
+    {
+      ...state,
+      document: reviewState.document,
+      selection: result.selection,
+      warnings: reviewState.warnings,
+      runtime: {
+        ...state.runtime,
+        activeCommentId: reviewState.activeCommentId,
+      },
+    },
+    {
+      historyBoundary: "push",
+      markDirty: true,
+      mapping: result.mapping,
+      effects: reviewState.effects,
+    },
+  );
+}
+
+function applyReviewCommand(
+  state: EditorState,
+  command: ReviewCommand,
+  timestamp: string,
+): EditorTransaction {
+  if (state.readOnly) {
+    return createTransaction(state, {
+      historyBoundary: "skip",
+      markDirty: false,
+    });
+  }
+
+  const result = applyRevisionRuntimeCommand({
+    state: {
+      document: state.document,
+      store: createRevisionStoreFromState(state),
+    },
+    command,
+    timestamp,
+  });
+  const hasAppliedOutcome = result.outcomes.some((outcome) => outcome.kind === "applied");
+
+  if (!hasAppliedOutcome) {
+    return createTransaction(state, {
+      historyBoundary: "skip",
+      markDirty: false,
+    });
+  }
+
+  let selection = state.selection;
+  let comments = result.document.review.comments;
+  let warnings = state.warnings;
+  let activeCommentId = state.runtime.activeCommentId;
+  const mappingSteps: MappingStep[] = [];
+
+  for (const entry of result.mappings) {
+    if (entry.steps === 0) {
+      continue;
+    }
+
+    selection = remapSelection(selection, entry.mapping);
+    mappingSteps.push(...entry.mapping.steps);
+
+    const remappedComments = remapCommentThreads({
+      comments,
+      mapping: entry.mapping,
+      nextContent: result.document.content,
+      existingWarnings: mapWarningsThroughMapping(warnings, entry.mapping),
+    });
+    comments = remappedComments.comments;
+    warnings = remappedComments.warnings;
+    activeCommentId =
+      activeCommentId && comments[activeCommentId]
+        ? activeCommentId
+        : undefined;
+  }
+
+  warnings = mergeDetachedRevisionWarnings(result.store, warnings);
+
+  const nextDocument = {
+    ...result.document,
+    review: {
+      ...result.document.review,
+      comments,
+      revisions: toEditorRevisionRecords(result.store),
+    },
+  };
+  const appliedRevisionIds = result.effects.appliedRevisionIds;
+
+  return createTransaction(
+    {
+      ...state,
+      document: nextDocument,
+      selection,
+      warnings,
+      runtime: {
+        ...state.runtime,
+        activeCommentId,
+      },
+    },
+    {
+      historyBoundary: "push",
+      markDirty: true,
+      mapping: combineMappingSteps(mappingSteps),
+      effects: {
+        ...buildWarningEffects(state.warnings, warnings),
+        changeAccepted:
+          command.type === "review.accept-revision" && appliedRevisionIds[0]
+            ? {
+                changeId: appliedRevisionIds[0],
+              }
+            : undefined,
+        changeRejected:
+          command.type === "review.reject-revision" && appliedRevisionIds[0]
+            ? {
+                changeId: appliedRevisionIds[0],
+              }
+            : undefined,
+      },
+    },
+  );
+}
+
+function remapReviewStateAfterContentChange(
+  state: EditorState,
+  nextDocument: CanonicalDocumentEnvelope,
+  mapping: TransactionMapping,
+): {
+  document: CanonicalDocumentEnvelope;
+  warnings: EditorWarning[];
+  activeCommentId?: string;
+  effects: Pick<TransactionEffects, "warningsAdded" | "warningsCleared">;
+} {
+  const mappedWarnings = mapWarningsThroughMapping(state.warnings, mapping);
+  const remappedComments = remapCommentThreads({
+    comments: nextDocument.review.comments,
+    mapping,
+    nextContent: nextDocument.content,
+    existingWarnings: mappedWarnings,
+  });
+  const revisions = Object.fromEntries(
+    Object.entries(nextDocument.review.revisions).map(([changeId, revision]) => [
+      changeId,
+      {
+        ...revision,
+        anchor: mapAnchor(revision.anchor, mapping),
+      },
+    ]),
+  );
+  const activeCommentId =
+    state.runtime.activeCommentId &&
+    remappedComments.comments[state.runtime.activeCommentId]
+      ? state.runtime.activeCommentId
+      : undefined;
+  const warnings = remappedComments.warnings;
+
+  return {
+    document: {
+      ...nextDocument,
+      review: {
+        ...nextDocument.review,
+        comments: remappedComments.comments,
+        revisions,
+      },
+    },
+    warnings,
+    activeCommentId,
+    effects: buildWarningEffects(state.warnings, warnings),
+  };
+}
+
+function createRevisionStoreFromState(
+  state: Pick<EditorState, "document">,
+): RevisionStore {
+  return {
+    version: "revision-store/1",
+    revisions: Object.fromEntries(
+      Object.values(state.document.review.revisions).map((revision) => [
+        revision.changeId,
+        {
+          revisionId: revision.changeId,
+          kind: revision.kind,
+          anchor: revision.anchor,
+          authorId: revision.authorId ?? "unknown",
+          createdAt: revision.createdAt,
+          status: revision.status === "open" ? "active" : revision.status,
+          warningIds: [...(revision.warningIds ?? [])],
+          metadata: {
+            source: revision.metadata?.source ?? "runtime",
+            storyTarget: revision.metadata?.storyTarget,
+            preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+            suggestionId: revision.metadata?.suggestionId,
+            semanticKind: revision.metadata?.semanticKind,
+            linkedRevisionIds: revision.metadata?.linkedRevisionIds,
+            predecessorSuggestionId: revision.metadata?.predecessorSuggestionId,
+            importedRevisionForm: revision.metadata?.importedRevisionForm,
+            originalRevisionType: revision.metadata?.originalRevisionType,
+            ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+          },
+        },
+      ]),
+    ),
+  };
+}
+
+function toEditorRevisionRecords(
+  store: RevisionStore,
+): EditorState["document"]["review"]["revisions"] {
+  return Object.fromEntries(
+    Object.values(store.revisions).map((revision) => [
+      revision.revisionId,
+      {
+        changeId: revision.revisionId,
+        kind: revision.kind,
+        anchor: revision.anchor,
+        authorId: revision.authorId,
+        createdAt: revision.createdAt,
+        warningIds: [...revision.warningIds],
+        metadata: {
+          source: revision.metadata.source,
+          storyTarget: revision.metadata.storyTarget,
+          preserveOnlyReason: revision.metadata.preserveOnlyReason,
+          suggestionId: revision.metadata.suggestionId,
+          semanticKind: revision.metadata.semanticKind,
+          linkedRevisionIds: revision.metadata.linkedRevisionIds,
+          predecessorSuggestionId: revision.metadata.predecessorSuggestionId,
+          importedRevisionForm: revision.metadata.importedRevisionForm,
+          originalRevisionType: revision.metadata.originalRevisionType,
+          ooxmlRevisionId: revision.metadata.ooxmlRevisionId,
+        },
+        status: revision.status === "active" ? "open" : revision.status,
+      },
+    ]),
+  );
+}
+
+function mapWarningsThroughMapping(
+  warnings: EditorWarning[],
+  mapping: TransactionMapping,
+): EditorWarning[] {
+  return warnings.map((warning) =>
+    warning.affectedAnchor
+      ? {
+          ...warning,
+          affectedAnchor: mapAnchor(warning.affectedAnchor, mapping),
+        }
+      : warning,
+  );
+}
+
+function buildWarningEffects(
+  previousWarnings: EditorWarning[],
+  nextWarnings: EditorWarning[],
+): Pick<TransactionEffects, "warningsAdded" | "warningsCleared"> {
+  const previousById = new Set(previousWarnings.map((warning) => warning.warningId));
+  const nextById = new Set(nextWarnings.map((warning) => warning.warningId));
+
+  return {
+    warningsAdded: nextWarnings.filter((warning) => !previousById.has(warning.warningId)),
+    warningsCleared: previousWarnings
+      .filter((warning) => !nextById.has(warning.warningId))
+      .map((warning) => ({
+        warningId: warning.warningId,
+        code: warning.code,
+      })),
+  };
+}
+
+function mergeDetachedRevisionWarnings(
+  store: RevisionStore,
+  existingWarnings: EditorWarning[],
+): EditorWarning[] {
+  const retainedWarnings = existingWarnings.filter(
+    (warning) =>
+      warning.code !== "revision_anchor_detached" ||
+      !warning.details ||
+      typeof warning.details.changeId !== "string" ||
+      store.revisions[warning.details.changeId]?.status === "detached",
+  );
+
+  const knownDetachedIds = new Set(
+    retainedWarnings
+      .filter((warning) => warning.code === "revision_anchor_detached")
+      .map((warning) =>
+        typeof warning.details?.changeId === "string"
+          ? warning.details.changeId
+          : undefined,
+      )
+      .filter((value): value is string => Boolean(value)),
+  );
+
+  const detachedWarnings = Object.values(store.revisions)
+    .filter(
+      (revision) =>
+        revision.status === "detached" && !knownDetachedIds.has(revision.revisionId),
+    )
+    .map((revision) => ({
+      warningId: `warning:revision-anchor-detached:${revision.revisionId}`,
+      code: "revision_anchor_detached" as const,
+      severity: "warning" as const,
+      message: `Revision ${revision.revisionId} detached after review remapping.`,
+      source: "review" as const,
+      affectedAnchor: revision.anchor.kind === "detached" ? revision.anchor : undefined,
+      details: {
+        changeId: revision.revisionId,
+        reason:
+          revision.anchor.kind === "detached"
+            ? revision.anchor.reason
+            : undefined,
+      },
+    }));
+
+  return [...retainedWarnings, ...detachedWarnings];
+}
+
+function combineMappingSteps(
+  steps: MappingStep[],
+): TransactionMapping {
+  return steps.length > 0
+    ? {
+        steps,
+      }
+    : createEmptyMapping();
+}
+
+// ---------------------------------------------------------------------------
+// Suggesting mode: creates revision records instead of (or alongside) text mutations
+// ---------------------------------------------------------------------------
+
+let suggestingRevisionCounter = 0;
+
+function createSuggestingRevisionId(
+  existing: Record<string, unknown>,
+  timestamp: string,
+): string {
+  suggestingRevisionCounter += 1;
+  const ts = timestamp.replace(/[^0-9]/gu, "");
+  let id = `change-${ts}-s${suggestingRevisionCounter}`;
+  while (existing[id]) {
+    suggestingRevisionCounter += 1;
+    id = `change-${ts}-s${suggestingRevisionCounter}`;
+  }
+  return id;
+}
+
+function createAuthoredRevision(
+  existing: Record<string, unknown>,
+  kind: "insertion" | "deletion",
+  from: number,
+  to: number,
+  authorId: string,
+  timestamp: string,
+  metadata: Partial<NonNullable<CanonicalRevisionRecord["metadata"]>> = {},
+): CanonicalRevisionRecord {
+  const changeId = createSuggestingRevisionId(existing, timestamp);
+  return {
+    changeId,
+    kind,
+    anchor: {
+      kind: "range",
+      range: { from, to },
+      assoc: { start: 1, end: -1 },
+    },
+    authorId,
+    createdAt: timestamp,
+    warningIds: [],
+    metadata: {
+      source: "runtime",
+      ...metadata,
+    },
+    status: "open",
+  };
+}
+
+function createSuggestionMetadata(args: {
+  suggestionId?: string;
+  semanticKind:
+    | "insertion"
+    | "deletion"
+    | "replacement"
+    | "formatting-change"
+    | "paragraph-property-change"
+    | "structural-change"
+    | "object-change";
+  linkedRevisionIds?: string[];
+  predecessorSuggestionId?: string;
+}): Partial<NonNullable<CanonicalRevisionRecord["metadata"]>> {
+  return {
+    suggestionId: args.suggestionId,
+    semanticKind: args.semanticKind,
+    linkedRevisionIds: args.linkedRevisionIds,
+    predecessorSuggestionId: args.predecessorSuggestionId,
+  };
+}
+
+function createSuggestingUnsupportedTransaction(
+  state: EditorState,
+  message: string,
+): EditorTransaction {
+  return createTransaction(state, {
+    historyBoundary: "skip",
+    markDirty: false,
+    effects: {
+      commandBlocked: {
+        code: "suggesting_unsupported",
+        message,
+      },
+    },
+  });
+}
+
+function isSingleParagraphSuggestingRange(
+  document: CanonicalDocumentEnvelope,
+  from: number,
+  to: number,
+): boolean {
+  const ranges: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+  let previousWasParagraph = false;
+
+  for (const block of document.content.children) {
+    if (block.type === "paragraph") {
+      if (previousWasParagraph) {
+        cursor += 1;
+      }
+      const start = cursor;
+      cursor += block.children.reduce<number>((size, child) => {
+        if (child.type === "text") {
+          return size + child.text.length;
+        }
+        if (child.type === "hyperlink") {
+          return size + child.children.reduce<number>((childSize, entry) => {
+            if (entry.type === "text") {
+              return childSize + entry.text.length;
+            }
+            return childSize + 1;
+          }, 0);
+        }
+        return size + 1;
+      }, 0);
+      ranges.push({ start, end: cursor });
+      previousWasParagraph = true;
+      continue;
+    }
+
+    cursor += 1;
+    previousWasParagraph = false;
+  }
+
+  return ranges.some((range) => from >= range.start && to <= range.end);
+}
+
+function applySuggestingInsert(
+  state: EditorState,
+  text: string,
+  context: CommandExecutionContext,
+): EditorTransaction | undefined {
+  if (state.readOnly) {
+    return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+  }
+
+  const authorId = context.defaultAuthorId ?? "unknown";
+  const selection = state.selection;
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  const isCollapsed = from === to;
+
+  if (!isCollapsed && !isSingleParagraphSuggestingRange(state.document, from, to)) {
+    return createSuggestingUnsupportedTransaction(
+      state,
+      "Suggesting mode does not yet support multi-paragraph replacement ranges.",
+    );
+  }
+
+  if (isCollapsed) {
+    // Pure insertion at cursor: apply normally, then create insertion revision
+    const result = insertText(state.document, selection, text, { timestamp: context.timestamp });
+    const insertedFrom = from;
+    const insertedTo = from + Array.from(text).length;
+
+    // Remap existing review state first (comments, pre-existing revisions)
+    const reviewState = remapReviewStateAfterContentChange(
+      state,
+      result.document,
+      result.mapping,
+    );
+
+    // Create the revision with pre-mapping positions — it refers to content
+    // that was just inserted, so its anchors are already correct in the new document
+    const revision = createAuthoredRevision(
+      reviewState.document.review.revisions,
+      "insertion",
+      insertedFrom,
+      insertedTo,
+      authorId,
+      context.timestamp,
+      createSuggestionMetadata({
+        semanticKind: "insertion",
+      }),
+    );
+
+    const finalDocument: CanonicalDocumentEnvelope = {
+      ...reviewState.document,
+      review: {
+        ...reviewState.document.review,
+        revisions: {
+          ...reviewState.document.review.revisions,
+          [revision.changeId]: revision,
+        },
+      },
+    };
+
+    return createTransaction(
+      {
+        ...state,
+        document: finalDocument,
+        selection: result.selection,
+        warnings: reviewState.warnings,
+        runtime: {
+          ...state.runtime,
+          activeCommentId: reviewState.activeCommentId,
+        },
+      },
+      {
+        historyBoundary: "push",
+        markDirty: true,
+        mapping: result.mapping,
+        effects: {
+          ...reviewState.effects,
+          revisionAuthored: { changeId: revision.changeId, kind: "insertion" },
+        },
+      },
+    );
+  }
+
+  // Non-collapsed selection: mark selected text as deletion, insert new text after selection
+  // Step 1: Insert new text at the end of the selection
+  const insertSelection = createSelectionSnapshot(to, to);
+  const result = insertText(state.document, insertSelection, text, { timestamp: context.timestamp });
+  const insertedFrom = to;
+  const insertedTo = to + Array.from(text).length;
+
+  // Step 2: Remap existing review state through the mapping first
+  const reviewState = remapReviewStateAfterContentChange(
+    state,
+    result.document,
+    result.mapping,
+  );
+  const replacementSuggestionId = createSuggestingRevisionId(
+    reviewState.document.review.revisions,
+    context.timestamp,
+  );
+
+  // Step 3: Create deletion revision for the selected range (text stays in place).
+  // Deletion range uses pre-mapping positions since content was not removed.
+  let deletionRevision = createAuthoredRevision(
+    reviewState.document.review.revisions,
+    "deletion",
+    from,
+    to,
+    authorId,
+    context.timestamp,
+    createSuggestionMetadata({
+      suggestionId: replacementSuggestionId,
+      semanticKind: "replacement",
+    }),
+  );
+
+  // Step 4: Create insertion revision for the new text (positions already correct)
+  const insertionRevision = createAuthoredRevision(
+    {
+      ...reviewState.document.review.revisions,
+      [deletionRevision.changeId]: deletionRevision,
+    },
+    "insertion",
+    insertedFrom,
+    insertedTo,
+    authorId,
+    context.timestamp,
+    createSuggestionMetadata({
+      suggestionId: replacementSuggestionId,
+      semanticKind: "replacement",
+      linkedRevisionIds: [deletionRevision.changeId],
+    }),
+  );
+  deletionRevision = {
+    ...deletionRevision,
+    metadata: {
+      ...deletionRevision.metadata,
+      linkedRevisionIds: [insertionRevision.changeId],
+    },
+  };
+
+  const finalDocument: CanonicalDocumentEnvelope = {
+    ...reviewState.document,
+    review: {
+      ...reviewState.document.review,
+      revisions: {
+        ...reviewState.document.review.revisions,
+        [deletionRevision.changeId]: deletionRevision,
+        [insertionRevision.changeId]: insertionRevision,
+      },
+    },
+  };
+
+  // Move cursor to after inserted text
+  const caretPos = insertedTo;
+
+  return createTransaction(
+    {
+      ...state,
+      document: finalDocument,
+      selection: createSelectionSnapshot(caretPos, caretPos),
+      warnings: reviewState.warnings,
+      runtime: {
+        ...state.runtime,
+        activeCommentId: reviewState.activeCommentId,
+      },
+    },
+    {
+      historyBoundary: "push",
+      markDirty: true,
+      mapping: result.mapping,
+      effects: {
+        ...reviewState.effects,
+        revisionAuthored: { changeId: insertionRevision.changeId, kind: "insertion" },
+      },
+    },
+  );
+}
+
+function applySuggestingDelete(
+  state: EditorState,
+  direction: "backward" | "forward",
+  context: CommandExecutionContext,
+): EditorTransaction | undefined {
+  if (state.readOnly) {
+    return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+  }
+
+  const authorId = context.defaultAuthorId ?? "unknown";
+  const selection = state.selection;
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  const isCollapsed = from === to;
+
+  if (!isCollapsed && !isSingleParagraphSuggestingRange(state.document, from, to)) {
+    return createSuggestingUnsupportedTransaction(
+      state,
+      "Suggesting mode does not yet support multi-paragraph deletion ranges.",
+    );
+  }
+
+  let deleteFrom: number;
+  let deleteTo: number;
+
+  if (isCollapsed) {
+    if (direction === "backward") {
+      deleteFrom = Math.max(0, from - 1);
+      deleteTo = from;
+    } else {
+      deleteFrom = from;
+      deleteTo = from + 1;
+    }
+  } else {
+    deleteFrom = from;
+    deleteTo = to;
+  }
+
+  // Validate the deletion range doesn't cross protected content
+  if (deleteFrom === deleteTo) {
+    return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+  }
+
+  // Check if the range overlaps an existing deletion revision from this suggesting session
+  // If so, extend the existing revision rather than creating a new one
+  const existingDeletion = findOverlappingAuthoredDeletion(
+    state.document.review.revisions,
+    deleteFrom,
+    deleteTo,
+  );
+
+  if (existingDeletion) {
+    // Extend the existing deletion revision to cover the new range
+    const extendedFrom = Math.min(
+      existingDeletion.anchor.kind === "range" ? existingDeletion.anchor.range.from : deleteFrom,
+      deleteFrom,
+    );
+    const extendedTo = Math.max(
+      existingDeletion.anchor.kind === "range" ? existingDeletion.anchor.range.to : deleteTo,
+      deleteTo,
+    );
+
+    const updatedRevision: CanonicalRevisionRecord = {
+      ...existingDeletion,
+      anchor: {
+        kind: "range",
+        range: { from: extendedFrom, to: extendedTo },
+        assoc: { start: 1, end: -1 },
+      },
+    };
+
+    const nextDocument: CanonicalDocumentEnvelope = {
+      ...state.document,
+      updatedAt: context.timestamp,
+      review: {
+        ...state.document.review,
+        revisions: {
+          ...state.document.review.revisions,
+          [updatedRevision.changeId]: updatedRevision,
+        },
+      },
+    };
+
+    const caretPos = direction === "backward" ? deleteFrom : deleteTo;
+
+    return createTransaction(
+      {
+        ...state,
+        document: nextDocument,
+        selection: createSelectionSnapshot(caretPos, caretPos),
+      },
+      {
+        historyBoundary: "push",
+        markDirty: true,
+        effects: {
+          revisionAuthored: { changeId: updatedRevision.changeId, kind: "deletion" },
+        },
+      },
+    );
+  }
+
+  // Create a new deletion revision — text stays in the document
+  const revision = createAuthoredRevision(
+    state.document.review.revisions,
+    "deletion",
+    deleteFrom,
+    deleteTo,
+    authorId,
+    context.timestamp,
+    createSuggestionMetadata({
+      semanticKind: "deletion",
+    }),
+  );
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...state.document,
+    updatedAt: context.timestamp,
+    review: {
+      ...state.document.review,
+      revisions: {
+        ...state.document.review.revisions,
+        [revision.changeId]: revision,
+      },
+    },
+  };
+
+  const caretPos = direction === "backward" ? deleteFrom : deleteTo;
+
+  return createTransaction(
+    {
+      ...state,
+      document: nextDocument,
+      selection: createSelectionSnapshot(caretPos, caretPos),
+    },
+    {
+      historyBoundary: "push",
+      markDirty: true,
+      effects: {
+        revisionAuthored: { changeId: revision.changeId, kind: "deletion" },
+      },
+    },
+  );
+}
+
+function applySuggestingInsertUnit(
+  state: EditorState,
+  unitType: "tab" | "hard_break",
+  context: CommandExecutionContext,
+): EditorTransaction | undefined {
+  if (state.readOnly) {
+    return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+  }
+
+  const authorId = context.defaultAuthorId ?? "unknown";
+  const selection = state.selection;
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+
+  if (from !== to && !isSingleParagraphSuggestingRange(state.document, from, to)) {
+    return createSuggestingUnsupportedTransaction(
+      state,
+      "Suggesting mode does not yet support multi-paragraph replacement ranges.",
+    );
+  }
+
+  // Insert the unit at the end of the selection (or at cursor if collapsed)
+  const insertPos = to;
+  const insertSelection = createSelectionSnapshot(insertPos, insertPos);
+  const applyFn = unitType === "tab" ? insertTab : insertHardBreak;
+  const result = applyFn(state.document, insertSelection, { timestamp: context.timestamp });
+
+  // Remap existing review state first, before adding new revisions
+  const reviewState = remapReviewStateAfterContentChange(
+    state,
+    result.document,
+    result.mapping,
+  );
+  const replacementSuggestionId = from !== to
+    ? createSuggestingRevisionId(reviewState.document.review.revisions, context.timestamp)
+    : undefined;
+
+  // If non-collapsed, mark selected range as deletion (positions are pre-mapping, content preserved)
+  let deletionRevision = from !== to
+    ? createAuthoredRevision(
+        reviewState.document.review.revisions,
+        "deletion",
+        from,
+        to,
+        authorId,
+        context.timestamp,
+        createSuggestionMetadata({
+          suggestionId: replacementSuggestionId,
+          semanticKind: "replacement",
+        }),
+      )
+    : undefined;
+
+  // Create insertion revision for the single inserted unit (positions already correct)
+  const insertionRevision = createAuthoredRevision(
+    {
+      ...reviewState.document.review.revisions,
+      ...(deletionRevision ? { [deletionRevision.changeId]: deletionRevision } : {}),
+    },
+    "insertion",
+    insertPos,
+    insertPos + 1,
+    authorId,
+    context.timestamp,
+    createSuggestionMetadata(
+      from !== to
+        ? {
+            suggestionId: replacementSuggestionId,
+            semanticKind: "replacement",
+            linkedRevisionIds: deletionRevision ? [deletionRevision.changeId] : undefined,
+          }
+        : {
+            semanticKind: "insertion",
+          },
+    ),
+  );
+  if (deletionRevision) {
+    deletionRevision = {
+      ...deletionRevision,
+      metadata: {
+        ...deletionRevision.metadata,
+        linkedRevisionIds: [insertionRevision.changeId],
+      },
+    };
+  }
+
+  const finalDocument: CanonicalDocumentEnvelope = {
+    ...reviewState.document,
+    review: {
+      ...reviewState.document.review,
+      revisions: {
+        ...reviewState.document.review.revisions,
+        ...(deletionRevision ? { [deletionRevision.changeId]: deletionRevision } : {}),
+        [insertionRevision.changeId]: insertionRevision,
+      },
+    },
+  };
+
+  return createTransaction(
+    {
+      ...state,
+      document: finalDocument,
+      selection: result.selection,
+      warnings: reviewState.warnings,
+      runtime: {
+        ...state.runtime,
+        activeCommentId: reviewState.activeCommentId,
+      },
+    },
+    {
+      historyBoundary: "push",
+      markDirty: true,
+      mapping: result.mapping,
+      effects: {
+        ...reviewState.effects,
+        revisionAuthored: { changeId: insertionRevision.changeId, kind: "insertion" },
+      },
+    },
+  );
+}
+
+function applySuggestingParagraphSplit(
+  state: EditorState,
+  context: CommandExecutionContext,
+): EditorTransaction | undefined {
+  if (state.readOnly) {
+    return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+  }
+
+  const selection = state.selection;
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+  if (from !== to) {
+    return createSuggestingUnsupportedTransaction(
+      state,
+      "Suggesting mode paragraph split currently requires a collapsed selection.",
+    );
+  }
+
+  const authorId = context.defaultAuthorId ?? "unknown";
+  const result = splitParagraph(state.document, selection, { timestamp: context.timestamp });
+
+  const reviewState = remapReviewStateAfterContentChange(
+    state,
+    result.document,
+    result.mapping,
+  );
+  const revision = createAuthoredRevision(
+    reviewState.document.review.revisions,
+    "insertion",
+    from,
+    from,
+    authorId,
+    context.timestamp,
+    {
+      ...createSuggestionMetadata({
+        semanticKind: "structural-change",
+      }),
+      importedRevisionForm: "paragraph-insertion",
+      originalRevisionType: "paragraph-ins",
+    },
+  );
+
+  const finalDocument: CanonicalDocumentEnvelope = {
+    ...reviewState.document,
+    review: {
+      ...reviewState.document.review,
+      revisions: {
+        ...reviewState.document.review.revisions,
+        [revision.changeId]: revision,
+      },
+    },
+  };
+
+  return createTransaction(
+    {
+      ...state,
+      document: finalDocument,
+      selection: result.selection,
+      warnings: reviewState.warnings,
+      runtime: {
+        ...state.runtime,
+        activeCommentId: reviewState.activeCommentId,
+      },
+    },
+    {
+      historyBoundary: "push",
+      markDirty: true,
+      mapping: result.mapping,
+      effects: {
+        ...reviewState.effects,
+        revisionAuthored: { changeId: revision.changeId, kind: "insertion" },
+      },
+    },
+  );
+}
+
+function findOverlappingAuthoredDeletion(
+  revisions: Record<string, CanonicalRevisionRecord>,
+  from: number,
+  to: number,
+): CanonicalRevisionRecord | undefined {
+  for (const revision of Object.values(revisions)) {
+    if (
+      revision.kind === "deletion" &&
+      revision.status === "open" &&
+      revision.metadata?.source === "runtime" &&
+      revision.anchor.kind === "range"
+    ) {
+      const revFrom = revision.anchor.range.from;
+      const revTo = revision.anchor.range.to;
+      // Adjacent or overlapping: the deletion is directly next to or overlapping the range
+      if (
+        (from >= revFrom && from <= revTo) ||
+        (to >= revFrom && to <= revTo) ||
+        (from === revTo) ||
+        (to === revFrom)
+      ) {
+        return revision;
+      }
+    }
+  }
+  return undefined;
+}