@beyondwork/docx-react-component 1.0.1 → 1.0.2

package/src/ui/WordReviewEditor.tsx

@@ -0,0 +1,1504 @@
+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;
+}
+
+const VISUALLY_HIDDEN_STYLES: React.CSSProperties = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: 0,
+  margin: "-1px",
+  overflow: "hidden",
+  clip: "rect(0 0 0 0)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
+const ACCESSIBLE_REGION_ORDER = [
+  "toolbar",
+  "document",
+  "review-rail",
+  "status",
+] as const;
+
+type AccessibleRegionId = (typeof ACCESSIBLE_REGION_ORDER)[number];
+
+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 shellRef = useRef<HTMLDivElement | null>(null);
+    const lastAnnouncedErrorIdRef = useRef<string | 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 diagnosticsModeMessage = getDiagnosticsModeMessage(loadError ?? snapshot.fatalError);
+    const accessibilityInstructionsId = `${documentId}-accessibility-instructions`;
+    const accessibilityStatusId = `${documentId}-accessibility-status`;
+    const accessibilityAlertId = `${documentId}-accessibility-alert`;
+
+    const dispatchSelection = (selection: PublicSelectionSnapshot) =>
+      activeRuntime.dispatch({
+        type: "selection.set",
+        selection: toRuntimeSelectionSnapshot(selection),
+      });
+
+    useEffect(() => {
+      const shell = shellRef.current;
+      if (!shell) {
+        return;
+      }
+
+      applyRegionAttributes(shell);
+    }, [runtime, snapshot.fatalError, snapshot.isReady]);
+
+    useEffect(() => {
+      const shell = shellRef.current;
+      const fatalError = loadError ?? snapshot.fatalError;
+      if (!shell || !fatalError) {
+        lastAnnouncedErrorIdRef.current = null;
+        return;
+      }
+
+      if (lastAnnouncedErrorIdRef.current === fatalError.errorId) {
+        return;
+      }
+
+      lastAnnouncedErrorIdRef.current = fatalError.errorId;
+      const alertTarget = shell.querySelector<HTMLElement>("[data-wre-alert='true']");
+      alertTarget?.focus();
+    }, [loadError, snapshot.fatalError]);
+
+    function handleShellKeyDownCapture(event: React.KeyboardEvent<HTMLDivElement>): void {
+      if (event.key !== "F6") {
+        return;
+      }
+
+      const shell = shellRef.current;
+      if (!shell) {
+        return;
+      }
+
+      event.preventDefault();
+      focusRelativeRegion(shell, event.shiftKey ? -1 : 1);
+    }
+
+    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 (
+      <div
+        ref={shellRef}
+        role="region"
+        aria-label={`Word review editor for ${snapshot.sourceLabel ?? documentId}`}
+        aria-describedby={`${accessibilityInstructionsId} ${accessibilityStatusId}${
+          diagnosticsModeMessage ? ` ${accessibilityAlertId}` : ""
+        }`}
+        className="relative h-full"
+        onKeyDownCapture={handleShellKeyDownCapture}
+      >
+        <p id={accessibilityInstructionsId} style={VISUALLY_HIDDEN_STYLES}>
+          Press F6 to move focus between the toolbar, document surface, review rail, and status bar.
+        </p>
+        <div
+          id={accessibilityStatusId}
+          role="status"
+          aria-live="polite"
+          aria-atomic="true"
+          style={VISUALLY_HIDDEN_STYLES}
+        >
+          {buildAccessibilityStatusMessage(snapshot, loadError ?? undefined)}
+        </div>
+        {diagnosticsModeMessage ? (
+          <div
+            id={accessibilityAlertId}
+            data-wre-alert="true"
+            role="alert"
+            aria-live="assertive"
+            aria-atomic="true"
+            tabIndex={-1}
+            className="border-b border-danger/30 bg-danger/5 px-4 py-3 text-sm text-danger"
+          >
+            {diagnosticsModeMessage}
+          </div>
+        ) : null}
+        <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");
+              }}
+            />
+          }
+        />
+      </div>
+    );
+  },
+);
+
+function applyRegionAttributes(shell: HTMLElement): void {
+  const toolbar = shell.querySelector<HTMLElement>("header");
+  if (toolbar) {
+    toolbar.dataset.wreRegion = "toolbar";
+    toolbar.setAttribute("role", toolbar.getAttribute("role") ?? "toolbar");
+    toolbar.setAttribute("aria-label", toolbar.getAttribute("aria-label") ?? "Editor toolbar");
+    toolbar.tabIndex = -1;
+  }
+
+  const documentSurface = shell.querySelector<HTMLElement>('[aria-label="Document surface"]');
+  if (documentSurface) {
+    documentSurface.dataset.wreRegion = "document";
+  }
+
+  const reviewRail = shell.querySelector<HTMLElement>('[aria-label="Review rail"]');
+  if (reviewRail) {
+    reviewRail.dataset.wreRegion = "review-rail";
+    reviewRail.tabIndex = -1;
+  }
+
+  const statusBar = shell.querySelector<HTMLElement>("footer");
+  if (statusBar) {
+    statusBar.dataset.wreRegion = "status";
+    statusBar.setAttribute("role", statusBar.getAttribute("role") ?? "status");
+    statusBar.setAttribute("aria-label", statusBar.getAttribute("aria-label") ?? "Editor status bar");
+    statusBar.tabIndex = -1;
+  }
+}
+
+function focusRelativeRegion(shell: HTMLElement, direction: -1 | 1): void {
+  const activeRegion = getActiveRegionId(shell);
+  const startIndex =
+    activeRegion === null ? (direction === 1 ? -1 : 0) : ACCESSIBLE_REGION_ORDER.indexOf(activeRegion);
+
+  for (let offset = 1; offset <= ACCESSIBLE_REGION_ORDER.length; offset += 1) {
+    const index =
+      (startIndex + direction * offset + ACCESSIBLE_REGION_ORDER.length) %
+      ACCESSIBLE_REGION_ORDER.length;
+    const regionId = ACCESSIBLE_REGION_ORDER[index];
+    const target = findRegionFocusTarget(shell, regionId);
+    if (target) {
+      target.focus();
+      return;
+    }
+  }
+}
+
+function getActiveRegionId(shell: HTMLElement): AccessibleRegionId | null {
+  const activeElement = shell.ownerDocument.activeElement;
+  if (!(activeElement instanceof HTMLElement)) {
+    return null;
+  }
+
+  const region = activeElement.closest<HTMLElement>("[data-wre-region]");
+  const regionId = region?.dataset.wreRegion;
+  return isAccessibleRegionId(regionId) ? regionId : null;
+}
+
+function findRegionFocusTarget(
+  shell: HTMLElement,
+  regionId: AccessibleRegionId,
+): HTMLElement | null {
+  const region = shell.querySelector<HTMLElement>(`[data-wre-region="${regionId}"]`);
+  if (!region) {
+    return null;
+  }
+
+  if (regionId === "document" || regionId === "toolbar" || regionId === "review-rail" || regionId === "status") {
+    return region;
+  }
+}
+
+function isAccessibleRegionId(value: string | undefined): value is AccessibleRegionId {
+  return value === "toolbar" || value === "document" || value === "review-rail" || value === "status";
+}
+
+function buildAccessibilityStatusMessage(
+  snapshot: RuntimeRenderSnapshot,
+  loadError?: EditorError,
+): string {
+  if (loadError) {
+    return `Editor failed to load. ${loadError.message}`;
+  }
+
+  if (!snapshot.isReady) {
+    return "Editor loading. Document surface is not ready yet.";
+  }
+
+  if (snapshot.fatalError) {
+    return `Editor opened in diagnostics mode. ${snapshot.fatalError.message}`;
+  }
+
+  return [
+    snapshot.readOnly ? "Read-only mode." : "Editing enabled.",
+    `${snapshot.comments.totalCount} comment${snapshot.comments.totalCount === 1 ? "" : "s"}.`,
+    `${snapshot.trackedChanges.totalCount} tracked change${
+      snapshot.trackedChanges.totalCount === 1 ? "" : "s"
+    }.`,
+    snapshot.compatibility.blockExport ? "Export blocked." : "Export available.",
+  ].join(" ");
+}
+
+function getDiagnosticsModeMessage(error?: EditorError | null): string | null {
+  if (!error) {
+    return null;
+  }
+
+  if (error.code === "package_corrupt") {
+    return `${error.message} The document opened in read-only diagnostics mode so you can inspect the issue safely, but editing and export stay blocked until you reload a valid .docx package.`;
+  }
+
+  if (error.code === "validation_failed") {
+    return `${error.message} The document opened in read-only diagnostics mode because OOXML validation failed, so editing and export stay blocked until the source package is repaired.`;
+  }
+
+  return error.isFatal ? error.message : null;
+}
+
+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;
+}