@beyondwork/docx-react-component 1.0.22 → 1.0.24-rc

package/src/runtime/document-runtime.ts

@@ -30,6 +30,8 @@ import type {
   HeaderFooterLinkPatch,
   ExportDocxOptions,
   ExportResult,
+  HostAnnotationOverlay,
+  HostAnnotationSnapshot,
   InteractionGuardSnapshot,
   PageLayoutSnapshot,
   PersistedEditorSnapshot,
@@ -65,7 +67,6 @@ import {
   type EditorCommand,
   type EditorTransaction,
 } from "../core/commands/index.ts";
-import { insertText } from "../core/commands/text-commands.ts";
 import {
   createDetachedAnchor,
   createEmptyMapping,
@@ -105,7 +106,11 @@ import {
   resolveActiveSection,
 } from "./document-layout.ts";
 import { normalizeHeaderFooterTarget } from "./story-context.ts";
-import { storyTargetKey } from "./story-targeting.ts";
+import {
+  getStoryBlocks,
+  replaceStoryBlocks,
+  storyTargetKey,
+} from "./story-targeting.ts";
 import {
   createViewState,
   setViewMode as applyViewMode,
@@ -149,12 +154,24 @@ export type DocumentRuntimeEvent =
     })
   | Exclude<WordReviewEditorEvent, { type: "ready" }>;
 
+export type ActiveStoryTextCommand =
+  | Extract<EditorCommand, { type: "text.insert" }>
+  | Extract<EditorCommand, { type: "text.delete-backward" }>
+  | Extract<EditorCommand, { type: "text.delete-forward" }>
+  | Extract<EditorCommand, { type: "text.insert-tab" }>
+  | Extract<EditorCommand, { type: "text.insert-hard-break" }>
+  | Extract<EditorCommand, { type: "paragraph.split" }>;
+
 export interface DocumentRuntime {
   subscribe(listener: () => void): Unsubscribe;
   subscribeToEvents(listener: (event: DocumentRuntimeEvent) => void): Unsubscribe;
   getRenderSnapshot(): RuntimeRenderSnapshot;
+  getCanonicalDocument(): CanonicalDocumentEnvelope;
+  getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
   replaceText(text: string, target?: EditorAnchorProjection): void;
+  applyActiveStoryTextCommand(command: ActiveStoryTextCommand): void;
   dispatch(command: EditorCommand): void;
+  emitBlockedCommand(command: string, reasons: WorkflowBlockedCommandReason[]): void;
   undo(): void;
   redo(): void;
   focus(): void;
@@ -194,6 +211,9 @@ export interface DocumentRuntime {
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
+  setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
+  clearHostAnnotationOverlay(): void;
+  getHostAnnotationSnapshot(): HostAnnotationSnapshot;
   getWorkflowCandidateRanges(options?: WorkflowCandidateRangeOptions): WorkflowCandidateRange[];
   replaceWorkflowMarkupText(markupId: string, text: string): void;
 }
@@ -254,6 +274,7 @@ export function createDocumentRuntime(
     preservedRangeCount: 0,
   };
   let workflowOverlay: WorkflowOverlay | null = null;
+  let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
   const initialPersistedSnapshot = options.initialSessionState
     ? persistedSnapshotFromEditorSessionState(options.initialSessionState, {
         savedAt: options.initialSessionState.updatedAt,
@@ -295,7 +316,7 @@ export function createDocumentRuntime(
   let cachedTrackedChanges:
     | {
         revisions: CanonicalDocumentEnvelope["review"]["revisions"];
-        plainText: string;
+        revisionToken: string;
         snapshot: TrackedChangesSnapshot;
       }
     | undefined;
@@ -344,6 +365,15 @@ export function createDocumentRuntime(
         snapshot: WorkflowScopeSnapshot;
       }
     | undefined;
+  let cachedWorkflowMarkupSnapshot:
+    | {
+        revisionToken: string;
+        activeStoryKey: string;
+        protectionSnapshot: ProtectionSnapshot;
+        preservation: CanonicalDocumentEnvelope["preservation"];
+        snapshot: WorkflowMarkupSnapshot;
+      }
+    | undefined;
 
   function getCachedSurface(
     document: CanonicalDocumentEnvelope,
@@ -422,21 +452,20 @@ export function createDocumentRuntime(
 
   function getCachedTrackedChangesSnapshot(
     nextState: EditorState,
-    surface: RuntimeRenderSnapshot["surface"],
+    _surface: RuntimeRenderSnapshot["surface"],
   ): TrackedChangesSnapshot {
-    const plainText = surface?.plainText ?? "";
     if (
       cachedTrackedChanges &&
       cachedTrackedChanges.revisions === nextState.document.review.revisions &&
-      cachedTrackedChanges.plainText === plainText
+      cachedTrackedChanges.revisionToken === nextState.revisionToken
     ) {
       return cachedTrackedChanges.snapshot;
     }
 
-    const snapshot = toPublicTrackedChangesSnapshot(nextState, plainText);
+    const snapshot = toPublicTrackedChangesSnapshot(nextState);
     cachedTrackedChanges = {
       revisions: nextState.document.review.revisions,
-      plainText,
+      revisionToken: nextState.revisionToken,
       snapshot,
     };
     return snapshot;
@@ -580,14 +609,28 @@ export function createDocumentRuntime(
       });
     }
 
+    const effectiveDocumentMode = getEffectiveDocumentMode(selection);
+
+    if (effectiveDocumentMode === "suggesting" && commandType) {
+      if (
+        activeStory.kind !== "main" &&
+        SUGGESTING_SECONDARY_STORY_UNSUPPORTED_COMMANDS.has(commandType)
+      ) {
+        reasons.push({
+          code: "suggesting_unsupported",
+          message: "Suggesting mode is not yet export-safe in this story.",
+        });
+      }
+      if (SUGGESTING_UNSUPPORTED_COMMANDS.has(commandType)) {
+        reasons.push({
+          code: "suggesting_unsupported",
+          message: `"${commandType}" is not supported in suggesting mode.`,
+        });
+      }
+    }
+
     if (workflowOverlay) {
-      const activeScopes = getEffectiveWorkflowScopes(workflowOverlay);
-      const matchingScope = activeScopes.find((scope) => {
-        if (scope.anchor.kind === "detached") return false;
-        const scopeFrom = scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
-        const scopeTo = scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
-        return selectionBounds.from >= scopeFrom && selectionBounds.to <= scopeTo;
-      });
+      const matchingScope = getMatchingWorkflowScope(selection);
 
       if (!matchingScope && workflowOverlay.scopes.length > 0) {
         reasons.push({
@@ -620,6 +663,39 @@ export function createDocumentRuntime(
     return reasons;
   }
 
+  function getMatchingWorkflowScope(
+    selection: EditorState["selection"],
+  ): WorkflowOverlay["scopes"][number] | null {
+    if (!workflowOverlay) {
+      return null;
+    }
+
+    const selectionBounds = {
+      from: Math.min(selection.anchor, selection.head),
+      to: Math.max(selection.anchor, selection.head),
+    };
+    const activeScopes = getEffectiveWorkflowScopes(workflowOverlay);
+    return activeScopes.find((scope) => {
+      if (scope.anchor.kind === "detached") return false;
+      const scopeFrom = scope.anchor.kind === "range" ? scope.anchor.from : scope.anchor.at;
+      const scopeTo = scope.anchor.kind === "range" ? scope.anchor.to : scope.anchor.at;
+      return selectionBounds.from >= scopeFrom && selectionBounds.to <= scopeTo;
+    }) ?? null;
+  }
+
+  function getEffectiveDocumentMode(
+    selection: EditorState["selection"],
+  ): DocumentMode {
+    if (viewState.documentMode === "viewing") {
+      return "viewing";
+    }
+    const matchingScope = getMatchingWorkflowScope(selection);
+    if (matchingScope?.mode === "suggest") {
+      return "suggesting";
+    }
+    return viewState.documentMode;
+  }
+
   function expandSelectionRange(
     range: { from: number; to: number },
   ): { from: number; to: number } {
@@ -632,10 +708,14 @@ export function createDocumentRuntime(
   function deriveOpaqueWorkflowBlockedReason(
     range: { from: number; to: number },
   ): WorkflowBlockedCommandReason | null {
+    const targetPartPath = getStoryTargetOpaquePartPath(activeStory);
+    if (!targetPartPath) {
+      return null;
+    }
     const fragments = findOpaqueFragmentsIntersectingRange(
       state.document.preservation,
       range,
-    );
+    ).filter((fragment) => fragment.packagePartName === targetPartPath);
 
     if (fragments.length === 0) {
       return null;
@@ -669,6 +749,35 @@ export function createDocumentRuntime(
     };
   }
 
+  function getStoryTargetOpaquePartPath(storyTarget: EditorStoryTarget): string | null {
+    if (storyTarget.kind === "main") {
+      return "/word/document.xml";
+    }
+    if (storyTarget.kind === "header") {
+      return state.document.subParts?.headers.find(
+        (header) =>
+          header.relationshipId === storyTarget.relationshipId
+          && header.variant === storyTarget.variant
+          && header.sectionIndex === storyTarget.sectionIndex,
+      )?.partPath ?? null;
+    }
+    if (storyTarget.kind === "footer") {
+      return state.document.subParts?.footers.find(
+        (footer) =>
+          footer.relationshipId === storyTarget.relationshipId
+          && footer.variant === storyTarget.variant
+          && footer.sectionIndex === storyTarget.sectionIndex,
+      )?.partPath ?? null;
+    }
+    if (storyTarget.kind === "footnote") {
+      return "/word/footnotes.xml";
+    }
+    if (storyTarget.kind === "endnote") {
+      return "/word/endnotes.xml";
+    }
+    return null;
+  }
+
   function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
     if (!workflowOverlay) return null;
     const blockedReasons = getCachedInteractionGuardSnapshot().blockedReasons;
@@ -687,6 +796,13 @@ export function createDocumentRuntime(
     };
   }
 
+  function deriveHostAnnotationSnapshot(): HostAnnotationSnapshot {
+    return {
+      totalCount: hostAnnotationOverlay?.annotations.length ?? 0,
+      annotations: structuredClone(hostAnnotationOverlay?.annotations ?? []),
+    };
+  }
+
   function getEffectiveWorkflowScopes(overlay: WorkflowOverlay): WorkflowOverlay["scopes"] {
     const activeWorkItemId = overlay.activeWorkItemId ?? null;
     const activeWorkItemScopeIds =
@@ -728,8 +844,25 @@ export function createDocumentRuntime(
       return cachedInteractionGuardSnapshot.snapshot;
     }
 
-    const snapshot = {
-      blockedReasons: evaluateWorkflowBlockedReasons(state.selection),
+    const blockedReasons = evaluateWorkflowBlockedReasons(state.selection);
+    const matchingScope = getMatchingWorkflowScope(state.selection);
+    const primaryBlockedReason = blockedReasons[0];
+    const snapshot: InteractionGuardSnapshot = {
+      effectiveMode: primaryBlockedReason
+        ? (
+          primaryBlockedReason.code === "workflow_comment_only"
+            ? "comment"
+            : primaryBlockedReason.code === "workflow_view_only"
+              ? "view"
+              : "blocked"
+        )
+        : getEffectiveDocumentMode(state.selection) === "suggesting"
+          ? "suggest"
+          : matchingScope?.mode ?? "edit",
+      ...(matchingScope?.scopeId ? { matchedScopeId: matchingScope.scopeId } : {}),
+      ...(matchingScope?.mode ? { matchedScopeMode: matchingScope.mode } : {}),
+      ...(primaryBlockedReason ? { disabledReason: primaryBlockedReason.message } : {}),
+      blockedReasons,
     };
     cachedInteractionGuardSnapshot = {
       revisionToken: state.revisionToken,
@@ -767,6 +900,34 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  function getCachedWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot {
+    const activeStoryKey = storyTargetKey(activeStory);
+    if (
+      cachedWorkflowMarkupSnapshot &&
+      cachedWorkflowMarkupSnapshot.revisionToken === state.revisionToken &&
+      cachedWorkflowMarkupSnapshot.activeStoryKey === activeStoryKey &&
+      cachedWorkflowMarkupSnapshot.protectionSnapshot === protectionSnapshot &&
+      cachedWorkflowMarkupSnapshot.preservation === state.document.preservation
+    ) {
+      return cachedWorkflowMarkupSnapshot.snapshot;
+    }
+
+    const snapshot = collectWorkflowMarkupSnapshot({
+      renderSnapshot: cachedRenderSnapshot,
+      fieldSnapshot: buildFieldSnapshot(state.document),
+      protectionSnapshot,
+      preservation: state.document.preservation,
+    });
+    cachedWorkflowMarkupSnapshot = {
+      revisionToken: state.revisionToken,
+      activeStoryKey,
+      protectionSnapshot,
+      preservation: state.document.preservation,
+      snapshot,
+    };
+    return snapshot;
+  }
+
   function refreshRenderSnapshot(): RuntimeRenderSnapshot {
     const surface = getCachedSurface(state.document, activeStory);
     return {
@@ -878,10 +1039,25 @@ export function createDocumentRuntime(
     getRenderSnapshot() {
       return cachedRenderSnapshot;
     },
+    getCanonicalDocument() {
+      return state.document;
+    },
+    getSourcePackage() {
+      return state.sourcePackage;
+    },
+    emitBlockedCommand(command, reasons) {
+      emit({
+        type: "command_blocked",
+        documentId: state.documentId,
+        command,
+        reasons,
+      });
+    },
     dispatch(command) {
+      const commandSelection = getCommandSelection(command, state.selection);
       if (isMutationCommand(command)) {
         const blockedReasons = evaluateWorkflowBlockedReasons(
-          getCommandSelection(command, state.selection),
+          commandSelection,
           command.type,
         );
         if (blockedReasons.length > 0) {
@@ -909,6 +1085,8 @@ export function createDocumentRuntime(
       try {
         const transaction = executeEditorCommand(state, command, {
           timestamp: command.origin?.timestamp ?? clock(),
+          documentMode: getEffectiveDocumentMode(commandSelection),
+          defaultAuthorId: defaultAuthorId ?? undefined,
         });
         commit(transaction);
       } catch (error) {
@@ -949,29 +1127,24 @@ export function createDocumentRuntime(
     replaceText(text, target) {
       try {
         const timestamp = clock();
-        const selection = target
-          ? createSelectionFromPublicAnchor(target)
-          : state.selection;
-        const blockedReasons = evaluateWorkflowBlockedReasons(selection, "text.insert");
-        if (blockedReasons.length > 0) {
-          emit({
-            type: "command_blocked",
-            documentId: state.documentId,
-            command: "replaceText",
-            reasons: blockedReasons,
-          });
-          return;
-        }
-        const result = insertText(state.document, selection, text, { timestamp });
-
-        this.dispatch({
-          type: "document.replace",
-          document: result.document,
-          mapping: result.mapping,
-          selection: result.selection,
-          protectionSelection: selection,
-          origin: createOrigin("api", timestamp),
-        });
+        applyTextCommandInActiveStory(
+          {
+            type: "text.insert",
+            text,
+            origin: createOrigin("api", timestamp),
+          },
+          {
+            selection: target ? createSelectionFromPublicAnchor(target) : state.selection,
+            blockedCommandName: "replaceText",
+          },
+        );
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    applyActiveStoryTextCommand(command) {
+      try {
+        applyTextCommandInActiveStory(command);
       } catch (error) {
         emitError(toRuntimeError(error));
       }
@@ -1308,12 +1481,32 @@ export function createDocumentRuntime(
       return getCachedInteractionGuardSnapshot();
     },
     getWorkflowMarkupSnapshot() {
-      return collectWorkflowMarkupSnapshot({
-        renderSnapshot: this.getRenderSnapshot(),
-        fieldSnapshot: this.getFieldSnapshot(),
-        protectionSnapshot,
-        preservation: state.document.preservation,
+      return getCachedWorkflowMarkupSnapshot();
+    },
+    setHostAnnotationOverlay(overlay) {
+      hostAnnotationOverlay = structuredClone(overlay);
+      emit({
+        type: "host_annotation_overlay_changed",
+        documentId: state.documentId,
+        snapshot: deriveHostAnnotationSnapshot(),
       });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    clearHostAnnotationOverlay() {
+      hostAnnotationOverlay = null;
+      emit({
+        type: "host_annotation_overlay_changed",
+        documentId: state.documentId,
+        snapshot: deriveHostAnnotationSnapshot(),
+      });
+      for (const listener of listeners) {
+        listener();
+      }
+    },
+    getHostAnnotationSnapshot() {
+      return deriveHostAnnotationSnapshot();
     },
     getWorkflowCandidateRanges(options) {
       return deriveWorkflowCandidateRangesFromMarkup(this.getWorkflowMarkupSnapshot(), options);
@@ -1325,6 +1518,14 @@ export function createDocumentRuntime(
       if (!target || target.anchor.kind === "detached") {
         return;
       }
+      const targetStory = target.storyTarget ?? MAIN_STORY_TARGET;
+      if (!storyTargetsEqual(activeStory, targetStory)) {
+        if (targetStory.kind === "main") {
+          this.closeStory();
+        } else if (!this.openStory(targetStory)) {
+          return;
+        }
+      }
       this.replaceText(text, target.anchor);
     },
   };
@@ -1343,7 +1544,7 @@ export function createDocumentRuntime(
     const previous = state;
     // Undo/redo changes the document — must mint a new revisionToken so
     // autosave/export checkpoint dedup treats it as fresh content.
-    state = finalizeState(target, true, clock());
+    state = finalizeState(target, true, clock(), previous.revision);
     storySelections.set(storyTargetKey(activeStory), state.selection);
     cachedRenderSnapshot = refreshRenderSnapshot();
     notify(previous, state, {
@@ -1427,6 +1628,27 @@ export function createDocumentRuntime(
       });
     }
 
+    if (transaction.effects.revisionAuthored) {
+      emit({
+        type: "change_authored",
+        documentId: next.documentId,
+        changeId: transaction.effects.revisionAuthored.changeId,
+        kind: transaction.effects.revisionAuthored.kind,
+      });
+    }
+
+    if (transaction.effects.commandBlocked) {
+      emit({
+        type: "command_blocked",
+        documentId: next.documentId,
+        command: transaction.effects.commandBlocked.code,
+        reasons: [{
+          code: transaction.effects.commandBlocked.code as WorkflowBlockedCommandReason["code"],
+          message: transaction.effects.commandBlocked.message,
+        }],
+      });
+    }
+
     for (const warning of transaction.effects.warningsAdded) {
       const publicWarning = toPublicWarning(warning);
       emit({
@@ -1451,6 +1673,164 @@ export function createDocumentRuntime(
     }
   }
 
+  function applyTextCommandInActiveStory(
+    command: ActiveStoryTextCommand,
+    options: {
+      selection?: EditorState["selection"];
+      blockedCommandName?: string;
+    } = {},
+  ): void {
+    const selection = options.selection ?? state.selection;
+    const blockedReasons = evaluateWorkflowBlockedReasons(selection, command.type);
+    if (blockedReasons.length > 0) {
+      emit({
+        type: "command_blocked",
+        documentId: state.documentId,
+        command: options.blockedCommandName ?? command.type,
+        reasons: blockedReasons,
+      });
+      return;
+    }
+
+    const timestamp = command.origin?.timestamp ?? clock();
+    const context = {
+      timestamp,
+      documentMode: getEffectiveDocumentMode(selection),
+      defaultAuthorId: defaultAuthorId ?? undefined,
+    } as const;
+    const baseState = selection === state.selection
+      ? state
+      : {
+          ...state,
+          selection,
+        };
+
+    if (activeStory.kind === "main") {
+      commit(executeEditorCommand(baseState, command, context));
+      return;
+    }
+
+    const localState = createEditorState({
+      documentId: state.documentId,
+      sessionId,
+      sourceLabel: state.sourceLabel,
+      readOnly: state.readOnly,
+      canonicalDocument: {
+        ...state.document,
+        content: {
+          type: "doc",
+          children: [...getStoryBlocks(state.document, activeStory)],
+        },
+        review: createSecondaryStoryLocalReviewState(state.document.review, activeStory),
+      },
+      compatibility: state.compatibility,
+      warnings: state.warnings,
+      fatalError: state.fatalError,
+    });
+    localState.selection = selection;
+    const localTransaction = executeEditorCommand(localState, command, context);
+
+    if (!localTransaction.markDirty) {
+      notify(state, state, {
+        nextState: state,
+        mapping: createEmptyMapping(),
+        effects: localTransaction.effects,
+        historyBoundary: "skip",
+        markDirty: false,
+      });
+      return;
+    }
+
+    const nextDocument = replaceStoryBlocks(
+      state.document,
+      activeStory,
+      localTransaction.nextState.document.content.children,
+    );
+    const nextDocumentWithReview = {
+      ...nextDocument,
+      review: mergeSecondaryStoryReviewState(
+        state.document.review,
+        localTransaction.nextState.document.review,
+        localTransaction.effects,
+        activeStory,
+      ),
+    };
+    const fullTransaction = executeEditorCommand(
+      baseState,
+      {
+        type: "document.replace",
+        document: nextDocumentWithReview,
+        selection: localTransaction.nextState.selection,
+        mapping: createEmptyMapping(),
+        protectionSelection: selection,
+        origin: command.origin,
+      },
+      context,
+    );
+
+    commit({
+      ...fullTransaction,
+      effects: mergeTransactionEffects(fullTransaction.effects, localTransaction.effects),
+    });
+  }
+
+  function mergeTransactionEffects(
+    base: EditorTransaction["effects"],
+    local: EditorTransaction["effects"],
+  ): EditorTransaction["effects"] {
+    return {
+      warningsAdded: [...base.warningsAdded, ...local.warningsAdded],
+      warningsCleared: [...base.warningsCleared, ...local.warningsCleared],
+      commentAdded: base.commentAdded ?? local.commentAdded,
+      commentResolved: base.commentResolved ?? local.commentResolved,
+      commentReopened: base.commentReopened ?? local.commentReopened,
+      commentReplyAdded: base.commentReplyAdded ?? local.commentReplyAdded,
+      commentBodyEdited: base.commentBodyEdited ?? local.commentBodyEdited,
+      changeAccepted: base.changeAccepted ?? local.changeAccepted,
+      changeRejected: base.changeRejected ?? local.changeRejected,
+      revisionAuthored: base.revisionAuthored ?? local.revisionAuthored,
+      commandBlocked: base.commandBlocked ?? local.commandBlocked,
+    };
+  }
+
+  function mergeSecondaryStoryReviewState(
+    currentReview: EditorState["document"]["review"],
+    localReview: EditorState["document"]["review"],
+    effects: EditorTransaction["effects"],
+    storyTarget: EditorStoryTarget,
+  ): EditorState["document"]["review"] {
+    const nextReview: EditorState["document"]["review"] = {
+      comments: { ...currentReview.comments },
+      revisions: { ...currentReview.revisions },
+    };
+
+    const currentStoryRevisionIds = Object.values(currentReview.revisions)
+      .filter((revision) => storyTargetsEqual(getRevisionStoryTarget(revision), storyTarget))
+      .map((revision) => revision.changeId);
+    for (const revisionId of currentStoryRevisionIds) {
+      delete nextReview.revisions[revisionId];
+    }
+    for (const revision of Object.values(localReview.revisions)) {
+      nextReview.revisions[revision.changeId] = {
+        ...revision,
+        metadata: {
+          ...revision.metadata,
+          storyTarget: createRevisionStoryTargetRecord(storyTarget),
+        },
+      };
+    }
+
+    if (effects.commentAdded) {
+      const commentId = effects.commentAdded.commentId;
+      const comment = localReview.comments[commentId];
+      if (comment) {
+        nextReview.comments[commentId] = comment;
+      }
+    }
+
+    return nextReview;
+  }
+
   function emit(event: DocumentRuntimeEvent): void {
     options.onEvent?.(event);
     for (const listener of eventListeners) {
@@ -1547,11 +1927,12 @@ function finalizeState(
   state: EditorState,
   markDirty: boolean,
   timestamp: string,
+  baseRevision?: number,
 ): EditorState {
   // Only increment revision on actual document mutations (markDirty=true).
   // Selection-only changes must not churn the revisionToken, which would
   // cause autosave/checkpoint dedup to treat cursor movement as new content.
-  const revision = markDirty ? state.revision + 1 : state.revision;
+  const revision = markDirty ? (baseRevision ?? state.revision) + 1 : state.revision;
 
   return {
     ...state,
@@ -1780,11 +2161,11 @@ function toPublicCommentSidebarSnapshot(
 
 function toPublicTrackedChangesSnapshot(
   state: EditorState,
-  surfaceText = "",
 ): TrackedChangesSnapshot {
   const projection = createRevisionSidebarProjection(
     createRevisionStoreFromDocument(state),
   );
+  const storyPlainTextCache = new Map<string, string>();
 
   return {
     pendingChangeIds: projection.activeRevisionIds,
@@ -1796,11 +2177,12 @@ function toPublicTrackedChangesSnapshot(
     totalCount: projection.totalCount,
     revisions: projection.revisions.map((revision): TrackedChangeEntrySnapshot => {
       const sourceRevision = state.document.review.revisions[revision.revisionId];
+      const storyTarget = getRevisionStoryTarget(sourceRevision);
       const preview = describeRevisionPreview(
         revision,
         sourceRevision?.anchor ??
           createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
-        surfaceText,
+        getStoryPlainText(state.document, storyTarget, storyPlainTextCache),
       );
 
       return {
@@ -1809,6 +2191,7 @@ function toPublicTrackedChangesSnapshot(
         label: revision.label,
         status: revision.status,
         actionability: revision.actionability,
+        storyTarget,
         anchor: toPublicAnchorProjection(
           sourceRevision?.anchor ??
             createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
@@ -1849,6 +2232,7 @@ function createRevisionStoreFromDocument(
           warningIds: [...(revision.warningIds ?? [])],
           metadata: {
             source: revision.metadata?.source ?? "runtime",
+            storyTarget: revision.metadata?.storyTarget,
             preserveOnlyReason: revision.metadata?.preserveOnlyReason,
             importedRevisionForm: revision.metadata?.importedRevisionForm,
             originalRevisionType: revision.metadata?.originalRevisionType,
@@ -1860,6 +2244,61 @@ function createRevisionStoreFromDocument(
   };
 }
 
+function getRevisionStoryTarget(
+  revision: EditorState["document"]["review"]["revisions"][string] | undefined,
+): EditorStoryTarget {
+  const storyTarget = revision?.metadata?.storyTarget;
+  return storyTarget ? { ...storyTarget } : MAIN_STORY_TARGET;
+}
+
+function createSecondaryStoryLocalReviewState(
+  review: EditorState["document"]["review"],
+  storyTarget: EditorStoryTarget,
+): EditorState["document"]["review"] {
+  return {
+    comments: {},
+    revisions: Object.fromEntries(
+      Object.values(review.revisions)
+        .filter((revision) => storyTargetsEqual(getRevisionStoryTarget(revision), storyTarget))
+        .map((revision) => [
+          revision.changeId,
+          {
+            ...revision,
+            metadata: {
+              ...revision.metadata,
+              storyTarget: createRevisionStoryTargetRecord(storyTarget),
+            },
+          },
+        ]),
+    ),
+  };
+}
+
+function getStoryPlainText(
+  document: CanonicalDocumentEnvelope,
+  storyTarget: EditorStoryTarget,
+  cache: Map<string, string>,
+): string {
+  const key = storyTargetKey(storyTarget);
+  const cached = cache.get(key);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const plainText = createEditorSurfaceSnapshot(
+    document,
+    createSelectionSnapshot(0, 0),
+    storyTarget,
+  ).plainText;
+  cache.set(key, plainText);
+  return plainText;
+}
+
+function createRevisionStoryTargetRecord(
+  storyTarget: EditorStoryTarget,
+): NonNullable<NonNullable<EditorState["document"]["review"]["revisions"][string]["metadata"]>["storyTarget"]> {
+  return { ...storyTarget };
+}
+
 function listBlockExportReasons(
   report: InternalCompatibilityReport,
 ): string[] {
@@ -2011,6 +2450,19 @@ const NON_MUTATION_COMMANDS = new Set([
   "comment.open",
 ]);
 
+/** Mutation commands that are not yet supported in suggesting mode. */
+const SUGGESTING_UNSUPPORTED_COMMANDS = new Set([
+  "paragraph.split",
+]);
+
+const SUGGESTING_SECONDARY_STORY_UNSUPPORTED_COMMANDS = new Set([
+  "text.insert",
+  "text.delete-backward",
+  "text.delete-forward",
+  "text.insert-tab",
+  "text.insert-hard-break",
+]);
+
 function isMutationCommand(command: EditorCommand): boolean {
   return !NON_MUTATION_COMMANDS.has(command.type);
 }