@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/io/docx-session.ts

@@ -1,12 +1,16 @@
 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,
@@ -23,7 +27,12 @@ import {
 } from "../core/selection/mapping.ts";
 import { DOCX_MIME_TYPE } from "./opc/docx-package.ts";
 import { readOpcPackage, type OpcPackage } from "./opc/package-reader.ts";
-import { parseMainDocumentXml } from "./ooxml/parse-main-document.ts";
+import {
+  parseMainDocumentXml,
+  type ParsedBlockNode,
+  type ParsedInlineNode,
+  type ParsedPermStartInlineNode,
+} from "./ooxml/parse-main-document.ts";
 import { normalizeParsedTextDocument } from "./normalize/normalize-text.ts";
 import {
   CONTENT_TYPES_PATH,
@@ -45,6 +54,7 @@ import { parseCommentsFromOoxml } from "./ooxml/parse-comments.ts";
 import { parseNumberingXml } from "./ooxml/parse-numbering.ts";
 import {
   createCommentExportIdMap,
+  mapParagraphBoundaries,
   serializeCommentAnchorsIntoDocumentXml,
   serializeMergedCommentsXml,
 } from "./export/serialize-comments.ts";
@@ -80,6 +90,7 @@ import type {
 import { createReadOnlyDiagnosticsRuntime } from "../runtime/read-only-diagnostics-runtime.ts";
 import {
   WORD_NUMBERING_CONTENT_TYPE,
+  hasSerializableNumberingEntries,
   serializeNumberingXml,
 } from "./export/serialize-numbering.ts";
 import {
@@ -89,6 +100,9 @@ import {
 } 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,
@@ -102,6 +116,11 @@ import {
   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";
@@ -149,22 +168,30 @@ 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;
+  editorBuild?: string;
 }
 
 export interface LoadedDocxEditorSession {
+  initialSessionState: EditorSessionState;
   initialSnapshot: PersistedEditorSnapshot;
   fatalError?: EditorError;
   readOnly: boolean;
+  protectionSnapshot: ProtectionSnapshot;
   exportDocx: (
-    snapshot: PersistedEditorSnapshot,
+    sessionState: EditorSessionState | PersistedEditorSnapshot,
     options?: ExportDocxOptions,
   ) => Promise<ExportResult>;
 }
@@ -190,6 +217,7 @@ interface ImportedDocxState {
   sourcePeopleRelationshipId?: string;
   sourcePeopleRootTag?: string;
   sourcePeopleAuthors: readonly string[];
+  protectionSnapshot: ProtectionSnapshot;
   preservedCommentDefinitions: readonly ImportedCommentDefinition[];
   blockingCommentDiagnostics: readonly CommentImportDiagnostic[];
   initialCanonicalSignature: string;
@@ -220,6 +248,10 @@ const BLOCKING_COMMENT_DIAGNOSTIC_CODES = new Set<CommentImportDiagnostic["code"
 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;
 
@@ -304,6 +336,7 @@ export function loadDocxEditorSession(
       mediaParts,
       mainDocumentPath,
     );
+    const protectionRanges = extractProtectionRanges(parsedDocument.blocks);
     const normalizedDocument = normalizeParsedTextDocument(
       parsedDocument,
       mainDocumentPath,
@@ -376,13 +409,14 @@ export function loadDocxEditorSession(
     const parsedFooters: FooterDocument[] = [];
     const sourceHeaderPaths: Array<{ partPath: string; relationshipId: string }> = [];
     const sourceFooterPaths: Array<{ partPath: string; relationshipId: string }> = [];
-    const seenSubPartRelIds = new Set<string>();
+    const seenSubPartKeys = new Set<string>();
 
     for (const ref of headerFooterRefs) {
-      if (seenSubPartRelIds.has(ref.relationshipId)) {
+      const dedupeKey = `${ref.kind}:${ref.variant}:${ref.relationshipId}`;
+      if (seenSubPartKeys.has(dedupeKey)) {
         continue;
       }
-      seenSubPartRelIds.add(ref.relationshipId);
+      seenSubPartKeys.add(dedupeKey);
 
       const relationship = documentPart.relationships.find(
         (r) => r.id === ref.relationshipId && r.targetMode === "internal",
@@ -404,6 +438,7 @@ export function loadDocxEditorSession(
           variant: ref.variant,
           partPath,
           relationshipId: ref.relationshipId,
+          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
           blocks: parsed.blocks,
         });
         sourceHeaderPaths.push({ partPath, relationshipId: ref.relationshipId });
@@ -413,6 +448,7 @@ export function loadDocxEditorSession(
           variant: ref.variant,
           partPath,
           relationshipId: ref.relationshipId,
+          ...(ref.sectionIndex !== undefined ? { sectionIndex: ref.sectionIndex } : {}),
           blocks: parsed.blocks,
         });
         sourceFooterPaths.push({ partPath, relationshipId: ref.relationshipId });
@@ -466,17 +502,60 @@ export function loadDocxEditorSession(
             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
+      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;
 
@@ -488,6 +567,7 @@ export function loadDocxEditorSession(
       media: normalizedDocument.media,
       content: normalizedDocument.content,
       subParts,
+      parsedStyles,
       preservation: {
         ...normalizedDocument.preservation,
         packageParts: {
@@ -532,12 +612,29 @@ export function loadDocxEditorSession(
     });
     const snapshot = createImportedSnapshot({
       documentId: options.documentId,
-      editorBuild: options.editorBuild,
+      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,
@@ -579,6 +676,7 @@ export function loadDocxEditorSession(
       )?.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),
@@ -597,10 +695,12 @@ export function loadDocxEditorSession(
     };
 
     return {
+      initialSessionState,
       initialSnapshot: snapshot,
       readOnly: false,
-      exportDocx: async (nextSnapshot, exportOptions) =>
-        exportDocxEditorSession(importedState, nextSnapshot, exportOptions),
+      protectionSnapshot: importedProtectionSnapshot,
+      exportDocx: async (nextSessionState, exportOptions) =>
+        exportDocxEditorSession(importedState, nextSessionState, exportOptions),
     };
   } catch (error) {
     return createDiagnosticsSession(
@@ -612,28 +712,41 @@ export function loadDocxEditorSession(
 
 function exportDocxEditorSession(
   state: ImportedDocxState,
-  snapshot: PersistedEditorSnapshot,
+  sessionStateOrSnapshot: EditorSessionState | PersistedEditorSnapshot,
   options?: ExportDocxOptions,
 ): ExportResult {
-  if (snapshot.compatibility.blockExport) {
+  const sessionState = toEditorSessionState(sessionStateOrSnapshot);
+
+  if (sessionState.compatibility.blockExport) {
     throw new Error("DOCX export is blocked by the current compatibility report.");
   }
 
-  const currentDocument = snapshot.canonicalDocument as CanonicalDocumentEnvelope;
-  if (
-    serializeCanonicalDocumentForExport(currentDocument) ===
-      state.initialCanonicalSignature &&
-    canReuseSourceBytesForCurrentDocument(state, currentDocument)
-  ) {
+  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;
+  console.error(`[DEBUG-EXPORT] docId=${sessionState.documentId} signatureMatch=${signatureMatch} canReuse=${canReuse} preservedDefs=${state.preservedCommentDefinitions.length} blockingDiags=${state.blockingCommentDiagnostics.length} comments=${commentCount}`);
+  if (signatureMatch && canReuse) {
     return {
       bytes: new Uint8Array(state.sourceBytes),
       mimeType: DOCX_MIME_TYPE,
-      fileName: options?.fileName ?? `${snapshot.documentId}.docx`,
+      fileName: options?.fileName ?? `${sessionState.documentId}.docx`,
+      delivery: {
+        mode: "exported-bytes-only",
+      },
     };
   }
-  if (state.blockingCommentDiagnostics.length > 0) {
+  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 ${state.blockingCommentDiagnostics.length} preserve-only comment anchors cannot be safely remapped after runtime edits.`,
+      `DOCX export is blocked because ${blockingCommentCount} preserve-only comment anchors cannot be safely remapped after runtime edits.`,
     );
   }
   const currentRevisions = toReviewRevisionRecords(currentDocument.review.revisions);
@@ -643,9 +756,6 @@ function exportDocxEditorSession(
   const commentThreads = Object.values(
     createCommentStoreFromRuntimeComments(currentDocument.review.comments).threads,
   );
-  const preservedCommentIds = new Set(
-    state.preservedCommentDefinitions.map((definition) => definition.commentId),
-  );
   const ownedCommentThreads = commentThreads.filter(
     (thread) => !preservedCommentIds.has(thread.commentId),
   );
@@ -660,6 +770,7 @@ function exportDocxEditorSession(
     {
       documentAttributes: state.sourceDocumentAttributes,
       media: currentDocument.media as MediaCatalog,
+      finalSectionProperties: currentDocument.subParts?.finalSectionProperties,
     },
   );
   const revisionDocument = serializeRuntimeRevisionsIntoDocumentXml(
@@ -698,6 +809,10 @@ function exportDocxEditorSession(
       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";
@@ -717,7 +832,9 @@ function exportDocxEditorSession(
     state.sourcePeoplePartPath ?? PEOPLE_PART_PATH;
   const numberingPartPath =
     state.sourceNumberingPartPath ?? NUMBERING_PART_PATH;
-  const serializedNumberingXml = hasNumberingEntries(currentDocument.numbering as NumberingCatalog)
+  const serializedNumberingXml = hasSerializableNumberingEntries(
+    currentDocument.numbering as NumberingCatalog,
+  )
     ? serializeNumberingXml(currentDocument.numbering as NumberingCatalog)
     : undefined;
   const nextRelationships = withDocumentRelatedParts(
@@ -802,7 +919,7 @@ function exportDocxEditorSession(
 
   exportSession.replaceOwnedPart({
     path: state.sourceDocumentPartPath,
-    bytes: new TextEncoder().encode(annotatedDocument.documentXml),
+    bytes: new TextEncoder().encode(protectedDocumentXml),
     contentType: MAIN_DOCUMENT_CONTENT_TYPE,
     relationships: nextRelationships,
   });
@@ -923,10 +1040,21 @@ function exportDocxEditorSession(
   return {
     bytes: exportSession.serialize(),
     mimeType: DOCX_MIME_TYPE,
-    fileName: options?.fileName ?? `${snapshot.documentId}.docx`,
+    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;
@@ -934,23 +1062,21 @@ function createImportedCanonicalDocument(input: {
   media: CanonicalDocumentEnvelope["media"];
   content: CanonicalDocumentEnvelope["content"];
   subParts?: SubPartsCatalog;
+  parsedStyles?: ParseStylesResult;
   preservation: CanonicalDocumentEnvelope["preservation"];
   diagnostics: CanonicalDocumentEnvelope["diagnostics"];
   review: CanonicalDocumentEnvelope["review"];
 }): CanonicalDocumentEnvelope {
-  const paragraphStyles = Object.fromEntries(
-    [...collectReferencedParagraphStyleIds(input.content, input.subParts)]
-      .sort((left, right) => left.localeCompare(right))
-      .map((styleId) => [
-        styleId,
-        {
-          styleId,
-          displayName: styleId,
-          kind: "paragraph" as const,
-          isDefault: styleId === "Normal",
-        },
-      ]),
+  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),
@@ -959,12 +1085,8 @@ function createImportedCanonicalDocument(input: {
     metadata: {
       customProperties: {},
     },
-    styles: {
-      paragraphs: paragraphStyles,
-      characters: {},
-      tables: {},
-    },
-    numbering: input.numbering,
+    styles,
+    numbering,
     media: input.media,
     content: input.content,
     review: input.review,
@@ -974,6 +1096,136 @@ function createImportedCanonicalDocument(input: {
   };
 }
 
+// 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,
@@ -1024,6 +1276,7 @@ function createImportedSnapshot(input: {
   timestamp: string;
   document: CanonicalDocumentEnvelope;
   compatibility: PersistedEditorSnapshot["compatibility"];
+  protectionSnapshot: ProtectionSnapshot;
   sourcePackage?: PersistedEditorSnapshot["sourcePackage"];
 }): PersistedEditorSnapshot {
   return {
@@ -1038,6 +1291,7 @@ function createImportedSnapshot(input: {
     canonicalDocument: input.document,
     compatibility: input.compatibility,
     warningLog: input.compatibility.warnings,
+    protectionSnapshot: input.protectionSnapshot,
     sourcePackage: input.sourcePackage,
   };
 }
@@ -1110,20 +1364,27 @@ function createDiagnosticsSession(
   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: options.editorBuild,
+    editorBuild,
     generatedAt: timestamp,
     diagnostics,
   });
   const initialSnapshot = runtime.getPersistedSnapshot();
+  const initialSessionState = editorSessionStateFromPersistedSnapshot(initialSnapshot);
 
   return {
+    initialSessionState,
     initialSnapshot,
     fatalError: diagnostics.fatalError,
     readOnly: true,
-    exportDocx: async (_snapshot, exportOptions) => runtime.exportDocx(exportOptions),
+    protectionSnapshot: EMPTY_PROTECTION_SNAPSHOT,
+    exportDocx: async (_sessionState, exportOptions) => runtime.exportDocx(exportOptions),
   };
 }
 
@@ -1238,8 +1499,10 @@ function normalizeImportedCommentThreads(
         commentId: thread.commentId,
         code: "opaque_anchor_preserve_only",
         message:
-          "Comment anchor intersects preserve-only OOXML and remains preserve-only on export.",
+          "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,
@@ -1257,8 +1520,10 @@ function normalizeImportedCommentThreads(
         commentId: thread.commentId,
         code: "preserve_only_revision_overlap",
         message:
-          "Comment anchor overlaps preserve-only review markup and remains preserve-only on export.",
+          "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,
@@ -1670,13 +1935,6 @@ function createEmptyNumberingCatalog(): NumberingCatalog {
   };
 }
 
-function hasNumberingEntries(catalog: NumberingCatalog): boolean {
-  return (
-    Object.keys(catalog.abstractDefinitions ?? {}).length > 0 ||
-    Object.keys(catalog.instances ?? {}).length > 0
-  );
-}
-
 function collectBrokenInternalRelationshipIssues(
   sourcePackage: OpcPackage,
   mainDocumentPath?: string,
@@ -2126,6 +2384,108 @@ function xmlNode(tagName: string, value: string | undefined): string | 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;")
@@ -2134,3 +2494,210 @@ function escapeXml(value: string): string {
     .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,
+  };
+}