@beyondwork/docx-react-component 1.0.1 → 1.0.2

package/src/io/docx-session.ts

@@ -0,0 +1,1763 @@
+import type {
+  CompatibilityReport as PublicCompatibilityReport,
+  EditorError,
+  EditorWarning as PublicEditorWarning,
+  EditorAnchorProjection as PublicEditorAnchorProjection,
+  ExportDocxOptions,
+  ExportResult,
+  PersistedEditorSnapshot,
+} from "../api/public-types.ts";
+import type {
+  CanonicalDocumentEnvelope,
+  CompatibilityFeatureEntry as InternalCompatibilityFeatureEntry,
+  CompatibilityReport as InternalCompatibilityReport,
+  CommentThreadRecord,
+  EditorError as InternalEditorError,
+  RevisionRecord as RuntimeRevisionRecord,
+  EditorWarning as InternalEditorWarning,
+} from "../core/state/editor-state.ts";
+import { createCanonicalDocumentId } from "../core/state/editor-state.ts";
+import {
+  createDetachedAnchor,
+  type EditorAnchorProjection as InternalEditorAnchorProjection,
+} from "../core/selection/mapping.ts";
+import { DOCX_MIME_TYPE } from "./opc/docx-package.ts";
+import { readOpcPackage, type OpcPackage } from "./opc/package-reader.ts";
+import { parseMainDocumentXml } from "./ooxml/parse-main-document.ts";
+import { normalizeParsedTextDocument } from "./normalize/normalize-text.ts";
+import {
+  normalizePartPath,
+  resolveRelationshipTarget,
+  type OpcRelationship,
+} from "./ooxml/part-manifest.ts";
+import {
+  classifyCorruptPackageError,
+  createBrokenRelationshipIssue,
+  createMissingPartIssue,
+} from "./opc/corrupt-package.ts";
+import { createExportSession } from "./export/export-session.ts";
+import { serializeMainDocument } from "./export/serialize-main-document.ts";
+import { parseRevisionsFromDocumentXml, type ParsedRevisionsResult } from "./ooxml/parse-revisions.ts";
+import { parseCommentsFromOoxml } from "./ooxml/parse-comments.ts";
+import { parseNumberingXml } from "./ooxml/parse-numbering.ts";
+import {
+  createCommentExportIdMap,
+  serializeCommentAnchorsIntoDocumentXml,
+  serializeMergedCommentsXml,
+} from "./export/serialize-comments.ts";
+import { splitDocumentAtReviewBoundaries } from "./export/split-review-boundaries.ts";
+import { serializeRuntimeRevisionsIntoDocumentXml } from "./export/serialize-runtime-revisions.ts";
+import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
+import type { CommentThread } from "../review/store/comment-store.ts";
+import type { RevisionRecord as ReviewRevisionRecord } from "../review/store/revision-types.ts";
+import { getRevisionActionability } from "../review/store/revision-types.ts";
+import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
+import {
+  createPackageImportDiagnostics,
+  createValidationImportDiagnostics,
+  type ImportDiagnosticsResult,
+} from "../validation/import-diagnostics.ts";
+import type {
+  FootnoteCollection,
+  HeaderDocument,
+  FooterDocument,
+  MediaCatalog,
+  NumberingCatalog,
+  OpaqueFragmentRecord,
+  PreservedPackagePart,
+  SubPartsCatalog,
+} from "../model/canonical-document.ts";
+import { createCanonicalDocumentSignature } from "../model/canonical-document.ts";
+import type {
+  CommentImportDiagnostic,
+  ImportedCommentDefinition,
+  ParsedCommentsResult,
+} from "./ooxml/parse-comments.ts";
+import { createReadOnlyDiagnosticsRuntime } from "../runtime/read-only-diagnostics-runtime.ts";
+import {
+  WORD_NUMBERING_CONTENT_TYPE,
+  serializeNumberingXml,
+} from "./export/serialize-numbering.ts";
+import {
+  parseHeaderFooterReferences,
+  parseHeaderXml,
+  parseFooterXml,
+} from "./ooxml/parse-headers-footers.ts";
+import { parseFootnotesXml, parseEndnotesXml } from "./ooxml/parse-footnotes.ts";
+import { parseThemeXml } from "./ooxml/parse-theme.ts";
+import {
+  serializeHeaderXml,
+  serializeFooterXml,
+  WORD_HEADER_CONTENT_TYPE,
+  WORD_FOOTER_CONTENT_TYPE,
+} from "./export/serialize-headers-footers.ts";
+import {
+  serializeFootnotesXml,
+  serializeEndnotesXml,
+  WORD_FOOTNOTES_CONTENT_TYPE,
+  WORD_ENDNOTES_CONTENT_TYPE,
+} from "./export/serialize-footnotes.ts";
+
+const MAIN_DOCUMENT_PATH = "/word/document.xml";
+const NUMBERING_PART_PATH = "/word/numbering.xml";
+const COMMENTS_PART_PATH = "/word/comments.xml";
+const COMMENTS_EXTENDED_PART_PATH = "/word/commentsExtended.xml";
+const COMMENTS_IDS_PART_PATH = "/word/commentsIds.xml";
+const PEOPLE_PART_PATH = "/word/people.xml";
+const MAIN_DOCUMENT_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml";
+const NUMBERING_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+const COMMENTS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
+const COMMENTS_EXTENDED_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
+const COMMENTS_IDS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
+const PEOPLE_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml";
+const COMMENTS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+const COMMENTS_EXTENDED_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
+const COMMENTS_IDS_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2016/09/relationships/commentsIds";
+const PEOPLE_RELATIONSHIP_TYPE =
+  "http://schemas.microsoft.com/office/2011/relationships/people";
+const HEADER_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
+const FOOTER_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+const FOOTNOTES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
+const ENDNOTES_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
+const FOOTNOTES_PART_PATH = "/word/footnotes.xml";
+const ENDNOTES_PART_PATH = "/word/endnotes.xml";
+
+interface LoadDocxEditorSessionOptions {
+  documentId: string;
+  sourceLabel?: string;
+  bytes: Uint8Array | ArrayBuffer;
+  editorBuild: string;
+}
+
+export interface LoadedDocxEditorSession {
+  initialSnapshot: PersistedEditorSnapshot;
+  fatalError?: EditorError;
+  readOnly: boolean;
+  exportDocx: (
+    snapshot: PersistedEditorSnapshot,
+    options?: ExportDocxOptions,
+  ) => Promise<ExportResult>;
+}
+
+interface ImportedDocxState {
+  sourceBytes: Uint8Array;
+  sourcePackage: OpcPackage;
+  sourceDocumentRelationships: readonly OpcRelationship[];
+  sourceDocumentAttributes: Record<string, string>;
+  sourceNumberingPartPath?: string;
+  sourceNumberingRelationshipId?: string;
+  sourceCommentsPartPath?: string;
+  sourceCommentsRelationshipId?: string;
+  sourceCommentsRootTag?: string;
+  sourceCommentsExtendedPartPath?: string;
+  sourceCommentsExtendedRelationshipId?: string;
+  sourceCommentsExtendedRootTag?: string;
+  sourceCommentsIdsPartPath?: string;
+  sourceCommentsIdsRelationshipId?: string;
+  sourceCommentsIdsRootTag?: string;
+  sourcePeoplePartPath?: string;
+  sourcePeopleRelationshipId?: string;
+  sourcePeopleRootTag?: string;
+  sourcePeopleAuthors: readonly string[];
+  preservedCommentDefinitions: readonly ImportedCommentDefinition[];
+  blockingCommentDiagnostics: readonly CommentImportDiagnostic[];
+  initialCanonicalSignature: string;
+  sourceSubPartPaths: {
+    headers: Array<{ partPath: string; relationshipId: string }>;
+    footers: Array<{ partPath: string; relationshipId: string }>;
+    footnotesPartPath?: string;
+    footnotesRelationshipId?: string;
+    endnotesPartPath?: string;
+    endnotesRelationshipId?: string;
+    themePartPath?: string;
+    themeRelationshipId?: string;
+  };
+}
+
+interface NormalizedImportedCommentsResult extends ParsedCommentsResult {
+  preservedDefinitions: readonly ImportedCommentDefinition[];
+}
+
+const BLOCKING_COMMENT_DIAGNOSTIC_CODES = new Set<CommentImportDiagnostic["code"]>([
+  "missing_comment_definition",
+  "missing_anchor_reference",
+  "multi_paragraph_anchor_preserve_only",
+  "opaque_anchor_preserve_only",
+  "preserve_only_revision_overlap",
+]);
+
+export function loadDocxEditorSession(
+  options: LoadDocxEditorSessionOptions,
+): LoadedDocxEditorSession {
+  const sourceBytes = toUint8Array(options.bytes);
+  let sourcePackage: OpcPackage;
+
+  try {
+    sourcePackage = readOpcPackage(sourceBytes);
+  } catch (error) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: classifyCorruptPackageError(error),
+      }),
+    );
+  }
+
+  const brokenRelationshipIssues = collectBrokenInternalRelationshipIssues(sourcePackage);
+  if (brokenRelationshipIssues.length > 0) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: {
+          ...brokenRelationshipIssues[0],
+          message: summarizeBrokenRelationshipIssues(brokenRelationshipIssues),
+          details: {
+            issueCount: brokenRelationshipIssues.length,
+            targets: brokenRelationshipIssues.map((issue) => issue.targetPartPath).filter(Boolean),
+          },
+        },
+      }),
+    );
+  }
+
+  const documentPart = sourcePackage.parts.get(MAIN_DOCUMENT_PATH);
+  if (!documentPart) {
+    return createDiagnosticsSession(
+      options,
+      createPackageImportDiagnostics({
+        issue: createMissingPartIssue(MAIN_DOCUMENT_PATH),
+      }),
+    );
+  }
+
+  try {
+    const sourceDocumentXml = decodeUtf8(documentPart.bytes);
+    const importedRevisions = parseRevisionsFromDocumentXml(sourceDocumentXml);
+    const numberingPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      documentPart.relationships,
+      NUMBERING_RELATIONSHIP_TYPE,
+      NUMBERING_PART_PATH,
+    );
+    const parsedNumbering = numberingPartPath
+      ? parseNumberingXml(
+          decodeUtf8(sourcePackage.parts.get(numberingPartPath)?.bytes ?? new Uint8Array()),
+        )
+      : createEmptyNumberingCatalog();
+    const mediaParts = collectInlineMediaParts(sourcePackage);
+    const parsedDocument = parseMainDocumentXml(
+      sourceDocumentXml,
+      documentPart.relationships,
+      mediaParts,
+      MAIN_DOCUMENT_PATH,
+    );
+    const normalizedDocument = normalizeParsedTextDocument(
+      parsedDocument,
+      MAIN_DOCUMENT_PATH,
+    );
+    const commentsPartPath = resolveCommentsPartPath(sourcePackage, documentPart.relationships);
+    const commentsExtendedPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      documentPart.relationships,
+      COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
+      COMMENTS_EXTENDED_PART_PATH,
+    );
+    const commentsIdsPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      documentPart.relationships,
+      COMMENTS_IDS_RELATIONSHIP_TYPE,
+      COMMENTS_IDS_PART_PATH,
+    );
+    const peoplePartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      documentPart.relationships,
+      PEOPLE_RELATIONSHIP_TYPE,
+      PEOPLE_PART_PATH,
+    );
+    const parsedComments = commentsPartPath
+      ? parseCommentsFromOoxml(
+          sourceDocumentXml,
+          {
+            commentsXml: decodeUtf8(sourcePackage.parts.get(commentsPartPath)?.bytes ?? new Uint8Array()),
+            commentsExtendedXml: decodeUtf8(
+              sourcePackage.parts.get(commentsExtendedPartPath ?? "")?.bytes ?? new Uint8Array(),
+            ),
+            commentsIdsXml: decodeUtf8(
+              sourcePackage.parts.get(commentsIdsPartPath ?? "")?.bytes ?? new Uint8Array(),
+            ),
+            peopleXml: decodeUtf8(
+              sourcePackage.parts.get(peoplePartPath ?? "")?.bytes ?? new Uint8Array(),
+            ),
+          },
+        )
+      : {
+          threads: [] as CommentThread[],
+          diagnostics: [] as CommentImportDiagnostic[],
+          definitions: [] as ImportedCommentDefinition[],
+          sourceRootTag: undefined,
+          sourceExtendedRootTag: undefined,
+          sourceIdsRootTag: undefined,
+          sourcePeopleRootTag: undefined,
+          peopleAuthors: [] as string[],
+        };
+    const normalizedRevisions = normalizeImportedRevisionRecords(
+      importedRevisions,
+      normalizedDocument.content,
+      normalizedDocument.preservation.opaqueFragments,
+    );
+    const normalizedComments = normalizeImportedCommentThreads(
+      parsedComments,
+      normalizedDocument.preservation.opaqueFragments,
+      normalizedRevisions.revisions,
+    );
+    // ---- Parse sub-parts: headers, footers, footnotes, endnotes, theme ----
+    const headerFooterRefs = parseHeaderFooterReferences(sourceDocumentXml);
+    const parsedHeaders: HeaderDocument[] = [];
+    const parsedFooters: FooterDocument[] = [];
+    const sourceHeaderPaths: Array<{ partPath: string; relationshipId: string }> = [];
+    const sourceFooterPaths: Array<{ partPath: string; relationshipId: string }> = [];
+    const seenSubPartRelIds = new Set<string>();
+
+    for (const ref of headerFooterRefs) {
+      if (seenSubPartRelIds.has(ref.relationshipId)) {
+        continue;
+      }
+      seenSubPartRelIds.add(ref.relationshipId);
+
+      const relationship = documentPart.relationships.find(
+        (r) => r.id === ref.relationshipId && r.targetMode === "internal",
+      );
+      if (!relationship) {
+        continue;
+      }
+
+      const partPath = resolveRelationshipTarget(MAIN_DOCUMENT_PATH, relationship);
+      const partBytes = sourcePackage.parts.get(partPath)?.bytes;
+      if (!partBytes) {
+        continue;
+      }
+
+      const xml = decodeUtf8(partBytes);
+      if (ref.kind === "header") {
+        const parsed = parseHeaderXml(xml);
+        parsedHeaders.push({
+          variant: ref.variant,
+          partPath,
+          relationshipId: ref.relationshipId,
+          blocks: parsed.blocks,
+        });
+        sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
+      } else {
+        const parsed = parseFooterXml(xml);
+        parsedFooters.push({
+          variant: ref.variant,
+          partPath,
+          relationshipId: ref.relationshipId,
+          blocks: parsed.blocks,
+        });
+        sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
+      }
+    }
+
+    const footnotesPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      documentPart.relationships,
+      FOOTNOTES_RELATIONSHIP_TYPE,
+      FOOTNOTES_PART_PATH,
+    );
+    const footnotesRelationshipId = documentPart.relationships.find(
+      (r) => r.type === FOOTNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
+    )?.id;
+    const endnotesPartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      documentPart.relationships,
+      ENDNOTES_RELATIONSHIP_TYPE,
+      ENDNOTES_PART_PATH,
+    );
+    const endnotesRelationshipId = documentPart.relationships.find(
+      (r) => r.type === ENDNOTES_RELATIONSHIP_TYPE && r.targetMode === "internal",
+    )?.id;
+
+    let footnoteCollection: FootnoteCollection | undefined;
+    if (footnotesPartPath) {
+      footnoteCollection = parseFootnotesXml(
+        decodeUtf8(sourcePackage.parts.get(footnotesPartPath)?.bytes ?? new Uint8Array()),
+      );
+    }
+    if (endnotesPartPath) {
+      footnoteCollection = parseEndnotesXml(
+        decodeUtf8(sourcePackage.parts.get(endnotesPartPath)?.bytes ?? new Uint8Array()),
+        footnoteCollection,
+      );
+    }
+
+    const themeRelationship = documentPart.relationships.find(
+      (r) => r.type === "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" &&
+        r.targetMode === "internal",
+    );
+    const themePartPath = themeRelationship
+      ? resolveRelationshipTarget(MAIN_DOCUMENT_PATH, themeRelationship)
+      : undefined;
+    const parsedTheme =
+      themePartPath && sourcePackage.parts.has(themePartPath)
+        ? parseThemeXml(
+            decodeUtf8(sourcePackage.parts.get(themePartPath)?.bytes ?? new Uint8Array()),
+          )
+        : undefined;
+
+    const subParts: SubPartsCatalog | undefined =
+      parsedHeaders.length > 0 ||
+      parsedFooters.length > 0 ||
+      footnoteCollection !== undefined ||
+      parsedTheme !== undefined
+        ? {
+            headers: parsedHeaders,
+            footers: parsedFooters,
+            ...(footnoteCollection !== undefined ? { footnoteCollection } : {}),
+            ...(parsedTheme !== undefined ? { theme: parsedTheme } : {}),
+          }
+        : undefined;
+
+    const timestamp = new Date().toISOString();
+    const document = createImportedCanonicalDocument({
+      documentId: options.documentId,
+      timestamp,
+      numbering: parsedNumbering,
+      media: normalizedDocument.media,
+      content: normalizedDocument.content,
+      subParts,
+      preservation: {
+        ...normalizedDocument.preservation,
+        packageParts: {
+          ...normalizedDocument.preservation.packageParts,
+          ...collectPreservedPackageParts(sourcePackage, [
+            numberingPartPath,
+            commentsPartPath,
+            commentsExtendedPartPath,
+            commentsIdsPartPath,
+            peoplePartPath,
+          ]),
+        },
+      },
+      diagnostics: {
+        warnings: [
+          ...normalizedDocument.diagnostics.warnings,
+          ...normalizedRevisions.diagnostics.map((diagnostic, index) => ({
+            diagnosticId: `diagnostic:revision-import-${index + 1}`,
+            warningId: `warning:revision-import-${diagnostic.revisionId}`,
+            source: "review" as const,
+            message: diagnostic.message,
+          })),
+          ...normalizedComments.diagnostics.map((diagnostic, index) => ({
+            diagnosticId: `diagnostic:comment-import-${index + 1}`,
+            warningId: `warning:comment-import-${diagnostic.commentId}`,
+            source: "review" as const,
+            message: diagnostic.message,
+          })),
+        ],
+        errors: [],
+      },
+      review: {
+        comments: toRuntimeCommentRecords(normalizedComments.threads),
+        revisions: toRuntimeRevisionRecords(normalizedRevisions.revisions),
+      },
+    });
+    const compatibility = buildCompatibilityReport({
+      document,
+      generatedAt: timestamp,
+    });
+    const snapshot = createImportedSnapshot({
+      documentId: options.documentId,
+      editorBuild: options.editorBuild,
+      timestamp,
+      document,
+      compatibility: toPublicCompatibilityReport(compatibility),
+    });
+    const importedState: ImportedDocxState = {
+      sourceBytes: new Uint8Array(sourceBytes),
+      sourcePackage,
+      sourceDocumentRelationships: documentPart.relationships,
+      sourceDocumentAttributes: extractDocumentRootAttributes(sourceDocumentXml),
+      sourceNumberingPartPath: numberingPartPath,
+      sourceNumberingRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === NUMBERING_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsPartPath: commentsPartPath,
+      sourceCommentsRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === COMMENTS_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsRootTag: normalizedComments.sourceRootTag,
+      sourceCommentsExtendedPartPath: commentsExtendedPartPath,
+      sourceCommentsExtendedRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === COMMENTS_EXTENDED_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsExtendedRootTag: normalizedComments.sourceExtendedRootTag,
+      sourceCommentsIdsPartPath: commentsIdsPartPath,
+      sourceCommentsIdsRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === COMMENTS_IDS_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourceCommentsIdsRootTag: normalizedComments.sourceIdsRootTag,
+      sourcePeoplePartPath: peoplePartPath,
+      sourcePeopleRelationshipId: documentPart.relationships.find(
+        (relationship) =>
+          relationship.type === PEOPLE_RELATIONSHIP_TYPE &&
+          relationship.targetMode === "internal",
+      )?.id,
+      sourcePeopleRootTag: normalizedComments.sourcePeopleRootTag,
+      sourcePeopleAuthors: normalizedComments.peopleAuthors,
+      preservedCommentDefinitions: normalizedComments.preservedDefinitions,
+      blockingCommentDiagnostics: normalizedComments.diagnostics.filter((diagnostic) =>
+        BLOCKING_COMMENT_DIAGNOSTIC_CODES.has(diagnostic.code),
+      ),
+      initialCanonicalSignature: serializeCanonicalDocumentForExport(document),
+      sourceSubPartPaths: {
+        headers: sourceHeaderPaths,
+        footers: sourceFooterPaths,
+        footnotesPartPath,
+        footnotesRelationshipId,
+        endnotesPartPath,
+        endnotesRelationshipId,
+        themePartPath,
+        themeRelationshipId: themeRelationship?.id,
+      },
+    };
+
+    return {
+      initialSnapshot: snapshot,
+      readOnly: false,
+      exportDocx: async (nextSnapshot, exportOptions) =>
+        exportDocxEditorSession(importedState, nextSnapshot, exportOptions),
+    };
+  } catch (error) {
+    return createDiagnosticsSession(
+      options,
+      createImportDiagnosticsFromError(error),
+    );
+  }
+}
+
+function exportDocxEditorSession(
+  state: ImportedDocxState,
+  snapshot: PersistedEditorSnapshot,
+  options?: ExportDocxOptions,
+): ExportResult {
+  if (snapshot.compatibility.blockExport) {
+    throw new Error("DOCX export is blocked by the current compatibility report.");
+  }
+
+  const currentDocument = snapshot.canonicalDocument as CanonicalDocumentEnvelope;
+  if (
+    serializeCanonicalDocumentForExport(currentDocument) ===
+      state.initialCanonicalSignature &&
+    canReuseSourceBytesForCurrentDocument(state, currentDocument)
+  ) {
+    return {
+      bytes: new Uint8Array(state.sourceBytes),
+      mimeType: DOCX_MIME_TYPE,
+      fileName: options?.fileName ?? `${snapshot.documentId}.docx`,
+    };
+  }
+  if (state.blockingCommentDiagnostics.length > 0) {
+    throw new Error(
+      `DOCX export is blocked because ${state.blockingCommentDiagnostics.length} preserve-only comment anchors cannot be safely remapped after runtime edits.`,
+    );
+  }
+  const currentRevisions = toReviewRevisionRecords(currentDocument.review.revisions);
+  const actionableRevisions = currentRevisions.filter(
+    (revision) => getRevisionActionability(revision) === "actionable",
+  );
+  const commentThreads = Object.values(
+    createCommentStoreFromRuntimeComments(currentDocument.review.comments).threads,
+  );
+  const preservedCommentIds = new Set(
+    state.preservedCommentDefinitions.map((definition) => definition.commentId),
+  );
+  const ownedCommentThreads = commentThreads.filter(
+    (thread) => !preservedCommentIds.has(thread.commentId),
+  );
+  const serialized = serializeMainDocument(
+    splitDocumentAtReviewBoundaries(
+      currentDocument.content as never,
+      ownedCommentThreads,
+      actionableRevisions,
+    ) as never,
+    currentDocument.preservation as never,
+    state.sourceDocumentRelationships,
+    {
+      documentAttributes: state.sourceDocumentAttributes,
+      media: currentDocument.media as MediaCatalog,
+    },
+  );
+  const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
+    serialized.documentXml,
+    actionableRevisions,
+    serialized.paragraphBoundaries,
+  );
+  if (revisionDocument.skippedRevisionIds.length > 0) {
+    throw new Error(
+      `DOCX export is blocked because ${revisionDocument.skippedRevisionIds.length} active revisions overlap unsupported serialization boundaries.`,
+    );
+  }
+
+  const strippedDocumentXml = stripCommentMarkup(
+    revisionDocument.documentXml,
+    ownedCommentThreads.map((thread) => thread.commentId),
+  );
+  const exportCommentIds = createCommentExportIdMap(
+    ownedCommentThreads,
+    state.preservedCommentDefinitions,
+  );
+  const serializedComments = serializeMergedCommentsXml(ownedCommentThreads, {
+    exportCommentIds,
+    preservedDefinitions: state.preservedCommentDefinitions,
+    sourceRootTag: state.sourceCommentsRootTag,
+    sourceExtendedRootTag: state.sourceCommentsExtendedRootTag,
+    sourceIdsRootTag: state.sourceCommentsIdsRootTag,
+    sourcePeopleRootTag: state.sourcePeopleRootTag,
+    peopleAuthors: state.sourcePeopleAuthors,
+  });
+  const annotatedDocument = serializeCommentAnchorsIntoDocumentXml(
+    strippedDocumentXml,
+    ownedCommentThreads,
+    undefined,
+    {
+      exportCommentIds,
+    },
+  );
+  const blockingSkippedCommentIds = annotatedDocument.skippedCommentIds.filter((commentId) => {
+    const thread = ownedCommentThreads.find((candidate) => candidate.commentId === commentId);
+    return !thread || thread.anchor.kind !== "detached";
+  });
+  if (blockingSkippedCommentIds.length > 0) {
+    throw new Error(
+      `DOCX export is blocked because ${blockingSkippedCommentIds.length} comments no longer map to serializable ranges.`,
+    );
+  }
+  const commentsPartPath =
+    state.sourceCommentsPartPath ?? COMMENTS_PART_PATH;
+  const commentsExtendedPartPath =
+    state.sourceCommentsExtendedPartPath ?? COMMENTS_EXTENDED_PART_PATH;
+  const commentsIdsPartPath =
+    state.sourceCommentsIdsPartPath ?? COMMENTS_IDS_PART_PATH;
+  const peoplePartPath =
+    state.sourcePeoplePartPath ?? PEOPLE_PART_PATH;
+  const numberingPartPath =
+    state.sourceNumberingPartPath ?? NUMBERING_PART_PATH;
+  const serializedNumberingXml = hasNumberingEntries(currentDocument.numbering as NumberingCatalog)
+    ? serializeNumberingXml(currentDocument.numbering as NumberingCatalog)
+    : undefined;
+  const nextRelationships = withDocumentRelatedParts(
+    serialized.relationships,
+    [
+      {
+        relationshipType: NUMBERING_RELATIONSHIP_TYPE,
+        partPath: numberingPartPath,
+        existingRelationshipId: state.sourceNumberingRelationshipId,
+        include:
+          Boolean(serializedNumberingXml) ||
+          Boolean(state.sourceNumberingPartPath),
+      },
+      {
+        relationshipType: COMMENTS_RELATIONSHIP_TYPE,
+        partPath: commentsPartPath,
+        existingRelationshipId: state.sourceCommentsRelationshipId,
+        include:
+          serializedComments.serializedCommentIds.length > 0 ||
+          Boolean(state.sourceCommentsPartPath),
+      },
+      {
+        relationshipType: COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
+        partPath: commentsExtendedPartPath,
+        existingRelationshipId: state.sourceCommentsExtendedRelationshipId,
+        include:
+          Boolean(serializedComments.commentsExtendedXml) ||
+          Boolean(state.sourceCommentsExtendedPartPath),
+      },
+      {
+        relationshipType: COMMENTS_IDS_RELATIONSHIP_TYPE,
+        partPath: commentsIdsPartPath,
+        existingRelationshipId: state.sourceCommentsIdsRelationshipId,
+        include:
+          Boolean(serializedComments.commentsIdsXml) ||
+          Boolean(state.sourceCommentsIdsPartPath),
+      },
+      {
+        relationshipType: PEOPLE_RELATIONSHIP_TYPE,
+        partPath: peoplePartPath,
+        existingRelationshipId: state.sourcePeopleRelationshipId,
+        include:
+          Boolean(serializedComments.peopleXml) ||
+          Boolean(state.sourcePeoplePartPath),
+      },
+    ],
+  );
+
+  const exportedSubParts = currentDocument.subParts as SubPartsCatalog | undefined;
+  const subPartOwnedPaths: string[] = [];
+  if (exportedSubParts) {
+    for (const header of exportedSubParts.headers) {
+      subPartOwnedPaths.push(header.partPath);
+    }
+    for (const footer of exportedSubParts.footers) {
+      subPartOwnedPaths.push(footer.partPath);
+    }
+    if (exportedSubParts.footnoteCollection) {
+      if (state.sourceSubPartPaths.footnotesPartPath) {
+        subPartOwnedPaths.push(state.sourceSubPartPaths.footnotesPartPath);
+      }
+      if (state.sourceSubPartPaths.endnotesPartPath) {
+        subPartOwnedPaths.push(state.sourceSubPartPaths.endnotesPartPath);
+      }
+    }
+    if (exportedSubParts.theme && state.sourceSubPartPaths.themePartPath) {
+      subPartOwnedPaths.push(state.sourceSubPartPaths.themePartPath);
+    }
+  }
+
+  const exportSession = createExportSession(state.sourcePackage, [
+    MAIN_DOCUMENT_PATH,
+    numberingPartPath,
+    commentsPartPath,
+    commentsExtendedPartPath,
+    commentsIdsPartPath,
+    peoplePartPath,
+    ...subPartOwnedPaths,
+  ]);
+
+  exportSession.replaceOwnedPart({
+    path: MAIN_DOCUMENT_PATH,
+    bytes: new TextEncoder().encode(annotatedDocument.documentXml),
+    contentType: MAIN_DOCUMENT_CONTENT_TYPE,
+    relationships: nextRelationships,
+  });
+
+  if (serializedNumberingXml || state.sourceNumberingPartPath) {
+    exportSession.replaceOwnedPart({
+      path: numberingPartPath,
+      bytes: new TextEncoder().encode(
+        serializedNumberingXml ??
+          `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"></w:numbering>`,
+      ),
+      contentType:
+        state.sourcePackage.parts.get(numberingPartPath)?.contentType ??
+        WORD_NUMBERING_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.serializedCommentIds.length > 0 || state.sourceCommentsPartPath) {
+    exportSession.replaceOwnedPart({
+      path: commentsPartPath,
+      bytes: new TextEncoder().encode(serializedComments.commentsXml),
+      contentType:
+        state.sourcePackage.parts.get(commentsPartPath)?.contentType ?? COMMENTS_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.commentsExtendedXml || state.sourceCommentsExtendedPartPath) {
+    exportSession.replaceOwnedPart({
+      path: commentsExtendedPartPath,
+      bytes: new TextEncoder().encode(
+        serializedComments.commentsExtendedXml ?? `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"></w15:commentsEx>`,
+      ),
+      contentType:
+        state.sourcePackage.parts.get(commentsExtendedPartPath)?.contentType ??
+        COMMENTS_EXTENDED_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.commentsIdsXml || state.sourceCommentsIdsPartPath) {
+    exportSession.replaceOwnedPart({
+      path: commentsIdsPartPath,
+      bytes: new TextEncoder().encode(
+        serializedComments.commentsIdsXml ?? `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w16cid:commentsIds xmlns:w16cid="http://schemas.microsoft.com/office/word/2016/wordml/cid"></w16cid:commentsIds>`,
+      ),
+      contentType:
+        state.sourcePackage.parts.get(commentsIdsPartPath)?.contentType ??
+        COMMENTS_IDS_CONTENT_TYPE,
+    });
+  }
+
+  if (serializedComments.peopleXml || state.sourcePeoplePartPath) {
+    exportSession.replaceOwnedPart({
+      path: peoplePartPath,
+      bytes: new TextEncoder().encode(
+        serializedComments.peopleXml ?? `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<w15:people xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"></w15:people>`,
+      ),
+      contentType:
+        state.sourcePackage.parts.get(peoplePartPath)?.contentType ??
+        PEOPLE_CONTENT_TYPE,
+    });
+  }
+
+  if (exportedSubParts) {
+    for (const header of exportedSubParts.headers) {
+      exportSession.replaceOwnedPart({
+        path: header.partPath,
+        bytes: new TextEncoder().encode(serializeHeaderXml(header)),
+        contentType:
+          state.sourcePackage.parts.get(header.partPath)?.contentType ?? WORD_HEADER_CONTENT_TYPE,
+      });
+    }
+    for (const footer of exportedSubParts.footers) {
+      exportSession.replaceOwnedPart({
+        path: footer.partPath,
+        bytes: new TextEncoder().encode(serializeFooterXml(footer)),
+        contentType:
+          state.sourcePackage.parts.get(footer.partPath)?.contentType ?? WORD_FOOTER_CONTENT_TYPE,
+      });
+    }
+    if (exportedSubParts.footnoteCollection) {
+      if (state.sourceSubPartPaths.footnotesPartPath) {
+        exportSession.replaceOwnedPart({
+          path: state.sourceSubPartPaths.footnotesPartPath,
+          bytes: new TextEncoder().encode(serializeFootnotesXml(exportedSubParts.footnoteCollection)),
+          contentType:
+            state.sourcePackage.parts.get(state.sourceSubPartPaths.footnotesPartPath)?.contentType ??
+            WORD_FOOTNOTES_CONTENT_TYPE,
+        });
+      }
+      if (state.sourceSubPartPaths.endnotesPartPath) {
+        exportSession.replaceOwnedPart({
+          path: state.sourceSubPartPaths.endnotesPartPath,
+          bytes: new TextEncoder().encode(serializeEndnotesXml(exportedSubParts.footnoteCollection)),
+          contentType:
+            state.sourcePackage.parts.get(state.sourceSubPartPaths.endnotesPartPath)?.contentType ??
+            WORD_ENDNOTES_CONTENT_TYPE,
+          });
+      }
+    }
+    if (exportedSubParts.theme && state.sourceSubPartPaths.themePartPath) {
+      const sourceThemePart = state.sourcePackage.parts.get(state.sourceSubPartPaths.themePartPath);
+      if (sourceThemePart) {
+        exportSession.replaceOwnedPart({
+          path: state.sourceSubPartPaths.themePartPath,
+          bytes: sourceThemePart.bytes,
+          contentType: sourceThemePart.contentType,
+          relationships: sourceThemePart.relationships,
+          compression: sourceThemePart.compression,
+        });
+      }
+    }
+  }
+
+  return {
+    bytes: exportSession.serialize(),
+    mimeType: DOCX_MIME_TYPE,
+    fileName: options?.fileName ?? `${snapshot.documentId}.docx`,
+  };
+}
+
+function createImportedCanonicalDocument(input: {
+  documentId: string;
+  timestamp: string;
+  numbering: CanonicalDocumentEnvelope["numbering"];
+  media: CanonicalDocumentEnvelope["media"];
+  content: CanonicalDocumentEnvelope["content"];
+  subParts?: SubPartsCatalog;
+  preservation: CanonicalDocumentEnvelope["preservation"];
+  diagnostics: CanonicalDocumentEnvelope["diagnostics"];
+  review: CanonicalDocumentEnvelope["review"];
+}): CanonicalDocumentEnvelope {
+  return {
+    schemaVersion: "cds/1.0.0",
+    docId: createCanonicalDocumentId(input.documentId),
+    createdAt: input.timestamp,
+    updatedAt: input.timestamp,
+    metadata: {
+      customProperties: {},
+    },
+    styles: {
+      paragraphs: {},
+      characters: {},
+      tables: {},
+    },
+    numbering: input.numbering,
+    media: input.media,
+    content: input.content,
+    review: input.review,
+    preservation: input.preservation,
+    diagnostics: input.diagnostics,
+    ...(input.subParts !== undefined ? { subParts: input.subParts } : {}),
+  };
+}
+
+function createImportedSnapshot(input: {
+  documentId: string;
+  editorBuild: string;
+  timestamp: string;
+  document: CanonicalDocumentEnvelope;
+  compatibility: PersistedEditorSnapshot["compatibility"];
+}): PersistedEditorSnapshot {
+  return {
+    snapshotVersion: "persisted-editor-snapshot/1",
+    schemaVersion: input.document.schemaVersion,
+    documentId: input.documentId,
+    docId: input.document.docId,
+    createdAt: input.document.createdAt,
+    updatedAt: input.document.updatedAt,
+    savedAt: input.timestamp,
+    editorBuild: input.editorBuild,
+    canonicalDocument: input.document,
+    compatibility: input.compatibility,
+    warningLog: input.compatibility.warnings,
+  };
+}
+
+function toPublicAnchorProjection(
+  anchor: InternalEditorAnchorProjection,
+): PublicEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        kind: "range",
+        from: anchor.range.from,
+        to: anchor.range.to,
+        assoc: anchor.assoc,
+      };
+    case "node":
+      return {
+        kind: "node",
+        at: anchor.at,
+        assoc: anchor.assoc,
+      };
+    case "detached":
+      return {
+        kind: "detached",
+        lastKnownRange: anchor.lastKnownRange,
+        reason: anchor.reason,
+      };
+  }
+}
+
+function toPublicCompatibilityFeatureEntry(entry: InternalCompatibilityFeatureEntry) {
+  return {
+    ...entry,
+    affectedAnchor: entry.affectedAnchor
+      ? toPublicAnchorProjection(entry.affectedAnchor)
+      : undefined,
+  };
+}
+
+function toPublicWarning(warning: InternalEditorWarning): PublicEditorWarning {
+  return {
+    ...warning,
+    affectedAnchor: warning.affectedAnchor
+      ? toPublicAnchorProjection(warning.affectedAnchor)
+      : undefined,
+  };
+}
+
+function toPublicError(error: InternalEditorError): EditorError {
+  return { ...error };
+}
+
+function toPublicCompatibilityReport(
+  report: InternalCompatibilityReport,
+): PublicCompatibilityReport {
+  return {
+    reportVersion: report.reportVersion,
+    generatedAt: report.generatedAt,
+    blockExport: report.blockExport,
+    featureEntries: report.featureEntries.map((entry) =>
+      toPublicCompatibilityFeatureEntry(entry),
+    ),
+    warnings: report.warnings.map((warning) => toPublicWarning(warning)),
+    errors: report.errors.map((error) => toPublicError(error)),
+  };
+}
+
+function createDiagnosticsSession(
+  options: LoadDocxEditorSessionOptions,
+  diagnostics: ImportDiagnosticsResult,
+): LoadedDocxEditorSession {
+  const timestamp = new Date().toISOString();
+  const runtime = createReadOnlyDiagnosticsRuntime({
+    documentId: options.documentId,
+    sourceLabel: options.sourceLabel,
+    editorBuild: options.editorBuild,
+    generatedAt: timestamp,
+    diagnostics,
+  });
+  const initialSnapshot = runtime.getPersistedSnapshot();
+
+  return {
+    initialSnapshot,
+    fatalError: diagnostics.fatalError,
+    readOnly: true,
+    exportDocx: async (_snapshot, exportOptions) => runtime.exportDocx(exportOptions),
+  };
+}
+
+function createImportDiagnosticsFromError(error: unknown): ImportDiagnosticsResult {
+  if (isPackageImportError(error)) {
+    return createPackageImportDiagnostics({
+      issue: classifyCorruptPackageError(error),
+    });
+  }
+
+  return createValidationImportDiagnostics({
+    message:
+      error instanceof Error
+        ? error.message
+        : "DOCX import failed during validation.",
+  });
+}
+
+function normalizeImportedRevisionRecords(
+  parsed: ParsedRevisionsResult,
+  content: CanonicalDocumentEnvelope["content"],
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+): ParsedRevisionsResult {
+  const opaqueRanges = Object.values(opaqueFragments).map((fragment) => fragment.lastKnownRange);
+  const paragraphRanges = collectCanonicalParagraphRanges(content);
+  if (opaqueRanges.length === 0) {
+    return {
+      ...parsed,
+      revisions: parsed.revisions.map((revision) => {
+        if (revision.anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
+          return revision;
+        }
+
+        const preserveOnlyReason = getStructuralPreserveOnlyReason(
+          revision,
+          paragraphRanges,
+        );
+        if (!preserveOnlyReason) {
+          return revision;
+        }
+
+        return {
+          ...revision,
+          metadata: {
+            ...revision.metadata,
+            preserveOnlyReason,
+          },
+        };
+      }),
+    };
+  }
+
+  return {
+    ...parsed,
+    revisions: parsed.revisions.map((revision) => {
+      if (revision.anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
+        return revision;
+      }
+
+      const preserveOnlyReason =
+        getStructuralPreserveOnlyReason(revision, paragraphRanges) ??
+        (opaqueRanges.some((range) => rangesIntersect(range, revision.anchor.range))
+          ? "Imported revision overlaps preserve-only OOXML and remains preserve-only."
+          : undefined);
+
+      if (!preserveOnlyReason) {
+        return revision;
+      }
+
+      return {
+        ...revision,
+        metadata: {
+          ...revision.metadata,
+          preserveOnlyReason,
+        },
+      };
+    }),
+  };
+}
+
+function normalizeImportedCommentThreads(
+  parsed: ParsedCommentsResult,
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  revisions: readonly ReviewRevisionRecord[],
+): NormalizedImportedCommentsResult {
+  const opaqueRanges = Object.values(opaqueFragments).map((fragment) => fragment.lastKnownRange);
+  const preserveOnlyRevisionRanges = revisions
+    .filter(
+      (revision) =>
+        revision.anchor.kind === "range" &&
+        typeof revision.metadata.preserveOnlyReason === "string" &&
+        revision.metadata.preserveOnlyReason.length > 0,
+    )
+    .map((revision) => revision.anchor.range);
+  const preserveOnlyCommentIds = new Set(parsed.diagnostics.map((diagnostic) => diagnostic.commentId));
+  const additionalDiagnostics: CommentImportDiagnostic[] = [];
+  const normalizedThreads = parsed.threads.map((thread) => {
+    if (thread.anchor.kind !== "range") {
+      preserveOnlyCommentIds.add(thread.commentId);
+      return thread;
+    }
+
+    const opaqueOverlap = opaqueRanges.some((range) => rangesIntersect(range, thread.anchor.range));
+    if (opaqueOverlap) {
+      preserveOnlyCommentIds.add(thread.commentId);
+      additionalDiagnostics.push({
+        commentId: thread.commentId,
+        code: "opaque_anchor_preserve_only",
+        message:
+          "Comment anchor intersects preserve-only OOXML and remains preserve-only on export.",
+        featureClass: "preserve-only",
+      });
+      return {
+        ...thread,
+        anchor: createDetachedAnchor(thread.anchor.range, "importAmbiguity"),
+        status: "detached",
+      };
+    }
+
+    const preserveOnlyRevisionOverlap = preserveOnlyRevisionRanges.some((range) =>
+      rangesIntersect(range, thread.anchor.range),
+    );
+    if (preserveOnlyRevisionOverlap) {
+      preserveOnlyCommentIds.add(thread.commentId);
+      additionalDiagnostics.push({
+        commentId: thread.commentId,
+        code: "preserve_only_revision_overlap",
+        message:
+          "Comment anchor overlaps preserve-only review markup and remains preserve-only on export.",
+        featureClass: "preserve-only",
+      });
+      return {
+        ...thread,
+        anchor: createDetachedAnchor(thread.anchor.range, "importAmbiguity"),
+        status: "detached",
+      };
+    }
+
+    return thread;
+  });
+
+  return {
+    ...parsed,
+    threads: normalizedThreads,
+    diagnostics: [...parsed.diagnostics, ...additionalDiagnostics],
+    definitions: parsed.definitions,
+    preservedDefinitions: parsed.definitions.filter((definition) =>
+      preserveOnlyCommentIds.has(
+        resolveDefinitionRootCommentId(definition, parsed.definitions),
+      ),
+    ),
+  };
+}
+
+function resolveDefinitionRootCommentId(
+  definition: ImportedCommentDefinition,
+  definitions: readonly ImportedCommentDefinition[],
+): string {
+  if (!definition.parentParaId) {
+    return definition.commentId;
+  }
+
+  const definitionsByParaId = new Map(
+    definitions
+      .filter((candidate) => typeof candidate.paraId === "string")
+      .map((candidate) => [candidate.paraId!, candidate]),
+  );
+  const visited = new Set<string>();
+  let current: ImportedCommentDefinition | undefined = definition;
+
+  while (current?.parentParaId) {
+    if (visited.has(current.parentParaId)) {
+      break;
+    }
+    visited.add(current.parentParaId);
+    const parent = definitionsByParaId.get(current.parentParaId);
+    if (!parent) {
+      break;
+    }
+    current = parent;
+  }
+
+  return current?.commentId ?? definition.commentId;
+}
+
+function getStructuralPreserveOnlyReason(
+  revision: ReviewRevisionRecord,
+  paragraphRanges: ReadonlyArray<{ start: number; end: number }>,
+): string | undefined {
+  const form = revision.metadata.importedRevisionForm;
+  if (!form || revision.anchor.kind !== "range") {
+    return undefined;
+  }
+
+  if (
+    (form === "run-insertion" || form === "run-deletion") &&
+    revision.anchor.range.from === revision.anchor.range.to
+  ) {
+    return "Imported zero-width run revision remains preserve-only.";
+  }
+
+  if (form === "paragraph-insertion" || form === "paragraph-deletion") {
+    const paragraphBoundary = paragraphRanges.find(
+      (boundary) =>
+        boundary.end === revision.anchor.range.from ||
+        (revision.anchor.range.from >= boundary.start &&
+          revision.anchor.range.from <= boundary.end),
+    );
+    return paragraphBoundary
+      ? undefined
+      : "Imported revision spans paragraph-level structure and remains preserve-only.";
+  }
+
+  const paragraphBoundary = paragraphRanges.find(
+    (boundary) =>
+      revision.anchor.range.from >= boundary.start &&
+      revision.anchor.range.to <= boundary.end,
+  );
+  return paragraphBoundary
+    ? undefined
+    : "Imported revision spans structural boundaries and remains preserve-only.";
+}
+
+function collectCanonicalParagraphRanges(
+  content: CanonicalDocumentEnvelope["content"],
+): Array<{ start: number; end: number }> {
+  const ranges: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+  let previousWasParagraph = false;
+
+  for (const block of content.children) {
+    if (block.type === "paragraph") {
+      if (previousWasParagraph) {
+        cursor += 1;
+      }
+      const start = cursor;
+      cursor += measureCanonicalParagraph(block);
+      ranges.push({ start, end: cursor });
+      previousWasParagraph = true;
+      continue;
+    }
+
+    cursor += 1;
+    previousWasParagraph = false;
+  }
+
+  return ranges;
+}
+
+function measureCanonicalParagraph(paragraph: CanonicalDocumentEnvelope["content"]["children"][number] & { type: "paragraph" }): number {
+  return paragraph.children.reduce((size, child) => {
+    switch (child.type) {
+      case "text":
+        return size + child.text.length;
+      case "tab":
+      case "hard_break":
+      case "image":
+      case "opaque_inline":
+        return size + 1;
+      case "hyperlink":
+        return (
+          size +
+          child.children.reduce((childSize, entry) => {
+            switch (entry.type) {
+              case "text":
+                return childSize + entry.text.length;
+              case "tab":
+              case "hard_break":
+                return childSize + 1;
+            }
+          }, 0)
+        );
+    }
+  }, 0);
+}
+
+function rangesIntersect(
+  left: { from: number; to: number },
+  right: { from: number; to: number },
+): boolean {
+  return left.from < right.to && right.from < left.to;
+}
+
+function resolveCommentsPartPath(
+  sourcePackage: OpcPackage,
+  relationships: readonly OpcRelationship[],
+): string | undefined {
+  return resolveDocumentRelatedPartPath(
+    sourcePackage,
+    relationships,
+    COMMENTS_RELATIONSHIP_TYPE,
+    COMMENTS_PART_PATH,
+  );
+}
+
+function resolveDocumentRelatedPartPath(
+  sourcePackage: OpcPackage,
+  relationships: readonly OpcRelationship[],
+  relationshipType: string,
+  fallbackPartPath: string,
+): string | undefined {
+  const relationship = relationships.find(
+    (candidate) =>
+      candidate.type === relationshipType &&
+      candidate.targetMode === "internal",
+  );
+  if (!relationship) {
+    return sourcePackage.parts.has(fallbackPartPath) ? fallbackPartPath : undefined;
+  }
+
+  const targetPath = resolveRelationshipTarget(MAIN_DOCUMENT_PATH, relationship);
+  return sourcePackage.parts.has(targetPath) ? targetPath : undefined;
+}
+
+function toRuntimeCommentRecords(
+  threads: readonly CommentThread[],
+): Record<string, CommentThreadRecord> {
+  return Object.fromEntries(
+    threads.map((thread) => {
+      return [
+        thread.commentId,
+        {
+          commentId: thread.commentId,
+          body: thread.entries.map((entry) => entry.body).join("\n"),
+          anchor: thread.anchor,
+          createdBy: thread.createdBy,
+          authorId: thread.createdBy,
+          createdAt: thread.createdAt,
+          entries: thread.entries.map((entry) => ({
+            entryId: entry.entryId,
+            authorId: entry.authorId,
+            body: entry.body,
+            createdAt: entry.createdAt,
+            metadata: entry.metadata
+              ? {
+                  ooxmlCommentId: entry.metadata.ooxmlCommentId,
+                  paraId: entry.metadata.paraId,
+                  parentParaId: entry.metadata.parentParaId,
+                  durableId: entry.metadata.durableId,
+                  initials: entry.metadata.initials,
+                }
+              : undefined,
+          })),
+          status: thread.status,
+          resolution: thread.resolution
+            ? {
+                resolvedAt: thread.resolution.resolvedAt,
+                resolvedBy: thread.resolution.resolvedBy,
+              }
+            : undefined,
+          resolvedAt: thread.resolution?.resolvedAt,
+          warningIds: [...thread.warningIds],
+          isResolved: thread.status === "resolved",
+          metadata: thread.metadata
+            ? {
+                source: thread.metadata.source,
+                rootOoxmlCommentId: thread.metadata.rootOoxmlCommentId,
+                rootParaId: thread.metadata.rootParaId,
+              }
+            : undefined,
+        } satisfies CommentThreadRecord,
+      ];
+    }),
+  );
+}
+
+function toRuntimeRevisionRecords(
+  revisions: readonly ReviewRevisionRecord[],
+): Record<string, RuntimeRevisionRecord> {
+  return Object.fromEntries(
+    revisions.map((revision) => [
+      revision.revisionId,
+      {
+        changeId: revision.revisionId,
+        kind: revision.kind,
+        anchor: revision.anchor,
+        authorId: revision.authorId,
+        createdAt: revision.createdAt,
+        warningIds: [...revision.warningIds],
+        metadata: {
+          source: revision.metadata.source,
+          preserveOnlyReason: revision.metadata.preserveOnlyReason,
+          importedRevisionForm: revision.metadata.importedRevisionForm,
+          originalRevisionType: revision.metadata.originalRevisionType,
+          ooxmlRevisionId: revision.metadata.ooxmlRevisionId,
+        },
+        status: revision.status === "active" ? "open" : revision.status,
+      } satisfies RuntimeRevisionRecord,
+    ]),
+  );
+}
+
+function toReviewRevisionRecords(
+  revisions: CanonicalDocumentEnvelope["review"]["revisions"],
+): ReviewRevisionRecord[] {
+  return Object.values(revisions).map((revision) => ({
+    revisionId: revision.changeId,
+    kind: revision.kind,
+    anchor: revision.anchor,
+    authorId: revision.authorId ?? "unknown",
+    createdAt: revision.createdAt,
+    warningIds: [...(revision.warningIds ?? [])],
+    metadata: {
+      source: revision.metadata?.source ?? "runtime",
+      preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+      importedRevisionForm: revision.metadata?.importedRevisionForm,
+      originalRevisionType: revision.metadata?.originalRevisionType,
+      ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+    },
+    status: revision.status === "open" ? "active" : revision.status,
+  }));
+}
+
+export function stripCommentMarkup(
+  documentXml: string,
+  ownedCommentIds: readonly string[],
+): string {
+  if (ownedCommentIds.length === 0) {
+    return documentXml;
+  }
+
+  let output = documentXml;
+  for (const commentId of ownedCommentIds) {
+    const escapedCommentId = escapeRegExp(commentId);
+    const attributePattern = `(?:w:id|id)=["']${escapedCommentId}["']`;
+    output = output
+      .replace(
+        new RegExp(`<w:commentRangeStart\\b[^>]*${attributePattern}[^>]*/>`, "gu"),
+        "",
+      )
+      .replace(
+        new RegExp(`<w:commentRangeEnd\\b[^>]*${attributePattern}[^>]*/>`, "gu"),
+        "",
+      )
+      .replace(
+        new RegExp(
+          `<w:r\\b[^>]*>(?:(?!<w:t\\b|</w:r>)[\\s\\S])*?<w:commentReference\\b[^>]*${attributePattern}[^>]*/>(?:(?!<w:t\\b|</w:r>)[\\s\\S])*?</w:r>`,
+          "gu",
+        ),
+        "",
+      );
+  }
+
+  return output;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function withDocumentRelatedParts(
+  relationships: readonly OpcRelationship[],
+  relatedParts: ReadonlyArray<{
+    relationshipType: string;
+    partPath: string;
+    existingRelationshipId?: string;
+    include: boolean;
+  }>,
+): OpcRelationship[] {
+  const filteredTypes = new Set(relatedParts.map((part) => part.relationshipType));
+  const nextRelationships = relationships
+    .filter((relationship) => !filteredTypes.has(relationship.type))
+    .map(cloneRelationship);
+
+  for (const part of relatedParts) {
+    if (!part.include) {
+      continue;
+    }
+
+    nextRelationships.push({
+      id: part.existingRelationshipId ?? createCommentsRelationshipId(nextRelationships),
+      type: part.relationshipType,
+      target: toDocumentRelativeTarget(part.partPath),
+      targetMode: "internal",
+    });
+  }
+
+  return nextRelationships;
+}
+
+function collectPreservedPackageParts(
+  sourcePackage: OpcPackage,
+  ownedPartPaths: ReadonlyArray<string | undefined>,
+): Record<string, PreservedPackagePart> {
+  const normalizedOwnedPaths = new Set(
+    ownedPartPaths
+      .filter((value): value is string => typeof value === "string")
+      .map((path) => normalizePartPath(path)),
+  );
+  return Object.fromEntries(
+    [...sourcePackage.parts.values()]
+      .filter((part) =>
+        shouldPreservePackagePart(part.path, part.surfaceKind, normalizedOwnedPaths),
+      )
+      .map((part) => [
+        part.path,
+        {
+          packagePartName: part.path,
+          contentType: part.contentType ?? "application/octet-stream",
+          relationshipIds: findRelationshipIdsTargetingPart(sourcePackage, part.path),
+        } satisfies PreservedPackagePart,
+      ]),
+  );
+}
+
+function collectInlineMediaParts(
+  sourcePackage: OpcPackage,
+): ReadonlyMap<string, { path: string; contentType: string }> {
+  return new Map(
+    [...sourcePackage.parts.values()]
+      .filter(
+        (part) =>
+          part.path.startsWith("/word/media/") && typeof part.contentType === "string",
+      )
+      .map((part) => [
+        part.path,
+        {
+          path: part.path,
+          contentType: part.contentType ?? "application/octet-stream",
+        },
+      ]),
+  );
+}
+
+function createEmptyNumberingCatalog(): NumberingCatalog {
+  return {
+    abstractDefinitions: {},
+    instances: {},
+  };
+}
+
+function hasNumberingEntries(catalog: NumberingCatalog): boolean {
+  return (
+    Object.keys(catalog.abstractDefinitions ?? {}).length > 0 ||
+    Object.keys(catalog.instances ?? {}).length > 0
+  );
+}
+
+function collectBrokenInternalRelationshipIssues(
+  sourcePackage: OpcPackage,
+): ReturnType<typeof createBrokenRelationshipIssue>[] {
+  const brokenTargets = new Map<string, ReturnType<typeof createBrokenRelationshipIssue>>();
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (relationship.targetMode !== "internal") {
+      continue;
+    }
+
+    const target = resolveRelationshipTarget(null, relationship);
+    if (!sourcePackage.parts.has(target)) {
+      brokenTargets.set(
+        `package:${relationship.id}:${target}`,
+        createBrokenRelationshipIssue({
+          relationshipSourcePath: null,
+          relationshipId: relationship.id,
+          targetPartPath: target,
+        }),
+      );
+    }
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (relationship.targetMode !== "internal") {
+        continue;
+      }
+
+      const target = resolveRelationshipTarget(part.path, relationship);
+      if (!sourcePackage.parts.has(target)) {
+        brokenTargets.set(
+          `${part.path}:${relationship.id}:${target}`,
+          createBrokenRelationshipIssue({
+            relationshipSourcePath: part.path,
+            relationshipId: relationship.id,
+            targetPartPath: target,
+          }),
+        );
+      }
+    }
+  }
+
+  return [...brokenTargets.values()].sort((left, right) =>
+    `${left.relationshipSourcePath ?? ""}:${left.relationshipId}:${left.targetPartPath}`.localeCompare(
+      `${right.relationshipSourcePath ?? ""}:${right.relationshipId}:${right.targetPartPath}`,
+    ),
+  );
+}
+
+function summarizeBrokenRelationshipIssues(
+  issues: readonly ReturnType<typeof createBrokenRelationshipIssue>[],
+): string {
+  return `DOCX package has unresolved internal relationships: ${issues
+    .map((issue) => issue.targetPartPath ?? issue.message)
+    .slice(0, 3)
+    .join(", ")}${issues.length > 3 ? ", ..." : ""}.`;
+}
+
+function shouldPreservePackagePart(
+  partPath: string,
+  surfaceKind: OpcPackage["parts"] extends Map<string, infer T>
+    ? T extends { surfaceKind: infer U }
+      ? U
+      : never
+    : never,
+  ownedPartPaths: ReadonlySet<string>,
+): boolean {
+  if (surfaceKind !== "content") {
+    return false;
+  }
+
+  if (
+    partPath === MAIN_DOCUMENT_PATH ||
+    ownedPartPaths.has(partPath) ||
+    partPath.startsWith("/word/media/") ||
+    CORE_NON_PRESERVED_PART_PATHS.has(partPath)
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+function findRelationshipIdsTargetingPart(
+  sourcePackage: OpcPackage,
+  targetPartPath: string,
+): string[] {
+  const ids = new Set<string>();
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (
+      relationship.targetMode === "internal" &&
+      resolveRelationshipTarget(null, relationship) === targetPartPath
+    ) {
+      ids.add(relationship.id);
+    }
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (
+        relationship.targetMode === "internal" &&
+        resolveRelationshipTarget(part.path, relationship) === targetPartPath
+      ) {
+        ids.add(relationship.id);
+      }
+    }
+  }
+
+  return [...ids].sort();
+}
+
+function extractDocumentRootAttributes(documentXml: string): Record<string, string> {
+  const match = documentXml.match(
+    /<(?:[A-Za-z_][A-Za-z0-9:._-]*:)?document\b([^>]*)>/u,
+  );
+  if (!match) {
+    return {};
+  }
+
+  const attributes: Record<string, string> = {};
+  const pattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  for (const attributeMatch of (match[1] ?? "").matchAll(pattern)) {
+    const name = attributeMatch[1];
+    const value = attributeMatch[3] ?? attributeMatch[4] ?? "";
+    if (!name) {
+      continue;
+    }
+    attributes[name] = value;
+  }
+
+  return attributes;
+}
+
+function isPackageImportError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const normalized = error.message.toLowerCase();
+  return (
+    normalized.includes("zip") ||
+    normalized.includes("opc package") ||
+    normalized.includes("compression") ||
+    normalized.includes("relationship") ||
+    normalized.includes("/[content_types].xml") ||
+    normalized.includes("/word/document.xml") ||
+    normalized.includes("xml")
+  );
+}
+
+const CORE_NON_PRESERVED_PART_PATHS = new Set([
+  "/docProps/app.xml",
+  "/docProps/core.xml",
+  "/docProps/custom.xml",
+  "/word/fontTable.xml",
+  "/word/numbering.xml",
+  "/word/settings.xml",
+  "/word/styles.xml",
+  "/word/stylesWithEffects.xml",
+  "/word/webSettings.xml",
+]);
+
+function createCommentsRelationshipId(
+  relationships: readonly OpcRelationship[],
+): string {
+  let nextIndex = 1;
+  while (relationships.some((relationship) => relationship.id === `rIdComments${nextIndex}`)) {
+    nextIndex += 1;
+  }
+
+  return `rIdComments${nextIndex}`;
+}
+
+function toDocumentRelativeTarget(partPath: string): string {
+  const normalized = normalizePartPath(partPath);
+  return normalized.startsWith("/word/") ? normalized.slice("/word/".length) : normalized.slice(1);
+}
+
+function cloneRelationship(relationship: OpcRelationship): OpcRelationship {
+  return { ...relationship };
+}
+
+function decodeUtf8(bytes: Uint8Array | undefined): string {
+  if (!bytes) {
+    return "";
+  }
+
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("utf8");
+}
+
+function toUint8Array(bytes: Uint8Array | ArrayBuffer): Uint8Array {
+  return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+}
+
+function serializeCanonicalDocumentForExport(document: CanonicalDocumentEnvelope): string {
+  return createCanonicalDocumentSignature(document);
+}
+
+function canReuseSourceBytesForCurrentDocument(
+  state: ImportedDocxState,
+  document: CanonicalDocumentEnvelope,
+): boolean {
+  const commentThreads = Object.values(document.review.comments);
+  const hasLiveComments = commentThreads.some((thread) => thread.anchor.kind !== "detached");
+  if (!hasLiveComments) {
+    return true;
+  }
+
+  return Boolean(
+    state.sourceCommentsPartPath &&
+      state.sourceCommentsExtendedPartPath &&
+      state.sourceCommentsIdsPartPath &&
+      state.sourcePeoplePartPath,
+  );
+}