@beyondwork/docx-react-component 1.0.18 → 1.0.20

package/src/io/ooxml/parse-headers-footers.ts

@@ -3,9 +3,18 @@ import type {
   FootnoteRefNode,
   HeaderFooterVariant,
   InlineNode,
+  ParagraphIndentation,
   ParagraphNode,
+  ParagraphSpacing,
+  TabStop,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
   TextMark,
 } from "../../model/canonical-document.ts";
+import { resolveHighlightColor } from "./highlight-colors.ts";
+import { classifyFieldInstruction } from "./parse-fields.ts";
+import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 
 // ---- Public types ----
 
@@ -13,6 +22,7 @@ export interface ParsedHeaderFooterReference {
   variant: HeaderFooterVariant;
   relationshipId: string;
   kind: "header" | "footer";
+  sectionIndex?: number;
 }
 
 export interface ParsedHeaderFooterDocument {
@@ -26,15 +36,21 @@ interface XmlElementNode {
   name: string;
   attributes: Record<string, string>;
   children: XmlNode[];
+  start: number;
+  end: number;
 }
 
 interface XmlTextNode {
   type: "text";
   text: string;
+  start: number;
+  end: number;
 }
 
 type XmlNode = XmlElementNode | XmlTextNode;
 
+let currentSourceXml = "";
+
 // ---- Public API ----
 
 /**
@@ -83,6 +99,7 @@ function collectSectPrReferences(
   element: XmlElementNode,
   refs: ParsedHeaderFooterReference[],
 ): void {
+  let sectionIndex = 0;
   for (const child of element.children) {
     if (child.type !== "element") {
       continue;
@@ -91,14 +108,16 @@ function collectSectPrReferences(
     const name = localName(child.name);
 
     if (name === "sectPr") {
-      extractSectPrRefs(child, refs);
+      // Body-level sectPr is the final section
+      extractSectPrRefs(child, refs, sectionIndex);
     } else if (name === "p") {
-      // Check paragraph properties for sectPr
+      // Check paragraph properties for sectPr (non-final section break)
       const pPr = findChildElementOptional(child, "pPr");
       if (pPr) {
         const sectPr = findChildElementOptional(pPr, "sectPr");
         if (sectPr) {
-          extractSectPrRefs(sectPr, refs);
+          extractSectPrRefs(sectPr, refs, sectionIndex);
+          sectionIndex++;
         }
       }
     }
@@ -108,6 +127,7 @@ function collectSectPrReferences(
 function extractSectPrRefs(
   sectPr: XmlElementNode,
   refs: ParsedHeaderFooterReference[],
+  sectionIndex: number,
 ): void {
   for (const child of sectPr.children) {
     if (child.type !== "element") {
@@ -129,11 +149,12 @@ function extractSectPrRefs(
 
       if (relationshipId) {
         // Avoid duplicates (multiple sectPr may reference same header)
+        const dedupeKey = `${kind}:${variant}:${relationshipId}`;
         const alreadyAdded = refs.some(
-          (ref) => ref.relationshipId === relationshipId && ref.kind === kind,
+          (ref) => `${ref.kind}:${ref.variant}:${ref.relationshipId}` === dedupeKey,
         );
         if (!alreadyAdded) {
-          refs.push({ variant, relationshipId, kind });
+          refs.push({ variant, relationshipId, kind, sectionIndex });
         }
       }
     }
@@ -172,18 +193,25 @@ function parseHdrFtrXml(
     if (name === "p") {
       blocks.push(parseParagraphElement(child));
     } else if (name === "tbl") {
-      // Table in header/footer: store as opaque to preserve fidelity
-      blocks.push({
-        type: "opaque_block",
-        fragmentId: "fragment:hdrftr-tbl",
-        warningId: "warning:hdrftr-opaque-table",
-      });
+      // Simple tables (no revisions, fields, or nested tables) are promoted
+      // to supported-roundtrip; structurally risky tables stay opaque.
+      if (isSimpleSecondaryStoryTable(child)) {
+        blocks.push(parseSimpleTableElement(child));
+      } else {
+        blocks.push({
+          type: "opaque_block",
+          fragmentId: "fragment:hdrftr-tbl",
+          warningId: "warning:hdrftr-opaque-table",
+          rawXml: serializeElementToXml(child),
+        });
+      }
     } else {
       // Other block-level elements: treat as opaque
       blocks.push({
         type: "opaque_block",
         fragmentId: "fragment:hdrftr-opaque",
         warningId: "warning:hdrftr-opaque-block",
+        rawXml: serializeElementToXml(child),
       });
     }
   }
@@ -194,7 +222,15 @@ function parseHdrFtrXml(
 function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
   let styleId: string | undefined;
   let alignment: ParagraphNode["alignment"];
+  let spacing: ParagraphNode["spacing"];
+  let indentation: ParagraphNode["indentation"];
+  let tabStops: ParagraphNode["tabStops"];
   const children: InlineNode[] = [];
+  let activeComplexField: {
+    instruction: string;
+    children: Array<Extract<InlineNode, { type: "text" | "hard_break" | "tab" }>>;
+    mode: "instruction" | "result";
+  } | null = null;
 
   for (const child of pElement.children) {
     if (child.type !== "element") {
@@ -211,25 +247,121 @@ function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
       if (jcVal === "left" || jcVal === "center" || jcVal === "right" || jcVal === "both" || jcVal === "distribute") {
         alignment = jcVal;
       }
+      spacing = readParagraphSpacing(child);
+      indentation = readParagraphIndentation(child);
+      tabStops = readParagraphTabStops(child);
     } else if (name === "r") {
-      children.push(...parseRunElement(child));
+      activeComplexField = appendRunNodes(child, children, activeComplexField);
     } else if (name === "hyperlink") {
       children.push(parseHyperlinkElement(child));
     } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
       children.push(parseBookmarkElement(child));
     } else if (name === "fldSimple") {
-      children.push(parseFieldElement(child));
+      if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
+        children.push({
+          type: "field",
+          fieldType: "complex",
+          instruction: activeComplexField.instruction,
+          children: activeComplexField.children,
+        });
+        activeComplexField = null;
+      }
+      pushFieldNode(children, child, "simple");
     }
   }
 
+  if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
+    children.push({
+      type: "field",
+      fieldType: "complex",
+      instruction: activeComplexField.instruction,
+      children: activeComplexField.children,
+    });
+  }
+
   return {
     type: "paragraph",
     ...(styleId ? { styleId } : {}),
     ...(alignment ? { alignment } : {}),
+    ...(spacing ? { spacing } : {}),
+    ...(indentation ? { indentation } : {}),
+    ...(tabStops && tabStops.length > 0 ? { tabStops } : {}),
     children,
   };
 }
 
+function appendRunNodes(
+  rElement: XmlElementNode,
+  nodes: InlineNode[],
+  activeComplexField: {
+    instruction: string;
+    children: Array<Extract<InlineNode, { type: "text" | "hard_break" | "tab" }>>;
+    mode: "instruction" | "result";
+  } | null,
+): {
+  instruction: string;
+  children: Array<Extract<InlineNode, { type: "text" | "hard_break" | "tab" }>>;
+  mode: "instruction" | "result";
+} | null {
+  const marks: TextMark[] = parseRunProperties(rElement);
+
+  for (const child of rElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+    if (name === "fldChar") {
+      const fldType = child.attributes["w:fldCharType"] ?? child.attributes.fldCharType;
+      if (fldType === "begin") {
+        activeComplexField = { instruction: "", children: [], mode: "instruction" };
+      } else if (fldType === "separate" && activeComplexField) {
+        activeComplexField.mode = "result";
+      } else if (fldType === "end" && activeComplexField) {
+        if (activeComplexField.instruction.trim().length > 0) {
+          nodes.push({
+            type: "field",
+            fieldType: "complex",
+            instruction: activeComplexField.instruction,
+            children: activeComplexField.children,
+          });
+        }
+        activeComplexField = null;
+      }
+      continue;
+    }
+
+    if (name === "instrText") {
+      if (activeComplexField) {
+        activeComplexField.instruction += extractTextContent(child);
+      } else {
+        pushFieldNode(nodes, child, "complex");
+      }
+      continue;
+    }
+
+    const inlineNode = parseRunChildNode(child, marks);
+    if (!inlineNode) {
+      continue;
+    }
+
+    if (activeComplexField?.mode === "result") {
+      if (
+        inlineNode.type === "text" ||
+        inlineNode.type === "hard_break" ||
+        inlineNode.type === "tab"
+      ) {
+        activeComplexField.children.push(inlineNode);
+      }
+      continue;
+    }
+
+    nodes.push(inlineNode);
+  }
+
+  return activeComplexField;
+}
+
 function parseRunElement(rElement: XmlElementNode): InlineNode[] {
   const nodes: InlineNode[] = [];
   const marks: TextMark[] = parseRunProperties(rElement);
@@ -278,14 +410,138 @@ function parseRunElement(rElement: XmlElementNode): InlineNode[] {
       }
     } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
       nodes.push(parseBookmarkElement(child));
-    } else if (name === "fldChar" || name === "instrText") {
-      nodes.push(parseFieldElement(child));
+    } else if (name === "instrText") {
+      pushFieldNode(nodes, child, "complex");
+    } else if (name === "drawing") {
+      const drawingXml = currentSourceXml.slice(child.start, child.end);
+      const shapeResult = parseShapeXml(drawingXml);
+      if (shapeResult) {
+        nodes.push(shapeResult);
+      }
+    } else if (name === "pict") {
+      const pictXml = currentSourceXml.slice(child.start, child.end);
+      const vmlResult = parseVmlXml(pictXml);
+      if (vmlResult) {
+        nodes.push(vmlResult);
+      }
+    } else if (name === "AlternateContent") {
+      const drawingNode = findFirstDescendant(child, "drawing");
+      if (drawingNode) {
+        const drawingXml = currentSourceXml.slice(drawingNode.start, drawingNode.end);
+        const shapeResult = parseShapeXml(drawingXml);
+        if (shapeResult) {
+          nodes.push({
+            ...shapeResult,
+            rawXml: currentSourceXml.slice(child.start, child.end),
+          });
+          continue;
+        }
+      }
+      const pictNode = findFirstDescendant(child, "pict");
+      if (pictNode) {
+        const pictXml = currentSourceXml.slice(pictNode.start, pictNode.end);
+        const vmlResult = parseVmlXml(pictXml);
+        if (vmlResult) {
+          nodes.push({
+            ...vmlResult,
+            rawXml: currentSourceXml.slice(child.start, child.end),
+          });
+        }
+      }
     }
   }
 
   return nodes;
 }
 
+function parseRunChildNode(
+  child: XmlElementNode,
+  marks: TextMark[],
+): InlineNode | null {
+  const name = localName(child.name);
+
+  if (name === "t") {
+    const text = extractTextContent(child);
+    if (text.length > 0) {
+      return {
+        type: "text",
+        text,
+        ...(marks.length > 0 ? { marks } : {}),
+      };
+    }
+    return null;
+  }
+  if (name === "br") {
+    return { type: "hard_break" };
+  }
+  if (name === "tab") {
+    return { type: "tab" };
+  }
+  if (name === "footnoteReference") {
+    const noteId =
+      child.attributes["w:id"] ?? child.attributes.id ?? "";
+    if (noteId) {
+      const ref: FootnoteRefNode = {
+        type: "footnote_ref",
+        noteId,
+        noteKind: "footnote",
+      };
+      return ref;
+    }
+    return null;
+  }
+  if (name === "endnoteReference") {
+    const noteId =
+      child.attributes["w:id"] ?? child.attributes.id ?? "";
+    if (noteId) {
+      const ref: FootnoteRefNode = {
+        type: "footnote_ref",
+        noteId,
+        noteKind: "endnote",
+      };
+      return ref;
+    }
+    return null;
+  }
+  if (name === "bookmarkStart" || name === "bookmarkEnd") {
+    return parseBookmarkElement(child);
+  }
+  if (name === "drawing") {
+    const drawingXml = currentSourceXml.slice(child.start, child.end);
+    return parseShapeXml(drawingXml);
+  }
+  if (name === "pict") {
+    const pictXml = currentSourceXml.slice(child.start, child.end);
+    return parseVmlXml(pictXml);
+  }
+  if (name === "AlternateContent") {
+    const drawingNode = findFirstDescendant(child, "drawing");
+    if (drawingNode) {
+      const drawingXml = currentSourceXml.slice(drawingNode.start, drawingNode.end);
+      const shapeResult = parseShapeXml(drawingXml);
+      if (shapeResult) {
+        return {
+          ...shapeResult,
+          rawXml: currentSourceXml.slice(child.start, child.end),
+        };
+      }
+    }
+    const pictNode = findFirstDescendant(child, "pict");
+    if (pictNode) {
+      const pictXml = currentSourceXml.slice(pictNode.start, pictNode.end);
+      const vmlResult = parseVmlXml(pictXml);
+      if (vmlResult) {
+        return {
+          ...vmlResult,
+          rawXml: currentSourceXml.slice(child.start, child.end),
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
 function parseHyperlinkElement(element: XmlElementNode): Extract<InlineNode, { type: "hyperlink" }> {
   const href = element.attributes["w:anchor"]
     ? `#${element.attributes["w:anchor"]}`
@@ -327,22 +583,30 @@ function parseBookmarkElement(
   };
 }
 
-function parseFieldElement(element: XmlElementNode): Extract<InlineNode, { type: "field" }> {
-  const rawFieldType =
-    element.attributes["w:fldCharType"] ??
-    element.attributes.fldCharType ??
-    localName(element.name);
-  const fieldType: "simple" | "complex" = rawFieldType === "complex" ? "complex" : "simple";
-  const instruction =
-    element.attributes["w:instr"] ??
-    element.attributes.instr ??
-    extractTextContent(element);
-  return {
+function pushFieldNode(
+  nodes: InlineNode[],
+  element: XmlElementNode,
+  fieldType: "simple" | "complex",
+): void {
+  const instruction = readFieldInstruction(element);
+  if (!instruction) {
+    return;
+  }
+
+  nodes.push({
     type: "field",
     fieldType,
     instruction,
     children: [],
-  };
+  });
+}
+
+function readFieldInstruction(element: XmlElementNode): string | undefined {
+  const instruction =
+    element.attributes["w:instr"] ??
+    element.attributes.instr ??
+    extractTextContent(element);
+  return instruction.trim().length > 0 ? instruction : undefined;
 }
 
 function parseRunProperties(rElement: XmlElementNode): TextMark[] {
@@ -387,12 +651,144 @@ function parseRunProperties(rElement: XmlElementNode): TextMark[] {
           marks.push({ type: "doubleStrikethrough" });
         }
         break;
+      case "rFonts": {
+        const family =
+          child.attributes["w:ascii"] ??
+          child.attributes["w:hAnsi"] ??
+          child.attributes.ascii ??
+          child.attributes.hAnsi;
+        if (family) {
+          marks.push({ type: "fontFamily", val: family });
+        }
+        break;
+      }
+      case "sz": {
+        const szVal = child.attributes["w:val"] ?? child.attributes.val;
+        if (szVal) {
+          const size = Number.parseInt(szVal, 10);
+          if (Number.isFinite(size) && size > 0) {
+            marks.push({ type: "fontSize", val: size });
+          }
+        }
+        break;
+      }
+      case "color": {
+        const colorVal = child.attributes["w:val"] ?? child.attributes.val;
+        if (colorVal && colorVal !== "auto") {
+          marks.push({ type: "textColor", color: colorVal });
+        }
+        break;
+      }
+      case "shd": {
+        const fill = child.attributes["w:fill"] ?? child.attributes.fill;
+        if (fill && fill !== "auto") {
+          marks.push({ type: "backgroundColor", color: fill });
+        }
+        break;
+      }
+      case "highlight": {
+        const resolvedHighlight = resolveHighlightColor(
+          child.attributes["w:val"] ?? child.attributes.val,
+        );
+        if (resolvedHighlight) {
+          marks.push({
+            type: "highlight",
+            color: resolvedHighlight.color,
+            val: resolvedHighlight.val,
+          });
+        }
+        break;
+      }
+      case "smallCaps":
+        if (val !== "0" && val !== "false") {
+          marks.push({ type: "smallCaps" });
+        }
+        break;
+      case "caps":
+        if (val !== "0" && val !== "false") {
+          marks.push({ type: "allCaps" });
+        }
+        break;
     }
   }
 
   return marks;
 }
 
+function readParagraphSpacing(pPr: XmlElementNode): ParagraphSpacing | undefined {
+  const spacingNode = findChildElementOptional(pPr, "spacing");
+  if (!spacingNode) return undefined;
+  const result: ParagraphSpacing = {};
+  const before = spacingNode.attributes["w:before"] ?? spacingNode.attributes.before;
+  if (before) result.before = Number.parseInt(before, 10);
+  const after = spacingNode.attributes["w:after"] ?? spacingNode.attributes.after;
+  if (after) result.after = Number.parseInt(after, 10);
+  const line = spacingNode.attributes["w:line"] ?? spacingNode.attributes.line;
+  if (line) result.line = Number.parseInt(line, 10);
+  const lineRule = spacingNode.attributes["w:lineRule"] ?? spacingNode.attributes.lineRule;
+  if (lineRule === "auto" || lineRule === "exact" || lineRule === "atLeast") {
+    result.lineRule = lineRule;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function readParagraphIndentation(pPr: XmlElementNode): ParagraphIndentation | undefined {
+  const indNode = findChildElementOptional(pPr, "ind");
+  if (!indNode) return undefined;
+  const result: ParagraphIndentation = {};
+  const left = indNode.attributes["w:left"] ?? indNode.attributes.left;
+  if (left) result.left = Number.parseInt(left, 10);
+  const right = indNode.attributes["w:right"] ?? indNode.attributes.right;
+  if (right) result.right = Number.parseInt(right, 10);
+  const firstLine = indNode.attributes["w:firstLine"] ?? indNode.attributes.firstLine;
+  if (firstLine) result.firstLine = Number.parseInt(firstLine, 10);
+  const hanging = indNode.attributes["w:hanging"] ?? indNode.attributes.hanging;
+  if (hanging) result.hanging = Number.parseInt(hanging, 10);
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function readParagraphTabStops(pPr: XmlElementNode): TabStop[] | undefined {
+  const tabsNode = findChildElementOptional(pPr, "tabs");
+  if (!tabsNode) return undefined;
+
+  const tabStops: TabStop[] = [];
+  for (const child of tabsNode.children) {
+    if (child.type !== "element" || localName(child.name) !== "tab") continue;
+    const pos = child.attributes["w:pos"] ?? child.attributes.pos;
+    const val = (child.attributes["w:val"] ?? child.attributes.val ?? "left").toLowerCase();
+    const leader = (child.attributes["w:leader"] ?? child.attributes.leader ?? "none").toLowerCase();
+
+    if (pos === undefined) continue;
+    const position = Number.parseInt(pos, 10);
+    if (!Number.isFinite(position)) continue;
+
+    const align = (["left", "center", "right", "decimal", "bar", "clear"] as const).includes(
+      val as "left" | "center" | "right" | "decimal" | "bar" | "clear",
+    )
+      ? (val as TabStop["align"])
+      : "left";
+
+    const leaderValue =
+      leader === "none" ||
+      leader === "dot" ||
+      leader === "hyphen" ||
+      leader === "underscore" ||
+      leader === "heavy"
+        ? (leader as Exclude<TabStop["leader"], "middleDot">)
+        : leader === "middledot"
+          ? "middleDot"
+          : undefined;
+
+    tabStops.push({
+      position,
+      align,
+      ...(leaderValue && leaderValue !== "none" ? { leader: leaderValue } : {}),
+    });
+  }
+
+  return tabStops.length > 0 ? tabStops : undefined;
+}
+
 function extractTextContent(tElement: XmlElementNode): string {
   let text = "";
   for (const child of tElement.children) {
@@ -413,19 +809,244 @@ function findChildElementOptional(
   );
 }
 
+function findFirstDescendant(
+  node: XmlElementNode,
+  childLocalName: string,
+): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) === childLocalName) {
+      return child;
+    }
+    const nested = findFirstDescendant(child, childLocalName);
+    if (nested) {
+      return nested;
+    }
+  }
+  return undefined;
+}
+
 function localName(name: string): string {
   const separatorIndex = name.indexOf(":");
   return separatorIndex >= 0 ? name.slice(separatorIndex + 1) : name;
 }
 
+// ---- Simple secondary-story table support ----
+
+/**
+ * Revision-bearing, field-bearing, or structurally risky elements that
+ * disqualify a secondary-story table from supported-roundtrip.
+ */
+const RISKY_TABLE_ELEMENT_NAMES = new Set([
+  "ins",
+  "del",
+  "moveFrom",
+  "moveTo",
+  "tblPrChange",
+  "trPrChange",
+  "tcPrChange",
+  "rPrChange",
+  "pPrChange",
+  "sectPrChange",
+  "sdt",
+  "customXml",
+]);
+
+function isSimpleSecondaryStoryTable(tblElement: XmlElementNode): boolean {
+  return !containsRiskyElement(tblElement);
+}
+
+function containsRiskyElement(element: XmlElementNode): boolean {
+  for (const child of element.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+    const name = localName(child.name);
+    if (name === "fldSimple" || name === "instrText") {
+      const instruction =
+        child.attributes["w:instr"] ??
+        child.attributes.instr ??
+        extractTextContent(child);
+      const classification = classifyFieldInstruction(instruction);
+      if (!isSafeSecondaryStoryFieldFamily(classification.family)) {
+        return true;
+      }
+      continue;
+    }
+    if (RISKY_TABLE_ELEMENT_NAMES.has(name)) {
+      return true;
+    }
+    if (name === "fldChar") {
+      continue;
+    }
+    // Nested tables remain risky
+    if (name === "tbl") {
+      return true;
+    }
+    if (containsRiskyElement(child)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isSafeSecondaryStoryFieldFamily(family: string): boolean {
+  return (
+    family === "REF" ||
+    family === "PAGEREF" ||
+    family === "NOTEREF" ||
+    family === "TOC" ||
+    family === "PAGE" ||
+    family === "NUMPAGES"
+  );
+}
+
+function parseSimpleTableElement(tblElement: XmlElementNode): TableNode {
+  let gridColumns: number[] = [];
+  const rows: TableRowNode[] = [];
+  let propertiesXml: string | undefined;
+  let styleId: string | undefined;
+
+  for (const child of tblElement.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "tblPr") {
+      propertiesXml = serializeElementToXml(child);
+      const pStyle = findChildElementOptional(child, "tblStyle");
+      styleId = pStyle?.attributes["w:val"] ?? pStyle?.attributes.val;
+    } else if (name === "tblGrid") {
+      gridColumns = readGridColumns(child);
+    } else if (name === "tr") {
+      rows.push(parseSimpleTableRow(child));
+    }
+  }
+
+  return {
+    type: "table",
+    ...(styleId ? { styleId } : {}),
+    ...(propertiesXml ? { propertiesXml } : {}),
+    gridColumns,
+    rows,
+  };
+}
+
+function readGridColumns(tblGrid: XmlElementNode): number[] {
+  const columns: number[] = [];
+  for (const child of tblGrid.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) === "gridCol") {
+      const w = child.attributes["w:w"] ?? child.attributes.w ?? "0";
+      columns.push(Number.parseInt(w, 10) || 0);
+    }
+  }
+  return columns;
+}
+
+function parseSimpleTableRow(trElement: XmlElementNode): TableRowNode {
+  const cells: TableCellNode[] = [];
+  let propertiesXml: string | undefined;
+
+  for (const child of trElement.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "trPr") {
+      propertiesXml = serializeElementToXml(child);
+    } else if (name === "tc") {
+      cells.push(parseSimpleTableCell(child));
+    }
+  }
+
+  return {
+    type: "table_row",
+    ...(propertiesXml ? { propertiesXml } : {}),
+    cells,
+  };
+}
+
+function parseSimpleTableCell(tcElement: XmlElementNode): TableCellNode {
+  const children: BlockNode[] = [];
+  let propertiesXml: string | undefined;
+  let gridSpan: number | undefined;
+  let verticalMerge: "restart" | "continue" | undefined;
+
+  for (const child of tcElement.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "tcPr") {
+      propertiesXml = serializeElementToXml(child);
+      const gsEl = findChildElementOptional(child, "gridSpan");
+      const gsVal = gsEl?.attributes["w:val"] ?? gsEl?.attributes.val;
+      if (gsVal) gridSpan = Number.parseInt(gsVal, 10) || undefined;
+
+      const vmEl = findChildElementOptional(child, "vMerge");
+      if (vmEl) {
+        const vmVal = vmEl.attributes["w:val"] ?? vmEl.attributes.val ?? "continue";
+        verticalMerge = vmVal === "restart" ? "restart" : "continue";
+      }
+    } else if (name === "p") {
+      children.push(parseParagraphElement(child));
+    }
+  }
+
+  return {
+    type: "table_cell",
+    ...(propertiesXml ? { propertiesXml } : {}),
+    ...(gridSpan ? { gridSpan } : {}),
+    ...(verticalMerge ? { verticalMerge } : {}),
+    children: children.length > 0 ? children : [{ type: "paragraph", children: [] }],
+  };
+}
+
+/**
+ * Serialize an XmlElementNode back to XML string for propertiesXml preservation.
+ */
+function serializeElementToXml(element: XmlElementNode): string {
+  const attrs = Object.entries(element.attributes)
+    .map(([key, value]) => ` ${key}="${escapeXmlAttribute(value)}"`)
+    .join("");
+  const children = element.children
+    .map((child) => {
+      if (child.type === "text") {
+        return escapeXmlText(child.text);
+      }
+      return serializeElementToXml(child);
+    })
+    .join("");
+  if (children.length === 0) {
+    return `<${element.name}${attrs}/>`;
+  }
+  return `<${element.name}${attrs}>${children}</${element.name}>`;
+}
+
+function escapeXmlAttribute(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeXmlText(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
 // ---- Minimal XML parser (same pattern as parse-numbering.ts) ----
 
 function parseXml(xml: string): XmlElementNode {
+  currentSourceXml = xml;
   const root: XmlElementNode = {
     type: "element",
     name: "__root__",
     attributes: {},
     children: [],
+    start: 0,
+    end: xml.length,
   };
   const stack: XmlElementNode[] = [root];
   let cursor = 0;
@@ -449,6 +1070,8 @@ function parseXml(xml: string): XmlElementNode {
       stack[stack.length - 1]?.children.push({
         type: "text",
         text: xml.slice(cursor + 9, textEnd),
+        start: cursor,
+        end: end >= 0 ? end + 3 : xml.length,
       });
       cursor = end >= 0 ? end + 3 : xml.length;
       continue;
@@ -459,7 +1082,7 @@ function parseXml(xml: string): XmlElementNode {
       const end = nextTag >= 0 ? nextTag : xml.length;
       const text = decodeXmlEntities(xml.slice(cursor, end));
       if (text.trim().length > 0 || (text.length > 0 && stack.length > 1)) {
-        stack[stack.length - 1]?.children.push({ type: "text", text });
+        stack[stack.length - 1]?.children.push({ type: "text", text, start: cursor, end });
       }
       cursor = end;
       continue;
@@ -471,7 +1094,10 @@ function parseXml(xml: string): XmlElementNode {
       if (end < 0) {
         break;
       }
-      stack.pop();
+      const current = stack.pop();
+      if (current) {
+        current.end = end + 1;
+      }
       cursor = end + 1;
       continue;
     }
@@ -498,6 +1124,8 @@ function parseXml(xml: string): XmlElementNode {
       name: tagName,
       attributes,
       children: [],
+      start: cursor,
+      end: tagEnd + 1,
     };
 
     stack[stack.length - 1]?.children.push(element);