@beyondwork/docx-react-component 1.0.0

package/src/ui/WordReviewEditor.tsx

@@ -0,0 +1,1283 @@
+import React, {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
+
+import type {
+  AutosaveState,
+  EditorDatastoreAdapter,
+  CompatibilityReport,
+  EditorError,
+  EditorWarning,
+  ExportDocxOptions,
+  PersistedEditorSnapshot,
+  RuntimeRenderSnapshot,
+  SelectionSnapshot as PublicSelectionSnapshot,
+  ExportResult,
+  WordReviewEditorEvent,
+  WordReviewEditorProps,
+  WordReviewEditorRef,
+} from "../api/public-types";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+} from "../core/selection/mapping.ts";
+import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
+import {
+  createDocumentRuntime,
+  type DocumentRuntime,
+} from "../runtime/document-runtime.ts";
+import { loadDocxEditorSession } from "../io/docx-session.ts";
+import { exportSnapshotToMinimalDocx } from "../io/export/minimal-docx.ts";
+import { DOCX_MIME_TYPE } from "../io/opc/docx-package.ts";
+import { deriveCapabilities } from "../runtime/session-capabilities";
+import { TwProseMirrorSurface } from "../ui-tailwind/editor-surface/tw-prosemirror-surface";
+import { TwReviewWorkspace } from "../ui-tailwind/tw-review-workspace";
+import type { ReviewRailTab } from "../ui-tailwind/review/tw-review-rail";
+import type { ViewMode } from "../ui-tailwind/toolbar/tw-toolbar";
+import type { MarkupDisplay } from "./headless/comment-decoration-model";
+
+interface ResolvedSource {
+  source: "docx" | "snapshot" | "datastore";
+  sourceLabel?: string;
+  initialDocx?: Uint8Array | ArrayBuffer;
+  initialSnapshot?: PersistedEditorSnapshot;
+}
+
+interface CreateRuntimeArgs {
+  documentId: string;
+  readOnly: boolean;
+  source: ResolvedSource;
+  datastore?: EditorDatastoreAdapter;
+  currentUserId?: string;
+}
+
+interface RuntimeLifecycleHandlers {
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}
+
+interface WordReviewEditorRuntime extends DocumentRuntime {
+  getFatalError?(): EditorError | undefined;
+  dispose?(): void;
+}
+
+export function __createWordReviewEditorRefBridge(
+  runtime: WordReviewEditorRuntime,
+): WordReviewEditorRef {
+  return {
+    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),
+    reopenComment: (commentId) => runtime.reopenComment(commentId),
+    addCommentReply: (commentId, body) => runtime.addCommentReply(commentId, body),
+    editCommentBody: (commentId, body) => runtime.editCommentBody(commentId, body),
+    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(),
+  };
+}
+
+export async function __resolveWordReviewEditorSource(
+  props: Pick<
+    WordReviewEditorProps,
+    | "documentId"
+    | "datastore"
+    | "externalDocSource"
+    | "initialDocx"
+    | "initialSnapshot"
+    | "initialSourceLabel"
+  >,
+): Promise<ResolvedSource> {
+  const explicitInitialCount =
+    Number(Boolean(props.initialDocx)) + Number(Boolean(props.initialSnapshot));
+  if (explicitInitialCount > 1) {
+    throw new Error("Provide exactly one of initialDocx or initialSnapshot.");
+  }
+
+  if (props.externalDocSource) {
+    return props.externalDocSource.kind === "docx"
+      ? {
+          source: "docx",
+          initialDocx: props.externalDocSource.bytes,
+          sourceLabel: props.externalDocSource.sourceLabel,
+        }
+      : {
+          source: "snapshot",
+          initialSnapshot: props.externalDocSource.snapshot,
+          sourceLabel: props.externalDocSource.sourceLabel,
+        };
+  }
+
+  if (props.initialSnapshot) {
+    return {
+      source: "snapshot",
+      initialSnapshot: props.initialSnapshot,
+      sourceLabel: props.initialSourceLabel,
+    };
+  }
+
+  if (props.initialDocx) {
+    return {
+      source: "docx",
+      initialDocx: props.initialDocx,
+      sourceLabel: props.initialSourceLabel,
+    };
+  }
+
+  if (!props.datastore) {
+    throw new Error(
+      `WordReviewEditor ${props.documentId} needs initialDocx, initialSnapshot, or datastore.load().`,
+    );
+  }
+
+  const loadResult = await props.datastore.load({
+    documentId: props.documentId,
+  });
+
+  if (!loadResult.source) {
+    throw new Error(`Datastore did not return a loadable source for ${props.documentId}.`);
+  }
+
+  return loadResult.source.kind === "docx"
+    ? {
+        source: "datastore",
+        initialDocx: loadResult.source.bytes,
+        sourceLabel: loadResult.source.sourceLabel,
+      }
+    : {
+        source: "datastore",
+        initialSnapshot: loadResult.source.snapshot,
+        sourceLabel: loadResult.source.sourceLabel,
+      };
+}
+
+export function __createFallbackRuntime(args: CreateRuntimeArgs): WordReviewEditorRuntime {
+  return createRuntime(args);
+}
+
+function createRuntime(
+  args: CreateRuntimeArgs,
+  handlers: RuntimeLifecycleHandlers = {},
+): WordReviewEditorRuntime {
+  const docxSession = args.source.initialDocx
+    ? loadDocxEditorSession({
+        documentId: args.documentId,
+        sourceLabel: args.source.sourceLabel,
+        bytes: args.source.initialDocx,
+        editorBuild: "dev",
+      })
+    : undefined;
+  const initialSnapshot =
+    args.source.initialSnapshot ??
+    docxSession?.initialSnapshot ??
+    createFallbackPersistedSnapshot(
+      args.documentId,
+      args.source.sourceLabel ?? "Generated shell snapshot",
+    );
+
+  return createDocumentRuntime({
+    documentId: args.documentId,
+    initialSnapshot,
+    sourceKind: args.source.source,
+    sourceLabel: args.source.sourceLabel,
+    readOnly: args.readOnly || docxSession?.readOnly,
+    editorBuild: initialSnapshot.editorBuild,
+    fatalError: docxSession?.fatalError,
+    exportDocx: async (snapshot, options) =>
+      docxSession
+        ? docxSession.exportDocx(snapshot, options)
+        : {
+            bytes: exportSnapshotToMinimalDocx(snapshot),
+            mimeType: DOCX_MIME_TYPE,
+            fileName: options?.fileName ?? `${args.documentId}.docx`,
+          },
+    onWarning: handlers.onWarning,
+    onError: handlers.onError,
+    defaultAuthorId: args.currentUserId,
+  });
+}
+
+export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditorProps>(
+  function WordReviewEditor(props, ref) {
+    const {
+      currentUser,
+      datastore,
+      documentId,
+      externalDocSource,
+      externalDocumentRevision,
+      initialDocx,
+      initialSnapshot,
+      initialSourceLabel,
+      markupDisplay = "simple",
+      onError,
+      onEvent,
+      onWarning,
+      readOnly = false,
+      reviewMode = "review",
+    } = props;
+
+    const [runtime, setRuntime] = useState<WordReviewEditorRuntime | null>(null);
+    const [loadError, setLoadError] = useState<EditorError | null>(null);
+    const [viewMode, setViewMode] = useState<ViewMode>("canvas");
+    const liveMarkupDisplay: MarkupDisplay = viewMode === "document" ? "all" : "clean";
+    const [activeRailTab, setActiveRailTab] = useState<ReviewRailTab>("comments");
+    const [showTrackedChanges, setShowTrackedChanges] = useState(false);
+    const [activeRevisionId, setActiveRevisionId] = useState<string | undefined>();
+    const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
+    const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const lastSavedRevisionTokenRef = useRef<string | null>(null);
+    const datastoreRef = useRef(datastore);
+    const onEventRef = useRef(onEvent);
+    const onWarningRef = useRef(onWarning);
+    const onErrorRef = useRef(onError);
+    const initialSourceRef = useRef<{
+      documentId: string;
+      initialDocx?: Uint8Array | ArrayBuffer;
+      initialSnapshot?: PersistedEditorSnapshot;
+      initialSourceLabel?: string;
+    } | null>(null);
+
+    if (!initialSourceRef.current || initialSourceRef.current.documentId !== documentId) {
+      initialSourceRef.current = {
+        documentId,
+        initialDocx,
+        initialSnapshot,
+        initialSourceLabel,
+      };
+    }
+
+    const stableInitialSource = initialSourceRef.current;
+    const sourceReloadKey = externalDocSource
+      ? `external:${externalDocSource.kind}:${externalDocumentRevision ?? "static"}`
+      : stableInitialSource?.initialSnapshot
+        ? "initial-snapshot"
+        : stableInitialSource?.initialDocx
+          ? "initial-docx"
+          : "datastore";
+
+    useEffect(() => {
+      datastoreRef.current = datastore;
+      onEventRef.current = onEvent;
+      onWarningRef.current = onWarning;
+      onErrorRef.current = onError;
+    }, [datastore, onError, onEvent, onWarning]);
+
+    useEffect(() => {
+      let cancelled = false;
+
+      async function loadRuntime(): Promise<void> {
+        setLoadError(null);
+
+        try {
+          const source = await __resolveWordReviewEditorSource({
+            documentId,
+            datastore: datastoreRef.current,
+            externalDocSource,
+            initialDocx: stableInitialSource?.initialDocx,
+            initialSnapshot: stableInitialSource?.initialSnapshot,
+            initialSourceLabel: stableInitialSource?.initialSourceLabel,
+          });
+
+          if (cancelled) {
+            return;
+          }
+
+          runtimeRef.current?.dispose?.();
+          const nextRuntime = createRuntime(
+            {
+              documentId,
+              readOnly,
+              source,
+              datastore: datastoreRef.current,
+              currentUserId: currentUser.userId,
+            },
+            {
+              onWarning: onWarningRef.current,
+              onError: onErrorRef.current,
+            },
+          );
+          emitEditorEvent({
+            datastore: datastoreRef.current,
+            onEvent: onEventRef.current,
+            event: createReadyEvent(nextRuntime, source.source),
+          });
+          runtimeRef.current = nextRuntime;
+          setRuntime(nextRuntime);
+        } catch (error) {
+          if (cancelled) {
+            return;
+          }
+
+          const normalized = normalizeEditorError(error);
+          setLoadError(normalized);
+          onErrorRef.current?.(normalized);
+          emitEditorEvent({
+            datastore: datastoreRef.current,
+            onEvent: onEventRef.current,
+            event: {
+              type: "error",
+              documentId,
+              error: normalized,
+            },
+          });
+        }
+      }
+
+      void loadRuntime();
+
+      return () => {
+        cancelled = true;
+      };
+    }, [
+      documentId,
+      readOnly,
+      sourceReloadKey,
+    ]);
+
+    useEffect(() => {
+      if (!runtime?.subscribeToEvents) {
+        return;
+      }
+
+      return runtime.subscribeToEvents((event) => {
+        emitEditorEvent({
+          datastore: datastoreRef.current,
+          onEvent: onEventRef.current,
+          event,
+        });
+      });
+    }, [runtime]);
+
+    useEffect(() => {
+      return () => {
+        if (autosaveTimerRef.current) {
+          clearTimeout(autosaveTimerRef.current);
+          autosaveTimerRef.current = null;
+        }
+        runtimeRef.current?.dispose?.();
+        runtimeRef.current = null;
+      };
+    }, []);
+
+    const optimisticRuntime = useMemo(
+      () =>
+        __createFallbackRuntime({
+          documentId,
+          readOnly,
+          currentUserId: currentUser.userId,
+          source: {
+            source: "snapshot",
+            initialSnapshot:
+              initialSnapshot ?? createFallbackPersistedSnapshot(documentId, initialSourceLabel),
+            sourceLabel: guessSourceLabel(initialSourceLabel, initialSnapshot, externalDocSource),
+          },
+          datastore: datastoreRef.current,
+        }),
+      [
+        currentUser.userId,
+        documentId,
+        initialSnapshot,
+        initialSourceLabel,
+        readOnly,
+        externalDocSource?.kind,
+        externalDocSource?.sourceLabel,
+      ],
+    );
+
+    const fallbackSnapshot = useMemo(
+      () =>
+        loadError
+          ? createErrorSnapshot(documentId, loadError)
+          : createLoadingSnapshot(
+              documentId,
+              readOnly,
+              guessSourceLabel(initialSourceLabel, initialSnapshot, externalDocSource),
+            ),
+      [
+        documentId,
+        externalDocSource,
+        initialSnapshot,
+        initialSourceLabel,
+        loadError,
+        readOnly,
+      ],
+    );
+
+    const snapshot = useSyncExternalStore(
+      (listener) => runtime?.subscribe(listener) ?? (() => undefined),
+      () => runtime?.getRenderSnapshot() ?? fallbackSnapshot,
+      () => runtime?.getRenderSnapshot() ?? fallbackSnapshot,
+    );
+
+    const activeRuntime = runtime ?? optimisticRuntime;
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: () => activeRuntime.focus(),
+        blur: () => activeRuntime.blur(),
+        undo: () => activeRuntime.undo(),
+        redo: () => activeRuntime.redo(),
+        addComment: (params) =>
+          activeRuntime.addComment({
+            ...params,
+            authorId: params.authorId ?? currentUser.userId,
+          }),
+        openComment: (commentId) => activeRuntime.openComment(commentId),
+        resolveComment: (commentId) => activeRuntime.resolveComment(commentId),
+        reopenComment: (commentId) => activeRuntime.reopenComment(commentId),
+        addCommentReply: (commentId, body) =>
+          activeRuntime.addCommentReply(commentId, body, currentUser.userId),
+        editCommentBody: (commentId, body) =>
+          activeRuntime.editCommentBody(commentId, body),
+        acceptChange: (changeId) => activeRuntime.acceptChange(changeId),
+        rejectChange: (changeId) => activeRuntime.rejectChange(changeId),
+        acceptAllChanges: () => activeRuntime.acceptAllChanges(),
+        rejectAllChanges: () => activeRuntime.rejectAllChanges(),
+        exportDocx: (options) =>
+          runtime
+            ? persistAndExport({
+                datastore: datastoreRef.current,
+                documentId,
+                runtime,
+                onError: onErrorRef.current,
+                onEvent: onEventRef.current,
+                options,
+                lastSavedRevisionTokenRef,
+                autosaveTimerRef,
+              })
+            : rejectExportWhileLoading({
+                documentId,
+                datastore: datastoreRef.current,
+                onError: onErrorRef.current,
+                onEvent: onEventRef.current,
+              }),
+        getSnapshot: () => activeRuntime.getPersistedSnapshot(),
+        getCompatibilityReport: () => activeRuntime.getCompatibilityReport(),
+        getWarnings: () => activeRuntime.getWarnings(),
+      }),
+      [activeRuntime, currentUser.userId, documentId, runtime],
+    );
+
+    useEffect(() => {
+      if (!datastoreRef.current || props.autosave?.enabled === false || !runtime || readOnly) {
+        if (autosaveTimerRef.current) {
+          clearTimeout(autosaveTimerRef.current);
+          autosaveTimerRef.current = null;
+        }
+        return;
+      }
+
+      if (!snapshot.isReady || !snapshot.isDirty) {
+        return;
+      }
+
+      if (lastSavedRevisionTokenRef.current === snapshot.revisionToken) {
+        return;
+      }
+
+      if (autosaveTimerRef.current) {
+        clearTimeout(autosaveTimerRef.current);
+      }
+
+      const debounceMs = props.autosave?.debounceMs ?? 800;
+      if (debounceMs <= 0) {
+        void persistSnapshot({
+          datastore: datastoreRef.current,
+          documentId,
+          runtime,
+          isAutosave: true,
+          onError: onErrorRef.current,
+          onEvent: onEventRef.current,
+          lastSavedRevisionTokenRef,
+        });
+        return;
+      }
+
+      autosaveTimerRef.current = setTimeout(() => {
+        void persistSnapshot({
+          datastore: datastoreRef.current,
+          documentId,
+          runtime,
+          isAutosave: true,
+          onError: onErrorRef.current,
+          onEvent: onEventRef.current,
+          lastSavedRevisionTokenRef,
+        });
+      }, debounceMs);
+
+      return () => {
+        if (autosaveTimerRef.current) {
+          clearTimeout(autosaveTimerRef.current);
+          autosaveTimerRef.current = null;
+        }
+      };
+    }, [
+      documentId,
+      props.autosave?.debounceMs,
+      props.autosave?.enabled,
+      readOnly,
+      runtime,
+      snapshot.isDirty,
+      snapshot.isReady,
+      snapshot.revisionToken,
+    ]);
+
+    // Auto-select the most relevant rail tab based on content.
+    // Health tab was moved to toolbar popover — rail has only comments/changes.
+    useEffect(() => {
+      if (
+        activeRailTab === "comments" &&
+        snapshot.comments.totalCount === 0 &&
+        snapshot.trackedChanges.totalCount > 0
+      ) {
+        setActiveRailTab("changes");
+        return;
+      }
+    }, [
+      activeRailTab,
+      loadError,
+      snapshot.comments.totalCount,
+      snapshot.compatibility.blockExport,
+      snapshot.fatalError,
+      snapshot.trackedChanges.totalCount,
+    ]);
+
+    function focusAnchor(anchor: PublicSelectionSnapshot["activeRange"]): void {
+      if (anchor.kind === "detached") {
+        return;
+      }
+
+      activeRuntime.dispatch({
+        type: "selection.set",
+        selection: toRuntimeSelectionSnapshot(createSelectionFromAnchor(anchor)),
+      });
+    }
+
+    function addReviewComment(): void {
+      activeRuntime.addComment({
+        anchor: snapshot.selection.activeRange,
+        body: "New review comment",
+        authorId: currentUser.userId,
+      });
+      setActiveRailTab("comments");
+    }
+
+    function exportCurrentDocument(): void {
+      void (runtime
+        ? persistAndExport({
+            datastore: datastoreRef.current,
+            documentId,
+            runtime,
+            onError: onErrorRef.current,
+            onEvent: onEventRef.current,
+            lastSavedRevisionTokenRef,
+            autosaveTimerRef,
+          })
+        : rejectExportWhileLoading({
+            documentId,
+            datastore: datastoreRef.current,
+            onError: onErrorRef.current,
+            onEvent: onEventRef.current,
+          }));
+    }
+
+    const selectionPreview = summarizeSelectionPreview(snapshot);
+    const capabilities = deriveCapabilities(snapshot, reviewMode);
+
+    const dispatchSelection = (selection: PublicSelectionSnapshot) =>
+      activeRuntime.dispatch({
+        type: "selection.set",
+        selection: toRuntimeSelectionSnapshot(selection),
+      });
+
+    const editorCallbacks = {
+      onFocus: () => activeRuntime.focus(),
+      onBlur: () => activeRuntime.blur(),
+      onSelectionChange: dispatchSelection,
+      onInsertText: (text: string) => activeRuntime.dispatch({ type: "text.insert", text }),
+      onDeleteBackward: () => activeRuntime.dispatch({ type: "text.delete-backward" }),
+      onDeleteForward: () => activeRuntime.dispatch({ type: "text.delete-forward" }),
+      onInsertTab: () => activeRuntime.dispatch({ type: "text.insert-tab" }),
+      onInsertHardBreak: () => activeRuntime.dispatch({ type: "text.insert-hard-break" }),
+      onSplitParagraph: () => activeRuntime.dispatch({ type: "paragraph.split" }),
+    };
+
+    const reviewCallbacks = {
+      onUndo: () => activeRuntime.undo(),
+      onRedo: () => activeRuntime.redo(),
+      onAddComment: addReviewComment,
+      onExport: exportCurrentDocument,
+      onOpenComment: (thread: typeof snapshot.comments.threads[number]) => {
+        activeRuntime.openComment(thread.commentId);
+        focusAnchor(thread.anchor);
+        setActiveRailTab("comments");
+      },
+      onResolveComment: (commentId: string) => {
+        activeRuntime.resolveComment(commentId);
+        setActiveRailTab("comments");
+      },
+      onReopenComment: (commentId: string) => {
+        activeRuntime.reopenComment(commentId);
+        setActiveRailTab("comments");
+      },
+      onAddReply: (commentId: string, body: string) => {
+        activeRuntime.addCommentReply(commentId, body, currentUser.userId);
+      },
+      onEditBody: (commentId: string, body: string) => {
+        activeRuntime.editCommentBody(commentId, body);
+      },
+      onOpenRevision: (revision: typeof snapshot.trackedChanges.revisions[number]) => {
+        setActiveRevisionId(revision.revisionId);
+        focusAnchor(revision.anchor);
+        setActiveRailTab("changes");
+      },
+      onAcceptRevision: (revisionId: string) => {
+        activeRuntime.acceptChange(revisionId);
+        setActiveRailTab("changes");
+      },
+      onRejectRevision: (revisionId: string) => {
+        activeRuntime.rejectChange(revisionId);
+        setActiveRailTab("changes");
+      },
+      onAcceptAllChanges: () => {
+        activeRuntime.acceptAllChanges();
+        setActiveRailTab("changes");
+      },
+      onRejectAllChanges: () => {
+        activeRuntime.rejectAllChanges();
+        setActiveRailTab("changes");
+      },
+    };
+
+    return (
+      <TwReviewWorkspace
+        snapshot={snapshot}
+        currentUserId={currentUser.userId}
+        capabilities={capabilities}
+        reviewMode={reviewMode}
+        viewMode={viewMode}
+        activeRailTab={activeRailTab}
+        activeCommentId={snapshot.comments.activeCommentId}
+        activeRevisionId={activeRevisionId}
+        showTrackedChanges={showTrackedChanges}
+        selectionPreview={selectionPreview}
+        onViewModeChange={setViewMode}
+        onActiveRailTabChange={setActiveRailTab}
+        onShowTrackedChangesChange={setShowTrackedChanges}
+        {...reviewCallbacks}
+        document={
+          <TwProseMirrorSurface
+            currentUser={currentUser}
+            snapshot={snapshot}
+            reviewMode={reviewMode}
+            markupDisplay={liveMarkupDisplay}
+            activeRevisionId={activeRevisionId}
+            showTrackedChanges={showTrackedChanges}
+            {...editorCallbacks}
+            onCommentActivated={(commentId) => {
+              activeRuntime.openComment(commentId);
+              setActiveRailTab("comments");
+            }}
+            onRevisionActivated={(revisionId) => {
+              setActiveRevisionId(revisionId);
+              setActiveRailTab("changes");
+            }}
+          />
+        }
+      />
+    );
+  },
+);
+
+function normalizeEditorError(error: unknown): EditorError {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "errorId" in error &&
+    "code" in error &&
+    "message" in error
+  ) {
+    return error as EditorError;
+  }
+
+  return {
+    errorId: "word-review-editor-load",
+    code: "internal_invariant",
+    message: error instanceof Error ? error.message : "Unknown editor load failure.",
+    isFatal: true,
+    source: "runtime",
+  };
+}
+
+function guessSourceLabel(
+  initialSourceLabel?: string,
+  initialSnapshot?: PersistedEditorSnapshot,
+  externalDocSource?: WordReviewEditorProps["externalDocSource"],
+): string | undefined {
+  return (
+    externalDocSource?.sourceLabel ??
+    initialSourceLabel ??
+    initialSnapshot?.editorBuild ??
+    undefined
+  );
+}
+
+function createLoadingSnapshot(
+  documentId: string,
+  readOnly: boolean,
+  sourceLabel?: string,
+): RuntimeRenderSnapshot {
+  return {
+    documentId,
+    sessionId: `${documentId}-loading`,
+    sourceLabel,
+    revisionToken: `${documentId}:loading`,
+    isReady: false,
+    isDirty: false,
+    readOnly,
+    selection: collapsedSelection(),
+    documentStats: {
+      storyLength: 0,
+      commentCount: 0,
+      revisionCount: 0,
+      opaqueFragmentCount: 0,
+    },
+    comments: {
+      openCommentIds: [],
+      resolvedCommentIds: [],
+      detachedCommentIds: [],
+      totalCount: 0,
+      threads: [],
+    },
+    trackedChanges: {
+      pendingChangeIds: [],
+      acceptedChangeIds: [],
+      rejectedChangeIds: [],
+      detachedChangeIds: [],
+      actionableChangeIds: [],
+      preserveOnlyChangeIds: [],
+      totalCount: 0,
+      revisions: [],
+    },
+    compatibility: {
+      blockExport: false,
+      blockExportReasons: [],
+      warningCount: 0,
+      errorCount: 0,
+      featureEntries: [],
+    },
+    warnings: [],
+    commandState: {
+      canUndo: false,
+      canRedo: false,
+      readOnly,
+    },
+  };
+}
+
+function createErrorSnapshot(documentId: string, error: EditorError): RuntimeRenderSnapshot {
+  return {
+    ...createLoadingSnapshot(documentId, true),
+    isReady: true,
+    sessionId: `${documentId}-error`,
+    revisionToken: `${documentId}:error`,
+    compatibility: {
+      blockExport: true,
+      blockExportReasons: [error.message],
+      warningCount: 0,
+      errorCount: 1,
+      featureEntries: [],
+    },
+    fatalError: error,
+  };
+}
+
+async function persistAndExport(input: {
+  datastore?: EditorDatastoreAdapter;
+  documentId: string;
+  runtime: WordReviewEditorRuntime;
+  onError?: (error: EditorError) => void;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  options?: ExportDocxOptions;
+  lastSavedRevisionTokenRef: React.MutableRefObject<string | null>;
+  autosaveTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
+}): Promise<ExportResult> {
+  if (input.autosaveTimerRef.current) {
+    clearTimeout(input.autosaveTimerRef.current);
+    input.autosaveTimerRef.current = null;
+  }
+
+  await persistSnapshot({
+    datastore: input.datastore,
+    documentId: input.documentId,
+    runtime: input.runtime,
+    isAutosave: false,
+    onError: input.onError,
+    onEvent: input.onEvent,
+    lastSavedRevisionTokenRef: input.lastSavedRevisionTokenRef,
+  });
+
+  const result = await input.runtime.exportDocx(input.options);
+
+  if (!input.datastore) {
+    return result;
+  }
+
+  try {
+    await input.datastore.saveExport({
+      documentId: input.documentId,
+      result,
+    });
+  } catch (error) {
+    const normalized = normalizeDatastoreError(error, {
+      message: "Export persisted bytes could not be stored.",
+      details: {
+        operation: "saveExport",
+      },
+    });
+    input.onError?.(normalized);
+    emitEditorEvent({
+      datastore: input.datastore,
+      onEvent: input.onEvent,
+      event: {
+        type: "error",
+        documentId: input.documentId,
+        error: normalized,
+      },
+    });
+  }
+
+  return result;
+}
+
+function rejectExportWhileLoading(input: {
+  documentId: string;
+  datastore?: EditorDatastoreAdapter;
+  onError?: (error: EditorError) => void;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+}): Promise<never> {
+  const error: EditorError = {
+    errorId: "word-review-editor-loading-export",
+    code: "internal_invariant",
+    message: "WordReviewEditor is still loading and cannot export yet.",
+    isFatal: false,
+    source: "runtime",
+  };
+  input.onError?.(error);
+  emitEditorEvent({
+    datastore: input.datastore,
+    onEvent: input.onEvent,
+    event: {
+      type: "error",
+      documentId: input.documentId,
+      error,
+    },
+  });
+  return Promise.reject(error);
+}
+
+async function persistSnapshot(input: {
+  datastore?: EditorDatastoreAdapter;
+  documentId: string;
+  runtime: WordReviewEditorRuntime;
+  isAutosave: boolean;
+  onError?: (error: EditorError) => void;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  lastSavedRevisionTokenRef: React.MutableRefObject<string | null>;
+}): Promise<void> {
+  if (!input.datastore) {
+    return;
+  }
+
+  const snapshot = input.runtime.getPersistedSnapshot();
+  const revisionToken = input.runtime.getRenderSnapshot().revisionToken;
+
+  if (input.isAutosave) {
+    emitEditorEvent({
+      datastore: input.datastore,
+      onEvent: input.onEvent,
+      event: {
+        type: "autosave_state",
+        documentId: input.documentId,
+        state: {
+          status: "saving",
+        } satisfies AutosaveState,
+      },
+    });
+  }
+
+  try {
+    const result = await input.datastore.saveSnapshot({
+      documentId: input.documentId,
+      snapshot,
+      isAutosave: input.isAutosave,
+    });
+    const savedSnapshot: PersistedEditorSnapshot = {
+      ...snapshot,
+      savedAt: result.savedAt,
+    };
+    input.lastSavedRevisionTokenRef.current = revisionToken;
+    emitEditorEvent({
+      datastore: input.datastore,
+      onEvent: input.onEvent,
+      event: {
+        type: "snapshot_saved",
+        documentId: input.documentId,
+        snapshot: savedSnapshot,
+        isAutosave: input.isAutosave,
+      },
+    });
+    if (input.isAutosave) {
+      emitEditorEvent({
+        datastore: input.datastore,
+        onEvent: input.onEvent,
+        event: {
+          type: "autosave_state",
+          documentId: input.documentId,
+          state: {
+            status: "saved",
+            savedAt: result.savedAt,
+          } satisfies AutosaveState,
+        },
+      });
+    }
+  } catch (error) {
+    const normalized = normalizeDatastoreError(error, {
+      message: input.isAutosave
+        ? "Autosave failed while storing the editor snapshot."
+        : "Snapshot save failed while preparing the export checkpoint.",
+      details: {
+        operation: "saveSnapshot",
+        isAutosave: input.isAutosave,
+      },
+    });
+    input.onError?.(normalized);
+    emitEditorEvent({
+      datastore: input.datastore,
+      onEvent: input.onEvent,
+      event: {
+        type: "error",
+        documentId: input.documentId,
+        error: normalized,
+      },
+    });
+    if (input.isAutosave) {
+      emitEditorEvent({
+        datastore: input.datastore,
+        onEvent: input.onEvent,
+        event: {
+          type: "autosave_state",
+          documentId: input.documentId,
+          state: {
+            status: "error",
+            error: normalized,
+          } satisfies AutosaveState,
+        },
+      });
+    }
+    if (!input.isAutosave) {
+      throw normalized;
+    }
+  }
+}
+
+function emitEditorEvent(input: {
+  datastore?: EditorDatastoreAdapter;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  event: WordReviewEditorEvent;
+}): void {
+  input.onEvent?.(input.event);
+  input.datastore?.logEvent?.({
+    type: input.event.type,
+    documentId: input.event.documentId,
+    detail: summarizeEventDetail(input.event),
+  });
+}
+
+function summarizeEventDetail(
+  event: WordReviewEditorEvent,
+): Record<string, unknown> | undefined {
+  switch (event.type) {
+    case "dirty_changed":
+      return { isDirty: event.isDirty };
+    case "comment_added":
+      return { commentId: event.commentId };
+    case "comment_resolved":
+      return { commentId: event.commentId };
+    case "change_accepted":
+    case "change_rejected":
+      return { changeId: event.changeId };
+    case "warning_added":
+      return { warningId: event.warning.warningId, code: event.warning.code };
+    case "warning_cleared":
+      return { warningId: event.warningId, code: event.code };
+    case "error":
+      return { errorId: event.error.errorId, code: event.error.code };
+    case "autosave_state":
+      return { status: event.state.status };
+    case "snapshot_saved":
+      return { isAutosave: event.isAutosave, savedAt: event.snapshot.savedAt };
+    case "export_completed":
+      return { fileName: event.result.fileName };
+    case "selection_changed":
+      return {
+        anchor: event.selection.anchor,
+        head: event.selection.head,
+      };
+    case "ready":
+      return {
+        source: event.source,
+        blockExport: event.compatibility.blockExport,
+      };
+  }
+}
+
+function createReadyEvent(
+  runtime: Pick<WordReviewEditorRuntime, "getCompatibilityReport" | "getRenderSnapshot">,
+  source: "docx" | "snapshot" | "datastore" | "canonical",
+): Extract<WordReviewEditorEvent, { type: "ready" }> {
+  const snapshot = runtime.getRenderSnapshot();
+  return {
+    type: "ready",
+    documentId: snapshot.documentId,
+    sessionId: snapshot.sessionId,
+    source,
+    stats: snapshot.documentStats,
+    compatibility: runtime.getCompatibilityReport(),
+  };
+}
+
+function normalizeDatastoreError(
+  error: unknown,
+  fallback: {
+    message: string;
+    details?: Record<string, unknown>;
+  },
+): EditorError {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "errorId" in error &&
+    "code" in error &&
+    "message" in error
+  ) {
+    return error as EditorError;
+  }
+
+  return {
+    errorId: "word-review-editor-datastore",
+    code: "datastore_failed",
+    message: error instanceof Error ? error.message : fallback.message,
+    isFatal: false,
+    source: "datastore",
+    details: fallback.details,
+  };
+}
+
+function createFallbackSnapshot(args: CreateRuntimeArgs): RuntimeRenderSnapshot {
+  const warnings = args.source.initialSnapshot?.warningLog ?? [];
+  const compatibility = args.source.initialSnapshot?.compatibility ?? emptyCompatibilityReport();
+
+  return {
+    ...createLoadingSnapshot(args.documentId, args.readOnly, args.source.sourceLabel),
+    sessionId: `${args.documentId}-session`,
+    revisionToken: `${args.documentId}:0`,
+    isReady: true,
+    documentStats: {
+      storyLength: estimateStoryLength(args.source.initialSnapshot),
+      commentCount: 0,
+      revisionCount: 0,
+      opaqueFragmentCount: 0,
+    },
+    compatibility: {
+      blockExport: compatibility.blockExport,
+      blockExportReasons: [],
+      warningCount: compatibility.warnings.length,
+      errorCount: compatibility.errors.length,
+      featureEntries: compatibility.featureEntries,
+    },
+    warnings,
+  };
+}
+
+function createFallbackPersistedSnapshot(
+  documentId: string,
+  label = "Generated shell snapshot",
+): PersistedEditorSnapshot {
+  const docId = createCanonicalDocumentId(documentId);
+  return {
+    snapshotVersion: "persisted-editor-snapshot/1",
+    schemaVersion: "cds/1.0.0",
+    documentId,
+    docId,
+    createdAt: "1970-01-01T00:00:00.000Z",
+    updatedAt: "1970-01-01T00:00:00.000Z",
+    savedAt: "1970-01-01T00:00:00.000Z",
+    editorBuild: label,
+    canonicalDocument: {
+      schemaVersion: "cds/1.0.0",
+      docId,
+      createdAt: "1970-01-01T00:00:00.000Z",
+      updatedAt: "1970-01-01T00:00:00.000Z",
+      metadata: {
+        customProperties: {},
+      },
+      styles: {
+        paragraphs: {},
+        characters: {},
+        tables: {},
+      },
+      numbering: {
+        abstractDefinitions: {},
+        instances: {},
+      },
+      media: {
+        items: {},
+      },
+      content: {
+        type: "doc",
+        children: [{ type: "paragraph", children: [] }],
+      },
+      review: {
+        comments: {},
+        revisions: {},
+      },
+      preservation: {
+        opaqueFragments: {},
+        packageParts: {},
+      },
+      diagnostics: {
+        warnings: [],
+        errors: [],
+      },
+    },
+    compatibility: emptyCompatibilityReport(),
+    warningLog: [],
+  };
+}
+
+function emptyCompatibilityReport(): CompatibilityReport {
+  return {
+    reportVersion: "compatibility-report/1",
+    generatedAt: "1970-01-01T00:00:00.000Z",
+    blockExport: false,
+    featureEntries: [],
+    warnings: [],
+    errors: [],
+  };
+}
+
+function toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot) {
+  return {
+    anchor: selection.anchor,
+    head: selection.head,
+    isCollapsed: selection.isCollapsed,
+    activeRange:
+      selection.activeRange.kind === "range"
+        ? createRangeAnchor(
+            selection.activeRange.from,
+            selection.activeRange.to,
+            selection.activeRange.assoc,
+          )
+        : selection.activeRange.kind === "node"
+          ? createNodeAnchor(selection.activeRange.at, selection.activeRange.assoc)
+          : createDetachedAnchor(
+              selection.activeRange.lastKnownRange,
+              selection.activeRange.reason,
+            ),
+  };
+}
+
+function createSelectionFromAnchor(
+  anchor: PublicSelectionSnapshot["activeRange"],
+): PublicSelectionSnapshot {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        anchor: anchor.from,
+        head: anchor.to,
+        isCollapsed: anchor.from === anchor.to,
+        activeRange: anchor,
+      };
+    case "node":
+      return {
+        anchor: anchor.at,
+        head: anchor.at,
+        isCollapsed: true,
+        activeRange: anchor,
+      };
+    case "detached":
+      return {
+        anchor: anchor.lastKnownRange.from,
+        head: anchor.lastKnownRange.to,
+        isCollapsed: anchor.lastKnownRange.from === anchor.lastKnownRange.to,
+        activeRange: anchor,
+      };
+  }
+}
+
+function estimateStoryLength(snapshot?: PersistedEditorSnapshot): number {
+  const content = snapshot?.canonicalDocument.content;
+  return Array.isArray(content) ? content.length : 0;
+}
+
+function collapsedSelection(): RuntimeRenderSnapshot["selection"] {
+  return {
+    anchor: 0,
+    head: 0,
+    isCollapsed: true,
+    activeRange: {
+      kind: "range",
+      from: 0,
+      to: 0,
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+  };
+}
+
+function toUint8Array(bytes: Uint8Array | ArrayBuffer): Uint8Array {
+  return bytes instanceof Uint8Array ? new Uint8Array(bytes) : new Uint8Array(bytes);
+}
+
+function summarizeSelectionPreview(snapshot: RuntimeRenderSnapshot): string | null {
+  if (!snapshot.surface || snapshot.selection.isCollapsed) {
+    return null;
+  }
+
+  const range = snapshot.selection.activeRange;
+  if (range.kind !== "range") {
+    return "Selected range";
+  }
+
+  const preview = snapshot.surface.plainText
+    .slice(range.from, range.to)
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!preview) {
+    return "Selected range";
+  }
+
+  return preview.length > 48 ? `${preview.slice(0, 45)}...` : preview;
+}