@beyondwork/docx-react-component 1.0.28 → 1.0.29

package/src/io/docx-session.ts

@@ -1,2882 +0,0 @@
-import type {
-  CompatibilityReport as PublicCompatibilityReport,
-  EditorError,
-  EditorSessionState,
-  EditorWarning as PublicEditorWarning,
-  EditorAnchorProjection as PublicEditorAnchorProjection,
-  ExportDocxOptions,
-  ExportResult,
-  PersistedEditorSnapshot,
-  ProtectionRange,
-  ProtectionSnapshot,
-} from "../api/public-types.ts";
-import { editorSessionStateFromPersistedSnapshot } from "../api/session-state.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,
-  type ParsedBlockNode,
-  type ParsedInlineNode,
-  type ParsedPermStartInlineNode,
-} from "./ooxml/parse-main-document.ts";
-import { normalizeParsedTextDocument } from "./normalize/normalize-text.ts";
-import {
-  CONTENT_TYPES_PATH,
-  PACKAGE_RELATIONSHIPS_PATH,
-  getRelationshipsPartPath,
-  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,
-  mapParagraphBoundaries,
-  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 {
-  BlockNode,
-  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,
-  hasSerializableNumberingEntries,
-  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 { resolveTheme } from "./ooxml/parse-theme.ts";
-import { parseSettingsXml } from "./ooxml/parse-settings.ts";
-import { parseStylesXml, type ParseStylesResult } from "./ooxml/parse-styles.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";
-import { createPersistedSourcePackage } from "./source-package-provenance.ts";
-import { validatePersistedEditorSnapshot } from "../model/snapshot.ts";
-import {
-  createSyntheticDocxNullNumberingCatalog,
-  DOCX_NULL_NUMBERING_INSTANCE_ID,
-} from "./ooxml/numbering-sentinels.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 APP_PROPERTIES_PART_PATH = "/docProps/app.xml";
-const CORE_PROPERTIES_PART_PATH = "/docProps/core.xml";
-const MAIN_DOCUMENT_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml";
-const APP_PROPERTIES_CONTENT_TYPE =
-  "application/vnd.openxmlformats-officedocument.extended-properties+xml";
-const CORE_PROPERTIES_CONTENT_TYPE =
-  "application/vnd.openxmlformats-package.core-properties+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 APP_PROPERTIES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
-const CORE_PROPERTIES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
-const OFFICE_DOCUMENT_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
-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 SETTINGS_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
-const STYLES_RELATIONSHIP_TYPE =
-  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
-const STYLES_PART_PATH = "/word/styles.xml";
-const FOOTNOTES_PART_PATH = "/word/footnotes.xml";
-const ENDNOTES_PART_PATH = "/word/endnotes.xml";
-const SETTINGS_PART_PATH = "/word/settings.xml";
-
-interface LoadDocxEditorSessionOptions {
-  documentId: string;
-  sourceLabel?: string;
-  bytes: Uint8Array | ArrayBuffer;
-  editorBuild?: string;
-}
-
-export interface LoadedDocxEditorSession {
-  initialSessionState: EditorSessionState;
-  initialSnapshot: PersistedEditorSnapshot;
-  fatalError?: EditorError;
-  readOnly: boolean;
-  protectionSnapshot: ProtectionSnapshot;
-  exportDocx: (
-    sessionState: EditorSessionState | PersistedEditorSnapshot,
-    options?: ExportDocxOptions,
-  ) => Promise<ExportResult>;
-}
-
-interface ImportedDocxState {
-  sourceBytes: Uint8Array;
-  sourcePackage: OpcPackage;
-  sourceDocumentPartPath: string;
-  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[];
-  protectionSnapshot: ProtectionSnapshot;
-  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 editorBuild =
-    typeof options.editorBuild === "string" && options.editorBuild.length > 0
-      ? options.editorBuild
-      : "dev";
-  const sourceBytes = toUint8Array(options.bytes);
-  let sourcePackage: OpcPackage;
-
-  try {
-    sourcePackage = readOpcPackage(sourceBytes);
-  } catch (error) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: classifyCorruptPackageError(error),
-      }),
-    );
-  }
-
-  const mainDocumentPath = resolveMainDocumentPartPath(sourcePackage);
-  const brokenRelationshipIssues = collectBrokenInternalRelationshipIssues(
-    sourcePackage,
-    mainDocumentPath,
-  );
-  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),
-          },
-        },
-      }),
-    );
-  }
-
-  if (!mainDocumentPath) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: createMissingPartIssue(MAIN_DOCUMENT_PATH),
-      }),
-    );
-  }
-
-  const documentPart = sourcePackage.parts.get(mainDocumentPath);
-  if (!documentPart) {
-    return createDiagnosticsSession(
-      options,
-      createPackageImportDiagnostics({
-        issue: createMissingPartIssue(mainDocumentPath),
-      }),
-    );
-  }
-  if (documentPart.contentType !== MAIN_DOCUMENT_CONTENT_TYPE) {
-    return createDiagnosticsSession(
-      options,
-      createValidationImportDiagnostics({
-        message: `DOCX main document part ${mainDocumentPath} must use content type ${MAIN_DOCUMENT_CONTENT_TYPE}.`,
-      }),
-    );
-  }
-
-  try {
-    const sourceDocumentXml = decodeUtf8(documentPart.bytes);
-    const importedRevisions = parseRevisionsFromDocumentXml(sourceDocumentXml);
-    const numberingPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      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,
-      mainDocumentPath,
-    );
-    const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
-    const normalizedDocument = normalizeParsedTextDocument(
-      parsedDocument,
-      mainDocumentPath,
-    );
-    const commentsPartPath = resolveCommentsPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-    );
-    const commentsExtendedPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      COMMENTS_EXTENDED_RELATIONSHIP_TYPE,
-      COMMENTS_EXTENDED_PART_PATH,
-    );
-    const commentsIdsPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      COMMENTS_IDS_RELATIONSHIP_TYPE,
-      COMMENTS_IDS_PART_PATH,
-    );
-    const peoplePartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      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,
-    );
-    const subPartOpaqueState = createSubPartOpaqueImportState(
-      normalizedDocument.preservation.opaqueFragments,
-      normalizedDocument.diagnostics.warnings,
-    );
-    // ---- 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 seenSubPartKeys = new Set<string>();
-
-    for (const ref of headerFooterRefs) {
-      const dedupeKey = `${ref.kind}:${ref.variant}:${ref.relationshipId}`;
-      if (seenSubPartKeys.has(dedupeKey)) {
-        continue;
-      }
-      seenSubPartKeys.add(dedupeKey);
-
-      const relationship = documentPart.relationships.find(
-        (r) => r.id === ref.relationshipId && r.targetMode === "internal",
-      );
-      if (!relationship) {
-        continue;
-      }
-
-      const partPath = resolveRelationshipTarget(mainDocumentPath, 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,
-          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: normalizeSubPartOpaqueBlocks(
-            parsed.blocks,
-            normalizedDocument.preservation.opaqueFragments,
-            normalizedDocument.diagnostics.warnings,
-            partPath,
-            subPartOpaqueState,
-          ),
-        });
-        sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
-      } else {
-        const parsed = parseFooterXml(xml);
-        parsedFooters.push({
-          variant: ref.variant,
-          partPath,
-          relationshipId: ref.relationshipId,
-          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
-          blocks: normalizeSubPartOpaqueBlocks(
-            parsed.blocks,
-            normalizedDocument.preservation.opaqueFragments,
-            normalizedDocument.diagnostics.warnings,
-            partPath,
-            subPartOpaqueState,
-          ),
-        });
-        sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
-      }
-    }
-
-    const footnotesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      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,
-      mainDocumentPath,
-      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()),
-      );
-      normalizeFootnoteCollectionOpaqueBlocks(
-        footnoteCollection,
-        "footnote",
-        normalizedDocument.preservation.opaqueFragments,
-        normalizedDocument.diagnostics.warnings,
-        footnotesPartPath,
-        subPartOpaqueState,
-      );
-    }
-    if (endnotesPartPath) {
-      footnoteCollection = parseEndnotesXml(
-        decodeUtf8(sourcePackage.parts.get(endnotesPartPath)?.bytes ?? new Uint8Array()),
-        footnoteCollection,
-      );
-      normalizeFootnoteCollectionOpaqueBlocks(
-        footnoteCollection,
-        "endnote",
-        normalizedDocument.preservation.opaqueFragments,
-        normalizedDocument.diagnostics.warnings,
-        endnotesPartPath,
-        subPartOpaqueState,
-      );
-    }
-
-    const themeRelationship = documentPart.relationships.find(
-      (r) => r.type === "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" &&
-        r.targetMode === "internal",
-    );
-    const themePartPath = themeRelationship
-      ? resolveRelationshipTarget(mainDocumentPath, themeRelationship)
-      : undefined;
-    const parsedTheme =
-      themePartPath && sourcePackage.parts.has(themePartPath)
-        ? parseThemeXml(
-            decodeUtf8(sourcePackage.parts.get(themePartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-    const resolvedTheme = parsedTheme ? resolveTheme(parsedTheme) : undefined;
-    const settingsPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      SETTINGS_RELATIONSHIP_TYPE,
-      SETTINGS_PART_PATH,
-    );
-    const parsedSettings =
-      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-        ? parseSettingsXml(
-            decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array()),
-          )
-        : undefined;
-    const settingsXmlForProtection =
-      settingsPartPath && sourcePackage.parts.has(settingsPartPath)
-        ? decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array())
-        : "";
-    const documentProtection = extractDocumentProtection(settingsXmlForProtection);
-    const importedProtectionSnapshot = buildProtectionSnapshot(documentProtection, protectionRanges);
-
-    // ---- Parse styles.xml for canonical style catalog ----
-    const stylesPartPath = resolveDocumentRelatedPartPath(
-      sourcePackage,
-      mainDocumentPath,
-      documentPart.relationships,
-      STYLES_RELATIONSHIP_TYPE,
-      STYLES_PART_PATH,
-    );
-    const parsedStyles =
-      stylesPartPath && sourcePackage.parts.has(stylesPartPath)
-        ? parseStylesXml(
-            decodeUtf8(sourcePackage.parts.get(stylesPartPath)?.bytes ?? new Uint8Array()),
-          )
-        : parseStylesXml("");
-
-    const subParts: SubPartsCatalog | undefined =
-      parsedHeaders.length > 0 ||
-      parsedFooters.length > 0 ||
-      footnoteCollection !== undefined ||
-      parsedTheme !== undefined ||
-      normalizedDocument.finalSectionProperties !== undefined ||
-      resolvedTheme !== undefined ||
-      parsedSettings !== undefined
-        ? {
-            headers: parsedHeaders,
-            footers: parsedFooters,
-            ...(footnoteCollection !== undefined ? { footnoteCollection } : {}),
-            ...(parsedTheme !== undefined ? { theme: parsedTheme } : {}),
-            ...(normalizedDocument.finalSectionProperties !== undefined
-              ? { finalSectionProperties: normalizedDocument.finalSectionProperties }
-              : {}),
-            ...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
-            ...(parsedSettings !== undefined ? { settings: parsedSettings } : {}),
-          }
-        : undefined;
-
-    const timestamp = new Date().toISOString();
-    const document = createImportedCanonicalDocument({
-      documentId: options.documentId,
-      timestamp,
-      numbering: parsedNumbering,
-      media: normalizedDocument.media,
-      content: normalizedDocument.content,
-      subParts,
-      parsedStyles,
-      preservation: {
-        ...normalizedDocument.preservation,
-        packageParts: {
-          ...normalizedDocument.preservation.packageParts,
-          ...collectPreservedPackageParts(sourcePackage, [
-            mainDocumentPath,
-            numberingPartPath,
-            commentsPartPath,
-            commentsExtendedPartPath,
-            commentsIdsPartPath,
-            peoplePartPath,
-          ]),
-        },
-      },
-      diagnostics: {
-        warnings: [
-          ...createBrokenRelationshipWarnings(sourcePackage, mainDocumentPath),
-          ...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,
-      timestamp,
-      document,
-      compatibility: toPublicCompatibilityReport(compatibility),
-      protectionSnapshot: importedProtectionSnapshot,
-      sourcePackage: createPersistedSourcePackage(sourceBytes, options.sourceLabel),
-    });
-    const snapshotIssues = validatePersistedEditorSnapshot(snapshot);
-    if (snapshotIssues.length > 0) {
-      const firstIssue = snapshotIssues[0];
-      return createDiagnosticsSession(
-        options,
-        createValidationImportDiagnostics({
-          message: `DOCX import produced an invalid editor state during validation${firstIssue ? ` (${firstIssue.path}: ${firstIssue.message})` : "."}`,
-          source: "import",
-          details: {
-            issueCount: snapshotIssues.length,
-            firstIssuePath: firstIssue?.path,
-          },
-        }),
-      );
-    }
-    const initialSessionState = editorSessionStateFromPersistedSnapshot(snapshot);
-    const importedState: ImportedDocxState = {
-      sourceBytes: new Uint8Array(sourceBytes),
-      sourcePackage,
-      sourceDocumentPartPath: mainDocumentPath,
-      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,
-      protectionSnapshot: buildProtectionSnapshot(documentProtection, protectionRanges),
-      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 {
-      initialSessionState,
-      initialSnapshot: snapshot,
-      readOnly: false,
-      protectionSnapshot: importedProtectionSnapshot,
-      exportDocx: async (nextSessionState, exportOptions) =>
-        exportDocxEditorSession(importedState, nextSessionState, exportOptions),
-    };
-  } catch (error) {
-    return createDiagnosticsSession(
-      options,
-      createImportDiagnosticsFromError(error),
-    );
-  }
-}
-
-function exportDocxEditorSession(
-  state: ImportedDocxState,
-  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
-  options?: ExportDocxOptions,
-): ExportResult {
-  const sessionState = toEditorSessionState(sessionStateOrSnapshot);
-
-  if (sessionState.compatibility.blockExport) {
-    throw new Error("DOCX export is blocked by the current compatibility report.");
-  }
-
-  const currentDocument = sessionState.canonicalDocument as CanonicalDocumentEnvelope;
-  const signatureMatch = serializeCanonicalDocumentForExport(currentDocument) ===
-      state.initialCanonicalSignature;
-  const canReuse = canReuseSourceBytesForCurrentDocument(state, currentDocument);
-  const commentCount = Object.keys(currentDocument.review?.comments ?? {}).length;
-
-  if (signatureMatch && canReuse) {
-    return {
-      bytes: new Uint8Array(state.sourceBytes),
-      mimeType: DOCX_MIME_TYPE,
-      fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
-      delivery: {
-        mode: "exported-bytes-only",
-      },
-    };
-  }
-  const preservedCommentIds = new Set(
-    state.preservedCommentDefinitions.map((definition) => definition.commentId),
-  );
-  const blockingCommentCount = Math.max(
-    state.blockingCommentDiagnostics.length,
-    preservedCommentIds.size,
-  );
-  if (blockingCommentCount > 0) {
-    throw new Error(
-      `DOCX export is blocked because ${blockingCommentCount} 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 secondaryStoryActionableRevisions = actionableRevisions.filter(
-    (revision) => revision.metadata.storyTarget?.kind && revision.metadata.storyTarget.kind !== "main",
-  );
-  if (secondaryStoryActionableRevisions.length > 0) {
-    throw new Error(
-      `DOCX export is blocked because ${secondaryStoryActionableRevisions.length} secondary-story tracked changes cannot yet be serialized safely.`,
-    );
-  }
-  const commentThreads = Object.values(
-    createCommentStoreFromRuntimeComments(currentDocument.review.comments).threads,
-  );
-  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,
-      finalSectionProperties: currentDocument.subParts?.finalSectionProperties,
-    },
-  );
-  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 protectedDocumentXml = serializeProtectionRangesIntoDocumentXml(
-    annotatedDocument.documentXml,
-    state.protectionSnapshot,
-  );
-  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 = hasSerializableNumberingEntries(
-    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, [
-    state.sourceDocumentPartPath,
-    APP_PROPERTIES_PART_PATH,
-    CORE_PROPERTIES_PART_PATH,
-    numberingPartPath,
-    commentsPartPath,
-    commentsExtendedPartPath,
-    commentsIdsPartPath,
-    peoplePartPath,
-    ...subPartOwnedPaths,
-  ]);
-
-  exportSession.replaceOwnedPart({
-    path: state.sourceDocumentPartPath,
-    bytes: new TextEncoder().encode(protectedDocumentXml),
-    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 ??
-            "application/vnd.openxmlformats-officedocument.theme+xml",
-          relationships: sourceThemePart.relationships,
-          compression: sourceThemePart.compression,
-        });
-      }
-    }
-  }
-
-  ensureHostMetadataParts(exportSession, state.sourcePackage, currentDocument);
-
-  return {
-    bytes: exportSession.serialize(),
-    mimeType: DOCX_MIME_TYPE,
-    fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
-    delivery: {
-      mode: "exported-bytes-only",
-    },
-  };
-}
-
-function toEditorSessionState(
-  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
-): EditorSessionState {
-  return "sessionVersion" in sessionStateOrSnapshot
-    ? sessionStateOrSnapshot
-    : editorSessionStateFromPersistedSnapshot(sessionStateOrSnapshot);
-}
-
-function createImportedCanonicalDocument(input: {
-  documentId: string;
-  timestamp: string;
-  numbering: CanonicalDocumentEnvelope["numbering"];
-  media: CanonicalDocumentEnvelope["media"];
-  content: CanonicalDocumentEnvelope["content"];
-  subParts?: SubPartsCatalog;
-  parsedStyles?: ParseStylesResult;
-  preservation: CanonicalDocumentEnvelope["preservation"];
-  diagnostics: CanonicalDocumentEnvelope["diagnostics"];
-  review: CanonicalDocumentEnvelope["review"];
-}): CanonicalDocumentEnvelope {
-  const numbering = ensureImportedNumberingCatalogSupportsContent(
-    input.numbering,
-    input.content,
-  );
-
-  // Use package-backed style catalog when available; fall back to synthetic
-  // styles derived from referenced styleId values when styles.xml is missing
-  // or could not be parsed.
-  const styles = buildStylesCatalog(input.parsedStyles, input.content, input.subParts);
-
-  return {
-    schemaVersion: "cds/1.0.0",
-    docId: createCanonicalDocumentId(input.documentId),
-    createdAt: input.timestamp,
-    updatedAt: input.timestamp,
-    metadata: {
-      customProperties: {},
-    },
-    styles,
-    numbering,
-    media: input.media,
-    content: input.content,
-    review: input.review,
-    preservation: input.preservation,
-    diagnostics: input.diagnostics,
-    ...(input.subParts !== undefined ? { subParts: input.subParts } : {}),
-  };
-}
-
-type SubPartOpaqueImportState = {
-  nextFragmentIndex: number;
-  nextWarningIndex: number;
-  nextDiagnosticIndex: number;
-  cursor: number;
-};
-
-function createSubPartOpaqueImportState(
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-): SubPartOpaqueImportState {
-  const maxByPrefix = (values: Iterable<string>, prefix: string): number => {
-    let max = 0;
-    for (const value of values) {
-      const match = new RegExp(`^${prefix}(\\d+)$`).exec(value);
-      if (!match) {
-        continue;
-      }
-      const parsed = Number.parseInt(match[1] ?? "0", 10);
-      if (Number.isFinite(parsed) && parsed > max) {
-        max = parsed;
-      }
-    }
-    return max;
-  };
-
-  const maxCursor = Object.values(opaqueFragments).reduce(
-    (currentMax, fragment) => Math.max(currentMax, fragment.lastKnownRange?.to ?? 0),
-    0,
-  );
-
-  return {
-    nextFragmentIndex:
-      maxByPrefix(Object.keys(opaqueFragments), "fragment:import-") + 1,
-    nextWarningIndex:
-      maxByPrefix(
-        [
-          ...Object.values(opaqueFragments).map((fragment) => fragment.warningId),
-          ...warnings.map((warning) => warning.warningId),
-        ],
-        "warning:import-",
-      ) + 1,
-    nextDiagnosticIndex:
-      maxByPrefix(warnings.map((warning) => warning.diagnosticId), "diagnostic:import-") + 1,
-    cursor: maxCursor,
-  };
-}
-
-function normalizeSubPartOpaqueBlocks(
-  blocks: BlockNode[],
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-  packagePartName: string,
-  state: SubPartOpaqueImportState,
-): BlockNode[] {
-  return blocks.map((block) => {
-    if (block.type !== "opaque_block" || typeof block.rawXml !== "string") {
-      return block;
-    }
-    return recordImportedOpaqueBlock(
-      block.rawXml,
-      opaqueFragments,
-      warnings,
-      packagePartName,
-      state,
-    );
-  });
-}
-
-function normalizeFootnoteCollectionOpaqueBlocks(
-  collection: FootnoteCollection | undefined,
-  kind: "footnote" | "endnote",
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-  packagePartName: string,
-  state: SubPartOpaqueImportState,
-): void {
-  if (!collection) {
-    return;
-  }
-  const notes = kind === "footnote" ? collection.footnotes : collection.endnotes;
-  for (const definition of Object.values(notes)) {
-    definition.blocks = normalizeSubPartOpaqueBlocks(
-      definition.blocks,
-      opaqueFragments,
-      warnings,
-      packagePartName,
-      state,
-    );
-  }
-}
-
-function recordImportedOpaqueBlock(
-  rawXml: string,
-  opaqueFragments: Record<string, OpaqueFragmentRecord>,
-  warnings: CanonicalDocumentEnvelope["diagnostics"]["warnings"],
-  packagePartName: string,
-  state: SubPartOpaqueImportState,
-): BlockNode {
-  const fragmentId = `fragment:import-${state.nextFragmentIndex}`;
-  state.nextFragmentIndex += 1;
-  const warningId = `warning:import-${state.nextWarningIndex}`;
-  state.nextWarningIndex += 1;
-  const diagnosticId = `diagnostic:import-${state.nextDiagnosticIndex}`;
-  state.nextDiagnosticIndex += 1;
-
-  const rangeStart = state.cursor;
-  const rangeEnd = state.cursor + 1;
-  state.cursor = rangeEnd;
-
-  opaqueFragments[fragmentId] = {
-    fragmentId,
-    payloadKind: "xml-subtree",
-    payloadReference: rawXml,
-    featureClass: "preserve-only",
-    lastKnownRange: {
-      from: rangeStart,
-      to: rangeEnd,
-    },
-    warningId,
-    packagePartName,
-  };
-  warnings.push({
-    diagnosticId,
-    warningId,
-    source: "import",
-    message: "Unsupported sub-part OOXML was preserved as an opaque placeholder.",
-  });
-
-  return {
-    type: "opaque_block",
-    fragmentId,
-    warningId,
-    rawXml,
-  };
-}
-
-// Canonical model styleId validation pattern — styleIds that don't match
-// are excluded from the catalog to avoid snapshot validation failures.
-const VALID_STYLE_ID = /^[A-Za-z_][A-Za-z0-9._-]{0,127}$/;
-
-function buildStylesCatalog(
-  parsedStyles: ParseStylesResult | undefined,
-  content: CanonicalDocumentEnvelope["content"],
-  subParts?: SubPartsCatalog,
-): CanonicalDocumentEnvelope["styles"] {
-  if (parsedStyles?.fromPackage) {
-    // Package-backed catalog: filter entries whose styleId does not satisfy
-    // the canonical model pattern (e.g. numeric-only ids from Word).
-    const catalog = filterValidStyleIds(parsedStyles.catalog);
-
-    // Merge in any referenced styleIds that the package styles.xml did not
-    // define (rare but defensive).
-    const referencedIds = collectReferencedParagraphStyleIds(content, subParts);
-    for (const styleId of referencedIds) {
-      if (!catalog.paragraphs[styleId] && VALID_STYLE_ID.test(styleId)) {
-        catalog.paragraphs[styleId] = {
-          styleId,
-          displayName: styleId,
-          kind: "paragraph",
-          isDefault: styleId === "Normal",
-        };
-      }
-    }
-    return {
-      ...catalog,
-      fromPackage: true,
-    };
-  }
-
-  // Synthetic fallback: no styles.xml available
-  const paragraphStyles = Object.fromEntries(
-    [...collectReferencedParagraphStyleIds(content, subParts)]
-      .sort((left, right) => left.localeCompare(right))
-      .filter((styleId) => VALID_STYLE_ID.test(styleId))
-      .map((styleId) => [
-        styleId,
-        {
-          styleId,
-          displayName: styleId,
-          kind: "paragraph" as const,
-          isDefault: styleId === "Normal",
-        },
-      ]),
-  );
-  return {
-    paragraphs: paragraphStyles,
-    characters: {},
-    tables: {},
-    fromPackage: false,
-  };
-}
-
-function filterValidStyleIds(
-  catalog: CanonicalDocumentEnvelope["styles"],
-): CanonicalDocumentEnvelope["styles"] {
-  const filterRecord = <T extends { styleId: string }>(
-    record: Record<string, T>,
-  ): Record<string, T> => {
-    const result: Record<string, T> = {};
-    for (const [key, value] of Object.entries(record)) {
-      if (VALID_STYLE_ID.test(key)) {
-        result[key] = value;
-      }
-    }
-    return result;
-  };
-
-  return {
-    paragraphs: filterRecord(catalog.paragraphs),
-    characters: filterRecord(catalog.characters),
-    tables: filterRecord(catalog.tables),
-    ...(catalog.latentStyles ? { latentStyles: catalog.latentStyles } : {}),
-    ...(catalog.fromPackage !== undefined ? { fromPackage: catalog.fromPackage } : {}),
-  };
-}
-
-function ensureImportedNumberingCatalogSupportsContent(
-  catalog: NumberingCatalog,
-  content: CanonicalDocumentEnvelope["content"],
-): NumberingCatalog {
-  if (
-    catalog.instances[DOCX_NULL_NUMBERING_INSTANCE_ID] ||
-    !collectReferencedNumberingInstanceIds(content).has(DOCX_NULL_NUMBERING_INSTANCE_ID)
-  ) {
-    return catalog;
-  }
-
-  const syntheticNullCatalog = createSyntheticDocxNullNumberingCatalog();
-  return {
-    abstractDefinitions: {
-      ...catalog.abstractDefinitions,
-      ...syntheticNullCatalog.abstractDefinitions,
-    },
-    instances: {
-      ...catalog.instances,
-      ...syntheticNullCatalog.instances,
-    },
-  };
-}
-
-function collectReferencedNumberingInstanceIds(
-  content: CanonicalDocumentEnvelope["content"],
-): Set<string> {
-  const numberingInstanceIds = new Set<string>();
-
-  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
-    for (const block of blocks) {
-      if (block.type === "paragraph" && block.numbering?.numberingInstanceId) {
-        numberingInstanceIds.add(block.numbering.numberingInstanceId);
-      }
-      if (block.type === "table") {
-        for (const row of block.rows) {
-          for (const cell of row.cells) {
-            visitBlocks(cell.children);
-          }
-        }
-      } else if (block.type === "sdt" || block.type === "custom_xml") {
-        visitBlocks(block.children);
-      }
-    }
-  };
-
-  visitBlocks(content.children);
-  return numberingInstanceIds;
-}
-
-function collectReferencedParagraphStyleIds(
-  content: CanonicalDocumentEnvelope["content"],
-  subParts?: SubPartsCatalog,
-): Set<string> {
-  const styleIds = new Set<string>();
-
-  const visitBlocks = (blocks: ReadonlyArray<BlockNode>) => {
-    for (const block of blocks) {
-      if ("styleId" in block && typeof block.styleId === "string" && block.styleId.length > 0) {
-        styleIds.add(block.styleId);
-      }
-      if (block.type === "table") {
-        for (const row of block.rows) {
-          for (const cell of row.cells) {
-            visitBlocks(cell.children);
-          }
-        }
-      } else if (block.type === "sdt" || block.type === "custom_xml") {
-        visitBlocks(block.children);
-      }
-    }
-  };
-
-  visitBlocks(content.children);
-  if (subParts) {
-    for (const header of subParts.headers) {
-      visitBlocks(header.blocks);
-    }
-    for (const footer of subParts.footers) {
-      visitBlocks(footer.blocks);
-    }
-    if (subParts.footnoteCollection) {
-      for (const note of Object.values(subParts.footnoteCollection.footnotes)) {
-        visitBlocks(note.blocks);
-      }
-      for (const note of Object.values(subParts.footnoteCollection.endnotes)) {
-        visitBlocks(note.blocks);
-      }
-    }
-  }
-
-  return styleIds;
-}
-
-function createImportedSnapshot(input: {
-  documentId: string;
-  editorBuild: string;
-  timestamp: string;
-  document: CanonicalDocumentEnvelope;
-  compatibility: PersistedEditorSnapshot["compatibility"];
-  protectionSnapshot: ProtectionSnapshot;
-  sourcePackage?: PersistedEditorSnapshot["sourcePackage"];
-}): PersistedEditorSnapshot {
-  return {
-    snapshotVersion: "persisted-editor-snapshot/2",
-    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,
-    protectionSnapshot: input.protectionSnapshot,
-    sourcePackage: input.sourcePackage,
-  };
-}
-
-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 editorBuild =
-    typeof options.editorBuild === "string" && options.editorBuild.length > 0
-      ? options.editorBuild
-      : "dev";
-  const runtime = createReadOnlyDiagnosticsRuntime({
-    documentId: options.documentId,
-    sourceLabel: options.sourceLabel,
-    editorBuild,
-    generatedAt: timestamp,
-    diagnostics,
-  });
-  const initialSnapshot = runtime.getPersistedSnapshot();
-  const initialSessionState = editorSessionStateFromPersistedSnapshot(initialSnapshot);
-
-  return {
-    initialSessionState,
-    initialSnapshot,
-    fatalError: diagnostics.fatalError,
-    readOnly: true,
-    protectionSnapshot: EMPTY_PROTECTION_SNAPSHOT,
-    exportDocx: async (_sessionState, 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) => {
-      const { anchor } = revision;
-      if (anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
-        return revision;
-      }
-
-      const preserveOnlyReason =
-        getStructuralPreserveOnlyReason(revision, paragraphRanges) ??
-        (opaqueRanges.some((range) => rangesIntersect(range, 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.flatMap((revision) => {
-    const { anchor } = revision;
-    if (
-      anchor.kind !== "range" ||
-      typeof revision.metadata.preserveOnlyReason !== "string" ||
-      revision.metadata.preserveOnlyReason.length === 0
-    ) {
-      return [];
-    }
-    return [anchor.range];
-  });
-  const preserveOnlyCommentIds = new Set(parsed.diagnostics.map((diagnostic) => diagnostic.commentId));
-  const additionalDiagnostics: CommentImportDiagnostic[] = [];
-  const normalizedThreads: CommentThread[] = parsed.threads.map((thread) => {
-    const { anchor } = thread;
-    if (anchor.kind !== "range") {
-      preserveOnlyCommentIds.add(thread.commentId);
-      return thread;
-    }
-
-    const opaqueOverlap = opaqueRanges.some((range) => rangesIntersect(range, 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 content. Thread is visible but detached; anchor cannot be safely remapped.",
-        featureClass: "preserve-only",
-        detachedReason: "opaque-region" as const,
-        actionabilityNote: "The comment body is preserved. The anchor overlaps opaque content that the editor cannot safely modify.",
-      });
-      return {
-        ...thread,
-        anchor: createDetachedAnchor(anchor.range, "importAmbiguity"),
-        status: "detached",
-      };
-    }
-
-    const preserveOnlyRevisionOverlap = preserveOnlyRevisionRanges.some((range) =>
-      rangesIntersect(range, 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. Thread is visible but detached; anchor cannot be safely remapped during editing.",
-        featureClass: "preserve-only",
-        detachedReason: "revision-overlap" as const,
-        actionabilityNote: "The comment body is preserved. The anchor overlaps preserve-only revision markup that the editor cannot safely modify.",
-      });
-      return {
-        ...thread,
-        anchor: createDetachedAnchor(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;
-  const { anchor } = revision;
-  if (!form || anchor.kind !== "range") {
-    return undefined;
-  }
-
-  if (
-    (form === "run-insertion" || form === "run-deletion") &&
-    anchor.range.from === 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 === anchor.range.from ||
-        (anchor.range.from >= boundary.start &&
-          anchor.range.from <= boundary.end),
-    );
-    return paragraphBoundary
-      ? undefined
-      : "Imported revision spans paragraph-level structure and remains preserve-only.";
-  }
-
-  const paragraphBoundary = paragraphRanges.find(
-    (boundary) =>
-      anchor.range.from >= boundary.start &&
-      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<number>((size, child) => {
-    if (child.type === "text") {
-      return size + child.text.length;
-    }
-    if (child.type === "hyperlink") {
-      return (
-        size +
-        child.children.reduce<number>((childSize, entry) => {
-          if (entry.type === "text") {
-            return childSize + entry.text.length;
-          }
-          return childSize + 1;
-        }, 0)
-      );
-    }
-    return size + 1;
-  }, 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,
-  sourceDocumentPartPath: string,
-  relationships: readonly OpcRelationship[],
-): string | undefined {
-  return resolveDocumentRelatedPartPath(
-    sourcePackage,
-    sourceDocumentPartPath,
-    relationships,
-    COMMENTS_RELATIONSHIP_TYPE,
-    COMMENTS_PART_PATH,
-  );
-}
-
-function resolveDocumentRelatedPartPath(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-  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(sourceDocumentPartPath, relationship);
-  return sourcePackage.parts.has(targetPath) ? targetPath : undefined;
-}
-
-function resolveMainDocumentPartPath(sourcePackage: OpcPackage): string | undefined {
-  const relationship = sourcePackage.manifest.packageRelationships.find(
-    (candidate) =>
-      candidate.type === OFFICE_DOCUMENT_RELATIONSHIP_TYPE &&
-      candidate.targetMode === "internal",
-  );
-  if (relationship) {
-    return resolveRelationshipTarget(null, relationship);
-  }
-
-  return sourcePackage.parts.has(MAIN_DOCUMENT_PATH) ? MAIN_DOCUMENT_PATH : 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,
-          storyTarget: revision.metadata.storyTarget,
-          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",
-      storyTarget: revision.metadata?.storyTarget,
-      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 collectBrokenInternalRelationshipIssues(
-  sourcePackage: OpcPackage,
-  mainDocumentPath?: string,
-): 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) &&
-      isFatalBrokenRelationship({
-        relationshipSourcePath: null,
-        relationship,
-        targetPartPath: target,
-        mainDocumentPath,
-      })
-    ) {
-      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) &&
-        isFatalBrokenRelationship({
-          relationshipSourcePath: part.path,
-          relationship,
-          targetPartPath: target,
-          mainDocumentPath,
-        })
-      ) {
-        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 createBrokenRelationshipWarnings(
-  sourcePackage: OpcPackage,
-  mainDocumentPath?: string,
-): CanonicalDocumentEnvelope["diagnostics"]["warnings"] {
-  const warnings = new Map<string, CanonicalDocumentEnvelope["diagnostics"]["warnings"][number]>();
-
-  for (const relationship of sourcePackage.manifest.packageRelationships) {
-    if (relationship.targetMode !== "internal") {
-      continue;
-    }
-
-    const target = resolveRelationshipTarget(null, relationship);
-    if (
-      sourcePackage.parts.has(target) ||
-      isFatalBrokenRelationship({
-        relationshipSourcePath: null,
-        relationship,
-        targetPartPath: target,
-        mainDocumentPath,
-      })
-    ) {
-      continue;
-    }
-
-    warnings.set(`package:${relationship.id}:${target}`, {
-      diagnosticId: `diagnostic:broken-relationship-package-${relationship.id}`,
-      warningId: `warning:broken-relationship:${relationship.id}`,
-      source: "preservation",
-      message: `DOCX package has unresolved internal relationships outside the editor-owned graph: ${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) ||
-        isFatalBrokenRelationship({
-          relationshipSourcePath: part.path,
-          relationship,
-          targetPartPath: target,
-          mainDocumentPath,
-        })
-      ) {
-        continue;
-      }
-
-      warnings.set(`${part.path}:${relationship.id}:${target}`, {
-        diagnosticId: `diagnostic:broken-relationship-${relationship.id}`,
-        warningId: `warning:broken-relationship:${relationship.id}`,
-        source: "preservation",
-        message: `DOCX package has unresolved internal relationships outside the editor-owned graph: ${target}.`,
-      });
-    }
-  }
-
-  return [...warnings.values()];
-}
-
-function isFatalBrokenRelationship(input: {
-  relationshipSourcePath: string | null;
-  relationship: OpcRelationship;
-  targetPartPath: string;
-  mainDocumentPath?: string;
-}): boolean {
-  return (
-    input.relationshipSourcePath === null &&
-    input.relationship.type === OFFICE_DOCUMENT_RELATIONSHIP_TYPE &&
-    input.targetPartPath === input.mainDocumentPath
-  );
-}
-
-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 (
-    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",
-  "/word/numbering.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 };
-}
-
-const UTF8_DECODER = new TextDecoder("utf-8");
-
-function decodeUtf8(bytes: Uint8Array | undefined): string {
-  if (!bytes) {
-    return "";
-  }
-
-  return UTF8_DECODER.decode(bytes);
-}
-
-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 {
-  if (requiresHostMetadataNormalization(state.sourcePackage, state.sourceDocumentPartPath)) {
-    return false;
-  }
-
-  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,
-  );
-}
-
-function requiresHostMetadataNormalization(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-): boolean {
-  return (
-    isSuspiciouslySkeletalWordPackage(sourcePackage, sourceDocumentPartPath) &&
-    !hasHostSafeMetadataPackageStructure(sourcePackage)
-  );
-}
-
-function ensureHostMetadataParts(
-  exportSession: ReturnType<typeof createExportSession>,
-  sourcePackage: OpcPackage,
-  document: CanonicalDocumentEnvelope,
-): void {
-  const corePropertiesPart = sourcePackage.parts.get(CORE_PROPERTIES_PART_PATH);
-  if (!corePropertiesPart || corePropertiesPart.contentType !== CORE_PROPERTIES_CONTENT_TYPE) {
-    exportSession.replaceOwnedPart({
-      path: CORE_PROPERTIES_PART_PATH,
-      bytes: corePropertiesPart?.bytes ?? new TextEncoder().encode(buildCorePropertiesXml(document)),
-      contentType: CORE_PROPERTIES_CONTENT_TYPE,
-      compression: corePropertiesPart?.compression,
-    });
-  }
-
-  const appPropertiesPart = sourcePackage.parts.get(APP_PROPERTIES_PART_PATH);
-  if (!appPropertiesPart || appPropertiesPart.contentType !== APP_PROPERTIES_CONTENT_TYPE) {
-    exportSession.replaceOwnedPart({
-      path: APP_PROPERTIES_PART_PATH,
-      bytes: appPropertiesPart?.bytes ?? new TextEncoder().encode(buildAppPropertiesXml()),
-      contentType: APP_PROPERTIES_CONTENT_TYPE,
-      compression: appPropertiesPart?.compression,
-    });
-  }
-
-  exportSession.ensurePackageRelationship({
-    type: CORE_PROPERTIES_RELATIONSHIP_TYPE,
-    target: CORE_PROPERTIES_PART_PATH,
-    preferredId: "rIdDocPropsCore",
-  });
-  exportSession.ensurePackageRelationship({
-    type: APP_PROPERTIES_RELATIONSHIP_TYPE,
-    target: APP_PROPERTIES_PART_PATH,
-    preferredId: "rIdDocPropsApp",
-  });
-}
-
-function hasHostSafeMetadataPackageStructure(sourcePackage: OpcPackage): boolean {
-  const corePropertiesPart = sourcePackage.parts.get(CORE_PROPERTIES_PART_PATH);
-  const appPropertiesPart = sourcePackage.parts.get(APP_PROPERTIES_PART_PATH);
-  return (
-    corePropertiesPart?.contentType === CORE_PROPERTIES_CONTENT_TYPE &&
-    appPropertiesPart?.contentType === APP_PROPERTIES_CONTENT_TYPE &&
-    hasPackageRelationshipTarget(
-      sourcePackage,
-      CORE_PROPERTIES_RELATIONSHIP_TYPE,
-      CORE_PROPERTIES_PART_PATH,
-    ) &&
-    hasPackageRelationshipTarget(
-      sourcePackage,
-      APP_PROPERTIES_RELATIONSHIP_TYPE,
-      APP_PROPERTIES_PART_PATH,
-    )
-  );
-}
-
-function hasPackageRelationshipTarget(
-  sourcePackage: OpcPackage,
-  relationshipType: string,
-  targetPartPath: string,
-): boolean {
-  return sourcePackage.manifest.packageRelationships.some(
-    (relationship) =>
-      relationship.type === relationshipType &&
-      relationship.targetMode === "internal" &&
-      resolveRelationshipTarget(null, relationship) === targetPartPath,
-  );
-}
-
-function isSuspiciouslySkeletalWordPackage(
-  sourcePackage: OpcPackage,
-  sourceDocumentPartPath: string,
-): boolean {
-  const allowedPaths = new Set<string>([
-    CONTENT_TYPES_PATH,
-    PACKAGE_RELATIONSHIPS_PATH,
-    sourceDocumentPartPath,
-  ]);
-  const relationshipsPartPath = getRelationshipsPartPath(sourceDocumentPartPath);
-  if (relationshipsPartPath) {
-    allowedPaths.add(relationshipsPartPath);
-  }
-
-  return [...sourcePackage.parts.keys()].every((partPath) => allowedPaths.has(partPath));
-}
-
-function buildCorePropertiesXml(document: CanonicalDocumentEnvelope): string {
-  const { metadata } = document;
-  const keywords =
-    Array.isArray(metadata.keywords) && metadata.keywords.length > 0
-      ? metadata.keywords.join(", ")
-      : undefined;
-  const propertyLines = [
-    xmlNode("dc:title", metadata.title),
-    xmlNode("dc:subject", metadata.subject),
-    xmlNode("dc:description", metadata.description),
-    xmlNode("dc:language", metadata.language),
-    xmlNode("cp:keywords", keywords),
-    xmlNode("cp:category", metadata.category),
-    xmlNode('dcterms:created xsi:type="dcterms:W3CDTF"', document.createdAt),
-    xmlNode('dcterms:modified xsi:type="dcterms:W3CDTF"', document.updatedAt),
-  ].filter((line): line is string => Boolean(line));
-
-  return [
-    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
-    `<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">`,
-    ...propertyLines.map((line) => `  ${line}`),
-    `</cp:coreProperties>`,
-  ].join("\n");
-}
-
-function buildAppPropertiesXml(): string {
-  return [
-    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
-    `<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">`,
-    `  <Application>React OOXML Office</Application>`,
-    `  <AppVersion>1.0</AppVersion>`,
-    `</Properties>`,
-  ].join("\n");
-}
-
-function xmlNode(tagName: string, value: string | undefined): string | undefined {
-  if (typeof value !== "string" || value.length === 0) {
-    return undefined;
-  }
-
-  return `<${tagName}>${escapeXml(value)}</${tagName.split(" ", 1)[0]}>`;
-}
-
-function serializeProtectionRangesIntoDocumentXml(
-  documentXml: string,
-  protection: ProtectionSnapshot,
-  paragraphs = mapParagraphBoundaries(documentXml),
-): string {
-  if (protection.ranges.length === 0) {
-    return documentXml;
-  }
-
-  const insertions = new Map<number, string[]>();
-
-  for (const range of protection.ranges) {
-    if (typeof range.start !== "number" || typeof range.end !== "number") {
-      continue;
-    }
-    const rangeStart = range.start;
-    const rangeEnd = range.end;
-
-    const startParagraph = paragraphs.find(
-      (candidate) => rangeStart >= candidate.start && rangeStart <= candidate.end,
-    );
-    const endParagraph = paragraphs.find(
-      (candidate) => rangeEnd >= candidate.start && rangeEnd <= candidate.end,
-    );
-    if (!startParagraph || !endParagraph) {
-      continue;
-    }
-
-    const startIndex =
-      startParagraph.boundaries.get(rangeStart) ??
-      findNearestBoundaryIndex(startParagraph.boundaries, rangeStart, "backward");
-    const endIndex =
-      endParagraph.boundaries.get(rangeEnd) ??
-      findNearestBoundaryIndex(endParagraph.boundaries, rangeEnd, "forward");
-    if (startIndex === undefined || endIndex === undefined) {
-      continue;
-    }
-
-    const permStartXml = [
-      `<w:permStart`,
-      ` w:id="${escapeXmlAttribute(range.rangeId)}"`,
-      range.editorGroup ? ` w:edGrp="${escapeXmlAttribute(range.editorGroup)}"` : "",
-      range.editor ? ` w:ed="${escapeXmlAttribute(range.editor)}"` : "",
-      `/>`,
-    ].join("");
-    const permEndXml = `<w:permEnd w:id="${escapeXmlAttribute(range.rangeId)}"/>`;
-
-    pushProtectionInsertion(insertions, startIndex, permStartXml);
-    pushProtectionInsertion(insertions, endIndex, permEndXml);
-  }
-
-  if (insertions.size === 0) {
-    return documentXml;
-  }
-
-  const parts: string[] = [];
-  let cursor = 0;
-  for (const [index, snippets] of [...insertions.entries()].sort(([left], [right]) => left - right)) {
-    parts.push(documentXml.slice(cursor, index));
-    parts.push(...snippets);
-    cursor = index;
-  }
-  parts.push(documentXml.slice(cursor));
-  return parts.join("");
-}
-
-function pushProtectionInsertion(
-  insertions: Map<number, string[]>,
-  index: number,
-  xml: string,
-): void {
-  const existing = insertions.get(index);
-  if (existing) {
-    existing.push(xml);
-    return;
-  }
-  insertions.set(index, [xml]);
-}
-
-function findNearestBoundaryIndex(
-  boundaries: Map<number, number>,
-  position: number,
-  direction: "backward" | "forward",
-): number | undefined {
-  const ordered = [...boundaries.entries()].sort(([left], [right]) => left - right);
-  if (direction === "backward") {
-    for (let index = ordered.length - 1; index >= 0; index -= 1) {
-      const [boundaryPos, boundaryIndex] = ordered[index]!;
-      if (boundaryPos <= position) {
-        return boundaryIndex;
-      }
-    }
-    return undefined;
-  }
-  for (const [boundaryPos, boundaryIndex] of ordered) {
-    if (boundaryPos >= position) {
-      return boundaryIndex;
-    }
-  }
-  return undefined;
-}
-
-function escapeXml(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/\"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
-function escapeXmlAttribute(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-// ---------------------------------------------------------------------------
-// Protection range extraction
-// ---------------------------------------------------------------------------
-
-const EMPTY_PROTECTION_SNAPSHOT: ProtectionSnapshot = {
-  hasDocumentProtection: false,
-  enforcementActive: false,
-  ranges: [],
-  enforcedRangeCount: 0,
-  preservedRangeCount: 0,
-};
-
-interface DocumentProtectionMeta {
-  editType?: string;
-  enforcement: boolean;
-}
-
-function extractDocumentProtection(settingsXml: string): DocumentProtectionMeta {
-  if (!settingsXml) return { enforcement: false };
-  const match = settingsXml.match(/<w:documentProtection\b([^/>]*)\/?>/);
-  if (!match) return { enforcement: false };
-  const attrs = match[1];
-  const editTypeMatch = attrs.match(/w:edit="([^"]*)"/);
-  const enforcementMatch = attrs.match(/w:enforcement="([^"]*)"/);
-  const editType = editTypeMatch?.[1];
-  const enforcement = enforcementMatch?.[1] === "1" || enforcementMatch?.[1] === "true";
-  return { editType, enforcement };
-}
-
-function extractProtectionRanges(blocks: readonly ParsedBlockNode[]): ProtectionRange[] {
-  const ranges: ProtectionRange[] = [];
-  const openRanges = new Map<string, Omit<ProtectionRange, "end">>();
-  collectProtectionRangesFromBlocks(blocks, ranges, openRanges, 0);
-  return ranges;
-}
-
-function collectProtectionRangesFromBlocks(
-  blocks: readonly ParsedBlockNode[],
-  ranges: ProtectionRange[],
-  openRanges: Map<string, Omit<ProtectionRange, "end">>,
-  cursor: number,
-): number {
-  let nextCursor = cursor;
-  let previousParagraph = false;
-
-  for (const block of blocks) {
-    if (block.type === "paragraph") {
-      if (previousParagraph) {
-        nextCursor += 1;
-      }
-      nextCursor = collectProtectionRangesFromInlines(
-        block.children,
-        ranges,
-        openRanges,
-        nextCursor,
-      );
-      previousParagraph = true;
-      continue;
-    }
-
-    if (block.type === "table") {
-      nextCursor += 1;
-      previousParagraph = false;
-      for (const row of block.rows) {
-        for (const cell of row.cells) {
-          nextCursor = collectProtectionRangesFromBlocks(
-            cell.children,
-            ranges,
-            openRanges,
-            nextCursor,
-          );
-        }
-      }
-      continue;
-    }
-
-    if (block.type === "sdt" || block.type === "custom_xml") {
-      nextCursor = collectProtectionRangesFromBlocks(
-        block.children,
-        ranges,
-        openRanges,
-        nextCursor,
-      );
-      previousParagraph = false;
-      continue;
-    }
-
-    nextCursor += 1;
-    previousParagraph = false;
-  }
-
-  return nextCursor;
-}
-
-function collectProtectionRangesFromInlines(
-  nodes: readonly ParsedInlineNode[],
-  ranges: ProtectionRange[],
-  openRanges: Map<string, Omit<ProtectionRange, "end">>,
-  cursor: number,
-): number {
-  let nextCursor = cursor;
-
-  for (const node of nodes) {
-    if (node.type === "perm_start") {
-      openRanges.set(node.rangeId, {
-        rangeId: node.rangeId,
-        start: nextCursor,
-        ...(node.editorGroup ? { editorGroup: node.editorGroup } : {}),
-        ...(node.editor ? { editor: node.editor } : {}),
-        enforced: false,
-        enforcementReason:
-          "preserve-only: runtime does not yet enforce permission range boundaries",
-      });
-      continue;
-    }
-
-    if (node.type === "perm_end") {
-      const openRange = openRanges.get(node.rangeId);
-      if (openRange) {
-        ranges.push({
-          ...openRange,
-          end: nextCursor,
-        });
-        openRanges.delete(node.rangeId);
-      }
-      continue;
-    }
-
-    nextCursor += measureParsedInlineNode(node);
-  }
-
-  return nextCursor;
-}
-
-function measureParsedInlineNode(node: ParsedInlineNode): number {
-  switch (node.type) {
-    case "text":
-      return node.text.length;
-    case "tab":
-    case "hard_break":
-    case "column_break":
-    case "footnote_ref":
-    case "image":
-    case "bookmark_start":
-    case "bookmark_end":
-      return 1;
-    case "hyperlink":
-      return node.children.reduce((size, child) => size + measureParsedInlineNode(child), 0);
-    case "field": {
-      const content = parseMainDocumentXml(
-        `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p>${node.contentXml}</w:p></w:body></w:document>`,
-      );
-      if (content.blocks[0]?.type === "paragraph") {
-        return content.blocks[0].children.reduce(
-          (size, child) => size + measureParsedInlineNode(child),
-          0,
-        );
-      }
-      return 1;
-    }
-    default:
-      return 1;
-  }
-}
-
-function buildProtectionSnapshot(
-  documentProtection: DocumentProtectionMeta,
-  ranges: ProtectionRange[],
-): ProtectionSnapshot {
-  const hasDocumentProtection =
-    documentProtection.editType !== undefined || documentProtection.enforcement;
-  const enforceRanges =
-    documentProtection.editType === "readOnly" || documentProtection.editType === "comments";
-  const normalizedRanges = ranges.map((range) => {
-    const canEnforce =
-      hasDocumentProtection &&
-      documentProtection.enforcement &&
-      enforceRanges &&
-      typeof range.start === "number" &&
-      typeof range.end === "number" &&
-      range.end >= range.start;
-    return {
-      ...range,
-      enforced: canEnforce,
-      enforcementReason: canEnforce
-        ? "runtime-enforced: permission range is mapped to canonical positions"
-        : "preserve-only: runtime does not yet enforce permission range boundaries",
-    };
-  });
-  return {
-    hasDocumentProtection,
-    editType: documentProtection.editType,
-    enforcementActive: documentProtection.enforcement,
-    ranges: normalizedRanges,
-    enforcedRangeCount: normalizedRanges.filter((r) => r.enforced).length,
-    preservedRangeCount: normalizedRanges.filter((r) => !r.enforced).length,
-  };
-}