@beyondwork/docx-react-component 1.0.11 → 1.0.13

package/src/ui/WordReviewEditor.tsx

@@ -14,9 +14,14 @@ import type {
   CompatibilityReport,
   EditorError,
   EditorWarning,
+  FormattingAlignment,
   ExportDocxOptions,
+  InsertImageOptions,
+  InsertTableOptions,
   PersistedEditorSnapshot,
   RuntimeRenderSnapshot,
+  SearchOptions,
+  SearchResultSnapshot,
   SelectionSnapshot as PublicSelectionSnapshot,
   ExportResult,
   WordReviewEditorEvent,
@@ -27,17 +32,42 @@ import {
   createDetachedAnchor,
   createNodeAnchor,
   createRangeAnchor,
+  type TransactionMapping,
 } from "../core/selection/mapping.ts";
-import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
+import {
+  applyFormattingOperationToDocument,
+  getFormattingStateFromRenderSnapshot,
+} from "../core/commands/formatting-commands.ts";
+import { insertImage as insertImageInDocument } from "../core/commands/image-commands.ts";
+import {
+  applyTableStructureOperation,
+} from "../core/commands/table-structure-commands.ts";
+import {
+  insertPageBreak as insertPageBreakInDocument,
+  insertTable as insertTableInDocument,
+} from "../core/commands/text-commands.ts";
+import {
+  createCanonicalDocumentId,
+  type SelectionSnapshot as InternalSelectionSnapshot,
+} 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 {
+  decodePersistedSourcePackageBytes,
+  hasValidPersistedSourcePackageDigest,
+} from "../io/source-package-provenance.ts";
 import { deriveCapabilities } from "../runtime/session-capabilities";
-import { TwProseMirrorSurface } from "../ui-tailwind/editor-surface/tw-prosemirror-surface";
+import {
+  createSearchExcerpt,
+  findSearchMatches,
+} from "../ui-tailwind/editor-surface/search-plugin";
+import {
+  TwProseMirrorSurface,
+  type TwProseMirrorSurfaceRef,
+} 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";
@@ -69,6 +99,15 @@ interface WordReviewEditorRuntime extends DocumentRuntime {
   dispose?(): void;
 }
 
+type PackageBackedDocxSession = ReturnType<typeof loadDocxEditorSession>;
+
+interface SnapshotExportBarrier {
+  reason:
+    | "missing_source_package_provenance"
+    | "invalid_source_package_provenance";
+  message: string;
+}
+
 const VISUALLY_HIDDEN_STYLES: React.CSSProperties = {
   position: "absolute",
   width: "1px",
@@ -92,6 +131,7 @@ type AccessibleRegionId = (typeof ACCESSIBLE_REGION_ORDER)[number];
 
 export function __createWordReviewEditorRefBridge(
   runtime: WordReviewEditorRuntime,
+  mountedSurface?: TwProseMirrorSurfaceRef | null,
 ): WordReviewEditorRef {
   return {
     focus: () => runtime.focus(),
@@ -114,6 +154,127 @@ export function __createWordReviewEditorRefBridge(
     getWarnings: () => runtime.getWarnings(),
     getComments: () => runtime.getRenderSnapshot().comments,
     getTrackedChanges: () => runtime.getRenderSnapshot().trackedChanges,
+    getFormattingState: () => getFormattingStateFromRenderSnapshot(runtime.getRenderSnapshot()),
+    toggleBold: () => {
+      applyRuntimeFormattingOperation(runtime, { type: "toggle", mark: "bold" });
+    },
+    toggleItalic: () => {
+      applyRuntimeFormattingOperation(runtime, { type: "toggle", mark: "italic" });
+    },
+    toggleUnderline: () => {
+      applyRuntimeFormattingOperation(runtime, { type: "toggle", mark: "underline" });
+    },
+    toggleStrikethrough: () => {
+      applyRuntimeFormattingOperation(runtime, {
+        type: "toggle",
+        mark: "strikethrough",
+      });
+    },
+    toggleSuperscript: () => {
+      applyRuntimeFormattingOperation(runtime, {
+        type: "toggle",
+        mark: "superscript",
+      });
+    },
+    toggleSubscript: () => {
+      applyRuntimeFormattingOperation(runtime, { type: "toggle", mark: "subscript" });
+    },
+    setFontFamily: (fontFamily) => {
+      applyRuntimeFormattingOperation(runtime, {
+        type: "set-font-family",
+        fontFamily,
+      });
+    },
+    setFontSize: (size) => {
+      applyRuntimeFormattingOperation(runtime, { type: "set-font-size", size });
+    },
+    setTextColor: (color) => {
+      applyRuntimeFormattingOperation(runtime, { type: "set-text-color", color });
+    },
+    setHighlightColor: (color) => {
+      applyRuntimeFormattingOperation(runtime, {
+        type: "set-highlight-color",
+        color,
+      });
+    },
+    setAlignment: (alignment) => {
+      applyRuntimeFormattingOperation(runtime, {
+        type: "set-alignment",
+        alignment,
+      });
+    },
+    indent: () => {
+      applyRuntimeFormattingOperation(runtime, { type: "indent" });
+    },
+    outdent: () => {
+      applyRuntimeFormattingOperation(runtime, { type: "outdent" });
+    },
+    insertPageBreak: () => {
+      applyRuntimeInsertPageBreak(runtime);
+    },
+    insertTable: (options) => {
+      applyRuntimeInsertTable(runtime, options);
+    },
+    insertImage: (options) => {
+      applyRuntimeInsertImage(runtime, options);
+    },
+    addRowBefore: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "add-row-before",
+      });
+    },
+    addRowAfter: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "add-row-after",
+      });
+    },
+    addColumnBefore: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "add-column-before",
+      });
+    },
+    addColumnAfter: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "add-column-after",
+      });
+    },
+    deleteRow: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "delete-row",
+      });
+    },
+    deleteColumn: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "delete-column",
+      });
+    },
+    deleteTable: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "delete-table",
+      });
+    },
+    mergeCells: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "merge-cells",
+      });
+    },
+    splitCell: () => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "split-cell",
+      });
+    },
+    setCellBackground: (color) => {
+      applyRuntimeTableStructureOperation(runtime, mountedSurface ?? null, {
+        type: "set-cell-background",
+        color,
+      });
+    },
+    search: (query, options) =>
+      mountedSurface?.search(query, options) ??
+      searchSnapshotSurface(runtime.getRenderSnapshot(), query, options),
+    clearSearch: () => {
+      mountedSurface?.clearSearch();
+    },
     scrollToRevision: (revisionId: string) => {
       const revision = runtime.getRenderSnapshot().trackedChanges.revisions.find(
         (r) => r.revisionId === revisionId,
@@ -227,6 +388,9 @@ function createRuntime(
         editorBuild: "dev",
       })
     : undefined;
+  const snapshotExportResolution = !args.source.initialDocx
+    ? resolveSnapshotExportSession(args)
+    : undefined;
   const initialSnapshot =
     args.source.initialSnapshot ??
     docxSession?.initialSnapshot ??
@@ -234,23 +398,36 @@ function createRuntime(
       args.documentId,
       args.source.sourceLabel ?? "Generated shell snapshot",
     );
+  const runtimeSnapshot = snapshotExportResolution?.barrier
+    ? applySnapshotExportBarrier(initialSnapshot, snapshotExportResolution.barrier)
+    : initialSnapshot;
 
   return createDocumentRuntime({
     documentId: args.documentId,
-    initialSnapshot,
+    initialSnapshot: runtimeSnapshot,
     sourceKind: args.source.source,
     sourceLabel: args.source.sourceLabel,
     readOnly: args.readOnly || docxSession?.readOnly,
-    editorBuild: initialSnapshot.editorBuild,
+    editorBuild: runtimeSnapshot.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`,
-          },
+    exportDocx: async (snapshot, options) => {
+      if (docxSession) {
+        return docxSession.exportDocx(snapshot, options);
+      }
+
+      if (snapshotExportResolution?.session) {
+        return snapshotExportResolution.session.exportDocx(snapshot, options);
+      }
+
+      throw createSnapshotExportBlockedError(
+        args.documentId,
+        snapshotExportResolution?.barrier ?? {
+          reason: "missing_source_package_provenance",
+          message:
+            "DOCX export is blocked because this snapshot does not carry embedded source package provenance.",
+        },
+      );
+    },
     onWarning: handlers.onWarning,
     onError: handlers.onError,
     defaultAuthorId: args.currentUserId,
@@ -285,6 +462,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     const [showTrackedChanges, setShowTrackedChanges] = useState(false);
     const [activeRevisionId, setActiveRevisionId] = useState<string | undefined>();
     const runtimeRef = useRef<WordReviewEditorRuntime | null>(null);
+    const surfaceRef = useRef<TwProseMirrorSurfaceRef | null>(null);
     const shellRef = useRef<HTMLDivElement | null>(null);
     const lastAnnouncedErrorIdRef = useRef<string | null>(null);
     const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -520,6 +698,146 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         getWarnings: () => activeRuntime.getWarnings(),
         getComments: () => activeRuntime.getRenderSnapshot().comments,
         getTrackedChanges: () => activeRuntime.getRenderSnapshot().trackedChanges,
+        getFormattingState: () =>
+          getFormattingStateFromRenderSnapshot(activeRuntime.getRenderSnapshot()),
+        toggleBold: () => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "toggle",
+            mark: "bold",
+          });
+        },
+        toggleItalic: () => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "toggle",
+            mark: "italic",
+          });
+        },
+        toggleUnderline: () => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "toggle",
+            mark: "underline",
+          });
+        },
+        toggleStrikethrough: () => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "toggle",
+            mark: "strikethrough",
+          });
+        },
+        toggleSuperscript: () => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "toggle",
+            mark: "superscript",
+          });
+        },
+        toggleSubscript: () => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "toggle",
+            mark: "subscript",
+          });
+        },
+        setFontFamily: (fontFamily) => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "set-font-family",
+            fontFamily,
+          });
+        },
+        setFontSize: (size) => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "set-font-size",
+            size,
+          });
+        },
+        setTextColor: (color) => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "set-text-color",
+            color,
+          });
+        },
+        setHighlightColor: (color) => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "set-highlight-color",
+            color,
+          });
+        },
+        setAlignment: (alignment) => {
+          applyRuntimeFormattingOperation(activeRuntime, {
+            type: "set-alignment",
+            alignment,
+          });
+        },
+        indent: () => {
+          applyRuntimeFormattingOperation(activeRuntime, { type: "indent" });
+        },
+        outdent: () => {
+          applyRuntimeFormattingOperation(activeRuntime, { type: "outdent" });
+        },
+        insertPageBreak: () => {
+          applyRuntimeInsertPageBreak(activeRuntime);
+        },
+        insertTable: (options) => {
+          applyRuntimeInsertTable(activeRuntime, options);
+        },
+        insertImage: (options) => {
+          applyRuntimeInsertImage(activeRuntime, options);
+        },
+        addRowBefore: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "add-row-before",
+          });
+        },
+        addRowAfter: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "add-row-after",
+          });
+        },
+        addColumnBefore: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "add-column-before",
+          });
+        },
+        addColumnAfter: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "add-column-after",
+          });
+        },
+        deleteRow: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "delete-row",
+          });
+        },
+        deleteColumn: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "delete-column",
+          });
+        },
+        deleteTable: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "delete-table",
+          });
+        },
+        mergeCells: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "merge-cells",
+          });
+        },
+        splitCell: () => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "split-cell",
+          });
+        },
+        setCellBackground: (color) => {
+          applyRuntimeTableStructureOperation(activeRuntime, surfaceRef.current, {
+            type: "set-cell-background",
+            color,
+          });
+        },
+        search: (query, options) =>
+          surfaceRef.current?.search(query, options) ??
+          searchSnapshotSurface(activeRuntime.getRenderSnapshot(), query, options),
+        clearSearch: () => {
+          surfaceRef.current?.clearSearch();
+        },
         scrollToRevision: (revisionId: string) => {
           const revision = activeRuntime.getRenderSnapshot().trackedChanges.revisions.find(
             (r) => r.revisionId === revisionId,
@@ -835,6 +1153,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           {...reviewCallbacks}
           document={
             <TwProseMirrorSurface
+              ref={surfaceRef}
               currentUser={currentUser}
               snapshot={snapshot}
               reviewMode={reviewMode}
@@ -858,6 +1177,231 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
   },
 );
 
+function applyRuntimeFormattingOperation(
+  runtime: WordReviewEditorRuntime,
+  operation:
+    | { type: "toggle"; mark: "bold" | "italic" | "underline" | "strikethrough" | "superscript" | "subscript" }
+    | { type: "set-font-family"; fontFamily: string | null }
+    | { type: "set-font-size"; size: number | null }
+    | { type: "set-text-color"; color: string | null }
+    | { type: "set-highlight-color"; color: string | null }
+    | { type: "set-alignment"; alignment: FormattingAlignment }
+    | { type: "indent" }
+    | { type: "outdent" },
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!snapshot.isReady || snapshot.readOnly || snapshot.fatalError) {
+    return;
+  }
+
+  const result = applyFormattingOperationToDocument(
+    runtime.getPersistedSnapshot().canonicalDocument,
+    snapshot,
+    operation,
+  );
+  if (!result.changed) {
+    return;
+  }
+
+  runtime.dispatch({
+    type: "document.replace",
+    document: result.document,
+    selection: toRuntimeSelectionSnapshot(result.selection),
+    origin: {
+      source: "api",
+      timestamp: new Date().toISOString(),
+    },
+  });
+}
+
+function applyRuntimeInsertPageBreak(runtime: WordReviewEditorRuntime): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot)) {
+    return;
+  }
+
+  const timestamp = new Date().toISOString();
+  const result = insertPageBreakInDocument(
+    runtime.getPersistedSnapshot().canonicalDocument,
+    toRuntimeSelectionSnapshot(snapshot.selection),
+    { timestamp },
+  );
+  dispatchRuntimeDocumentMutation(runtime, result, timestamp);
+}
+
+function applyRuntimeInsertTable(
+  runtime: WordReviewEditorRuntime,
+  options: InsertTableOptions,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot)) {
+    return;
+  }
+
+  const timestamp = new Date().toISOString();
+  const result = insertTableInDocument(
+    runtime.getPersistedSnapshot().canonicalDocument,
+    toRuntimeSelectionSnapshot(snapshot.selection),
+    options,
+    { timestamp },
+  );
+  dispatchRuntimeDocumentMutation(runtime, result, timestamp);
+}
+
+function applyRuntimeInsertImage(
+  runtime: WordReviewEditorRuntime,
+  options: InsertImageOptions,
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot)) {
+    return;
+  }
+
+  const timestamp = new Date().toISOString();
+  try {
+    const result = insertImageInDocument(
+      runtime.getPersistedSnapshot().canonicalDocument,
+      toRuntimeSelectionSnapshot(snapshot.selection),
+      options.data,
+      options.mimeType,
+      options.width,
+      options.height,
+      {
+        timestamp,
+        altText: options.altText,
+      },
+    );
+    dispatchRuntimeDocumentMutation(runtime, {
+      changed: true,
+      document: result.document,
+      selection: result.selection,
+      mapping: result.mapping,
+    }, timestamp);
+  } catch {
+    return;
+  }
+}
+
+function applyRuntimeTableStructureOperation(
+  runtime: WordReviewEditorRuntime,
+  mountedSurface: TwProseMirrorSurfaceRef | null | undefined,
+  operation:
+    | { type: "add-row-before" }
+    | { type: "add-row-after" }
+    | { type: "add-column-before" }
+    | { type: "add-column-after" }
+    | { type: "delete-row" }
+    | { type: "delete-column" }
+    | { type: "delete-table" }
+    | { type: "merge-cells" }
+    | { type: "split-cell" }
+    | { type: "set-cell-background"; color: string },
+): void {
+  const snapshot = runtime.getRenderSnapshot();
+  if (!canApplyRuntimeMutation(snapshot)) {
+    return;
+  }
+
+  const timestamp = new Date().toISOString();
+  const result = applyTableStructureOperation(
+    runtime.getPersistedSnapshot().canonicalDocument,
+    snapshot,
+    mountedSurface?.getTableSelection() ?? null,
+    operation,
+  );
+  dispatchRuntimeDocumentMutation(runtime, result, timestamp);
+}
+
+function canApplyRuntimeMutation(snapshot: RuntimeRenderSnapshot): boolean {
+  return snapshot.isReady && !snapshot.readOnly && !snapshot.fatalError;
+}
+
+function dispatchRuntimeDocumentMutation(
+  runtime: WordReviewEditorRuntime,
+  result: {
+    changed: boolean;
+    document: PersistedEditorSnapshot["canonicalDocument"];
+    selection: InternalSelectionSnapshot;
+    mapping?: TransactionMapping;
+  },
+  timestamp: string,
+): void {
+  if (!result.changed) {
+    return;
+  }
+
+  runtime.dispatch({
+    type: "document.replace",
+    document: {
+      ...result.document,
+      updatedAt: timestamp,
+    },
+    mapping: result.mapping,
+    selection: result.selection,
+    origin: {
+      source: "api",
+      timestamp,
+    },
+  });
+}
+
+function searchSnapshotSurface(
+  snapshot: RuntimeRenderSnapshot,
+  query: string,
+  options: SearchOptions = {},
+): SearchResultSnapshot[] {
+  const normalizedQuery = query.trim();
+  if (!normalizedQuery || !snapshot.surface) {
+    return [];
+  }
+
+  const rawResults = findSearchMatches(
+    snapshot.surface.plainText,
+    normalizedQuery,
+    options,
+  ).slice(0, options.limit ?? Number.POSITIVE_INFINITY);
+  const activeResultIndex = getActiveSearchResultIndex(rawResults, snapshot.selection);
+
+  return rawResults.map((result, index) => ({
+    resultId: `search-result-${index}`,
+    anchor: {
+      kind: "range",
+      from: result.from,
+      to: result.to,
+      assoc: {
+        start: -1,
+        end: 1,
+      },
+    },
+    excerpt: createSearchExcerpt(
+      snapshot.surface?.plainText ?? "",
+      result.from,
+      result.to,
+    ),
+    isActive: index === activeResultIndex,
+  }));
+}
+
+function getActiveSearchResultIndex(
+  results: Array<{ from: number; to: number }>,
+  selection: PublicSelectionSnapshot,
+): number {
+  if (results.length === 0) {
+    return -1;
+  }
+
+  const selectionFrom = Math.min(selection.anchor, selection.head);
+  const selectionTo = Math.max(selection.anchor, selection.head);
+  const activeIndex = results.findIndex((result) => {
+    if (selectionFrom === selectionTo) {
+      return selectionFrom >= result.from && selectionFrom <= result.to;
+    }
+    return selectionFrom < result.to && selectionTo > result.from;
+  });
+
+  return activeIndex >= 0 ? activeIndex : 0;
+}
+
 function applyRegionAttributes(shell: HTMLElement): void {
   const toolbar = shell.querySelector<HTMLElement>("header");
   if (toolbar) {
@@ -1006,6 +1550,7 @@ function guessSourceLabel(
   return (
     externalDocSource?.sourceLabel ??
     initialSourceLabel ??
+    initialSnapshot?.sourcePackage?.sourceLabel ??
     initialSnapshot?.editorBuild ??
     undefined
   );
@@ -1106,7 +1651,23 @@ async function persistAndExport(input: {
     lastSavedRevisionTokenRef: input.lastSavedRevisionTokenRef,
   });
 
-  const result = await input.runtime.exportDocx(input.options);
+  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({
+      datastore: input.datastore,
+      onEvent: input.onEvent,
+      event: {
+        type: "error",
+        documentId: input.documentId,
+        error: normalized,
+      },
+    });
+    throw normalized;
+  }
 
   if (!input.datastore) {
     return result;
@@ -1397,7 +1958,7 @@ function createFallbackPersistedSnapshot(
 ): PersistedEditorSnapshot {
   const docId = createCanonicalDocumentId(documentId);
   return {
-    snapshotVersion: "persisted-editor-snapshot/1",
+    snapshotVersion: "persisted-editor-snapshot/2",
     schemaVersion: "cds/1.0.0",
     documentId,
     docId,
@@ -1458,6 +2019,137 @@ function emptyCompatibilityReport(): CompatibilityReport {
   };
 }
 
+function resolveSnapshotExportSession(args: CreateRuntimeArgs): {
+  session?: PackageBackedDocxSession;
+  barrier?: SnapshotExportBarrier;
+} {
+  const sourcePackage = args.source.initialSnapshot?.sourcePackage;
+  if (!sourcePackage) {
+    return {
+      barrier: {
+        reason: "missing_source_package_provenance",
+        message:
+          "DOCX export is blocked because this snapshot 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.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 applySnapshotExportBarrier(
+  snapshot: PersistedEditorSnapshot,
+  barrier: SnapshotExportBarrier,
+): PersistedEditorSnapshot {
+  const featureEntryId = `feature:source-package-provenance:${barrier.reason}`;
+  const featureEntries = snapshot.compatibility.featureEntries.some(
+    (entry) => entry.featureEntryId === featureEntryId,
+  )
+    ? snapshot.compatibility.featureEntries
+    : [
+        ...snapshot.compatibility.featureEntries,
+        {
+          featureEntryId,
+          featureKey: "source-package-provenance",
+          featureClass: "unsupported-fatal" as const,
+          message: barrier.message,
+          details: {
+            reason: barrier.reason,
+          },
+        },
+      ];
+
+  return {
+    ...snapshot,
+    compatibility: {
+      ...snapshot.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 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 toRuntimeSelectionSnapshot(selection: PublicSelectionSnapshot) {
   return {
     anchor: selection.anchor,