@beyondwork/docx-react-component 1.0.29 → 1.0.30

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

@@ -0,0 +1,1212 @@
+import type {
+  BlockNode,
+  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 {
+  readCellBorders,
+  readCellShading,
+  readCellVerticalAlign,
+  readCellWidth,
+  readGridColumns as readSharedGridColumns,
+  readRowHeight,
+  readRowHeightRule,
+  readRowIsHeader,
+  readTableAlignment,
+  readTableBorders,
+  readTableCellMargins,
+  readTableLook,
+  readTableStyleId,
+  readTableWidth,
+} from "./parse-tables.ts";
+import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
+
+// ---- Public types ----
+
+export interface ParsedHeaderFooterReference {
+  variant: HeaderFooterVariant;
+  relationshipId: string;
+  kind: "header" | "footer";
+  sectionIndex?: number;
+}
+
+export interface ParsedHeaderFooterDocument {
+  blocks: BlockNode[];
+}
+
+// ---- 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;
+
+let currentSourceXml = "";
+
+// ---- Public API ----
+
+/**
+ * Scan a document body XML for w:headerReference / w:footerReference elements
+ * inside w:sectPr and return the relationship references.
+ */
+export function parseHeaderFooterReferences(
+  documentXml: string,
+): ParsedHeaderFooterReference[] {
+  const root = parseXml(documentXml);
+  const documentElement = findChildElementOptional(root, "document");
+  if (!documentElement) {
+    return [];
+  }
+
+  const bodyElement = findChildElementOptional(documentElement, "body");
+  if (!bodyElement) {
+    return [];
+  }
+
+  const refs: ParsedHeaderFooterReference[] = [];
+
+  // Collect all sectPr elements (can appear in paragraph pPr and at body level)
+  collectSectPrReferences(bodyElement, refs);
+
+  return refs;
+}
+
+/**
+ * Parse a headerN.xml part (<w:hdr> root) into block nodes.
+ */
+export function parseHeaderXml(xml: string): ParsedHeaderFooterDocument {
+  return parseHdrFtrXml(xml, "hdr");
+}
+
+/**
+ * Parse a footerN.xml part (<w:ftr> root) into block nodes.
+ */
+export function parseFooterXml(xml: string): ParsedHeaderFooterDocument {
+  return parseHdrFtrXml(xml, "ftr");
+}
+
+// ---- Internal helpers ----
+
+function collectSectPrReferences(
+  element: XmlElementNode,
+  refs: ParsedHeaderFooterReference[],
+): void {
+  let sectionIndex = 0;
+  for (const child of element.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+
+    if (name === "sectPr") {
+      // Body-level sectPr is the final section
+      extractSectPrRefs(child, refs, sectionIndex);
+    } else if (name === "p") {
+      // 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, sectionIndex);
+          sectionIndex++;
+        }
+      }
+    }
+  }
+}
+
+function extractSectPrRefs(
+  sectPr: XmlElementNode,
+  refs: ParsedHeaderFooterReference[],
+  sectionIndex: number,
+): void {
+  for (const child of sectPr.children) {
+    if (child.type !== "element") {
+      continue;
+    }
+
+    const name = localName(child.name);
+    if (name === "headerReference" || name === "footerReference") {
+      const kind: "header" | "footer" = name === "headerReference" ? "header" : "footer";
+      const rawType =
+        child.attributes["w:type"] ?? child.attributes.type ?? "default";
+      const variant = toHeaderFooterVariant(rawType);
+      const relationshipId =
+        child.attributes["r:id"] ??
+        child.attributes["r:Id"] ??
+        child.attributes.id ??
+        child.attributes.Id ??
+        "";
+
+      if (relationshipId) {
+        // Avoid duplicates (multiple sectPr may reference same header)
+        const dedupeKey = `${kind}:${variant}:${relationshipId}`;
+        const alreadyAdded = refs.some(
+          (ref) => `${ref.kind}:${ref.variant}:${ref.relationshipId}` === dedupeKey,
+        );
+        if (!alreadyAdded) {
+          refs.push({ variant, relationshipId, kind, sectionIndex });
+        }
+      }
+    }
+  }
+}
+
+function toHeaderFooterVariant(raw: string): HeaderFooterVariant {
+  if (raw === "first") {
+    return "first";
+  }
+  if (raw === "even") {
+    return "even";
+  }
+  return "default";
+}
+
+function parseHdrFtrXml(
+  xml: string,
+  rootLocalName: "hdr" | "ftr",
+): ParsedHeaderFooterDocument {
+  const root = parseXml(xml);
+  const hdrFtrElement = findChildElementOptional(root, rootLocalName);
+  if (!hdrFtrElement) {
+    return { blocks: [] };
+  }
+
+  const blocks: BlockNode[] = [];
+
+  for (const child of hdrFtrElement.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: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),
+      });
+    }
+  }
+
+  return { blocks };
+}
+
+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") {
+      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);
+      tabStops = readParagraphTabStops(child);
+    } else if (name === "r") {
+      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") {
+      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);
+
+  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 === "footnoteReference") {
+      const noteId =
+        child.attributes["w:id"] ?? child.attributes.id ?? "";
+      if (noteId) {
+        const ref: FootnoteRefNode = {
+          type: "footnote_ref",
+          noteId,
+          noteKind: "footnote",
+        };
+        nodes.push(ref);
+      }
+    } else if (name === "endnoteReference") {
+      const noteId =
+        child.attributes["w:id"] ?? child.attributes.id ?? "";
+      if (noteId) {
+        const ref: FootnoteRefNode = {
+          type: "footnote_ref",
+          noteId,
+          noteKind: "endnote",
+        };
+        nodes.push(ref);
+      }
+    } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
+      nodes.push(parseBookmarkElement(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"]}`
+    : 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 "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) {
+    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 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;
+  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: [] }],
+  };
+}
+
+/**
+ * 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;
+
+  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;
+    }
+
+    // Closing tag
+    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;
+    }
+
+    // Open or self-closing tag
+    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)),
+    );
+}