@beyondwork/docx-react-component 1.0.29 → 1.0.31

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

@@ -0,0 +1,952 @@
+import type {
+  BlockNode,
+  FootnoteCollection,
+  FootnoteDefinition,
+  InlineNode,
+  ParagraphIndentation,
+  ParagraphNode,
+  ParagraphSpacing,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+  TextMark,
+} from "../../model/canonical-document.ts";
+import {
+  readCellBorders,
+  readCellShading,
+  readCellVerticalAlign,
+  readCellWidth,
+  readGridColumns as readSharedGridColumns,
+  readRowHeight,
+  readRowHeightRule,
+  readRowIsHeader,
+  readTableAlignment,
+  readTableBorders,
+  readTableCellMargins,
+  readTableLook,
+  readTableStyleId,
+  readTableWidth,
+} from "./parse-tables.ts";
+
+// ---- XML node types (inline, no external dep) ----
+
+interface XmlElementNode {
+  type: "element";
+  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;
+
+// ---- Special footnote/endnote IDs to skip ----
+
+const SPECIAL_NOTE_IDS = new Set(["-1", "0"]);
+const SPECIAL_NOTE_TYPES = new Set(["separator", "continuationSeparator"]);
+
+// ---- Public API ----
+
+/**
+ * Parse footnotes.xml (<w:footnotes> root) into a FootnoteCollection.
+ * Also accepts endnotes.xml (<w:endnotes> root).
+ */
+export function parseFootnotesXml(xml: string): FootnoteCollection {
+  const root = parseXml(xml);
+
+  const footnotesElement = findChildElementOptional(root, "footnotes");
+  const endnotesElement = findChildElementOptional(root, "endnotes");
+
+  const footnotes: Record<string, FootnoteDefinition> = {};
+  const endnotes: Record<string, FootnoteDefinition> = {};
+
+  if (footnotesElement) {
+    for (const child of footnotesElement.children) {
+      if (child.type !== "element") {
+        continue;
+      }
+      if (localName(child.name) !== "footnote") {
+        continue;
+      }
+      const definition = parseNoteElement(child, "footnote");
+      if (definition) {
+        footnotes[definition.noteId] = definition;
+      }
+    }
+  }
+
+  if (endnotesElement) {
+    for (const child of endnotesElement.children) {
+      if (child.type !== "element") {
+        continue;
+      }
+      if (localName(child.name) !== "endnote") {
+        continue;
+      }
+      const definition = parseNoteElement(child, "endnote");
+      if (definition) {
+        endnotes[definition.noteId] = definition;
+      }
+    }
+  }
+
+  return { footnotes, endnotes };
+}
+
+/**
+ * Parse a standalone endnotes.xml (<w:endnotes> root).
+ * Merges into the provided collection or creates a new one.
+ */
+export function parseEndnotesXml(
+  xml: string,
+  existing?: FootnoteCollection,
+): FootnoteCollection {
+  const root = parseXml(xml);
+  const endnotesElement = findChildElementOptional(root, "endnotes");
+  const endnotes: Record<string, FootnoteDefinition> = {
+    ...(existing?.endnotes ?? {}),
+  };
+
+  if (endnotesElement) {
+    for (const child of endnotesElement.children) {
+      if (child.type !== "element") {
+        continue;
+      }
+      if (localName(child.name) !== "endnote") {
+        continue;
+      }
+      const definition = parseNoteElement(child, "endnote");
+      if (definition) {
+        endnotes[definition.noteId] = definition;
+      }
+    }
+  }
+
+  return {
+    footnotes: existing?.footnotes ?? {},
+    endnotes,
+  };
+}
+
+// ---- Internal helpers ----
+
+function parseNoteElement(
+  element: XmlElementNode,
+  kind: "footnote" | "endnote",
+): FootnoteDefinition | undefined {
+  const rawId =
+    element.attributes["w:id"] ?? element.attributes.id ?? "";
+  const rawType =
+    element.attributes["w:type"] ?? element.attributes.type ?? "";
+
+  if (!rawId || SPECIAL_NOTE_IDS.has(rawId) || SPECIAL_NOTE_TYPES.has(rawType)) {
+    return undefined;
+  }
+
+  const noteId = rawId;
+  const blocks: BlockNode[] = [];
+
+  for (const child of element.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+    const name = localName(child.name);
+    if (name === "p") {
+      blocks.push(parseParagraphElement(child));
+    } else if (name === "tbl") {
+      // 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:note-tbl-${noteId}`,
+          warningId: `warning:note-opaque-table`,
+          rawXml: serializeElementToXml(child),
+        });
+      }
+    } else {
+      blocks.push({
+        type: "opaque_block",
+        fragmentId: `fragment:note-opaque-${noteId}`,
+        warningId: `warning:note-opaque-block`,
+        rawXml: serializeElementToXml(child),
+      });
+    }
+  }
+
+  return { noteId, kind, blocks };
+}
+
+function parseParagraphElement(pElement: XmlElementNode): ParagraphNode {
+  let styleId: string | undefined;
+  let alignment: ParagraphNode["alignment"];
+  let spacing: ParagraphNode["spacing"];
+  let indentation: ParagraphNode["indentation"];
+  const children: InlineNode[] = [];
+  let activeComplexField: {
+    instruction: string;
+    children: InlineNode[];
+    mode: "instruction" | "result";
+  } | null = null;
+
+  for (const child of pElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (name === "pPr") {
+      const pStyle = findChildElementOptional(child, "pStyle");
+      styleId = pStyle?.attributes["w:val"] ?? pStyle?.attributes.val;
+      const jc = findChildElementOptional(child, "jc");
+      const jcVal = jc?.attributes["w:val"] ?? jc?.attributes.val;
+      if (jcVal === "left" || jcVal === "center" || jcVal === "right" || jcVal === "both" || jcVal === "distribute") {
+        alignment = jcVal;
+      }
+      spacing = readParagraphSpacing(child);
+      indentation = readParagraphIndentation(child);
+    } else if (name === "r") {
+      activeComplexField = appendRunNodes(child, children, activeComplexField);
+    } else if (name === "hyperlink") {
+      if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
+        children.push({
+          type: "field",
+          fieldType: "complex",
+          instruction: activeComplexField.instruction,
+          children: activeComplexField.children,
+        });
+        activeComplexField = null;
+      }
+      children.push(parseHyperlinkElement(child));
+    } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
+      const bookmarkNode = parseBookmarkElement(child);
+      if (activeComplexField?.mode === "result") {
+        activeComplexField.children.push(bookmarkNode);
+      } else {
+        if (activeComplexField && activeComplexField.instruction.trim().length > 0) {
+          children.push({
+            type: "field",
+            fieldType: "complex",
+            instruction: activeComplexField.instruction,
+            children: activeComplexField.children,
+          });
+          activeComplexField = null;
+        }
+        children.push(bookmarkNode);
+      }
+    } else if (name === "fldSimple") {
+      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 } : {}),
+    children,
+  };
+}
+
+function appendRunNodes(
+  rElement: XmlElementNode,
+  nodes: InlineNode[],
+  activeComplexField: {
+    instruction: string;
+    children: InlineNode[];
+    mode: "instruction" | "result";
+  } | null,
+): {
+  instruction: string;
+  children: InlineNode[];
+  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") {
+      activeComplexField.children.push(inlineNode);
+      continue;
+    }
+
+    nodes.push(inlineNode);
+  }
+
+  return activeComplexField;
+}
+
+function parseRunElement(rElement: XmlElementNode): InlineNode[] {
+  const nodes: InlineNode[] = [];
+  const marks: TextMark[] = parseRunProperties(rElement);
+
+  for (const child of rElement.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (name === "t") {
+      const text = extractTextContent(child);
+      if (text.length > 0) {
+        nodes.push({
+          type: "text",
+          text,
+          ...(marks.length > 0 ? { marks } : {}),
+        });
+      }
+    } else if (name === "br") {
+      nodes.push({ type: "hard_break" });
+    } else if (name === "tab") {
+      nodes.push({ type: "tab" });
+    } else if (name === "footnoteRef" || name === "endnoteRef") {
+      // The in-note reference marker (superscript) - skip, rendered by the host
+    } else if (name === "footnoteReference") {
+      const noteId =
+        child.attributes["w:id"] ?? child.attributes.id ?? "";
+      if (noteId) {
+        nodes.push({ type: "footnote_ref", noteId, noteKind: "footnote" });
+      }
+    } else if (name === "endnoteReference") {
+      const noteId =
+        child.attributes["w:id"] ?? child.attributes.id ?? "";
+      if (noteId) {
+        nodes.push({ type: "footnote_ref", noteId, noteKind: "endnote" });
+      }
+    } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
+      nodes.push(parseBookmarkElement(child));
+    } else if (name === "instrText") {
+      pushFieldNode(nodes, child, "complex");
+    }
+  }
+
+  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) {
+      return { type: "footnote_ref", noteId, noteKind: "footnote" };
+    }
+    return null;
+  }
+  if (name === "endnoteReference") {
+    const noteId =
+      child.attributes["w:id"] ?? child.attributes.id ?? "";
+    if (noteId) {
+      return { type: "footnote_ref", noteId, noteKind: "endnote" };
+    }
+    return null;
+  }
+  if (name === "bookmarkStart" || name === "bookmarkEnd") {
+    return parseBookmarkElement(child);
+  }
+
+  return null;
+}
+
+function parseHyperlinkElement(element: XmlElementNode): Extract<InlineNode, { type: "hyperlink" }> {
+  const href = element.attributes["w:anchor"]
+    ? `#${element.attributes["w:anchor"]}`
+    : element.attributes["r:id"] ?? "relationship:unknown";
+  const children: Array<Extract<InlineNode, { type: "text" | "hard_break" | "tab" }>> = [];
+
+  for (const child of element.children) {
+    if (child.type === "element" && localName(child.name) === "r") {
+      for (const runChild of parseRunElement(child)) {
+        if (runChild.type === "text" || runChild.type === "hard_break" || runChild.type === "tab") {
+          children.push(runChild);
+        }
+      }
+    }
+  }
+
+  return {
+    type: "hyperlink",
+    href,
+    children,
+  };
+}
+
+function parseBookmarkElement(
+  element: XmlElementNode,
+): Extract<InlineNode, { type: "bookmark_start" | "bookmark_end" }> {
+  const bookmarkId = element.attributes["w:id"] ?? element.attributes.id ?? "0";
+  if (localName(element.name) === "bookmarkStart") {
+    return {
+      type: "bookmark_start",
+      bookmarkId,
+      name: element.attributes["w:name"] ?? element.attributes.name ?? "",
+    };
+  }
+
+  return {
+    type: "bookmark_end",
+    bookmarkId,
+  };
+}
+
+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[] {
+  const rPr = findChildElementOptional(rElement, "rPr");
+  if (!rPr) {
+    return [];
+  }
+
+  const marks: TextMark[] = [];
+
+  for (const child of rPr.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+    const val = child.attributes["w:val"] ?? child.attributes.val ?? "true";
+
+    switch (name) {
+      case "b":
+        if (val !== "0" && val !== "false") marks.push({ type: "bold" });
+        break;
+      case "i":
+        if (val !== "0" && val !== "false") marks.push({ type: "italic" });
+        break;
+      case "u":
+        if (val !== "none" && val !== "0") marks.push({ type: "underline" });
+        break;
+      case "strike":
+        if (val !== "0" && val !== "false") marks.push({ type: "strikethrough" });
+        break;
+      case "dstrike":
+        if (val !== "0" && val !== "false") 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 "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 extractTextContent(tElement: XmlElementNode): string {
+  let text = "";
+  for (const child of tElement.children) {
+    if (child.type === "text") {
+      text += child.text;
+    }
+  }
+  return text;
+}
+
+function findChildElementOptional(
+  node: XmlElementNode,
+  childLocalName: string,
+): XmlElementNode | undefined {
+  return node.children.find(
+    (entry): entry is XmlElementNode =>
+      entry.type === "element" && localName(entry.name) === childLocalName,
+  );
+}
+
+function localName(name: string): string {
+  const idx = name.indexOf(":");
+  return idx >= 0 ? name.slice(idx + 1) : name;
+}
+
+// ---- Simple secondary-story table support ----
+
+const RISKY_TABLE_ELEMENT_NAMES = new Set([
+  "ins",
+  "del",
+  "moveFrom",
+  "moveTo",
+  "tblPrChange",
+  "trPrChange",
+  "tcPrChange",
+  "rPrChange",
+  "pPrChange",
+  "sectPrChange",
+  "fldSimple",
+  "fldChar",
+  "instrText",
+  "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 (RISKY_TABLE_ELEMENT_NAMES.has(name)) {
+      return true;
+    }
+    if (name === "tbl") {
+      return true;
+    }
+    if (containsRiskyElement(child)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function parseSimpleTableElement(tblElement: XmlElementNode): TableNode {
+  let gridColumns: number[] = [];
+  const rows: TableRowNode[] = [];
+  let propertiesXml: string | undefined;
+  let styleId: string | undefined;
+  let width: TableNode["width"];
+  let alignment: TableNode["alignment"];
+  let borders: TableNode["borders"];
+  let cellMargins: TableNode["cellMargins"];
+  let tblLook: TableNode["tblLook"];
+
+  for (const child of tblElement.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "tblPr") {
+      propertiesXml = serializeElementToXml(child);
+      styleId = readTableStyleId(child);
+      width = readTableWidth(child);
+      alignment = readTableAlignment(child);
+      borders = readTableBorders(child);
+      cellMargins = readTableCellMargins(child);
+      tblLook = readTableLook(child);
+    } else if (name === "tblGrid") {
+      gridColumns = readGridColumns(child);
+    } else if (name === "tr") {
+      rows.push(parseSimpleTableRow(child));
+    }
+  }
+
+  return {
+    type: "table",
+    ...(styleId ? { styleId } : {}),
+    ...(propertiesXml ? { propertiesXml } : {}),
+    gridColumns,
+    rows,
+    ...(width ? { width } : {}),
+    ...(alignment ? { alignment } : {}),
+    ...(borders ? { borders } : {}),
+    ...(cellMargins ? { cellMargins } : {}),
+    ...(tblLook ? { tblLook } : {}),
+  };
+}
+
+function readGridColumns(tblGrid: XmlElementNode): number[] {
+  return readSharedGridColumns(tblGrid);
+}
+
+function parseSimpleTableRow(trElement: XmlElementNode): TableRowNode {
+  const cells: TableCellNode[] = [];
+  let propertiesXml: string | undefined;
+  let height: TableRowNode["height"];
+  let heightRule: TableRowNode["heightRule"];
+  let isHeader: TableRowNode["isHeader"];
+
+  for (const child of trElement.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+
+    if (name === "trPr") {
+      propertiesXml = serializeElementToXml(child);
+      height = readRowHeight(child);
+      heightRule = readRowHeightRule(child);
+      isHeader = readRowIsHeader(child);
+    } else if (name === "tc") {
+      cells.push(parseSimpleTableCell(child));
+    }
+  }
+
+  return {
+    type: "table_row",
+    ...(propertiesXml ? { propertiesXml } : {}),
+    ...(height !== undefined ? { height } : {}),
+    ...(heightRule ? { heightRule } : {}),
+    ...(isHeader !== undefined ? { isHeader } : {}),
+    cells,
+  };
+}
+
+function parseSimpleTableCell(tcElement: XmlElementNode): TableCellNode {
+  const children: BlockNode[] = [];
+  let propertiesXml: string | undefined;
+  let gridSpan: number | undefined;
+  let verticalMerge: "restart" | "continue" | undefined;
+  let width: TableCellNode["width"];
+  let borders: TableCellNode["borders"];
+  let shading: TableCellNode["shading"];
+  let verticalAlign: TableCellNode["verticalAlign"];
+
+  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";
+      }
+      width = readCellWidth(child);
+      borders = readCellBorders(child);
+      shading = readCellShading(child);
+      verticalAlign = readCellVerticalAlign(child);
+    } else if (name === "p") {
+      children.push(parseParagraphElement(child));
+    }
+  }
+
+  return {
+    type: "table_cell",
+    ...(propertiesXml ? { propertiesXml } : {}),
+    ...(gridSpan ? { gridSpan } : {}),
+    ...(verticalMerge ? { verticalMerge } : {}),
+    ...(width ? { width } : {}),
+    ...(borders ? { borders } : {}),
+    ...(shading ? { shading } : {}),
+    ...(verticalAlign ? { verticalAlign } : {}),
+    children: children.length > 0 ? children : [{ type: "paragraph", children: [] }],
+  };
+}
+
+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 {
+  const root: XmlElementNode = {
+    type: "element",
+    name: "__root__",
+    attributes: {},
+    children: [],
+    start: 0,
+    end: xml.length,
+  };
+  const stack: XmlElementNode[] = [root];
+  let cursor = 0;
+
+  while (cursor < xml.length) {
+    if (xml.startsWith("<!--", cursor)) {
+      const end = xml.indexOf("-->", cursor);
+      cursor = end >= 0 ? end + 3 : xml.length;
+      continue;
+    }
+
+    if (xml.startsWith("<?", cursor)) {
+      const end = xml.indexOf("?>", cursor);
+      cursor = end >= 0 ? end + 2 : xml.length;
+      continue;
+    }
+
+    if (xml.startsWith("<![CDATA[", cursor)) {
+      const end = xml.indexOf("]]>", cursor);
+      const textEnd = end >= 0 ? end : xml.length;
+      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;
+    }
+
+    if (xml[cursor] !== "<") {
+      const nextTag = xml.indexOf("<", cursor);
+      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, start: cursor, end });
+      }
+      cursor = end;
+      continue;
+    }
+
+    if (xml[cursor + 1] === "/") {
+      const end = xml.indexOf(">", cursor);
+      if (end < 0) break;
+      const current = stack.pop();
+      if (current) {
+        current.end = end + 1;
+      }
+      cursor = end + 1;
+      continue;
+    }
+
+    const tagEnd = xml.indexOf(">", cursor);
+    if (tagEnd < 0) break;
+
+    const tagContent = xml.slice(cursor + 1, tagEnd);
+    const selfClosing = tagContent.endsWith("/");
+    const normalized = selfClosing ? tagContent.slice(0, -1).trimEnd() : tagContent;
+
+    const spaceIndex = normalized.search(/\s/);
+    const tagName = spaceIndex >= 0 ? normalized.slice(0, spaceIndex) : normalized;
+    const attrString = spaceIndex >= 0 ? normalized.slice(spaceIndex + 1) : "";
+    const attributes = parseAttributes(attrString);
+
+    const element: XmlElementNode = {
+      type: "element",
+      name: tagName,
+      attributes,
+      children: [],
+      start: cursor,
+      end: tagEnd + 1,
+    };
+
+    stack[stack.length - 1]?.children.push(element);
+
+    if (!selfClosing) {
+      stack.push(element);
+    }
+
+    cursor = tagEnd + 1;
+  }
+
+  return root;
+}
+
+function parseAttributes(attrString: string): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  const pattern = /([A-Za-z_:][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  for (const match of attrString.matchAll(pattern)) {
+    const name = match[1];
+    const value = match[3] ?? match[4] ?? "";
+    if (name) {
+      attrs[name] = decodeXmlEntities(value);
+    }
+  }
+  return attrs;
+}
+
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10)))
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) =>
+      String.fromCodePoint(Number.parseInt(hex, 16)),
+    );
+}