@beyondwork/docx-react-component 1.0.19 → 1.0.21

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

@@ -0,0 +1,1448 @@
+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,
+    replaceText: () => 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: () => ({ blockedReasons: [] }),
+    getWorkflowMarkupSnapshot: () => ({
+      totalCount: 0,
+      items: [],
+      highlights: [],
+      comments: [],
+      revisions: [],
+      fields: [],
+      protectedRanges: [],
+      opaqueFragments: [],
+    }),
+    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,
+      },
+    },
+  };
+}