@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/src/ui/WordReviewEditor.tsx

@@ -1,1283 +0,0 @@
-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;
-}