@beyondwork/docx-react-component 1.0.1 → 1.0.3

package/src/runtime/document-runtime.ts

@@ -0,0 +1,967 @@
+import {
+  createEditorState,
+  createPersistedEditorSnapshot,
+  deriveDocumentStats,
+  type CanonicalDocumentEnvelope,
+  type CommentEntryRecord,
+  type CommentThreadRecord,
+  type CompatibilityFeatureEntry as InternalCompatibilityFeatureEntry,
+  type CompatibilityReport as InternalCompatibilityReport,
+  type EditorError as InternalEditorError,
+  type EditorState,
+  type EditorWarning as InternalEditorWarning,
+} from "../core/state/editor-state.ts";
+import type {
+  AddCommentParams,
+  CommentSidebarSnapshot,
+  CommentSidebarThreadSnapshot,
+  CompatibilityReport,
+  EditorAnchorProjection,
+  EditorError,
+  EditorWarning,
+  ExportDocxOptions,
+  ExportResult,
+  PersistedEditorSnapshot,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot,
+  TrackedChangeEntrySnapshot,
+  TrackedChangesSnapshot,
+  WordReviewEditorEvent,
+} from "../api/public-types";
+import {
+  executeEditorCommand,
+  selectionChanged,
+  type CommandOrigin,
+  type EditorCommand,
+  type EditorTransaction,
+} from "../core/commands/index.ts";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+  type EditorAnchorProjection as InternalEditorAnchorProjection,
+} from "../core/selection/mapping.ts";
+import { createCommentSidebarProjection } from "../review/store/comment-store.ts";
+import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
+import {
+  createRevisionSidebarProjection,
+  type RevisionStore,
+} from "../review/store/revision-store.ts";
+import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
+import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
+
+export type Unsubscribe = () => void;
+
+export interface DocumentRuntime {
+  subscribe(listener: () => void): Unsubscribe;
+  subscribeToEvents(listener: (event: WordReviewEditorEvent) => void): Unsubscribe;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  dispatch(command: EditorCommand): void;
+  undo(): void;
+  redo(): void;
+  focus(): void;
+  blur(): void;
+  addComment(params: AddCommentParams): string;
+  openComment(commentId: string): void;
+  resolveComment(commentId: string): void;
+  reopenComment(commentId: string): void;
+  addCommentReply(commentId: string, body: string, authorId?: string): void;
+  editCommentBody(commentId: string, body: string): void;
+  acceptChange(changeId: string): void;
+  rejectChange(changeId: string): void;
+  acceptAllChanges(): void;
+  rejectAllChanges(): void;
+  getPersistedSnapshot(): PersistedEditorSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+}
+
+export interface CreateDocumentRuntimeOptions {
+  documentId: string;
+  initialSnapshot?: PersistedEditorSnapshot;
+  initialCanonicalDocument?: CanonicalDocumentEnvelope;
+  sourceLabel?: string;
+  sourceKind?: "docx" | "snapshot" | "datastore" | "canonical";
+  readOnly?: boolean;
+  editorBuild?: string;
+  defaultAuthorId?: string;
+  fatalError?: EditorError;
+  clock?: () => string;
+  exportDocx?: (
+    snapshot: PersistedEditorSnapshot,
+    options?: ExportDocxOptions,
+  ) => Promise<ExportResult>;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}
+
+interface HistoryState {
+  past: EditorState[];
+  future: EditorState[];
+}
+
+export function createDocumentRuntime(
+  options: CreateDocumentRuntimeOptions,
+): DocumentRuntime {
+  const clock = options.clock ?? (() => new Date().toISOString());
+  const editorBuild = options.editorBuild ?? "dev";
+  const sessionId = createSessionId(options.documentId, clock());
+  const listeners = new Set<() => void>();
+  const eventListeners = new Set<(event: WordReviewEditorEvent) => void>();
+  const history: HistoryState = {
+    past: [],
+    future: [],
+  };
+
+  let state = createEditorState({
+    documentId: options.documentId,
+    sessionId,
+    sourceLabel: options.sourceLabel,
+    readOnly: options.readOnly,
+    persistedSnapshot: options.initialSnapshot as never,
+    canonicalDocument: options.initialCanonicalDocument,
+    fatalError: options.fatalError as never,
+  });
+  let cachedRenderSnapshot = createPublicRenderSnapshot(state, history);
+
+  emit({
+    type: "ready",
+    documentId: state.documentId,
+    sessionId: state.sessionId,
+    source: options.sourceKind ?? (options.initialSnapshot ? "snapshot" : "canonical"),
+    stats: toPublicDocumentStats(state),
+    compatibility: toPublicCompatibilityReport(createDerivedCompatibility(state)),
+  });
+  if (options.fatalError) {
+    emit({
+      type: "error",
+      documentId: state.documentId,
+      error: options.fatalError,
+    });
+  }
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    subscribeToEvents(listener) {
+      eventListeners.add(listener);
+      return () => {
+        eventListeners.delete(listener);
+      };
+    },
+    getRenderSnapshot() {
+      return cachedRenderSnapshot;
+    },
+    dispatch(command) {
+      if (command.type === "history.undo") {
+        applyHistory("undo");
+        return;
+      }
+
+      if (command.type === "history.redo") {
+        applyHistory("redo");
+        return;
+      }
+
+      try {
+        const transaction = executeEditorCommand(state, command, {
+          timestamp: command.origin?.timestamp ?? clock(),
+        });
+        commit(transaction);
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
+    undo() {
+      this.dispatch({
+        type: "history.undo",
+        origin: createOrigin("runtime", clock()),
+      });
+    },
+    redo() {
+      this.dispatch({
+        type: "history.redo",
+        origin: createOrigin("runtime", clock()),
+      });
+    },
+    focus() {
+      this.dispatch({
+        type: "runtime.focus",
+        focused: true,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    blur() {
+      this.dispatch({
+        type: "runtime.focus",
+        focused: false,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    addComment(params) {
+      const commentId = createEntityId("comment", state.document.review.comments, clock());
+      const anchor = params.anchor
+        ? toInternalAnchorProjection(params.anchor)
+        : state.selection.activeRange;
+      const authorId = params.authorId ?? options.defaultAuthorId ?? "unknown";
+      const createdAt = clock();
+      const entries: CommentEntryRecord[] = [
+        {
+          entryId: `${commentId}-entry-1`,
+          authorId,
+          body: params.body ?? "",
+          createdAt,
+        },
+      ];
+      const comment: CommentThreadRecord = {
+        commentId,
+        anchor,
+        createdAt,
+        createdBy: authorId,
+        authorId,
+        body: params.body ?? "",
+        entries,
+        status: anchor.kind === "detached" ? "detached" : "open",
+        warningIds: [],
+        isResolved: false,
+        metadata: {
+          source: "runtime",
+        },
+      };
+
+      this.dispatch({
+        type: "comment.add",
+        comment,
+        origin: createOrigin("api", clock()),
+      });
+
+      return commentId;
+    },
+    openComment(commentId) {
+      this.dispatch({
+        type: "comment.open",
+        commentId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    resolveComment(commentId) {
+      this.dispatch({
+        type: "comment.resolve",
+        commentId,
+        resolvedBy: options.defaultAuthorId ?? "unknown",
+        origin: createOrigin("api", clock()),
+      });
+    },
+    reopenComment(commentId) {
+      this.dispatch({
+        type: "comment.reopen",
+        commentId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    addCommentReply(commentId, body, authorId) {
+      this.dispatch({
+        type: "comment.add-reply",
+        commentId,
+        body,
+        authorId: authorId ?? options.defaultAuthorId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    editCommentBody(commentId, body) {
+      this.dispatch({
+        type: "comment.edit-body",
+        commentId,
+        body,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    acceptChange(changeId) {
+      this.dispatch({
+        type: "change.accept",
+        changeId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    rejectChange(changeId) {
+      this.dispatch({
+        type: "change.reject",
+        changeId,
+        origin: createOrigin("api", clock()),
+      });
+    },
+    acceptAllChanges() {
+      this.dispatch({
+        type: "change.accept-all",
+        origin: createOrigin("api", clock()),
+      });
+    },
+    rejectAllChanges() {
+      this.dispatch({
+        type: "change.reject-all",
+        origin: createOrigin("api", clock()),
+      });
+    },
+    getPersistedSnapshot() {
+      const compatibility = createDerivedCompatibility(state);
+      return createPersistedEditorSnapshot(state, {
+        editorBuild,
+        savedAt: clock(),
+        compatibility,
+      }) as unknown as PersistedEditorSnapshot;
+    },
+    getCompatibilityReport() {
+      return toPublicCompatibilityReport(createDerivedCompatibility(state));
+    },
+    getWarnings() {
+      return state.warnings.map((warning) => toPublicWarning(warning));
+    },
+    async exportDocx(exportOptions) {
+      if (!options.exportDocx) {
+        const error: InternalEditorError = {
+          errorId: createEntityId("error", {}, clock()),
+          code: "export_failed",
+          isFatal: false,
+          message: "DOCX export requires an injected exporter until the IO substrate lands.",
+          source: "export",
+          details: {
+            requestedOptions: exportOptions ?? {},
+          },
+        };
+        emitError(error);
+        throw new Error(error.message);
+      }
+
+      const result = await options.exportDocx(
+        createPersistedEditorSnapshot(state, {
+          editorBuild,
+          savedAt: clock(),
+          compatibility: createDerivedCompatibility(state),
+        }) as unknown as PersistedEditorSnapshot,
+        exportOptions,
+      );
+
+      emit({
+        type: "export_completed",
+        documentId: state.documentId,
+        result,
+      });
+
+      return result;
+    },
+  };
+
+  function applyHistory(direction: "undo" | "redo"): void {
+    const source = direction === "undo" ? history.past : history.future;
+    const target = source.pop();
+
+    if (!target) {
+      return;
+    }
+
+    const counterpart = direction === "undo" ? history.future : history.past;
+    counterpart.push(state);
+
+    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());
+    cachedRenderSnapshot = createPublicRenderSnapshot(state, history);
+    notify(previous, state, {
+      nextState: state,
+      mapping: { steps: [] },
+      effects: {
+        warningsAdded: [],
+        warningsCleared: [],
+      },
+      historyBoundary: "skip",
+      markDirty: true,
+    });
+  }
+
+  function commit(transaction: EditorTransaction): void {
+    const previous = state;
+
+    if (transaction.historyBoundary === "push") {
+      history.past.push(state);
+      history.future = [];
+    }
+
+    state = finalizeState(transaction.nextState, transaction.markDirty, clock());
+    cachedRenderSnapshot = createPublicRenderSnapshot(state, history);
+    notify(previous, state, transaction);
+  }
+
+  function notify(
+    previous: EditorState,
+    next: EditorState,
+    transaction: EditorTransaction,
+  ): void {
+    if (previous.isDirty !== next.isDirty) {
+      emit({
+        type: "dirty_changed",
+        documentId: next.documentId,
+        isDirty: next.isDirty,
+      });
+    }
+
+    if (selectionChanged(previous.selection, next.selection)) {
+      emit({
+        type: "selection_changed",
+        documentId: next.documentId,
+        selection: toPublicSelectionSnapshot(next.selection),
+      });
+    }
+
+    if (transaction.effects.commentAdded) {
+      emit({
+        type: "comment_added",
+        documentId: next.documentId,
+        commentId: transaction.effects.commentAdded.commentId,
+        anchor: toPublicAnchorProjection(transaction.effects.commentAdded.anchor),
+      });
+    }
+
+    if (transaction.effects.commentResolved) {
+      emit({
+        type: "comment_resolved",
+        documentId: next.documentId,
+        commentId: transaction.effects.commentResolved.commentId,
+      });
+    }
+
+    if (transaction.effects.changeAccepted) {
+      emit({
+        type: "change_accepted",
+        documentId: next.documentId,
+        changeId: transaction.effects.changeAccepted.changeId,
+      });
+    }
+
+    if (transaction.effects.changeRejected) {
+      emit({
+        type: "change_rejected",
+        documentId: next.documentId,
+        changeId: transaction.effects.changeRejected.changeId,
+      });
+    }
+
+    for (const warning of transaction.effects.warningsAdded) {
+      const publicWarning = toPublicWarning(warning);
+      emit({
+        type: "warning_added",
+        documentId: next.documentId,
+        warning: publicWarning,
+      });
+      options.onWarning?.(publicWarning);
+    }
+
+    for (const cleared of transaction.effects.warningsCleared) {
+      emit({
+        type: "warning_cleared",
+        documentId: next.documentId,
+        warningId: cleared.warningId,
+        code: cleared.code,
+      });
+    }
+
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  function emit(event: WordReviewEditorEvent): void {
+    options.onEvent?.(event);
+    for (const listener of eventListeners) {
+      listener(event);
+    }
+  }
+
+  function emitError(error: InternalEditorError): void {
+    const nextState: EditorState = {
+      ...state,
+      phase: error.isFatal ? "error" : state.phase,
+      fatalError: error.isFatal ? error : state.fatalError,
+    };
+    state = nextState;
+    cachedRenderSnapshot = createPublicRenderSnapshot(state, history);
+    const publicError = toPublicError(error);
+    options.onError?.(publicError);
+    emit({
+      type: "error",
+      documentId: state.documentId,
+      error: publicError,
+    });
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+}
+
+function createSessionId(documentId: string, timestamp: string): string {
+  return `session-${documentId}-${timestamp.replace(/[^0-9]/gu, "")}`;
+}
+
+function createOrigin(
+  source: CommandOrigin["source"],
+  timestamp: string,
+): CommandOrigin {
+  return {
+    source,
+    timestamp,
+  };
+}
+
+function createEntityId(
+  prefix: string,
+  existing: Record<string, unknown>,
+  timestamp: string,
+): string {
+  let counter = Object.keys(existing).length;
+  let nextId = `${prefix}-${timestamp.replace(/[^0-9]/gu, "")}-${counter}`;
+
+  while (existing[nextId]) {
+    counter += 1;
+    nextId = `${prefix}-${timestamp.replace(/[^0-9]/gu, "")}-${counter}`;
+  }
+
+  return nextId;
+}
+
+function finalizeState(
+  state: EditorState,
+  markDirty: boolean,
+  timestamp: string,
+): 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;
+
+  return {
+    ...state,
+    document: {
+      ...state.document,
+      updatedAt: markDirty ? timestamp : state.document.updatedAt,
+    },
+    selection: state.selection,
+    revision,
+    revisionToken: `${state.sessionId}:${revision}`,
+    isDirty: state.isDirty || markDirty,
+  };
+}
+
+function toRuntimeError(error: unknown): InternalEditorError {
+  if (typeof error === "object" && error && "message" in error) {
+    return {
+      errorId: createSessionId("runtime-error", new Date().toISOString()),
+      code: "internal_invariant",
+      isFatal: false,
+      message: String((error as { message?: unknown }).message ?? "Runtime error"),
+      source: "runtime",
+    };
+  }
+
+  return {
+    errorId: createSessionId("runtime-error", new Date().toISOString()),
+    code: "internal_invariant",
+    isFatal: false,
+    message: "Runtime error",
+    source: "runtime",
+  };
+}
+
+function createPublicRenderSnapshot(
+  state: EditorState,
+  history: HistoryState,
+): RuntimeRenderSnapshot {
+  const compatibility = createDerivedCompatibility(state);
+  const surface = createEditorSurfaceSnapshot(state.document, state.selection);
+  const comments = toPublicCommentSidebarSnapshot(state);
+  const trackedChanges = toPublicTrackedChangesSnapshot(state, surface.plainText);
+
+  return {
+    documentId: state.documentId,
+    sessionId: state.sessionId,
+    sourceLabel: state.sourceLabel,
+    revisionToken: state.revisionToken,
+    isReady: state.phase === "ready",
+    isDirty: state.isDirty,
+    readOnly: state.readOnly,
+    selection: toPublicSelectionSnapshot(state.selection),
+    documentStats: toPublicDocumentStats(state),
+    comments,
+    trackedChanges,
+    compatibility: {
+      blockExport: compatibility.blockExport,
+      blockExportReasons: listBlockExportReasons(compatibility),
+      warningCount: compatibility.warnings.length,
+      errorCount: compatibility.errors.length,
+      featureEntries: compatibility.featureEntries.map((entry) =>
+        toPublicCompatibilityFeatureEntry(entry),
+      ),
+    },
+    warnings: state.warnings.map((warning) => toPublicWarning(warning)),
+    fatalError: state.fatalError ? toPublicError(state.fatalError) : undefined,
+    commandState: {
+      canUndo: history.past.length > 0,
+      canRedo: history.future.length > 0,
+      readOnly: state.readOnly,
+    },
+    surface,
+  };
+}
+
+function toPublicDocumentStats(state: Pick<EditorState, "document">) {
+  const stats = deriveDocumentStats(state);
+  return {
+    storyLength: stats.characterCount,
+    commentCount: stats.commentCount,
+    revisionCount: stats.revisionCount,
+    opaqueFragmentCount: countOpaqueFragments(state.document.preservation.opaqueFragments),
+  };
+}
+
+function toPublicSelectionSnapshot(
+  selection: EditorState["selection"],
+): SelectionSnapshot {
+  return {
+    anchor: selection.anchor,
+    head: selection.head,
+    isCollapsed: selection.isCollapsed,
+    activeRange: toPublicAnchorProjection(selection.activeRange),
+  };
+}
+
+function toPublicAnchorProjection(
+  anchor: InternalEditorAnchorProjection,
+): EditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        kind: "range",
+        from: anchor.range.from,
+        to: anchor.range.to,
+        assoc: anchor.assoc,
+      };
+    case "node":
+      return {
+        kind: "node",
+        at: anchor.at,
+        assoc: anchor.assoc,
+      };
+    case "detached":
+      return {
+        kind: "detached",
+        lastKnownRange: anchor.lastKnownRange,
+        reason: anchor.reason,
+      };
+  }
+}
+
+function toInternalAnchorProjection(
+  anchor: EditorAnchorProjection,
+): InternalEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(anchor.from, anchor.to, anchor.assoc);
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}
+
+function toPublicCompatibilityReport(
+  report: InternalCompatibilityReport,
+): CompatibilityReport {
+  return {
+    reportVersion: report.reportVersion,
+    generatedAt: report.generatedAt,
+    blockExport: report.blockExport,
+    featureEntries: report.featureEntries.map((entry) =>
+      toPublicCompatibilityFeatureEntry(entry),
+    ),
+    warnings: report.warnings.map((warning) => toPublicWarning(warning)),
+    errors: report.errors.map((error) => toPublicError(error)),
+  };
+}
+
+function toPublicCompatibilityFeatureEntry(
+  entry: InternalCompatibilityFeatureEntry,
+) {
+  return {
+    ...entry,
+    affectedAnchor: entry.affectedAnchor
+      ? toPublicAnchorProjection(entry.affectedAnchor)
+      : undefined,
+  };
+}
+
+function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
+  return {
+    ...warning,
+    affectedAnchor: warning.affectedAnchor
+      ? toPublicAnchorProjection(warning.affectedAnchor)
+      : undefined,
+  };
+}
+
+function toPublicError(error: InternalEditorError): EditorError {
+  return { ...error };
+}
+
+function countOpaqueFragments(opaqueFragments: Record<string, unknown>): number {
+  return Object.keys(opaqueFragments).length;
+}
+
+function createDerivedCompatibility(state: EditorState): InternalCompatibilityReport {
+  return buildCompatibilityReport({
+    document: state.document,
+    warnings: state.warnings,
+    fatalError: state.fatalError,
+    generatedAt: state.document.updatedAt,
+  });
+}
+
+function toPublicCommentSidebarSnapshot(
+  state: EditorState,
+): CommentSidebarSnapshot {
+  const projection = createCommentSidebarProjection(
+    createCommentStoreFromRuntimeComments(state.document.review.comments),
+    state.runtime.activeCommentId,
+  );
+
+  return {
+    activeCommentId: state.runtime.activeCommentId,
+    openCommentIds: projection.openCommentIds,
+    resolvedCommentIds: projection.resolvedCommentIds,
+    detachedCommentIds: projection.detachedCommentIds,
+    totalCount: projection.totalCount,
+    threads: projection.threads.map((thread): CommentSidebarThreadSnapshot => {
+      const sourceThread = state.document.review.comments[thread.commentId];
+      const projectedEntries =
+        sourceThread?.entries?.map((entry) => ({
+          entryId: entry.entryId,
+          authorId: entry.authorId,
+          body: entry.body,
+          createdAt: entry.createdAt,
+        })) ??
+        (sourceThread?.body
+          ? [
+              {
+                entryId: `${thread.commentId}-entry-1`,
+                authorId:
+                  sourceThread.authorId ?? sourceThread.createdBy ?? "unknown",
+                body: sourceThread.body,
+                createdAt: sourceThread.createdAt,
+              },
+            ]
+          : []);
+
+      return {
+        commentId: thread.commentId,
+        status: thread.status,
+        anchor: toPublicAnchorProjection(
+          sourceThread?.anchor ??
+            createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+        ),
+        excerpt: thread.excerpt,
+        entryCount: thread.entryCount,
+        createdAt: thread.createdAt,
+        createdBy: thread.createdBy,
+        warningCount: thread.warningCount,
+        anchorLabel: thread.anchorLabel,
+        isActive: thread.isActive,
+        resolvedAt: thread.resolvedAt,
+        resolvedBy: thread.resolvedBy,
+        entries: projectedEntries,
+      };
+    }),
+  };
+}
+
+function toPublicTrackedChangesSnapshot(
+  state: EditorState,
+  surfaceText = "",
+): TrackedChangesSnapshot {
+  const projection = createRevisionSidebarProjection(
+    createRevisionStoreFromDocument(state),
+  );
+
+  return {
+    pendingChangeIds: projection.activeRevisionIds,
+    acceptedChangeIds: projection.acceptedRevisionIds,
+    rejectedChangeIds: projection.rejectedRevisionIds,
+    detachedChangeIds: projection.detachedRevisionIds,
+    actionableChangeIds: projection.actionableRevisionIds,
+    preserveOnlyChangeIds: projection.preserveOnlyRevisionIds,
+    totalCount: projection.totalCount,
+    revisions: projection.revisions.map((revision): TrackedChangeEntrySnapshot => {
+      const sourceRevision = state.document.review.revisions[revision.revisionId];
+      const preview = describeRevisionPreview(
+        revision,
+        sourceRevision?.anchor ??
+          createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+        surfaceText,
+      );
+
+      return {
+        revisionId: revision.revisionId,
+        kind: revision.kind,
+        label: revision.label,
+        status: revision.status,
+        actionability: revision.actionability,
+        anchor: toPublicAnchorProjection(
+          sourceRevision?.anchor ??
+            createDetachedAnchor({ from: 0, to: 0 }, "importAmbiguity"),
+        ),
+        anchorLabel: revision.anchorLabel,
+        createdAt: revision.createdAt,
+        authorId: revision.authorId,
+        warningCount: revision.warningCount,
+        canAccept: revision.canAccept,
+        canReject: revision.canReject,
+        importedRevisionForm: sourceRevision?.metadata?.importedRevisionForm,
+        preserveOnlyReason: revision.preserveOnlyReason,
+        excerpt: preview.excerpt,
+        detail: preview.detail,
+      };
+    }),
+  };
+}
+
+function createRevisionStoreFromDocument(
+  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",
+            preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+            importedRevisionForm: revision.metadata?.importedRevisionForm,
+            originalRevisionType: revision.metadata?.originalRevisionType,
+            ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+          },
+        },
+      ]),
+    ),
+  };
+}
+
+function listBlockExportReasons(
+  report: InternalCompatibilityReport,
+): string[] {
+  return [
+    ...report.featureEntries
+      .filter((entry) => entry.featureClass === "unsupported-fatal")
+      .map((entry) => entry.message),
+    ...report.errors
+      .filter((error) => error.isFatal)
+      .map((error) => error.message),
+  ];
+}
+
+function describeRevisionPreview(
+  revision: ReturnType<typeof createRevisionSidebarProjection>["revisions"][number],
+  anchor: InternalEditorAnchorProjection,
+  plainText: string,
+): { excerpt: string; detail: string } {
+  const { from, to } = toAnchorBounds(anchor);
+  const excerpt = summarizeRevisionExcerpt(plainText, from, to, revision.label);
+
+  if (revision.actionability === "preserve-only") {
+    return {
+      excerpt,
+      detail:
+        revision.preserveOnlyReason ??
+        "Visible for review, but this change remains preserve-only in the current runtime.",
+    };
+  }
+
+  if (revision.status === "accepted") {
+    return {
+      excerpt,
+      detail: "Accepted in the live review runtime and retained here for audit visibility.",
+    };
+  }
+
+  if (revision.status === "rejected") {
+    return {
+      excerpt,
+      detail: "Rejected in the live review runtime and retained here for audit visibility.",
+    };
+  }
+
+  return {
+    excerpt,
+    detail:
+      revision.kind === "deletion"
+        ? "Deleted content stays reviewable here until it is accepted or rejected."
+        : "Runtime-backed change. Review it here or reopen the anchor in the canvas.",
+  };
+}
+
+function toAnchorBounds(anchor: InternalEditorAnchorProjection): { from: number; to: number } {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        from: Math.min(anchor.range.from, anchor.range.to),
+        to: Math.max(anchor.range.from, anchor.range.to),
+      };
+    case "node":
+      return {
+        from: anchor.at,
+        to: anchor.at + 1,
+      };
+    case "detached":
+      return {
+        from: Math.min(anchor.lastKnownRange.from, anchor.lastKnownRange.to),
+        to: Math.max(anchor.lastKnownRange.from, anchor.lastKnownRange.to),
+      };
+  }
+}
+
+function summarizeRevisionExcerpt(
+  plainText: string,
+  from: number,
+  to: number,
+  fallback: string,
+): string {
+  const normalizedFrom = Math.max(0, Math.min(from, plainText.length));
+  const normalizedTo = Math.max(normalizedFrom, Math.min(to, plainText.length));
+  const collapsed = plainText
+    .slice(normalizedFrom, normalizedTo)
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!collapsed) {
+    return fallback;
+  }
+
+  return collapsed.length > 96 ? `${collapsed.slice(0, 93)}...` : collapsed;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}