@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/io/ooxml/parse-revisions.ts

@@ -0,0 +1,1045 @@
+import { createDetachedAnchor } from "../../core/selection/mapping.ts";
+import {
+  createRevisionRecord,
+  type RevisionRecord,
+} from "../../review/store/revision-store.ts";
+import {
+  createRevisionRangeAnchor,
+  type MoveData,
+  type PropertyChangeData,
+  type RevisionKind,
+} from "../../review/store/revision-types.ts";
+import {
+  findChildElement,
+  findRequiredChildElement,
+  localName,
+  mapRevisionBoundaries,
+  parseXmlWithPositions,
+  type RevisionParagraphBoundary,
+  type XmlElementNode,
+  type XmlNode,
+} from "./revision-boundaries.ts";
+
+export interface PreservedRevisionMarkup {
+  revisionId: string;
+  rawXml: string;
+  xmlStart: number;
+  xmlEnd: number;
+  originalRevisionType: string;
+  paragraphIndex?: number;
+  containerXmlStart?: number;
+  containerXmlEnd?: number;
+  beforeContainerXml?: string;
+}
+
+export interface RevisionImportDiagnostic {
+  revisionId: string;
+  code:
+    | "preserve_only_move_revision"
+    | "preserve_only_formatting_revision"
+    | "nested_revision_preserve_only"
+    | "shallow_nested_revision_promoted"
+    | "linked_move_pair"
+    | "unlinked_move_revision"
+    | "ambiguous_revision_anchor"
+    | "table_structural_revision_preserve_only"
+    | "table_property_revision_parsed";
+  message: string;
+  featureClass: "preserve-only" | "supported" | "informational";
+}
+
+export interface ParsedRevisionsResult {
+  revisions: RevisionRecord[];
+  preservedMarkup: PreservedRevisionMarkup[];
+  diagnostics: RevisionImportDiagnostic[];
+  boundaries: RevisionParagraphBoundary[];
+}
+
+interface ParseState {
+  documentXml: string;
+  boundaries: RevisionParagraphBoundary[];
+  revisions: RevisionRecord[];
+  preservedMarkup: PreservedRevisionMarkup[];
+  diagnostics: RevisionImportDiagnostic[];
+  nextGeneratedIndex: number;
+}
+
+interface RevisionMetadata {
+  revisionId: string;
+  ooxmlRevisionId?: string;
+  authorId: string;
+  createdAt: string;
+}
+
+const SUPPORTED_CONTAINER_TYPES = new Set(["ins", "del"]);
+const PRESERVE_ONLY_CONTAINER_TYPES = new Set(["moveFrom", "moveTo"]);
+const PROPERTY_CHANGE_REVISION_TYPES = new Set(["rPrChange", "pPrChange"]);
+const STRUCTURAL_TABLE_REVISION_TYPES = new Set(["cellIns", "cellDel", "cellMerge"]);
+
+export function parseRevisionsFromDocumentXml(
+  documentXml: string,
+): ParsedRevisionsResult {
+  const root = parseXmlWithPositions(documentXml);
+  const documentElement = findRequiredChildElement(root, "document");
+  const bodyElement = findRequiredChildElement(documentElement, "body");
+  const boundaries = mapRevisionBoundaries(documentXml);
+  const state: ParseState = {
+    documentXml,
+    boundaries,
+    revisions: [],
+    preservedMarkup: [],
+    diagnostics: [],
+    nextGeneratedIndex: 1,
+  };
+
+  let paragraphIndex = -1;
+  let cursor = 0;
+  let previousWasParagraph = false;
+
+  for (const child of bodyElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const childType = localName(child.name);
+
+    if (childType !== "p") {
+      if (childType === "tbl") {
+        parseTblPropertyRevisions(child, cursor, state);
+        const nested = parseNestedParagraphContainers(
+          child.children,
+          paragraphIndex,
+          cursor,
+          previousWasParagraph,
+          state,
+        );
+        paragraphIndex = nested.paragraphIndex;
+        cursor = nested.cursor;
+        previousWasParagraph = nested.previousWasParagraph;
+      } else if (childType === "sectPr") {
+        parseSectPrRevisions(child, cursor, state);
+        cursor += 1;
+        previousWasParagraph = false;
+      } else {
+        cursor += 1;
+        previousWasParagraph = false;
+      }
+      continue;
+    }
+
+    if (previousWasParagraph) {
+      cursor += 1;
+    }
+    paragraphIndex += 1;
+    const paragraphBoundary = boundaries[paragraphIndex];
+    if (!paragraphBoundary) {
+      continue;
+    }
+
+    parseParagraphMarkRevisions(child, paragraphBoundary, state);
+    walkParagraphContent(child.children, paragraphIndex, state, () => cursor, (next) => {
+      cursor = next;
+    });
+    previousWasParagraph = true;
+  }
+
+  linkMoveRevisionPairs(state);
+
+  return {
+    revisions: state.revisions,
+    preservedMarkup: state.preservedMarkup.sort((left, right) => left.xmlStart - right.xmlStart),
+    diagnostics: state.diagnostics,
+    boundaries,
+  };
+}
+
+function parseNestedParagraphContainers(
+  nodes: XmlNode[],
+  paragraphIndex: number,
+  cursor: number,
+  previousWasParagraph: boolean,
+  state: ParseState,
+): {
+  paragraphIndex: number;
+  cursor: number;
+  previousWasParagraph: boolean;
+} {
+  let nextParagraphIndex = paragraphIndex;
+  let nextCursor = cursor;
+  let nextPreviousWasParagraph = previousWasParagraph;
+
+  for (const node of nodes) {
+    if (node.type !== "element") {
+      continue;
+    }
+
+    const type = localName(node.name);
+    if (type === "p") {
+      nextParagraphIndex += 1;
+      const paragraphBoundary = state.boundaries[nextParagraphIndex];
+      if (!paragraphBoundary) {
+        continue;
+      }
+      parseParagraphMarkRevisions(node, paragraphBoundary, state);
+      walkParagraphContent(node.children, nextParagraphIndex, state, () => nextCursor, (next) => {
+        nextCursor = next;
+      });
+      nextPreviousWasParagraph = false;
+      continue;
+    }
+
+    if (
+      type === "tbl" ||
+      type === "tr" ||
+      type === "tc" ||
+      type === "sdtContent" ||
+      type === "customXml" ||
+      type === "smartTag"
+    ) {
+      const nested = parseNestedParagraphContainers(
+        node.children,
+        nextParagraphIndex,
+        nextCursor,
+        nextPreviousWasParagraph,
+        state,
+      );
+      nextParagraphIndex = nested.paragraphIndex;
+      nextCursor = nested.cursor;
+      nextPreviousWasParagraph = nested.previousWasParagraph;
+      continue;
+    }
+
+    if (
+      type === "tblPr" ||
+      type === "tblGrid" ||
+      type === "gridCol" ||
+      type === "trPr" ||
+      type === "tcPr"
+    ) {
+      continue;
+    }
+
+    nextCursor += 1;
+    nextPreviousWasParagraph = false;
+  }
+
+  return {
+    paragraphIndex: nextParagraphIndex,
+    cursor: nextCursor,
+    previousWasParagraph: nextPreviousWasParagraph,
+  };
+}
+
+export function parseRevisionsFromStoryXml(
+  storyXml: string,
+): ParsedRevisionsResult {
+  const xmlDeclMatch = storyXml.match(/^<\?xml[\s\S]*?\?>\s*/u);
+  const withoutDecl = xmlDeclMatch ? storyXml.slice(xmlDeclMatch[0].length) : storyXml;
+  const rootMatch = withoutDecl.match(/^<([A-Za-z0-9:._-]+)([^>]*)>([\s\S]*)<\/\1>\s*$/u);
+  if (!rootMatch) {
+    return {
+      revisions: [],
+      preservedMarkup: [],
+      diagnostics: [],
+      boundaries: [],
+    };
+  }
+
+  const innerXml = rootMatch[3] ?? "";
+  const wrapped =
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
+    `<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">` +
+    `<w:body>${innerXml}</w:body></w:document>`;
+  return parseRevisionsFromDocumentXml(wrapped);
+}
+
+function parseParagraphMarkRevisions(
+  paragraph: XmlElementNode,
+  boundary: RevisionParagraphBoundary,
+  state: ParseState,
+): void {
+  const paragraphProperties = findChildElement(paragraph, "pPr");
+  const paragraphRunProperties = paragraphProperties
+    ? findChildElement(paragraphProperties, "rPr")
+    : undefined;
+
+  if (!paragraphProperties) {
+    return;
+  }
+
+  const paragraphRange =
+    boundary.start === boundary.end
+      ? createRevisionRangeAnchor(boundary.end, boundary.end)
+      : createRevisionRangeAnchor(boundary.start, boundary.end);
+
+  for (const child of paragraphProperties.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const type = localName(child.name);
+    if (type === "pPrChange") {
+      const metadata = readRevisionMetadata(child, state, "property-change");
+      const innerPPr = findChildElement(child, "pPr");
+      const beforeXml = innerPPr ? state.documentXml.slice(innerPPr.start, innerPPr.end) : "";
+      const propertyChangeData: PropertyChangeData = {
+        xmlTag: "pPrChange",
+        beforeXml,
+      };
+      state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: "property-change",
+          anchor: paragraphRange,
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            originalRevisionType: "pPrChange",
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+            propertyChangeData,
+          },
+        }),
+      );
+      state.preservedMarkup.push({
+        revisionId: metadata.revisionId,
+        rawXml: state.documentXml.slice(child.start, child.end),
+        xmlStart: child.start,
+        xmlEnd: child.end,
+        originalRevisionType: "pPrChange",
+        containerXmlStart: paragraphProperties.start,
+        containerXmlEnd: paragraphProperties.end,
+        beforeContainerXml: beforeXml,
+      });
+    }
+  }
+
+  if (!paragraphRunProperties) {
+    return;
+  }
+
+  for (const child of paragraphRunProperties.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const type = localName(child.name);
+    if (!SUPPORTED_CONTAINER_TYPES.has(type)) {
+      continue;
+    }
+
+    const metadata = readRevisionMetadata(child, state, type);
+    state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: type === "ins" ? "insertion" : "deletion",
+          anchor: createRevisionRangeAnchor(boundary.end, boundary.end),
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            semanticKind: "structural-change",
+            importedRevisionForm:
+              type === "ins" ? "paragraph-insertion" : "paragraph-deletion",
+            originalRevisionType: `paragraph-${type}`,
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+          },
+        }),
+    );
+    state.preservedMarkup.push({
+      revisionId: metadata.revisionId,
+      rawXml: state.documentXml.slice(child.start, child.end),
+      xmlStart: child.start,
+      xmlEnd: child.end,
+      originalRevisionType: `paragraph-${type}`,
+      paragraphIndex: boundary.paragraphIndex,
+    });
+  }
+}
+
+function walkParagraphContent(
+  nodes: XmlNode[],
+  paragraphIndex: number,
+  state: ParseState,
+  getCursor: () => number,
+  setCursor: (next: number) => void,
+): void {
+  for (const node of nodes) {
+    walkContentNode(node, paragraphIndex, state, getCursor, setCursor);
+  }
+}
+
+function walkContentNode(
+  node: XmlNode,
+  paragraphIndex: number,
+  state: ParseState,
+  getCursor: () => number,
+  setCursor: (next: number) => void,
+): void {
+  if (node.type !== "element") {
+    return;
+  }
+
+  const type = localName(node.name);
+  if (type === "pPr") {
+    return;
+  }
+
+  if (type === "r") {
+    parseRunFormattingRevisions(node, paragraphIndex, state, getCursor());
+    for (const child of node.children) {
+      walkContentNode(child, paragraphIndex, state, getCursor, setCursor);
+    }
+    return;
+  }
+
+  if (SUPPORTED_CONTAINER_TYPES.has(type) || PRESERVE_ONLY_CONTAINER_TYPES.has(type)) {
+    const start = getCursor();
+    const length = measureStoryLength(node);
+    const end = start + length;
+    const hasNestedRevision = containsNestedRevision(node);
+    const metadata = readRevisionMetadata(
+      node,
+      state,
+      type === "moveFrom" || type === "moveTo" ? "move" : type,
+    );
+
+    if (hasNestedRevision) {
+      const nestedKind = type === "ins" ? "insertion" : type === "del" ? "deletion" : "move";
+      const isShallowNesting = isShallowPropertyChangeNesting(node);
+
+      if (isShallowNesting && SUPPORTED_CONTAINER_TYPES.has(type)) {
+        state.revisions.push(
+          createRevisionRecord({
+            revisionId: metadata.revisionId,
+            kind: nestedKind as "insertion" | "deletion",
+            anchor:
+              length > 0
+                ? createRevisionRangeAnchor(start, end)
+                : createDetachedAnchor({ from: start, to: end }, "importAmbiguity"),
+            authorId: metadata.authorId,
+            createdAt: metadata.createdAt,
+            metadata: {
+              source: "import",
+              importedRevisionForm:
+                type === "ins" ? "run-insertion" : "run-deletion",
+              originalRevisionType: type,
+              ooxmlRevisionId: metadata.ooxmlRevisionId,
+            },
+          }),
+        );
+        state.preservedMarkup.push({
+          revisionId: metadata.revisionId,
+          rawXml: state.documentXml.slice(node.start, node.end),
+          xmlStart: node.start,
+          xmlEnd: node.end,
+          originalRevisionType: type,
+        });
+        state.diagnostics.push({
+          revisionId: metadata.revisionId,
+          code: "shallow_nested_revision_promoted",
+          message: "Shallow nested revision (property changes inside ins/del) promoted to supported rendering.",
+          featureClass: "supported",
+        });
+        parseNestedPropertyChangeRevisions(node, paragraphIndex, state, start);
+        advanceCursor(node, setCursor, getCursor);
+        return;
+      }
+
+      state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: nestedKind,
+          anchor:
+            length > 0
+              ? createRevisionRangeAnchor(start, end)
+              : createDetachedAnchor({ from: start, to: end }, "importAmbiguity"),
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            originalRevisionType: type,
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+            preserveOnlyReason: "Nested revision markup remains preserve-only.",
+          },
+        }),
+      );
+      state.preservedMarkup.push({
+        revisionId: metadata.revisionId,
+        rawXml: state.documentXml.slice(node.start, node.end),
+        xmlStart: node.start,
+        xmlEnd: node.end,
+        originalRevisionType: type,
+      });
+      state.diagnostics.push({
+        revisionId: metadata.revisionId,
+        code: "nested_revision_preserve_only",
+        message: "Nested revision markup remains preserve-only and is exported unchanged.",
+        featureClass: "preserve-only",
+      });
+      advanceCursor(node, setCursor, getCursor);
+      return;
+    }
+
+    if (type === "moveFrom" || type === "moveTo") {
+      const moveData: MoveData = {
+        moveId: metadata.ooxmlRevisionId ?? `generated-${metadata.revisionId}`,
+        direction: type === "moveFrom" ? "from" : "to",
+      };
+      state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: "move",
+          anchor:
+            length > 0
+              ? createRevisionRangeAnchor(start, end)
+              : createDetachedAnchor({ from: start, to: end }, "importAmbiguity"),
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            originalRevisionType: type,
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+            preserveOnlyReason: "Imported preserve-only revision.",
+            moveData,
+          },
+        }),
+      );
+      state.preservedMarkup.push({
+        revisionId: metadata.revisionId,
+        rawXml: state.documentXml.slice(node.start, node.end),
+        xmlStart: node.start,
+        xmlEnd: node.end,
+        originalRevisionType: type,
+      });
+      state.diagnostics.push({
+        revisionId: metadata.revisionId,
+        code: "preserve_only_move_revision",
+        message: "Move revision parsed as preserve-only. Content is preserved for round-trip; linking resolved in post-parse step.",
+        featureClass: "preserve-only",
+      });
+      advanceCursor(node, setCursor, getCursor);
+      return;
+    }
+
+    state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: type === "ins" ? "insertion" : "deletion",
+          anchor: createRevisionRangeAnchor(start, end),
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            importedRevisionForm:
+              type === "ins" ? "run-insertion" : "run-deletion",
+            originalRevisionType: type,
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+          },
+        }),
+    );
+    state.preservedMarkup.push({
+      revisionId: metadata.revisionId,
+      rawXml: state.documentXml.slice(node.start, node.end),
+      xmlStart: node.start,
+      xmlEnd: node.end,
+      originalRevisionType: type,
+    });
+    advanceCursor(node, setCursor, getCursor);
+    return;
+  }
+
+  switch (type) {
+    case "t":
+    case "delText":
+    case "instrText":
+    case "delInstrText": {
+      const text = node.children
+        .filter((child): child is XmlElementNode["children"][number] & { type: "text" } => child.type === "text")
+        .map((child) => child.text)
+        .join("");
+      setCursor(getCursor() + Array.from(text).length);
+      return;
+    }
+    case "tab":
+    case "br":
+    case "cr":
+      setCursor(getCursor() + 1);
+      return;
+    default:
+      for (const child of node.children) {
+        walkContentNode(child, paragraphIndex, state, getCursor, setCursor);
+      }
+  }
+}
+
+function parseRunFormattingRevisions(
+  run: XmlElementNode,
+  _paragraphIndex: number,
+  state: ParseState,
+  runStart: number,
+): void {
+  const runProperties = findChildElement(run, "rPr");
+  if (!runProperties) {
+    return;
+  }
+
+  const runLength = measureStoryLength(run);
+  const anchor =
+    runLength > 0
+      ? createRevisionRangeAnchor(runStart, runStart + runLength)
+      : createDetachedAnchor({ from: runStart, to: runStart }, "importAmbiguity");
+
+  for (const child of runProperties.children) {
+    if (child.type !== "element" || !PROPERTY_CHANGE_REVISION_TYPES.has(localName(child.name))) {
+      continue;
+    }
+
+    const childLocalName = localName(child.name) as "rPrChange" | "pPrChange";
+    const metadata = readRevisionMetadata(child, state, "property-change");
+    const innerRPr = findChildElement(child, "rPr");
+    const beforeXml = innerRPr ? state.documentXml.slice(innerRPr.start, innerRPr.end) : "";
+    const propertyChangeData: PropertyChangeData = {
+      xmlTag: childLocalName === "rPrChange" ? "rPrChange" : "pPrChange",
+      beforeXml,
+    };
+    state.revisions.push(
+      createRevisionRecord({
+        revisionId: metadata.revisionId,
+        kind: "property-change",
+        anchor,
+        authorId: metadata.authorId,
+        createdAt: metadata.createdAt,
+        metadata: {
+          source: "import",
+          originalRevisionType: childLocalName,
+          ooxmlRevisionId: metadata.ooxmlRevisionId,
+          propertyChangeData,
+        },
+      }),
+    );
+    state.preservedMarkup.push({
+      revisionId: metadata.revisionId,
+      rawXml: state.documentXml.slice(child.start, child.end),
+      xmlStart: child.start,
+      xmlEnd: child.end,
+      originalRevisionType: childLocalName,
+      containerXmlStart: runProperties.start,
+      containerXmlEnd: runProperties.end,
+      beforeContainerXml: beforeXml,
+    });
+  }
+}
+
+function parseTblPropertyRevisions(
+  table: XmlElementNode,
+  position: number,
+  state: ParseState,
+): void {
+  const tblPr = findChildElement(table, "tblPr");
+  if (tblPr) {
+    const tblPrChange = findChildElement(tblPr, "tblPrChange");
+    if (tblPrChange) {
+      const metadata = readRevisionMetadata(tblPrChange, state, "property-change");
+      const innerTblPr = findChildElement(tblPrChange, "tblPr");
+      const beforeXml = innerTblPr ? state.documentXml.slice(innerTblPr.start, innerTblPr.end) : "";
+      const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
+
+      state.revisions.push(
+        createRevisionRecord({
+          revisionId: metadata.revisionId,
+          kind: "property-change",
+          anchor: createRevisionRangeAnchor(position, position),
+          authorId: metadata.authorId,
+          createdAt: metadata.createdAt,
+          metadata: {
+            source: "import",
+            originalRevisionType: "tblPrChange",
+            ooxmlRevisionId: metadata.ooxmlRevisionId,
+            propertyChangeData,
+          },
+        }),
+      );
+      state.preservedMarkup.push({
+        revisionId: metadata.revisionId,
+        rawXml: state.documentXml.slice(tblPrChange.start, tblPrChange.end),
+        xmlStart: tblPrChange.start,
+        xmlEnd: tblPrChange.end,
+        originalRevisionType: "tblPrChange",
+        containerXmlStart: tblPr.start,
+        containerXmlEnd: tblPr.end,
+        beforeContainerXml: beforeXml,
+      });
+      state.diagnostics.push({
+        revisionId: metadata.revisionId,
+        code: "table_property_revision_parsed",
+        message: "Table property change (tblPrChange) parsed as actionable property-change revision.",
+        featureClass: "supported",
+      });
+    }
+  }
+
+  parseTableRowAndCellRevisions(table, position, state);
+}
+
+function parseTableRowAndCellRevisions(
+  table: XmlElementNode,
+  position: number,
+  state: ParseState,
+): void {
+  for (const child of table.children) {
+    if (child.type !== "element" || localName(child.name) !== "tr") {
+      continue;
+    }
+
+    const trPr = findChildElement(child, "trPr");
+    if (trPr) {
+      const trPrChange = findChildElement(trPr, "trPrChange");
+      if (trPrChange) {
+        const metadata = readRevisionMetadata(trPrChange, state, "property-change");
+        const innerTrPr = findChildElement(trPrChange, "trPr");
+        const beforeXml = innerTrPr ? state.documentXml.slice(innerTrPr.start, innerTrPr.end) : "";
+        const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
+
+        state.revisions.push(
+          createRevisionRecord({
+            revisionId: metadata.revisionId,
+            kind: "property-change",
+            anchor: createRevisionRangeAnchor(position, position),
+            authorId: metadata.authorId,
+            createdAt: metadata.createdAt,
+            metadata: {
+              source: "import",
+              originalRevisionType: "trPrChange",
+              ooxmlRevisionId: metadata.ooxmlRevisionId,
+              propertyChangeData,
+              preserveOnlyReason: "Row property changes remain preserve-only for export safety.",
+            },
+          }),
+        );
+        state.preservedMarkup.push({
+          revisionId: metadata.revisionId,
+          rawXml: state.documentXml.slice(trPrChange.start, trPrChange.end),
+          xmlStart: trPrChange.start,
+          xmlEnd: trPrChange.end,
+          originalRevisionType: "trPrChange",
+          containerXmlStart: trPr.start,
+          containerXmlEnd: trPr.end,
+          beforeContainerXml: beforeXml,
+        });
+      }
+    }
+
+    for (const tcNode of child.children) {
+      if (tcNode.type !== "element" || localName(tcNode.name) !== "tc") {
+        continue;
+      }
+
+      const tcPr = findChildElement(tcNode, "tcPr");
+      if (!tcPr) {
+        continue;
+      }
+
+      const tcPrChange = findChildElement(tcPr, "tcPrChange");
+      if (tcPrChange) {
+        const metadata = readRevisionMetadata(tcPrChange, state, "property-change");
+        const innerTcPr = findChildElement(tcPrChange, "tcPr");
+        const beforeXml = innerTcPr ? state.documentXml.slice(innerTcPr.start, innerTcPr.end) : "";
+        const propertyChangeData: PropertyChangeData = { xmlTag: "tblPrChange", beforeXml };
+
+        state.revisions.push(
+          createRevisionRecord({
+            revisionId: metadata.revisionId,
+            kind: "property-change",
+            anchor: createRevisionRangeAnchor(position, position),
+            authorId: metadata.authorId,
+            createdAt: metadata.createdAt,
+            metadata: {
+              source: "import",
+              originalRevisionType: "tcPrChange",
+              ooxmlRevisionId: metadata.ooxmlRevisionId,
+              propertyChangeData,
+              preserveOnlyReason: "Cell property changes remain preserve-only for export safety.",
+            },
+          }),
+        );
+        state.preservedMarkup.push({
+          revisionId: metadata.revisionId,
+          rawXml: state.documentXml.slice(tcPrChange.start, tcPrChange.end),
+          xmlStart: tcPrChange.start,
+          xmlEnd: tcPrChange.end,
+          originalRevisionType: "tcPrChange",
+          containerXmlStart: tcPr.start,
+          containerXmlEnd: tcPr.end,
+          beforeContainerXml: beforeXml,
+        });
+      }
+
+      for (const tcChild of tcPr.children) {
+        if (tcChild.type !== "element") {
+          continue;
+        }
+
+        const tcChildName = localName(tcChild.name);
+        if (STRUCTURAL_TABLE_REVISION_TYPES.has(tcChildName)) {
+          const metadata = readRevisionMetadata(tcChild, state, tcChildName);
+          state.preservedMarkup.push({
+            revisionId: metadata.revisionId,
+            rawXml: state.documentXml.slice(tcChild.start, tcChild.end),
+            xmlStart: tcChild.start,
+            xmlEnd: tcChild.end,
+            originalRevisionType: tcChildName,
+          });
+          state.diagnostics.push({
+            revisionId: metadata.revisionId,
+            code: "table_structural_revision_preserve_only",
+            message: `Structural table revision (${tcChildName}) remains preserve-only; topology-altering changes cannot be safely applied.`,
+            featureClass: "preserve-only",
+          });
+        }
+      }
+    }
+  }
+}
+
+function parseSectPrRevisions(
+  sectPr: XmlElementNode,
+  position: number,
+  state: ParseState,
+): void {
+  const sectPrChange = findChildElement(sectPr, "sectPrChange");
+  if (!sectPrChange) {
+    return;
+  }
+
+  const metadata = readRevisionMetadata(sectPrChange, state, "property-change");
+  const innerSectPr = findChildElement(sectPrChange, "sectPr");
+  const beforeXml = innerSectPr ? state.documentXml.slice(innerSectPr.start, innerSectPr.end) : "";
+  const propertyChangeData: PropertyChangeData = { xmlTag: "sectPrChange", beforeXml };
+
+  state.revisions.push(
+    createRevisionRecord({
+      revisionId: metadata.revisionId,
+      kind: "property-change",
+      anchor: createRevisionRangeAnchor(position, position),
+      authorId: metadata.authorId,
+      createdAt: metadata.createdAt,
+      metadata: {
+        source: "import",
+        originalRevisionType: "sectPrChange",
+        ooxmlRevisionId: metadata.ooxmlRevisionId,
+        propertyChangeData,
+      },
+    }),
+  );
+  state.preservedMarkup.push({
+    revisionId: metadata.revisionId,
+    rawXml: state.documentXml.slice(sectPrChange.start, sectPrChange.end),
+    xmlStart: sectPrChange.start,
+    xmlEnd: sectPrChange.end,
+    originalRevisionType: "sectPrChange",
+    containerXmlStart: sectPr.start,
+    containerXmlEnd: sectPr.end,
+    beforeContainerXml: beforeXml,
+  });
+}
+
+function readRevisionMetadata(
+  node: XmlElementNode,
+  state: ParseState,
+  prefix: string,
+): RevisionMetadata {
+  const rawId = node.attributes["w:id"] ?? node.attributes.id;
+  const ooxmlRevisionId = rawId ? rawId : undefined;
+  const revisionId = rawId
+    ? `revision:${sanitizeRevisionToken(prefix)}-${sanitizeRevisionToken(rawId)}`
+    : `revision:${sanitizeRevisionToken(prefix)}-generated-${state.nextGeneratedIndex++}`;
+  const authorId =
+    node.attributes["w:author"] ??
+    node.attributes.author ??
+    "word:unknown-author";
+  const createdAt =
+    normalizeImportedTimestamp(
+      node.attributes["w:date"] ?? node.attributes.date,
+    ) ??
+    "1970-01-01T00:00:00.000Z";
+
+  return {
+    revisionId,
+    ooxmlRevisionId,
+    authorId,
+    createdAt,
+  };
+}
+
+function normalizeImportedTimestamp(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.valueOf())) {
+    return undefined;
+  }
+
+  return parsed.toISOString();
+}
+
+function sanitizeRevisionToken(value: string): string {
+  const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  return sanitized.length > 0 ? sanitized : "unknown";
+}
+
+function linkMoveRevisionPairs(state: ParseState): void {
+  const moveRevisions = state.revisions.filter(
+    (r) => r.kind === "move" && r.metadata.moveData,
+  );
+
+  const byMoveId = new Map<string, typeof moveRevisions>();
+  for (const revision of moveRevisions) {
+    const moveId = revision.metadata.moveData!.moveId;
+    const group = byMoveId.get(moveId) ?? [];
+    group.push(revision);
+    byMoveId.set(moveId, group);
+  }
+
+  for (const [moveId, group] of byMoveId) {
+    const fromRevision = group.find(
+      (r) => r.metadata.moveData!.direction === "from",
+    );
+    const toRevision = group.find(
+      (r) => r.metadata.moveData!.direction === "to",
+    );
+
+    if (fromRevision && toRevision) {
+      fromRevision.metadata.moveData!.linkedRevisionId = toRevision.revisionId;
+      toRevision.metadata.moveData!.linkedRevisionId = fromRevision.revisionId;
+
+      state.diagnostics.push({
+        revisionId: fromRevision.revisionId,
+        code: "linked_move_pair",
+        message: `Move-from revision linked to move-to revision ${toRevision.revisionId} via moveId ${moveId}.`,
+        featureClass: "informational",
+      });
+      state.diagnostics.push({
+        revisionId: toRevision.revisionId,
+        code: "linked_move_pair",
+        message: `Move-to revision linked to move-from revision ${fromRevision.revisionId} via moveId ${moveId}.`,
+        featureClass: "informational",
+      });
+    } else {
+      for (const revision of group) {
+        state.diagnostics.push({
+          revisionId: revision.revisionId,
+          code: "unlinked_move_revision",
+          message: `Move revision has no matching counterpart for moveId ${moveId}. Remains preserve-only.`,
+          featureClass: "preserve-only",
+        });
+      }
+    }
+  }
+}
+
+function isShallowPropertyChangeNesting(node: XmlElementNode): boolean {
+  for (const child of node.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (SUPPORTED_CONTAINER_TYPES.has(name) || PRESERVE_ONLY_CONTAINER_TYPES.has(name)) {
+      return false;
+    }
+
+    if (name === "r") {
+      const runProperties = findChildElement(child, "rPr");
+      if (runProperties) {
+        for (const rpChild of runProperties.children) {
+          if (rpChild.type !== "element") {
+            continue;
+          }
+
+          const rpChildName = localName(rpChild.name);
+          if (
+            SUPPORTED_CONTAINER_TYPES.has(rpChildName) ||
+            PRESERVE_ONLY_CONTAINER_TYPES.has(rpChildName)
+          ) {
+            return false;
+          }
+        }
+      }
+      continue;
+    }
+
+    if (!isShallowPropertyChangeNesting(child)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function parseNestedPropertyChangeRevisions(
+  container: XmlElementNode,
+  paragraphIndex: number,
+  state: ParseState,
+  containerStart: number,
+): void {
+  for (const child of container.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    if (localName(child.name) === "r") {
+      parseRunFormattingRevisions(child, paragraphIndex, state, containerStart);
+    }
+  }
+}
+
+function containsNestedRevision(node: XmlElementNode): boolean {
+  return node.children.some(
+    (child) =>
+      child.type === "element" &&
+      (SUPPORTED_CONTAINER_TYPES.has(localName(child.name)) ||
+        PRESERVE_ONLY_CONTAINER_TYPES.has(localName(child.name)) ||
+        PROPERTY_CHANGE_REVISION_TYPES.has(localName(child.name)) ||
+        containsNestedRevision(child)),
+  );
+}
+
+function advanceCursor(
+  node: XmlElementNode,
+  setCursor: (next: number) => void,
+  getCursor: () => number,
+): void {
+  setCursor(getCursor() + measureStoryLength(node));
+}
+
+function measureStoryLength(node: XmlNode): number {
+  if (node.type !== "element") {
+    return 0;
+  }
+
+  switch (localName(node.name)) {
+    case "t":
+    case "delText":
+    case "instrText":
+    case "delInstrText":
+      return node.children
+        .filter((child): child is XmlElementNode["children"][number] & { type: "text" } => child.type === "text")
+        .map((child) => Array.from(child.text).length)
+        .reduce((total, length) => total + length, 0);
+    case "tab":
+    case "br":
+    case "cr":
+      return 1;
+    case "pPr":
+    case "rPr":
+    case "rPrChange":
+    case "pPrChange":
+      return 0;
+    default:
+      return node.children.reduce((total, child) => total + measureStoryLength(child), 0);
+  }
+}