@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/.tmp-a4/src/ui/WordReviewEditor.tsx

@@ -0,0 +1,1302 @@
+import React, {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useSyncExternalStore,
+} from "react";
+
+import type {
+  AddCommentParams,
+  CompatibilityReport,
+  DocumentStats,
+  EditorAnchorProjection,
+  EditorDatastoreAdapter,
+  EditorError,
+  EditorWarning,
+  ExportDocxOptions,
+  ExportResult,
+  ExternalDocumentSource,
+  PersistedEditorSnapshot,
+  SelectionSnapshot,
+  WordReviewEditorEvent,
+  WordReviewEditorProps,
+  WordReviewEditorRef,
+} from "../api/public-types";
+import {
+  EditorSurface,
+  type EditorSurfaceModel,
+} from "./editor-surface/editor-surface";
+
+type Unsubscribe = () => void;
+
+interface RuntimeViewportDelegate {
+  focus(): void;
+  blur(): void;
+}
+
+interface RuntimeCommentThread {
+  commentId: string;
+  body: string;
+  status: "open" | "resolved" | "detached";
+  anchor: EditorAnchorProjection;
+}
+
+interface RuntimeTrackedChange {
+  changeId: string;
+  kind: "insertion" | "deletion";
+  status: "active" | "accepted" | "rejected" | "detached";
+}
+
+interface RuntimeCommandStateSnapshot {
+  canUndo: boolean;
+  canRedo: boolean;
+  canAddComment: boolean;
+  canAcceptAllChanges: boolean;
+  canRejectAllChanges: boolean;
+  canExport: boolean;
+  canSaveSnapshot: boolean;
+}
+
+interface RuntimeCompatibilityPanelSnapshot {
+  report: CompatibilityReport;
+  blockExport: boolean;
+  preserveOnlyCount: number;
+  fatalCount: number;
+}
+
+interface RuntimeCommentSidebarSnapshot {
+  commentIdsInOrder: string[];
+  threads: Record<string, RuntimeCommentThread>;
+  openCommentId?: string;
+}
+
+interface RuntimeTrackedChangesSnapshot {
+  changeIdsInOrder: string[];
+  changes: Record<string, RuntimeTrackedChange>;
+}
+
+interface RuntimeRenderSnapshot {
+  documentId: string;
+  sessionId: string;
+  sourceLabel?: string;
+  revisionToken: string;
+  isReady: boolean;
+  isDirty: boolean;
+  readOnly: boolean;
+  selection: SelectionSnapshot;
+  documentStats: DocumentStats;
+  comments: RuntimeCommentSidebarSnapshot;
+  trackedChanges: RuntimeTrackedChangesSnapshot;
+  compatibility: RuntimeCompatibilityPanelSnapshot;
+  warnings: EditorWarning[];
+  fatalError?: EditorError;
+  commandState: RuntimeCommandStateSnapshot;
+}
+
+interface RuntimeOptions {
+  documentId: string;
+  readOnly: boolean;
+  initialSource?: ExternalDocumentSource;
+  initialSourceLabel?: string;
+  datastore?: EditorDatastoreAdapter;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}
+
+interface RuntimeInitializeOptions {
+  documentId: string;
+  initialSource?: ExternalDocumentSource;
+  datastore?: EditorDatastoreAdapter;
+}
+
+interface RuntimeSourceDescriptor {
+  source: ExternalDocumentSource;
+  sourceKind: "docx" | "snapshot" | "datastore";
+}
+
+interface WordReviewEditorRuntime {
+  subscribe(listener: () => void): Unsubscribe;
+  getRenderSnapshot(): RuntimeRenderSnapshot;
+  initialize(options: RuntimeInitializeOptions): Promise<void>;
+  replaceExternalSource(
+    revisionToken: string,
+    source: ExternalDocumentSource,
+  ): Promise<void>;
+  focus(): void;
+  blur(): void;
+  undo(): void;
+  redo(): void;
+  addComment(params: AddCommentParams): string;
+  openComment(commentId: string): void;
+  resolveComment(commentId: string): void;
+  acceptChange(changeId: string): void;
+  rejectChange(changeId: string): void;
+  acceptAllChanges(): void;
+  rejectAllChanges(): void;
+  saveSnapshot(isAutosave: boolean): Promise<PersistedEditorSnapshot>;
+  getPersistedSnapshot(): PersistedEditorSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+  exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
+  attachViewport(delegate: RuntimeViewportDelegate | null): void;
+  destroy(): void;
+}
+
+let runtimeInstanceCounter = 0;
+let commentCounter = 0;
+
+function createNowIsoString() {
+  return new Date().toISOString();
+}
+
+function createSessionId(documentId: string) {
+  runtimeInstanceCounter += 1;
+  return `wre-${documentId}-${runtimeInstanceCounter}`;
+}
+
+function toUint8Array(
+  bytes: Uint8Array | ArrayBuffer,
+): Uint8Array<ArrayBufferLike> {
+  return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+}
+
+function createEmptyAnchorProjection(): EditorAnchorProjection {
+  return {
+    kind: "range",
+    from: 0,
+    to: 0,
+    assoc: { start: 1, end: 1 },
+  };
+}
+
+function createEmptySelectionSnapshot(): SelectionSnapshot {
+  return {
+    anchor: 0,
+    head: 0,
+    isCollapsed: true,
+    activeRange: createEmptyAnchorProjection(),
+  };
+}
+
+function createCompatibilityReport(overrides?: Partial<CompatibilityReport>): CompatibilityReport {
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt: createNowIsoString(),
+    blockExport: false,
+    featureEntries: [],
+    warnings: [],
+    errors: [],
+    ...overrides,
+  };
+}
+
+function createEmptyCanonicalDocument(documentId: string) {
+  return {
+    schemaVersion: "cds/1.0.0" as const,
+    docId: `doc-${documentId}`,
+    metadata: {},
+    styles: {},
+    numbering: {},
+    media: {},
+    content: [],
+    review: {
+      comments: {},
+      revisions: {},
+    },
+    preservation: {},
+    diagnostics: {},
+  };
+}
+
+function createPersistedSnapshot(
+  documentId: string,
+  compatibility: CompatibilityReport,
+): PersistedEditorSnapshot {
+  const now = createNowIsoString();
+
+  return {
+    snapshotVersion: "persisted-editor-snapshot/1",
+    schemaVersion: "cds/1.0.0",
+    documentId,
+    docId: `doc-${documentId}`,
+    createdAt: now,
+    updatedAt: now,
+    savedAt: now,
+    editorBuild: "wave-2-shell",
+    canonicalDocument: createEmptyCanonicalDocument(documentId),
+    compatibility,
+    warningLog: compatibility.warnings,
+  };
+}
+
+function createRuntimeError(
+  code: EditorError["code"],
+  message: string,
+  source: EditorError["source"],
+  isFatal: boolean,
+  details?: Record<string, unknown>,
+): EditorError {
+  return {
+    errorId: `${code}-${Math.random().toString(36).slice(2, 10)}`,
+    code,
+    message,
+    isFatal,
+    source,
+    details,
+  };
+}
+
+function buildDocumentStats(
+  source: ExternalDocumentSource | undefined,
+  commentCount: number,
+  changeCount: number,
+): DocumentStats {
+  if (!source) {
+    return {
+      wordCount: 0,
+      paragraphCount: 0,
+      commentCount,
+      changeCount,
+    };
+  }
+
+  if (source.kind === "snapshot") {
+    const content = source.snapshot.canonicalDocument.content;
+    const paragraphCount = Array.isArray(content) ? content.length : 0;
+
+    return {
+      wordCount: Math.max(32, source.snapshot.warningLog.length * 8),
+      paragraphCount: Math.max(1, paragraphCount),
+      commentCount,
+      changeCount,
+    };
+  }
+
+  const byteLength = toUint8Array(source.bytes).byteLength;
+
+  return {
+    wordCount: Math.max(32, Math.floor(byteLength / 6)),
+    paragraphCount: Math.max(1, Math.floor(byteLength / 320)),
+    commentCount,
+    changeCount,
+  };
+}
+
+function buildCompatibilityPanelSnapshot(
+  report: CompatibilityReport,
+): RuntimeCompatibilityPanelSnapshot {
+  return {
+    report,
+    blockExport: report.blockExport,
+    preserveOnlyCount: report.featureEntries.filter(
+      (entry) => entry.featureClass === "preserve-only",
+    ).length,
+    fatalCount: report.featureEntries.filter(
+      (entry) => entry.featureClass === "unsupported-fatal",
+    ).length,
+  };
+}
+
+function createBaseRenderSnapshot(
+  documentId: string,
+  readOnly: boolean,
+): RuntimeRenderSnapshot {
+  const compatibility = createCompatibilityReport();
+
+  return {
+    documentId,
+    sessionId: createSessionId(documentId),
+    revisionToken: "initial",
+    isReady: false,
+    isDirty: false,
+    readOnly,
+    selection: createEmptySelectionSnapshot(),
+    documentStats: {
+      wordCount: 0,
+      paragraphCount: 0,
+      commentCount: 0,
+      changeCount: 0,
+    },
+    comments: {
+      commentIdsInOrder: [],
+      threads: {},
+    },
+    trackedChanges: {
+      changeIdsInOrder: [],
+      changes: {},
+    },
+    compatibility: buildCompatibilityPanelSnapshot(compatibility),
+    warnings: [],
+    commandState: {
+      canUndo: false,
+      canRedo: false,
+      canAddComment: !readOnly,
+      canAcceptAllChanges: false,
+      canRejectAllChanges: false,
+      canExport: true,
+      canSaveSnapshot: false,
+    },
+  };
+}
+
+function resolveInitialExplicitSource(
+  props: Pick<
+    WordReviewEditorProps,
+    "initialDocx" | "initialSnapshot" | "initialSourceLabel"
+  >,
+): ExternalDocumentSource | undefined {
+  if (props.initialSnapshot) {
+    return {
+      kind: "snapshot",
+      snapshot: props.initialSnapshot,
+      sourceLabel: props.initialSourceLabel,
+    };
+  }
+
+  if (props.initialDocx) {
+    return {
+      kind: "docx",
+      bytes: props.initialDocx,
+      sourceLabel: props.initialSourceLabel,
+    };
+  }
+
+  return undefined;
+}
+
+function buildEditorSurfaceModel(
+  snapshot: RuntimeRenderSnapshot,
+  reviewMode: NonNullable<WordReviewEditorProps["reviewMode"]>,
+  markupDisplay: NonNullable<WordReviewEditorProps["markupDisplay"]>,
+): EditorSurfaceModel {
+  const features = snapshot.compatibility.report.featureEntries.map((entry) => ({
+    featureEntryId: entry.featureEntryId,
+    featureClass: entry.featureClass,
+    message: entry.message,
+  }));
+
+  const comments = snapshot.comments.commentIdsInOrder.map((commentId) => {
+    const thread = snapshot.comments.threads[commentId];
+
+    return {
+      commentId,
+      preview: thread.body.slice(0, 72) || "Untitled comment",
+      status: thread.status,
+      isActive: snapshot.comments.openCommentId === commentId,
+    };
+  });
+
+  const trackedChanges = snapshot.trackedChanges.changeIdsInOrder.map(
+    (changeId) => {
+      const change = snapshot.trackedChanges.changes[changeId];
+
+      return {
+        changeId,
+        label: `${change.kind} ${changeId}`,
+        status: change.status,
+      };
+    },
+  );
+
+  const warningSummary =
+    snapshot.warnings.length === 0
+      ? "No active runtime warnings"
+      : `${snapshot.warnings.length} active warning${
+          snapshot.warnings.length === 1 ? "" : "s"
+        }`;
+
+  const compatibilitySummary = snapshot.compatibility.blockExport
+    ? "Export is blocked pending compatibility remediation"
+    : snapshot.compatibility.report.featureEntries.length === 0
+      ? "No compatibility findings in the current snapshot"
+      : `${snapshot.compatibility.report.featureEntries.length} compatibility entr${
+          snapshot.compatibility.report.featureEntries.length === 1 ? "y" : "ies"
+        } tracked`;
+
+  const activeRange = snapshot.selection.activeRange;
+  const selectionLabel =
+    activeRange.kind === "range"
+      ? `${activeRange.from} → ${activeRange.to}`
+      : activeRange.kind === "node"
+        ? `Node at ${activeRange.at}`
+        : `Detached (${activeRange.reason})`;
+
+  return {
+    documentId: snapshot.documentId,
+    sessionId: snapshot.sessionId,
+    sourceLabel: snapshot.sourceLabel,
+    isReady: snapshot.isReady,
+    isDirty: snapshot.isDirty,
+    readOnly: snapshot.readOnly,
+    reviewMode,
+    markupDisplay,
+    documentStats: snapshot.documentStats,
+    selectionLabel,
+    warningSummary,
+    compatibilitySummary,
+    warnings: snapshot.warnings.map((warning) => ({
+      warningId: warning.warningId,
+      severity: warning.severity,
+      code: warning.code,
+      message: warning.message,
+    })),
+    comments,
+    trackedChanges,
+    features,
+  };
+}
+
+export function __unstable_createWordReviewEditorRuntime(
+  options: RuntimeOptions,
+): WordReviewEditorRuntime {
+  let listeners = new Set<() => void>();
+  let viewportDelegate: RuntimeViewportDelegate | null = null;
+  let renderSnapshot = createBaseRenderSnapshot(options.documentId, options.readOnly);
+  let persistedSnapshot = createPersistedSnapshot(
+    options.documentId,
+    renderSnapshot.compatibility.report,
+  );
+  let lastExport: Uint8Array<ArrayBufferLike> = new Uint8Array();
+  let destroyed = false;
+
+  const notify = () => {
+    if (destroyed) {
+      return;
+    }
+
+    listeners.forEach((listener) => listener());
+  };
+
+  const emitEvent = (event: WordReviewEditorEvent) => {
+    options.onEvent?.(event);
+    options.datastore?.logEvent?.({
+      type: event.type,
+      documentId: event.documentId,
+    });
+  };
+
+  const emitError = (error: EditorError) => {
+    options.onError?.(error);
+    emitEvent({
+      type: "error",
+      documentId: renderSnapshot.documentId,
+      error,
+    });
+  };
+
+  const setDirty = (isDirty: boolean) => {
+    if (renderSnapshot.isDirty === isDirty) {
+      return;
+    }
+
+    renderSnapshot = {
+      ...renderSnapshot,
+      isDirty,
+    };
+    emitEvent({
+      type: "dirty_changed",
+      documentId: renderSnapshot.documentId,
+      isDirty,
+    });
+  };
+
+  const setRenderSnapshot = (
+    nextSnapshot:
+      | RuntimeRenderSnapshot
+      | ((current: RuntimeRenderSnapshot) => RuntimeRenderSnapshot),
+  ) => {
+    renderSnapshot =
+      typeof nextSnapshot === "function" ? nextSnapshot(renderSnapshot) : nextSnapshot;
+
+    persistedSnapshot = {
+      ...persistedSnapshot,
+      documentId: renderSnapshot.documentId,
+      updatedAt: createNowIsoString(),
+      warningLog: renderSnapshot.warnings,
+      compatibility: renderSnapshot.compatibility.report,
+    };
+
+    notify();
+  };
+
+  const applySource = (
+    descriptor: RuntimeSourceDescriptor | undefined,
+    revisionToken: string,
+  ) => {
+    const source = descriptor?.source;
+    const sourceLabel = source?.sourceLabel ?? options.initialSourceLabel;
+    const compatibility =
+      source?.kind === "snapshot"
+        ? source.snapshot.compatibility
+        : createCompatibilityReport();
+    const warnings =
+      source?.kind === "snapshot" ? source.snapshot.warningLog : compatibility.warnings;
+    const comments: RuntimeCommentSidebarSnapshot = {
+      commentIdsInOrder: [],
+      threads: {},
+    };
+    const trackedChanges: RuntimeTrackedChangesSnapshot = {
+      changeIdsInOrder: [],
+      changes: {},
+    };
+
+    const nextSnapshot: RuntimeRenderSnapshot = {
+      ...renderSnapshot,
+      documentId: options.documentId,
+      sessionId: createSessionId(options.documentId),
+      sourceLabel,
+      revisionToken,
+      isReady: true,
+      isDirty: false,
+      readOnly: options.readOnly,
+      documentStats: buildDocumentStats(source, 0, 0),
+      comments,
+      trackedChanges,
+      compatibility: buildCompatibilityPanelSnapshot(compatibility),
+      warnings,
+      fatalError: undefined,
+      commandState: {
+        canUndo: false,
+        canRedo: false,
+        canAddComment: !options.readOnly,
+        canAcceptAllChanges: false,
+        canRejectAllChanges: false,
+        canExport: !compatibility.blockExport,
+        canSaveSnapshot: Boolean(options.datastore),
+      },
+    };
+
+    persistedSnapshot =
+      source?.kind === "snapshot"
+        ? {
+            ...source.snapshot,
+            documentId: options.documentId,
+          }
+        : createPersistedSnapshot(options.documentId, compatibility);
+
+    if (source?.kind === "docx") {
+      lastExport = toUint8Array(source.bytes);
+    } else {
+      lastExport = new Uint8Array();
+    }
+
+    setRenderSnapshot(nextSnapshot);
+    warnings.forEach((warning) => options.onWarning?.(warning));
+    emitEvent({
+      type: "ready",
+      documentId: options.documentId,
+      sessionId: nextSnapshot.sessionId,
+      source: descriptor?.sourceKind ?? "datastore",
+      stats: nextSnapshot.documentStats,
+      compatibility: nextSnapshot.compatibility.report,
+    });
+  };
+
+  const handleLoadFailure = (message: string, details?: Record<string, unknown>) => {
+    const error = createRuntimeError(
+      "datastore_failed",
+      message,
+      "datastore",
+      true,
+      details,
+    );
+
+    setRenderSnapshot((current) => ({
+      ...current,
+      isReady: true,
+      fatalError: error,
+      commandState: {
+        ...current.commandState,
+        canAddComment: false,
+        canExport: false,
+        canSaveSnapshot: false,
+      },
+    }));
+    emitError(error);
+  };
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    getRenderSnapshot() {
+      return renderSnapshot;
+    },
+
+    async initialize(runtimeOptions) {
+      if (destroyed) {
+        return;
+      }
+
+      if (
+        runtimeOptions.initialSource &&
+        options.datastore &&
+        options.datastore.logEvent
+      ) {
+        options.datastore.logEvent({
+          type: "runtime_initialized",
+          documentId: runtimeOptions.documentId,
+        });
+      }
+
+      if (runtimeOptions.initialSource) {
+        applySource(
+          {
+            source: runtimeOptions.initialSource,
+            sourceKind: runtimeOptions.initialSource.kind,
+          },
+          "initial-load",
+        );
+        return;
+      }
+
+      if (!runtimeOptions.datastore) {
+        applySource(undefined, "empty-load");
+        return;
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        isReady: false,
+      }));
+
+      try {
+        const loaded = await runtimeOptions.datastore.load({
+          documentId: runtimeOptions.documentId,
+        });
+
+        applySource(
+          loaded.source
+            ? {
+                source: loaded.source,
+                sourceKind: "datastore",
+              }
+            : undefined,
+          "datastore-load",
+        );
+      } catch (error) {
+        handleLoadFailure("Datastore load failed.", {
+          cause: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+
+    async replaceExternalSource(revisionToken, source) {
+      applySource(
+        {
+          source,
+          sourceKind: source.kind,
+        },
+        revisionToken,
+      );
+    },
+
+    focus() {
+      viewportDelegate?.focus();
+    },
+
+    blur() {
+      viewportDelegate?.blur();
+    },
+
+    undo() {},
+
+    redo() {},
+
+    addComment(params) {
+      commentCounter += 1;
+      const commentId = `comment-${commentCounter}`;
+      const nextThreads = {
+        ...renderSnapshot.comments.threads,
+        [commentId]: {
+          commentId,
+          body: params.body,
+          status: "open" as const,
+          anchor: params.anchor,
+        },
+      };
+      const nextCommentIds = [...renderSnapshot.comments.commentIdsInOrder, commentId];
+      const nextStats = {
+        ...renderSnapshot.documentStats,
+        commentCount: nextCommentIds.length,
+      };
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        comments: {
+          commentIdsInOrder: nextCommentIds,
+          threads: nextThreads,
+          openCommentId: commentId,
+        },
+        documentStats: nextStats,
+      }));
+      setDirty(true);
+      emitEvent({
+        type: "comment_added",
+        documentId: renderSnapshot.documentId,
+        commentId,
+        anchor: params.anchor,
+      });
+
+      return commentId;
+    },
+
+    openComment(commentId) {
+      if (!renderSnapshot.comments.threads[commentId]) {
+        return;
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        comments: {
+          ...current.comments,
+          openCommentId: commentId,
+        },
+      }));
+    },
+
+    resolveComment(commentId) {
+      const thread = renderSnapshot.comments.threads[commentId];
+      if (!thread) {
+        return;
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        comments: {
+          ...current.comments,
+          threads: {
+            ...current.comments.threads,
+            [commentId]: {
+              ...thread,
+              status: "resolved",
+            },
+          },
+        },
+      }));
+      setDirty(true);
+      emitEvent({
+        type: "comment_resolved",
+        documentId: renderSnapshot.documentId,
+        commentId,
+      });
+    },
+
+    acceptChange(changeId) {
+      const change = renderSnapshot.trackedChanges.changes[changeId];
+      if (!change) {
+        return;
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        trackedChanges: {
+          ...current.trackedChanges,
+          changes: {
+            ...current.trackedChanges.changes,
+            [changeId]: {
+              ...change,
+              status: "accepted",
+            },
+          },
+        },
+      }));
+      setDirty(true);
+      emitEvent({
+        type: "change_accepted",
+        documentId: renderSnapshot.documentId,
+        changeId,
+      });
+    },
+
+    rejectChange(changeId) {
+      const change = renderSnapshot.trackedChanges.changes[changeId];
+      if (!change) {
+        return;
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        trackedChanges: {
+          ...current.trackedChanges,
+          changes: {
+            ...current.trackedChanges.changes,
+            [changeId]: {
+              ...change,
+              status: "rejected",
+            },
+          },
+        },
+      }));
+      setDirty(true);
+      emitEvent({
+        type: "change_rejected",
+        documentId: renderSnapshot.documentId,
+        changeId,
+      });
+    },
+
+    acceptAllChanges() {
+      const nextChanges: RuntimeTrackedChangesSnapshot["changes"] = {};
+
+      for (const [changeId, change] of Object.entries(
+        renderSnapshot.trackedChanges.changes,
+      )) {
+        nextChanges[changeId] = { ...change, status: "accepted" };
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        trackedChanges: {
+          ...current.trackedChanges,
+          changes: nextChanges,
+        },
+      }));
+      setDirty(true);
+    },
+
+    rejectAllChanges() {
+      const nextChanges: RuntimeTrackedChangesSnapshot["changes"] = {};
+
+      for (const [changeId, change] of Object.entries(
+        renderSnapshot.trackedChanges.changes,
+      )) {
+        nextChanges[changeId] = { ...change, status: "rejected" };
+      }
+
+      setRenderSnapshot((current) => ({
+        ...current,
+        trackedChanges: {
+          ...current.trackedChanges,
+          changes: nextChanges,
+        },
+      }));
+      setDirty(true);
+    },
+
+    async saveSnapshot(isAutosave) {
+      const snapshot = {
+        ...persistedSnapshot,
+        updatedAt: createNowIsoString(),
+        savedAt: createNowIsoString(),
+        warningLog: renderSnapshot.warnings,
+        compatibility: renderSnapshot.compatibility.report,
+      };
+
+      persistedSnapshot = snapshot;
+
+      if (options.datastore) {
+        try {
+          await options.datastore.saveSnapshot({
+            documentId: renderSnapshot.documentId,
+            snapshot,
+            isAutosave,
+          });
+        } catch (error) {
+          emitError(
+            createRuntimeError(
+              "datastore_failed",
+              "Snapshot save failed.",
+              "datastore",
+              false,
+              {
+                cause: error instanceof Error ? error.message : String(error),
+              },
+            ),
+          );
+        }
+      }
+
+      emitEvent({
+        type: "snapshot_saved",
+        documentId: renderSnapshot.documentId,
+        snapshot,
+        isAutosave,
+      });
+      setDirty(false);
+
+      return snapshot;
+    },
+
+    getPersistedSnapshot() {
+      return persistedSnapshot;
+    },
+
+    getCompatibilityReport() {
+      return renderSnapshot.compatibility.report;
+    },
+
+    getWarnings() {
+      return renderSnapshot.warnings;
+    },
+
+    async exportDocx(_options) {
+      const result: ExportResult = {
+        docx: lastExport,
+        compatibilityReport: renderSnapshot.compatibility.report,
+        warnings: renderSnapshot.warnings,
+      };
+
+      if (options.datastore) {
+        try {
+          await options.datastore.saveExport({
+            documentId: renderSnapshot.documentId,
+            docx: result.docx,
+            compatibilityReport: result.compatibilityReport,
+          });
+        } catch (error) {
+          emitError(
+            createRuntimeError(
+              "datastore_failed",
+              "Export persistence failed.",
+              "datastore",
+              false,
+              {
+                cause: error instanceof Error ? error.message : String(error),
+              },
+            ),
+          );
+        }
+      }
+
+      emitEvent({
+        type: "export_completed",
+        documentId: renderSnapshot.documentId,
+        result,
+      });
+
+      return result;
+    },
+
+    attachViewport(delegate) {
+      viewportDelegate = delegate;
+    },
+
+    destroy() {
+      destroyed = true;
+      listeners.clear();
+      viewportDelegate = null;
+    },
+  };
+}
+
+function ToolbarButton({
+  label,
+  disabled,
+  onClick,
+}: {
+  label: string;
+  disabled?: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      style={{
+        padding: "8px 12px",
+        borderRadius: "12px",
+        border: "1px solid rgba(23, 31, 38, 0.08)",
+        background: disabled ? "rgba(241, 238, 229, 0.7)" : "rgba(255, 255, 255, 0.9)",
+        color: disabled ? "#8b949b" : "#18212a",
+        fontSize: "13px",
+        cursor: disabled ? "not-allowed" : "pointer",
+      }}
+    >
+      {label}
+    </button>
+  );
+}
+
+export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditorProps>(
+  function WordReviewEditor(
+    {
+      documentId,
+      currentUser,
+      initialDocx,
+      initialSnapshot,
+      initialSourceLabel,
+      externalDocumentRevision,
+      externalDocSource,
+      readOnly = false,
+      reviewMode = "review",
+      markupDisplay = "all",
+      datastore,
+      autosave,
+      onEvent,
+      onWarning,
+      onError,
+    },
+    ref,
+  ) {
+    const initialSourceStateRef = useRef<{
+      initialized: boolean;
+      value?: ExternalDocumentSource;
+    }>({
+      initialized: false,
+      value: undefined,
+    });
+    const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
+    const canvasRef = useRef<HTMLDivElement | null>(null);
+    const previousRevisionRef = useRef(externalDocumentRevision);
+
+    if (!initialSourceStateRef.current.initialized) {
+      initialSourceStateRef.current = {
+        initialized: true,
+        value: resolveInitialExplicitSource({
+          initialDocx,
+          initialSnapshot,
+          initialSourceLabel,
+        }),
+      };
+    }
+
+    const initialSource = initialSourceStateRef.current.value;
+
+    if (!runtimeRef.current) {
+      runtimeRef.current = __unstable_createWordReviewEditorRuntime({
+        documentId,
+        readOnly,
+        initialSource,
+        initialSourceLabel,
+        datastore,
+        onEvent,
+        onWarning,
+        onError,
+      });
+    }
+
+    const runtime = runtimeRef.current;
+    const snapshot = useSyncExternalStore(
+      runtime.subscribe,
+      runtime.getRenderSnapshot,
+      runtime.getRenderSnapshot,
+    );
+
+    useEffect(() => {
+      void runtime.initialize({
+        documentId,
+        initialSource,
+        datastore,
+      });
+
+      return () => {
+        runtime.destroy();
+      };
+    }, [runtime]);
+
+    useEffect(() => {
+      runtime.attachViewport({
+        focus() {
+          canvasRef.current?.focus();
+        },
+        blur() {
+          canvasRef.current?.blur();
+        },
+      });
+
+      return () => {
+        runtime.attachViewport(null);
+      };
+    }, [runtime]);
+
+    useEffect(() => {
+      if (
+        externalDocumentRevision &&
+        externalDocSource &&
+        previousRevisionRef.current !== externalDocumentRevision
+      ) {
+        previousRevisionRef.current = externalDocumentRevision;
+        void runtime.replaceExternalSource(
+          externalDocumentRevision,
+          externalDocSource,
+        );
+      }
+    }, [externalDocumentRevision, externalDocSource, runtime]);
+
+    useEffect(() => {
+      if (!autosave?.enabled || !snapshot.isDirty) {
+        return;
+      }
+
+      const timeoutId = window.setTimeout(() => {
+        void runtime.saveSnapshot(true);
+      }, autosave.debounceMs);
+
+      return () => {
+        window.clearTimeout(timeoutId);
+      };
+    }, [autosave, runtime, snapshot.isDirty]);
+
+    useImperativeHandle(
+      ref,
+      (): WordReviewEditorRef => ({
+        focus: () => runtime.focus(),
+        blur: () => runtime.blur(),
+        undo: () => runtime.undo(),
+        redo: () => runtime.redo(),
+        addComment: (params) => runtime.addComment(params),
+        openComment: (commentId) => runtime.openComment(commentId),
+        resolveComment: (commentId) => runtime.resolveComment(commentId),
+        acceptChange: (changeId) => runtime.acceptChange(changeId),
+        rejectChange: (changeId) => runtime.rejectChange(changeId),
+        acceptAllChanges: () => runtime.acceptAllChanges(),
+        rejectAllChanges: () => runtime.rejectAllChanges(),
+        exportDocx: (options) => runtime.exportDocx(options),
+        getSnapshot: () => runtime.getPersistedSnapshot(),
+        getCompatibilityReport: () => runtime.getCompatibilityReport(),
+        getWarnings: () => runtime.getWarnings(),
+      }),
+      [runtime],
+    );
+
+    const surfaceModel = buildEditorSurfaceModel(
+      snapshot,
+      reviewMode,
+      markupDisplay,
+    );
+
+    return (
+      <section
+        aria-label="Word Review Editor"
+        data-document-id={documentId}
+        data-session-id={snapshot.sessionId}
+        style={{
+          minHeight: "100%",
+          background:
+            "radial-gradient(circle at top left, rgba(227, 232, 225, 0.8), transparent 34%), linear-gradient(180deg, #eef1ea 0%, #e4e8df 100%)",
+          color: "#18212a",
+          padding: "24px",
+          borderRadius: "28px",
+        }}
+      >
+        <div
+          style={{
+            display: "grid",
+            gap: "18px",
+          }}
+        >
+          <header
+            style={{
+              display: "flex",
+              flexWrap: "wrap",
+              justifyContent: "space-between",
+              gap: "14px",
+              alignItems: "center",
+              padding: "12px 14px",
+              borderRadius: "18px",
+              border: "1px solid rgba(23, 31, 38, 0.07)",
+              background: "rgba(250, 249, 246, 0.82)",
+              backdropFilter: "blur(10px)",
+            }}
+          >
+            <div style={{ display: "flex", gap: "8px", flexWrap: "wrap" }}>
+              <ToolbarButton
+                label="Undo"
+                disabled={!snapshot.commandState.canUndo}
+                onClick={() => runtime.undo()}
+              />
+              <ToolbarButton
+                label="Redo"
+                disabled={!snapshot.commandState.canRedo}
+                onClick={() => runtime.redo()}
+              />
+              <ToolbarButton
+                label="Add comment"
+                disabled={!snapshot.commandState.canAddComment}
+                onClick={() =>
+                  runtime.addComment({
+                    anchor: snapshot.selection.activeRange,
+                    body: `Comment from ${currentUser.displayName}`,
+                  })
+                }
+              />
+              <ToolbarButton
+                label="Accept all"
+                disabled={!snapshot.commandState.canAcceptAllChanges}
+                onClick={() => runtime.acceptAllChanges()}
+              />
+              <ToolbarButton
+                label="Reject all"
+                disabled={!snapshot.commandState.canRejectAllChanges}
+                onClick={() => runtime.rejectAllChanges()}
+              />
+            </div>
+
+            <div style={{ display: "flex", gap: "8px", flexWrap: "wrap" }}>
+              <ToolbarButton
+                label="Save snapshot"
+                disabled={!snapshot.commandState.canSaveSnapshot}
+                onClick={() => {
+                  void runtime.saveSnapshot(false);
+                }}
+              />
+              <ToolbarButton
+                label="Export docx"
+                disabled={!snapshot.commandState.canExport}
+                onClick={() => {
+                  void runtime.exportDocx({
+                    includeCompatibilityReport: true,
+                  });
+                }}
+              />
+            </div>
+          </header>
+
+          {snapshot.fatalError ? (
+            <div
+              role="alert"
+              style={{
+                padding: "16px 18px",
+                borderRadius: "18px",
+                background: "rgba(242, 223, 223, 0.92)",
+                border: "1px solid rgba(142, 59, 59, 0.25)",
+                color: "#5f2626",
+              }}
+            >
+              {snapshot.fatalError.message}
+            </div>
+          ) : null}
+
+          <EditorSurface
+            canvasRef={canvasRef}
+            model={surfaceModel}
+            onOpenComment={(commentId) => runtime.openComment(commentId)}
+          />
+
+          <footer
+            style={{
+              display: "flex",
+              flexWrap: "wrap",
+              justifyContent: "space-between",
+              gap: "12px",
+              color: "#58646f",
+              fontSize: "13px",
+              padding: "0 4px",
+            }}
+          >
+            <span>
+              {snapshot.isReady ? "Ready" : "Loading"} •{" "}
+              {snapshot.isDirty ? "Unsaved changes" : "Clean"} • session{" "}
+              {snapshot.sessionId}
+            </span>
+            <span>
+              {reviewMode} review • {markupDisplay} markup •{" "}
+              {snapshot.compatibility.blockExport ? "export blocked" : "export allowed"}
+            </span>
+          </footer>
+        </div>
+      </section>
+    );
+  },
+);
+
+export default WordReviewEditor;