@beyondwork/docx-react-component 1.0.28 → 1.0.29

package/src/ui/editor-runtime-boundary.ts

@@ -1,1457 +0,0 @@
-import React, { useEffect, useMemo, useRef, useState } from "react";
-
-import type {
-  AutosaveState,
-  CompatibilityReport,
-  DocumentNavigationSnapshot,
-  EditorDatastoreAdapter,
-  EditorError,
-  EditorHostAdapter,
-  EditorSessionState,
-  EditorViewStateSnapshot,
-  EditorWarning,
-  ExportDocxOptions,
-  ExportResult,
-  FieldSnapshot,
-  PersistedEditorSnapshot,
-  RuntimeRenderSnapshot,
-  TocRefreshResult,
-  UpdateFieldsResult,
-  ViewMode as EditorViewMode,
-  WordReviewEditorEvent,
-  WordReviewEditorProps,
-  WorkspaceMode,
-  ZoomLevel,
-} from "../api/public-types";
-import {
-  editorSessionStateFromPersistedSnapshot,
-  persistedSnapshotFromEditorSessionState,
-} from "../api/session-state.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 {
-  decodePersistedSourcePackageBytes,
-  hasValidPersistedSourcePackageDigest,
-} from "../io/source-package-provenance.ts";
-import {
-  createEditorViewStateSnapshot,
-  createViewState,
-} from "../runtime/view-state.ts";
-import {
-  recordPerfSample,
-} from "../ui-tailwind/editor-surface/perf-probe.ts";
-import {
-  downloadExportResult,
-  withExportDelivery,
-} from "./browser-export";
-
-export interface ResolvedSource {
-  source: "docx" | "session" | "snapshot";
-  sourceLabel?: string;
-  initialDocx?: Uint8Array | ArrayBuffer;
-  initialSessionState?: EditorSessionState;
-  initialSnapshot?: PersistedEditorSnapshot;
-}
-
-export interface CreateRuntimeArgs {
-  documentId: string;
-  readOnly: boolean;
-  source: ResolvedSource;
-  initialViewState?: {
-    workspaceMode?: WorkspaceMode;
-    zoomLevel?: ZoomLevel;
-  };
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  currentUserId?: string;
-}
-
-interface RuntimeLifecycleHandlers {
-  onWarning?: (warning: EditorWarning) => void;
-  onError?: (error: EditorError) => void;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-}
-
-export interface WordReviewEditorRuntime extends DocumentRuntime {
-  getFatalError?(): EditorError | undefined;
-  dispose?(): void;
-  setDefaultAuthorId?(authorId?: string): void;
-  emitBlockedCommand(
-    command: string,
-    reasons: Extract<WordReviewEditorEvent, { type: "command_blocked" }>["reasons"],
-  ): void;
-}
-
-type PackageBackedDocxSession = ReturnType<typeof loadDocxEditorSession>;
-
-interface SnapshotExportBarrier {
-  reason:
-    | "missing_source_package_provenance"
-    | "invalid_source_package_provenance";
-  message: string;
-}
-
-export interface EditorRuntimeBoundaryState {
-  runtime: WordReviewEditorRuntime | null;
-  loadError: EditorError | null;
-  activeRuntime: WordReviewEditorRuntime;
-  fallbackSnapshot: RuntimeRenderSnapshot;
-  loadingSessionState: EditorSessionState;
-  loadingViewState: EditorViewStateSnapshot;
-  loadingNavigation: DocumentNavigationSnapshot;
-  hostAdapterRef: React.MutableRefObject<EditorHostAdapter | undefined>;
-  datastoreRef: React.MutableRefObject<EditorDatastoreAdapter | undefined>;
-  onEventRef: React.MutableRefObject<((event: WordReviewEditorEvent) => void) | undefined>;
-  onWarningRef: React.MutableRefObject<((warning: EditorWarning) => void) | undefined>;
-  onErrorRef: React.MutableRefObject<((error: EditorError) => void) | undefined>;
-  autosaveTimerRef: React.MutableRefObject<ReturnType<typeof setTimeout> | null>;
-  lastSavedRevisionTokenRef: React.MutableRefObject<string | null>;
-  runtimeViewStateSeedRef: React.MutableRefObject<{
-    workspaceMode: WorkspaceMode;
-    zoomLevel: ZoomLevel;
-  }>;
-}
-
-export async function __resolveWordReviewEditorSource(
-  props: Pick<
-    WordReviewEditorProps,
-    | "documentId"
-    | "hostAdapter"
-    | "datastore"
-    | "externalDocSource"
-    | "initialDocx"
-    | "initialSessionState"
-    | "initialSnapshot"
-    | "initialSourceLabel"
-    | "loadRevision"
-    | "loadSourcePolicy"
-  >,
-): Promise<ResolvedSource> {
-  const explicitInitialCount =
-    Number(Boolean(props.initialDocx)) +
-    Number(Boolean(props.initialSessionState)) +
-    Number(Boolean(props.initialSnapshot));
-  if (explicitInitialCount > 1) {
-    throw new Error(
-      "Provide exactly one of initialDocx, initialSessionState, or initialSnapshot.",
-    );
-  }
-
-  if (props.externalDocSource) {
-    if (props.externalDocSource.kind === "docx") {
-      return {
-        source: "docx",
-        initialDocx: props.externalDocSource.bytes,
-        sourceLabel: props.externalDocSource.sourceLabel,
-      };
-    }
-
-    if (props.externalDocSource.kind === "session") {
-      return {
-        source: "session",
-        initialSessionState: props.externalDocSource.sessionState,
-        sourceLabel:
-          props.externalDocSource.sourceLabel ??
-          props.externalDocSource.sessionState.sourcePackage?.sourceLabel,
-      };
-    }
-
-    return {
-      source: "snapshot",
-      initialSnapshot: props.externalDocSource.snapshot,
-      sourceLabel: props.externalDocSource.sourceLabel,
-    };
-  }
-
-  if (props.initialSessionState) {
-    return {
-      source: "session",
-      initialSessionState: props.initialSessionState,
-      sourceLabel:
-        props.initialSourceLabel ??
-        props.initialSessionState.sourcePackage?.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,
-    };
-  }
-
-  const loader = props.hostAdapter?.load ?? props.datastore?.load;
-  if (!loader) {
-    throw new Error(
-      `WordReviewEditor ${props.documentId} needs initialDocx, initialSessionState, initialSnapshot, or a host/datastore load source.`,
-    );
-  }
-
-  const loadResult = await loader({
-    documentId: props.documentId,
-    loadRevision: props.loadRevision,
-    loadSourcePolicy: props.loadSourcePolicy,
-  });
-
-  if (!loadResult.source) {
-    throw new Error(
-      `Host or datastore loader did not return a loadable source for ${props.documentId}.`,
-    );
-  }
-
-  if (loadResult.source.kind === "docx") {
-    return {
-      source: "docx",
-      initialDocx: loadResult.source.bytes,
-      sourceLabel: loadResult.source.sourceLabel,
-    };
-  }
-
-  if (loadResult.source.kind === "session") {
-    return {
-      source: "session",
-      initialSessionState: loadResult.source.sessionState,
-      sourceLabel:
-        loadResult.source.sourceLabel ??
-        loadResult.source.sessionState.sourcePackage?.sourceLabel,
-    };
-  }
-
-  return {
-    source: "snapshot",
-    initialSnapshot: loadResult.source.snapshot,
-    sourceLabel: loadResult.source.sourceLabel,
-  };
-}
-
-export function __createFallbackRuntime(args: CreateRuntimeArgs): WordReviewEditorRuntime {
-  return createRuntime(args);
-}
-
-export function useEditorRuntimeBoundary(
-  props: WordReviewEditorProps,
-): EditorRuntimeBoundaryState {
-  const {
-    currentUser,
-    datastore,
-    documentId,
-    externalDocSource,
-    externalDocumentRevision,
-    hostAdapter,
-    initialDocx,
-    initialSessionState,
-    initialSnapshot,
-    initialSourceLabel,
-    loadRevision,
-    loadSourcePolicy = "prefer-saved-state",
-    onError,
-    onEvent,
-    onWarning,
-    readOnly = false,
-    reviewMode = "review",
-  } = props;
-
-  const [runtime, setRuntime] = useState<WordReviewEditorRuntime | null>(null);
-  const [loadError, setLoadError] = useState<EditorError | null>(null);
-  const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
-  const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastSavedRevisionTokenRef = useRef<string | null>(null);
-  const hostAdapterRef = useRef(hostAdapter);
-  const datastoreRef = useRef(datastore);
-  const onEventRef = useRef(onEvent);
-  const onWarningRef = useRef(onWarning);
-  const onErrorRef = useRef(onError);
-  const runtimeViewStateSeedRef = useRef<{
-    workspaceMode: WorkspaceMode;
-    zoomLevel: ZoomLevel;
-  }>({
-    workspaceMode: "canvas",
-    zoomLevel: 100,
-  });
-  const initialSourceRef = useRef<{
-    documentId: string;
-    initialDocx?: Uint8Array | ArrayBuffer;
-    initialSessionState?: EditorSessionState;
-    initialSnapshot?: PersistedEditorSnapshot;
-    initialSourceLabel?: string;
-  } | null>(null);
-
-  if (!initialSourceRef.current || initialSourceRef.current.documentId !== documentId) {
-    initialSourceRef.current = {
-      documentId,
-      initialDocx,
-      initialSessionState,
-      initialSnapshot,
-      initialSourceLabel,
-    };
-  }
-
-  const stableInitialSource = initialSourceRef.current;
-  const sourceReloadKey = externalDocSource
-    ? `external:${externalDocSource.kind}:${externalDocumentRevision ?? "static"}`
-    : stableInitialSource?.initialSessionState
-      ? "initial-session"
-      : stableInitialSource?.initialSnapshot
-        ? "initial-snapshot"
-        : stableInitialSource?.initialDocx
-          ? "initial-docx"
-          : hostAdapter
-            ? `host-adapter:${loadRevision ?? "static"}`
-            : `datastore:${loadRevision ?? "static"}`;
-
-  useEffect(() => {
-    hostAdapterRef.current = hostAdapter;
-    datastoreRef.current = datastore;
-    onEventRef.current = onEvent;
-    onWarningRef.current = onWarning;
-    onErrorRef.current = onError;
-  }, [datastore, hostAdapter, onError, onEvent, onWarning]);
-
-  useEffect(() => {
-    runtimeRef.current?.setDefaultAuthorId?.(currentUser.userId);
-  }, [currentUser.userId]);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    async function loadRuntime(): Promise<void> {
-      setLoadError(null);
-
-      try {
-        const source = await __resolveWordReviewEditorSource({
-          documentId,
-          hostAdapter: hostAdapterRef.current,
-          datastore: datastoreRef.current,
-          externalDocSource,
-          initialDocx: stableInitialSource?.initialDocx,
-          initialSessionState: stableInitialSource?.initialSessionState,
-          initialSnapshot: stableInitialSource?.initialSnapshot,
-          initialSourceLabel: stableInitialSource?.initialSourceLabel,
-          loadRevision,
-          loadSourcePolicy,
-        });
-
-        if (cancelled) {
-          return;
-        }
-
-        runtimeRef.current?.dispose?.();
-        const nextRuntime = createRuntime(
-          {
-            documentId,
-            readOnly,
-            source,
-            initialViewState: runtimeViewStateSeedRef.current,
-            hostAdapter: hostAdapterRef.current,
-            datastore: datastoreRef.current,
-            currentUserId: currentUser.userId,
-          },
-          {
-            onWarning: onWarningRef.current,
-            onError: onErrorRef.current,
-            onEvent: onEventRef.current,
-          },
-        );
-        recordPerfSample("runtime.create");
-        emitEditorEvent({
-          hostAdapter: hostAdapterRef.current,
-          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({
-          hostAdapter: hostAdapterRef.current,
-          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) => {
-      if (event.type === "export_completed" || event.type === "ready") {
-        return;
-      }
-      emitEditorEvent({
-        hostAdapter: hostAdapterRef.current,
-        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 fallbackSnapshot = useMemo(
-    () =>
-      loadError
-        ? createErrorSnapshot(documentId, loadError)
-        : createLoadingSnapshot(
-            documentId,
-            readOnly,
-            guessSourceLabel(
-              initialSourceLabel,
-              initialSessionState,
-              initialSnapshot,
-              externalDocSource,
-            ),
-          ),
-    [
-      documentId,
-      externalDocSource,
-      initialSessionState,
-      initialSnapshot,
-      initialSourceLabel,
-      loadError,
-      readOnly,
-    ],
-  );
-  const loadingPersistedSnapshot = useMemo(
-    () => createFallbackPersistedSnapshot(documentId, initialSourceLabel),
-    [documentId, initialSourceLabel],
-  );
-  const loadingSessionState = useMemo(
-    () =>
-      initialSessionState ??
-      (initialSnapshot
-        ? editorSessionStateFromPersistedSnapshot(initialSnapshot)
-        : editorSessionStateFromPersistedSnapshot(loadingPersistedSnapshot)),
-    [initialSessionState, initialSnapshot, loadingPersistedSnapshot],
-  );
-  const loadingViewState = useMemo(
-    () =>
-      createLoadingViewStateSnapshot(
-        fallbackSnapshot,
-        runtimeViewStateSeedRef.current,
-        deriveEditorViewMode(fallbackSnapshot.readOnly, reviewMode),
-      ),
-    [fallbackSnapshot, reviewMode],
-  );
-  const loadingNavigation = useMemo(
-    () => createLoadingNavigationSnapshot(),
-    [],
-  );
-  const loadingRuntimeBridge = useMemo(
-    () =>
-      createLoadingRuntimeBridge({
-        snapshot: fallbackSnapshot,
-        sessionState: loadingSessionState,
-        viewState: loadingViewState,
-        navigation: loadingNavigation,
-      }),
-    [fallbackSnapshot, loadingNavigation, loadingSessionState, loadingViewState],
-  );
-
-  return {
-    runtime,
-    loadError,
-    activeRuntime: runtime ?? loadingRuntimeBridge,
-    fallbackSnapshot,
-    loadingSessionState,
-    loadingViewState,
-    loadingNavigation,
-    hostAdapterRef,
-    datastoreRef,
-    onEventRef,
-    onWarningRef,
-    onErrorRef,
-    autosaveTimerRef,
-    lastSavedRevisionTokenRef,
-    runtimeViewStateSeedRef,
-  };
-}
-
-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 snapshotExportResolution = !args.source.initialDocx
-    ? resolvePackageBackedExportSession(args)
-    : undefined;
-  const initialSessionState =
-    args.source.initialSessionState ??
-    docxSession?.initialSessionState ??
-    (args.source.initialSnapshot
-      ? editorSessionStateFromPersistedSnapshot(args.source.initialSnapshot)
-      : editorSessionStateFromPersistedSnapshot(
-          createFallbackPersistedSnapshot(
-            args.documentId,
-            args.source.sourceLabel ?? "Generated shell snapshot",
-          ),
-        ));
-  const runtimeSessionState = snapshotExportResolution?.barrier
-    ? applySessionExportBarrier(initialSessionState, snapshotExportResolution.barrier)
-    : initialSessionState;
-
-  const runtime: WordReviewEditorRuntime = Object.assign(createDocumentRuntime({
-    documentId: args.documentId,
-    initialSessionState: runtimeSessionState,
-    sourceKind: args.source.source,
-    sourceLabel: args.source.sourceLabel,
-    initialViewState: args.initialViewState,
-    readOnly: args.readOnly || docxSession?.readOnly,
-    editorBuild: runtimeSessionState.editorBuild,
-    fatalError: docxSession?.fatalError,
-    protectionSnapshot: docxSession?.protectionSnapshot,
-    exportDocx: async (sessionState, options) => {
-      if (docxSession) {
-        return docxSession.exportDocx(sessionState, options);
-      }
-
-      if (snapshotExportResolution?.session) {
-        return snapshotExportResolution.session.exportDocx(sessionState, options);
-      }
-
-      throw createSnapshotExportBlockedError(
-        args.documentId,
-        snapshotExportResolution?.barrier ?? {
-          reason: "missing_source_package_provenance",
-          message:
-            "DOCX export is blocked because this session does not carry embedded source package provenance.",
-        },
-      );
-    },
-    onWarning: handlers.onWarning,
-    onError: handlers.onError,
-    defaultAuthorId: args.currentUserId,
-  }), {
-    emitBlockedCommand: (
-      command: string,
-      reasons: Extract<WordReviewEditorEvent, { type: "command_blocked" }>["reasons"],
-    ) => {
-      emitEditorEvent({
-        hostAdapter: args.hostAdapter,
-        datastore: args.datastore,
-        onEvent: handlers.onEvent,
-        event: {
-          type: "command_blocked",
-          documentId: args.documentId,
-          command,
-          reasons,
-        },
-      });
-    },
-  });
-
-  return runtime;
-}
-
-function createLoadingSnapshot(
-  documentId: string,
-  readOnly: boolean,
-  sourceLabel?: string,
-): RuntimeRenderSnapshot {
-  return {
-    documentId,
-    sessionId: `${documentId}-loading`,
-    sourceLabel,
-    revisionToken: `${documentId}:loading`,
-    isReady: false,
-    isDirty: false,
-    readOnly,
-    documentMode: "editing",
-    selection: collapsedSelection(),
-    activeStory: { kind: "main" },
-    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,
-    },
-    protectionSnapshot: {
-      hasDocumentProtection: false,
-      enforcementActive: false,
-      ranges: [],
-      enforcedRangeCount: 0,
-      preservedRangeCount: 0,
-    },
-  };
-}
-
-function createLoadingNavigationSnapshot(): DocumentNavigationSnapshot {
-  return {
-    pageCount: 0,
-    pages: [],
-    headings: [],
-    activePageIndex: 0,
-    activeSectionIndex: 0,
-  };
-}
-
-function createLoadingViewStateSnapshot(
-  snapshot: RuntimeRenderSnapshot,
-  seed: {
-    workspaceMode?: WorkspaceMode;
-    zoomLevel?: ZoomLevel;
-  },
-  viewMode: EditorViewMode,
-): EditorViewStateSnapshot {
-  return createEditorViewStateSnapshot(
-    createViewState({
-      viewMode,
-      workspaceMode: seed.workspaceMode,
-      zoomLevel: seed.zoomLevel,
-    }),
-    snapshot.activeStory,
-    snapshot.selection,
-    snapshot.surface,
-    snapshot.surface,
-    snapshot.pageLayout,
-  );
-}
-
-function createLoadingRuntimeBridge(input: {
-  snapshot: RuntimeRenderSnapshot;
-  sessionState: EditorSessionState;
-  viewState: EditorViewStateSnapshot;
-  navigation: DocumentNavigationSnapshot;
-}): WordReviewEditorRuntime {
-  const emptyFieldSnapshot: FieldSnapshot = {
-    totalCount: 0,
-    supportedCount: 0,
-    preserveOnlyCount: 0,
-    fields: [],
-  };
-  const emptyFieldResult: UpdateFieldsResult = {
-    totalCount: 0,
-    updatedCount: 0,
-    preserveOnlyCount: 0,
-  };
-  const emptyTocResult: TocRefreshResult = {
-    entryCount: 0,
-    entries: [],
-  };
-
-  return {
-    subscribe: () => () => undefined,
-    subscribeToEvents: () => () => undefined,
-    emitBlockedCommand: () => undefined,
-    getRenderSnapshot: () => input.snapshot,
-    getCanonicalDocument: () => input.sessionState.canonicalDocument,
-    getSourcePackage: () => input.sessionState.sourcePackage,
-    replaceText: () => undefined,
-    applyActiveStoryTextCommand: () => undefined,
-    dispatch: () => undefined,
-    undo: () => undefined,
-    redo: () => undefined,
-    focus: () => undefined,
-    blur: () => undefined,
-    addComment: () => {
-      throw createLoadingBoundaryError(input.snapshot.documentId, "comment");
-    },
-    openComment: () => undefined,
-    resolveComment: () => undefined,
-    reopenComment: () => undefined,
-    addCommentReply: () => undefined,
-    editCommentBody: () => undefined,
-    acceptChange: () => undefined,
-    rejectChange: () => undefined,
-    acceptAllChanges: () => undefined,
-    rejectAllChanges: () => undefined,
-    openStory: () => false,
-    closeStory: () => undefined,
-    getActiveStory: () => input.snapshot.activeStory,
-    getViewState: () => input.viewState,
-    setViewMode: () => undefined,
-    setDocumentMode: () => undefined,
-    getProtectionSnapshot: () => input.snapshot.protectionSnapshot,
-    setWorkspaceMode: () => undefined,
-    setZoom: () => undefined,
-    getPageLayoutSnapshot: () => null,
-    getDocumentNavigationSnapshot: () => input.navigation,
-    getFieldSnapshot: () => emptyFieldSnapshot,
-    updateFields: () => emptyFieldResult,
-    updateTableOfContents: () => emptyTocResult,
-    getSessionState: () => {
-      throw createLoadingBoundaryError(input.snapshot.documentId, "session");
-    },
-    getPersistedSnapshot: () => {
-      throw createLoadingBoundaryError(input.snapshot.documentId, "snapshot");
-    },
-    getCompatibilityReport: () => ({
-      reportVersion: "compatibility-report/1",
-      generatedAt: input.sessionState.updatedAt,
-      blockExport: input.snapshot.compatibility.blockExport,
-      featureEntries: input.snapshot.compatibility.featureEntries,
-      warnings: input.snapshot.warnings,
-      errors: input.snapshot.fatalError ? [input.snapshot.fatalError] : [],
-    }),
-    getWarnings: () => input.snapshot.warnings,
-    exportDocx: () =>
-      Promise.reject(createLoadingBoundaryError(input.snapshot.documentId, "export")),
-    setWorkflowOverlay: () => undefined,
-    clearWorkflowOverlay: () => undefined,
-    getWorkflowScopeSnapshot: () => null,
-    getInteractionGuardSnapshot: () => ({ effectiveMode: "edit", blockedReasons: [] }),
-    getWorkflowMarkupSnapshot: () => ({
-      totalCount: 0,
-      items: [],
-      highlights: [],
-      comments: [],
-      revisions: [],
-      fields: [],
-      protectedRanges: [],
-      opaqueFragments: [],
-    }),
-    setHostAnnotationOverlay: () => undefined,
-    clearHostAnnotationOverlay: () => undefined,
-    getHostAnnotationSnapshot: () => ({
-      totalCount: 0,
-      annotations: [],
-    }),
-    getWorkflowCandidateRanges: () => [],
-    replaceWorkflowMarkupText: () => undefined,
-  };
-}
-
-function createLoadingBoundaryError(
-  documentId: string,
-  target: "comment" | "session" | "snapshot" | "export",
-): EditorError {
-  return {
-    errorId: `${documentId}-loading-${target}`,
-    code: "internal_invariant",
-    message: "Editor is still loading.",
-    isFatal: false,
-    source: "runtime",
-  };
-}
-
-function deriveEditorViewMode(
-  readOnly: boolean,
-  reviewMode: WordReviewEditorProps["reviewMode"] = "review",
-): EditorViewMode {
-  if (readOnly) {
-    return "view";
-  }
-  return reviewMode === "editing" ? "editing" : "review";
-}
-
-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,
-  };
-}
-
-export async function persistAndExport(input: {
-  hostAdapter?: EditorHostAdapter;
-  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 persistSession({
-    hostAdapter: input.hostAdapter,
-    datastore: input.datastore,
-    documentId: input.documentId,
-    runtime: input.runtime,
-    isAutosave: false,
-    onError: input.onError,
-    onEvent: input.onEvent,
-    lastSavedRevisionTokenRef: input.lastSavedRevisionTokenRef,
-  });
-
-  let result: ExportResult;
-  try {
-    result = await input.runtime.exportDocx(input.options);
-  } catch (error) {
-    const normalized = normalizeExportError(error, input.documentId, input.options);
-    input.onError?.(normalized);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "error",
-        documentId: input.documentId,
-        error: normalized,
-      },
-    });
-    throw normalized;
-  }
-
-  const saveExport = input.hostAdapter?.saveExport ?? input.datastore?.saveExport;
-  const saveExportSource = input.hostAdapter?.saveExport ? "host" : "datastore";
-  if (!saveExport) {
-    result = downloadExportResult(result);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "export_completed",
-        documentId: input.documentId,
-        result,
-      },
-    });
-    return result;
-  }
-
-  try {
-    const saveResult = await saveExport({
-      documentId: input.documentId,
-      result,
-    });
-    result = withExportDelivery(result, {
-      mode: "persisted-by-host",
-      savedAt: saveResult.savedAt,
-    });
-  } catch (error) {
-    const normalized = normalizeStorageError(error, {
-      message: "Export persisted bytes could not be stored.",
-      source: saveExportSource,
-      details: {
-        operation: "saveExport",
-      },
-    });
-    input.onError?.(normalized);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "error",
-        documentId: input.documentId,
-        error: normalized,
-      },
-    });
-    result = withExportDelivery(result, {
-      mode: "exported-bytes-only",
-    });
-  }
-
-  emitEditorEvent({
-    hostAdapter: input.hostAdapter,
-    datastore: input.datastore,
-    onEvent: input.onEvent,
-    event: {
-      type: "export_completed",
-      documentId: input.documentId,
-      result,
-    },
-  });
-
-  return result;
-}
-
-export function rejectExportWhileLoading(input: {
-  documentId: string;
-  hostAdapter?: EditorHostAdapter;
-  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({
-    hostAdapter: input.hostAdapter,
-    datastore: input.datastore,
-    onEvent: input.onEvent,
-    event: {
-      type: "error",
-      documentId: input.documentId,
-      error,
-    },
-  });
-  return Promise.reject(error);
-}
-
-export async function persistSession(input: {
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  documentId: string;
-  runtime: WordReviewEditorRuntime;
-  isAutosave: boolean;
-  onError?: (error: EditorError) => void;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  lastSavedRevisionTokenRef: React.MutableRefObject<string | null>;
-}): Promise<void> {
-  const saveSession = input.hostAdapter?.saveSession;
-  const saveSnapshot = input.datastore?.saveSnapshot;
-  if (!saveSession && !saveSnapshot) {
-    return;
-  }
-
-  const sessionState = input.runtime.getSessionState();
-  const snapshot = input.runtime.getPersistedSnapshot();
-  const revisionToken = input.runtime.getRenderSnapshot().revisionToken;
-
-  if (input.isAutosave) {
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "autosave_state",
-        documentId: input.documentId,
-        state: {
-          status: "saving",
-        } satisfies AutosaveState,
-      },
-    });
-  }
-
-  try {
-    const result = saveSession
-      ? await saveSession({
-          documentId: input.documentId,
-          sessionState,
-          isAutosave: input.isAutosave,
-        })
-      : await saveSnapshot!({
-          documentId: input.documentId,
-          snapshot,
-          isAutosave: input.isAutosave,
-        });
-    input.lastSavedRevisionTokenRef.current = revisionToken;
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: saveSession
-        ? {
-            type: "session_saved",
-            documentId: input.documentId,
-            sessionState: input.runtime.getSessionState(),
-            savedAt: result.savedAt,
-            isAutosave: input.isAutosave,
-          }
-        : {
-            type: "snapshot_saved",
-            documentId: input.documentId,
-            snapshot: {
-              ...snapshot,
-              savedAt: result.savedAt,
-            },
-            isAutosave: input.isAutosave,
-          },
-    });
-    if (input.isAutosave) {
-      emitEditorEvent({
-        hostAdapter: input.hostAdapter,
-        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 = normalizeStorageError(error, {
-      message: input.isAutosave
-        ? saveSession
-          ? "Autosave failed while storing the editor session."
-          : "Autosave failed while storing the editor snapshot."
-        : saveSession
-          ? "Session save failed while preparing the export checkpoint."
-          : "Snapshot save failed while preparing the export checkpoint.",
-      source: saveSession ? "host" : "datastore",
-      details: {
-        operation: saveSession ? "saveSession" : "saveSnapshot",
-        isAutosave: input.isAutosave,
-      },
-    });
-    input.onError?.(normalized);
-    emitEditorEvent({
-      hostAdapter: input.hostAdapter,
-      datastore: input.datastore,
-      onEvent: input.onEvent,
-      event: {
-        type: "error",
-        documentId: input.documentId,
-        error: normalized,
-      },
-    });
-    if (input.isAutosave) {
-      emitEditorEvent({
-        hostAdapter: input.hostAdapter,
-        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: {
-  hostAdapter?: EditorHostAdapter;
-  datastore?: EditorDatastoreAdapter;
-  onEvent?: (event: WordReviewEditorEvent) => void;
-  event: WordReviewEditorEvent;
-}): void {
-  input.onEvent?.(input.event);
-  const logEvent = input.hostAdapter?.logEvent ?? input.datastore?.logEvent;
-  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":
-    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 "session_saved":
-      return { isAutosave: event.isAutosave, savedAt: event.savedAt };
-    case "export_completed":
-      return {
-        fileName: event.result.fileName,
-        deliveryMode: event.result.delivery?.mode,
-        savedAt: event.result.delivery?.savedAt,
-      };
-    case "story_changed":
-      return { activeStory: event.activeStory };
-    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" | "session" | "snapshot",
-): Extract<WordReviewEditorEvent, { type: "ready" }> {
-  const snapshot = runtime.getRenderSnapshot();
-  return {
-    type: "ready",
-    documentId: snapshot.documentId,
-    sessionId: snapshot.sessionId,
-    source,
-    stats: snapshot.documentStats,
-    compatibility: runtime.getCompatibilityReport(),
-    comments: snapshot.comments,
-    trackedChanges: snapshot.trackedChanges,
-  };
-}
-
-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,
-  initialSessionState?: EditorSessionState,
-  initialSnapshot?: PersistedEditorSnapshot,
-  externalDocSource?: WordReviewEditorProps["externalDocSource"],
-): string | undefined {
-  return (
-    externalDocSource?.sourceLabel ??
-    (externalDocSource?.kind === "session"
-      ? externalDocSource.sessionState.sourcePackage?.sourceLabel
-      : undefined) ??
-    (externalDocSource?.kind === "snapshot"
-      ? externalDocSource.snapshot.sourcePackage?.sourceLabel
-      : undefined) ??
-    initialSourceLabel ??
-    initialSessionState?.sourcePackage?.sourceLabel ??
-    initialSessionState?.editorBuild ??
-    initialSnapshot?.sourcePackage?.sourceLabel ??
-    initialSnapshot?.editorBuild ??
-    undefined
-  );
-}
-
-function createFallbackPersistedSnapshot(
-  documentId: string,
-  label = "Generated shell snapshot",
-): PersistedEditorSnapshot {
-  const docId = createCanonicalDocumentId(documentId);
-  return {
-    snapshotVersion: "persisted-editor-snapshot/2",
-    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 resolvePackageBackedExportSession(args: CreateRuntimeArgs): {
-  session?: PackageBackedDocxSession;
-  barrier?: SnapshotExportBarrier;
-} {
-  const sourcePackage =
-    args.source.initialSessionState?.sourcePackage ??
-    args.source.initialSnapshot?.sourcePackage;
-  if (!sourcePackage) {
-    return {
-      barrier: {
-        reason: "missing_source_package_provenance",
-        message:
-          "DOCX export is blocked because this session was loaded without embedded source package provenance.",
-      },
-    };
-  }
-
-  try {
-    const bytes = decodePersistedSourcePackageBytes(sourcePackage);
-    if (!hasValidPersistedSourcePackageDigest(sourcePackage, bytes)) {
-      return {
-        barrier: {
-          reason: "invalid_source_package_provenance",
-          message:
-            "DOCX export is blocked because the embedded source package provenance failed its integrity check.",
-        },
-      };
-    }
-
-    const session = loadDocxEditorSession({
-      documentId: args.documentId,
-      sourceLabel: sourcePackage.sourceLabel ?? args.source.sourceLabel,
-      bytes,
-      editorBuild:
-        args.source.initialSessionState?.editorBuild ??
-        args.source.initialSnapshot?.editorBuild ??
-        "dev",
-    });
-    if (session.readOnly || session.fatalError) {
-      return {
-        barrier: {
-          reason: "invalid_source_package_provenance",
-          message:
-            "DOCX export is blocked because the embedded source package provenance is no longer loadable as a valid package-backed session.",
-        },
-      };
-    }
-
-    return { session };
-  } catch {
-    return {
-      barrier: {
-        reason: "invalid_source_package_provenance",
-        message:
-          "DOCX export is blocked because the embedded source package provenance could not be decoded into a package-backed session.",
-      },
-    };
-  }
-}
-
-function applySessionExportBarrier(
-  sessionState: EditorSessionState,
-  barrier: SnapshotExportBarrier,
-): EditorSessionState {
-  const featureEntryId = `feature:source-package-provenance:${barrier.reason}`;
-  const featureEntries = sessionState.compatibility.featureEntries.some(
-    (entry) => entry.featureEntryId === featureEntryId,
-  )
-    ? sessionState.compatibility.featureEntries
-    : [
-        ...sessionState.compatibility.featureEntries,
-        {
-          featureEntryId,
-          featureKey: "source-package-provenance",
-          featureClass: "unsupported-fatal" as const,
-          message: barrier.message,
-          details: {
-            reason: barrier.reason,
-          },
-        },
-      ];
-
-  return {
-    ...sessionState,
-    compatibility: {
-      ...sessionState.compatibility,
-      blockExport: true,
-      featureEntries,
-    },
-  };
-}
-
-function createSnapshotExportBlockedError(
-  documentId: string,
-  barrier: SnapshotExportBarrier,
-): EditorError {
-  return {
-    errorId: `${documentId}:export:${barrier.reason}`,
-    code: "export_failed",
-    message: barrier.message,
-    isFatal: false,
-    source: "export",
-    details: {
-      reason: barrier.reason,
-    },
-  };
-}
-
-function normalizeStorageError(
-  error: unknown,
-  fallback: {
-    message: string;
-    source: "host" | "datastore";
-    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:
-      fallback.source === "host"
-        ? "word-review-editor-host"
-        : "word-review-editor-datastore",
-    code: "datastore_failed",
-    message: error instanceof Error ? error.message : fallback.message,
-    isFatal: false,
-    source: fallback.source === "host" ? "host" : "datastore",
-    details: fallback.details,
-  };
-}
-
-function normalizeExportError(
-  error: unknown,
-  documentId: string,
-  options?: ExportDocxOptions,
-): EditorError {
-  if (
-    typeof error === "object" &&
-    error !== null &&
-    "errorId" in error &&
-    "code" in error &&
-    "message" in error
-  ) {
-    return error as EditorError;
-  }
-
-  return {
-    errorId: `${documentId}:export:failed`,
-    code: "export_failed",
-    message:
-      error instanceof Error ? error.message : "DOCX export failed for an unknown reason.",
-    isFatal: false,
-    source: "export",
-    details: {
-      requestedOptions: options ?? {},
-    },
-  };
-}
-
-function collapsedSelection(): RuntimeRenderSnapshot["selection"] {
-  return {
-    anchor: 0,
-    head: 0,
-    isCollapsed: true,
-    activeRange: {
-      kind: "range",
-      from: 0,
-      to: 0,
-      assoc: {
-        start: -1,
-        end: 1,
-      },
-    },
-  };
-}