@beyondwork/docx-react-component 1.0.60 → 1.0.62

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

@@ -14,6 +14,7 @@ import type {
 } from "../../model/canonical-document.ts";
 import type { LegacyFormFieldNode } from "../../model/canonical-document.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
+import type { ParseDrawingOpts } from "./parse-drawing.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { parseXmlWithOffsets as parseXml } from "./xml-parser.ts";
@@ -49,6 +50,7 @@ import {
   readTableStyleId,
   readTableWidth,
 } from "./parse-tables.ts";
+import { parseDrawingFrame } from "./parse-drawing.ts";
 import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 
 const TAB_ALIGN_VOCAB = new Set<TabStop["align"]>(["left", "center", "right", "decimal", "num", "bar", "clear"]);
@@ -67,6 +69,8 @@ export interface ParsedHeaderFooterDocument {
   blocks: BlockNode[];
 }
 
+export type ParseHeaderFooterOpts = Omit<ParseDrawingOpts, "blockParser">;
+
 // ---- XML node types (inline, no external dep) ----
 
 interface XmlElementNode {
@@ -121,15 +125,21 @@ export function parseHeaderFooterReferences(
 /**
  * Parse a headerN.xml part (<w:hdr> root) into block nodes.
  */
-export function parseHeaderXml(xml: string): ParsedHeaderFooterDocument {
-  return parseHdrFtrXml(xml, "hdr");
+export function parseHeaderXml(
+  xml: string,
+  opts: ParseHeaderFooterOpts = { relationships: [] },
+): ParsedHeaderFooterDocument {
+  return parseHdrFtrXml(xml, "hdr", opts);
 }
 
 /**
  * Parse a footerN.xml part (<w:ftr> root) into block nodes.
  */
-export function parseFooterXml(xml: string): ParsedHeaderFooterDocument {
-  return parseHdrFtrXml(xml, "ftr");
+export function parseFooterXml(
+  xml: string,
+  opts: ParseHeaderFooterOpts = { relationships: [] },
+): ParsedHeaderFooterDocument {
+  return parseHdrFtrXml(xml, "ftr", opts);
 }
 
 // ---- Internal helpers ----
@@ -213,6 +223,7 @@ function toHeaderFooterVariant(raw: string): HeaderFooterVariant {
 function parseHdrFtrXml(
   xml: string,
   rootLocalName: "hdr" | "ftr",
+  opts: ParseHeaderFooterOpts = { relationships: [] },
 ): ParsedHeaderFooterDocument {
   currentSourceXml = xml;
   let root: XmlElementNode;
@@ -239,12 +250,12 @@ function parseHdrFtrXml(
     const name = localName(child.name);
 
     if (name === "p") {
-      blocks.push(parseParagraphElement(child, xml));
+      blocks.push(parseParagraphElement(child, xml, opts));
     } 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, xml));
+        blocks.push(parseSimpleTableElement(child, xml, opts));
       } else {
         blocks.push({
           type: "opaque_block",
@@ -267,7 +278,11 @@ function parseHdrFtrXml(
   return { blocks };
 }
 
-function parseParagraphElement(pElement: XmlElementNode, sourceXml: string): ParagraphNode {
+function parseParagraphElement(
+  pElement: XmlElementNode,
+  sourceXml: string,
+  opts: ParseHeaderFooterOpts,
+): ParagraphNode {
   let styleId: string | undefined;
   let alignment: ParagraphNode["alignment"];
   let spacing: ParagraphNode["spacing"];
@@ -295,9 +310,9 @@ function parseParagraphElement(pElement: XmlElementNode, sourceXml: string): Par
       indentation = readParagraphIndentation(child);
       tabStops = readParagraphTabStops(child);
     } else if (name === "r") {
-      activeComplexField = appendRunNodes(child, children, activeComplexField, sourceXml);
+      activeComplexField = appendRunNodes(child, children, activeComplexField, sourceXml, opts);
     } else if (name === "hyperlink") {
-      children.push(parseHyperlinkElement(child));
+      children.push(parseHyperlinkElement(child, opts));
     } else if (name === "bookmarkStart" || name === "bookmarkEnd") {
       children.push(parseBookmarkElement(child));
     } else if (name === "fldSimple") {
@@ -350,6 +365,7 @@ function appendRunNodes(
   nodes: InlineNode[],
   activeComplexField: ActiveComplexField | null,
   sourceXml: string,
+  opts: ParseHeaderFooterOpts,
 ): ActiveComplexField | null {
   const marks: TextMark[] = parseRunProperties(rElement);
 
@@ -398,7 +414,7 @@ function appendRunNodes(
       continue;
     }
 
-    const inlineNode = parseRunChildNode(child, marks);
+    const inlineNode = parseRunChildNode(child, marks, opts);
     if (!inlineNode) {
       continue;
     }
@@ -420,7 +436,10 @@ function appendRunNodes(
   return activeComplexField;
 }
 
-function parseRunElement(rElement: XmlElementNode): InlineNode[] {
+function parseRunElement(
+  rElement: XmlElementNode,
+  opts: ParseHeaderFooterOpts,
+): InlineNode[] {
   const nodes: InlineNode[] = [];
   const marks: TextMark[] = parseRunProperties(rElement);
 
@@ -472,9 +491,9 @@ function parseRunElement(rElement: XmlElementNode): InlineNode[] {
       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);
+      const drawingResult = parseDrawingInlineNode(drawingXml, opts);
+      if (drawingResult) {
+        nodes.push(drawingResult);
       }
     } else if (name === "pict") {
       const pictXml = currentSourceXml.slice(child.start, child.end);
@@ -483,17 +502,19 @@ function parseRunElement(rElement: XmlElementNode): InlineNode[] {
         nodes.push(vmlResult);
       }
     } else if (name === "AlternateContent") {
+      const alternateXml = currentSourceXml.slice(child.start, child.end);
       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 legacyDrawingXml = drawingNode
+        ? currentSourceXml.slice(drawingNode.start, drawingNode.end)
+        : undefined;
+      const alternateDrawingResult = parseDrawingInlineNode(
+        alternateXml,
+        opts,
+        legacyDrawingXml,
+      );
+      if (alternateDrawingResult) {
+        nodes.push(alternateDrawingResult);
+        continue;
       }
       const pictNode = findFirstDescendant(child, "pict");
       if (pictNode) {
@@ -515,6 +536,7 @@ function parseRunElement(rElement: XmlElementNode): InlineNode[] {
 function parseRunChildNode(
   child: XmlElementNode,
   marks: TextMark[],
+  opts: ParseHeaderFooterOpts,
 ): InlineNode | null {
   const name = localName(child.name);
 
@@ -566,23 +588,21 @@ function parseRunChildNode(
   }
   if (name === "drawing") {
     const drawingXml = currentSourceXml.slice(child.start, child.end);
-    return parseShapeXml(drawingXml);
+    return parseDrawingInlineNode(drawingXml, opts);
   }
   if (name === "pict") {
     const pictXml = currentSourceXml.slice(child.start, child.end);
     return parseVmlXml(pictXml);
   }
   if (name === "AlternateContent") {
+    const alternateXml = currentSourceXml.slice(child.start, child.end);
     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 drawingXml = drawingNode
+      ? currentSourceXml.slice(drawingNode.start, drawingNode.end)
+      : undefined;
+    const drawingResult = parseDrawingInlineNode(alternateXml, opts, drawingXml);
+    if (drawingResult) {
+      return drawingResult;
     }
     const pictNode = findFirstDescendant(child, "pict");
     if (pictNode) {
@@ -600,7 +620,10 @@ function parseRunChildNode(
   return null;
 }
 
-function parseHyperlinkElement(element: XmlElementNode): Extract<InlineNode, { type: "hyperlink" }> {
+function parseHyperlinkElement(
+  element: XmlElementNode,
+  opts: ParseHeaderFooterOpts,
+): Extract<InlineNode, { type: "hyperlink" }> {
   const href = element.attributes["w:anchor"]
     ? `#${element.attributes["w:anchor"]}`
     : element.attributes["r:id"] ?? "relationship:unknown";
@@ -608,7 +631,7 @@ function parseHyperlinkElement(element: XmlElementNode): Extract<InlineNode, { t
 
   for (const child of element.children) {
     if (child.type === "element" && localName(child.name) === "r") {
-      for (const runChild of parseRunElement(child)) {
+      for (const runChild of parseRunElement(child, opts)) {
         if (runChild.type === "text" || runChild.type === "hard_break" || runChild.type === "tab") {
           children.push(runChild);
         }
@@ -623,6 +646,46 @@ function parseHyperlinkElement(element: XmlElementNode): Extract<InlineNode, { t
   };
 }
 
+function parseDrawingInlineNode(
+  rawXml: string,
+  opts: ParseHeaderFooterOpts,
+  legacyDrawingXml?: string,
+): InlineNode | null {
+  try {
+    const frame = parseDrawingFrame(rawXml, {
+      ...opts,
+      relationships: opts.relationships ?? [],
+    });
+    if (
+      frame &&
+      !(
+        frame.content.type === "shape" &&
+        frame.content.isTextBox
+      )
+    ) {
+      return frame;
+    }
+    if (frame?.content.type !== "shape" || !frame.content.isTextBox) {
+      return frame;
+    }
+  } catch {
+    // Fall through to the legacy shape path.
+  }
+
+  const shapeXml = legacyDrawingXml ?? rawXml;
+  const legacyShape = parseShapeXml(shapeXml);
+  if (!legacyShape) {
+    return null;
+  }
+  if (legacyDrawingXml) {
+    return {
+      ...legacyShape,
+      rawXml,
+    };
+  }
+  return legacyShape;
+}
+
 function parseBookmarkElement(
   element: XmlElementNode,
 ): Extract<InlineNode, { type: "bookmark_start" | "bookmark_end" }> {
@@ -958,7 +1021,11 @@ function isSafeSecondaryStoryFieldFamily(family: string): boolean {
   );
 }
 
-function parseSimpleTableElement(tblElement: XmlElementNode, sourceXml: string): TableNode {
+function parseSimpleTableElement(
+  tblElement: XmlElementNode,
+  sourceXml: string,
+  opts: ParseHeaderFooterOpts,
+): TableNode {
   let gridColumns: number[] = [];
   const rows: TableRowNode[] = [];
   let propertiesXml: string | undefined;
@@ -998,7 +1065,7 @@ function parseSimpleTableElement(tblElement: XmlElementNode, sourceXml: string):
     } else if (name === "tblGrid") {
       gridColumns = readGridColumns(child);
     } else if (name === "tr") {
-      rows.push(parseSimpleTableRow(child, sourceXml));
+      rows.push(parseSimpleTableRow(child, sourceXml, opts));
     }
   }
 
@@ -1027,7 +1094,11 @@ function readGridColumns(tblGrid: XmlElementNode): number[] {
   return readSharedGridColumns(tblGrid);
 }
 
-function parseSimpleTableRow(trElement: XmlElementNode, sourceXml: string): TableRowNode {
+function parseSimpleTableRow(
+  trElement: XmlElementNode,
+  sourceXml: string,
+  opts: ParseHeaderFooterOpts,
+): TableRowNode {
   const cells: TableCellNode[] = [];
   let propertiesXml: string | undefined;
   let height: TableRowNode["height"];
@@ -1050,7 +1121,7 @@ function parseSimpleTableRow(trElement: XmlElementNode, sourceXml: string): Tabl
       horizontalAlignment = readRowHorizontalAlignment(child);
       cnfStyle = readRowCnfStyle(child);
     } else if (name === "tc") {
-      cells.push(parseSimpleTableCell(child, sourceXml));
+      cells.push(parseSimpleTableCell(child, sourceXml, opts));
     }
   }
 
@@ -1067,7 +1138,11 @@ function parseSimpleTableRow(trElement: XmlElementNode, sourceXml: string): Tabl
   };
 }
 
-function parseSimpleTableCell(tcElement: XmlElementNode, sourceXml: string): TableCellNode {
+function parseSimpleTableCell(
+  tcElement: XmlElementNode,
+  sourceXml: string,
+  opts: ParseHeaderFooterOpts,
+): TableCellNode {
   const children: BlockNode[] = [];
   let propertiesXml: string | undefined;
   let gridSpan: number | undefined;
@@ -1107,7 +1182,7 @@ function parseSimpleTableCell(tcElement: XmlElementNode, sourceXml: string): Tab
       margins = readCellMargins(child);
       cnfStyle = readCellCnfStyle(child);
     } else if (name === "p") {
-      children.push(parseParagraphElement(child, sourceXml));
+      children.push(parseParagraphElement(child, sourceXml, opts));
     }
   }
 

package/src/io/ooxml/parse-main-document.ts

@@ -1150,15 +1150,15 @@ function parseBodyChild(
     ...(contextualSpacing !== undefined ? { contextualSpacing } : {}),
     ...(indentation ? { indentation } : {}),
     ...(tabStops && tabStops.length > 0 ? { tabStops } : {}),
-    ...(keepNext ? { keepNext } : {}),
-    ...(keepLines ? { keepLines } : {}),
+    ...(keepNext !== undefined ? { keepNext } : {}),
+    ...(keepLines !== undefined ? { keepLines } : {}),
     ...(outlineLevel !== undefined ? { outlineLevel } : {}),
-    ...(pageBreakBefore ? { pageBreakBefore } : {}),
-    ...(widowControl ? { widowControl } : {}),
+    ...(pageBreakBefore !== undefined ? { pageBreakBefore } : {}),
+    ...(widowControl !== undefined ? { widowControl } : {}),
     ...(borders ? { borders } : {}),
     ...(shading ? { shading } : {}),
-    ...(bidi ? { bidi } : {}),
-    ...(suppressLineNumbers ? { suppressLineNumbers } : {}),
+    ...(bidi !== undefined ? { bidi } : {}),
+    ...(suppressLineNumbers !== undefined ? { suppressLineNumbers } : {}),
     ...(cnfStyle ? { cnfStyle } : {}),
     ...(wordExtensionIds ? { wordExtensionIds } : {}),
     ...(sectionProperties ? { sectionProperties } : {}),
@@ -1848,7 +1848,7 @@ function tableRequiresOpaquePreservation(rawXml: string): boolean {
   // nested tables, floating images, VML preview atoms, and bounded field
   // families already owned by the current field slice. Risky table-local
   // semantics still fail closed to preserve-only.
-  if (/<w:(ins|del|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag|tblCellSpacing)\b/.test(rawXml)) {
+  if (/<w:(ins|del|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/.test(rawXml)) {
     return true;
   }
 
@@ -2103,7 +2103,7 @@ function readOnOffParagraphProperty(node: XmlElementNode, name: string): boolean
   );
   if (!propNode) return undefined;
   const val = (propNode.attributes["w:val"] ?? propNode.attributes.val ?? "true").toLowerCase();
-  return val !== "false" && val !== "0" && val !== "off" ? true : undefined;
+  return val !== "false" && val !== "0" && val !== "off";
 }
 
 function readOptionalOnOffParagraphProperty(
@@ -2172,9 +2172,21 @@ function readParagraphShading(node: XmlElementNode): ParagraphShading | undefine
   const fill = shadingNode.attributes["w:fill"] ?? shadingNode.attributes.fill;
   const color = shadingNode.attributes["w:color"] ?? shadingNode.attributes.color;
   const val = shadingNode.attributes["w:val"] ?? shadingNode.attributes.val;
+  const themeFill = shadingNode.attributes["w:themeFill"] ?? shadingNode.attributes.themeFill;
+  const themeFillTint = shadingNode.attributes["w:themeFillTint"] ?? shadingNode.attributes.themeFillTint;
+  const themeFillShade = shadingNode.attributes["w:themeFillShade"] ?? shadingNode.attributes.themeFillShade;
+  const themeColor = shadingNode.attributes["w:themeColor"] ?? shadingNode.attributes.themeColor;
+  const themeColorTint = shadingNode.attributes["w:themeColorTint"] ?? shadingNode.attributes.themeColorTint;
+  const themeColorShade = shadingNode.attributes["w:themeColorShade"] ?? shadingNode.attributes.themeColorShade;
   if (fill) shading.fill = fill;
   if (color) shading.color = color;
   if (val) shading.val = val;
+  if (themeFill) shading.themeFill = themeFill;
+  if (themeFillTint) shading.themeFillTint = themeFillTint;
+  if (themeFillShade) shading.themeFillShade = themeFillShade;
+  if (themeColor) shading.themeColor = themeColor;
+  if (themeColorTint) shading.themeColorTint = themeColorTint;
+  if (themeColorShade) shading.themeColorShade = themeColorShade;
   return Object.keys(shading).length > 0 ? shading : undefined;
 }
 

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

@@ -22,6 +22,7 @@ import type { OleEmbedNode } from "../../model/canonical-document.ts";
 import type { OpcRelationship } from "./part-manifest.ts";
 import type { XmlElementNode } from "./xml-element.ts";
 import { resolveOleRelationship } from "./parse-ole-relationship.ts";
+import { classifyEmbedding } from "./classify-embedding.ts";
 
 /**
  * Parse a `<w:object>` element into an `OleEmbedNode` if it contains an
@@ -64,6 +65,28 @@ export function parseObject(
     return undefined;
   }
 
+  // hotfix/ole-digestibility-guard — classify the embedding before
+  // constructing a canonical node. When the classifier returns
+  // "store-only" (nested Word docs, PDF OLE, Excel/PowerPoint
+  // embeddings, unknown ProgIDs), return undefined so the caller's
+  // existing opaque-fragment fallback preserves both <w:object> XML
+  // and its r:id verbatim. Binary preservation is unaffected —
+  // collectPreservedPackageParts indexes embedding parts by path, not
+  // by canonical-tree reference.
+  //
+  // TODO(refactor/01 Step 6-7): replace this skip-construction with
+  // extraction + offload via hostAdapter.storeEmbeddedDocument?. See
+  // docs/architecture/01-package-session.md §P8 + docs/plans/refactor/
+  // 01-package-session.md Steps 6-7.
+  const kind = classifyEmbedding({
+    progId,
+    relationshipType: resolved.relationshipType,
+    targetPath: resolved.target,
+  });
+  if (kind !== "digestible") {
+    return undefined;
+  }
+
   const metadata: OleEmbedNode["metadata"] = {};
   if (resolved.originalFilename) {
     metadata.originalFilename = resolved.originalFilename;

package/src/io/ooxml/parse-paragraph-formatting.ts

@@ -132,11 +132,35 @@ function readShading(node: XmlElementNode): ParagraphShading | undefined {
   const val = node.attributes["w:val"] ?? node.attributes.val;
   const fill = node.attributes["w:fill"] ?? node.attributes.fill;
   const color = node.attributes["w:color"] ?? node.attributes.color;
-  if (!val && !fill && !color) return undefined;
+  const themeFill = node.attributes["w:themeFill"] ?? node.attributes.themeFill;
+  const themeFillTint = node.attributes["w:themeFillTint"] ?? node.attributes.themeFillTint;
+  const themeFillShade = node.attributes["w:themeFillShade"] ?? node.attributes.themeFillShade;
+  const themeColor = node.attributes["w:themeColor"] ?? node.attributes.themeColor;
+  const themeColorTint = node.attributes["w:themeColorTint"] ?? node.attributes.themeColorTint;
+  const themeColorShade = node.attributes["w:themeColorShade"] ?? node.attributes.themeColorShade;
+  if (
+    !val &&
+    !fill &&
+    !color &&
+    !themeFill &&
+    !themeFillTint &&
+    !themeFillShade &&
+    !themeColor &&
+    !themeColorTint &&
+    !themeColorShade
+  ) {
+    return undefined;
+  }
   return {
     ...(val ? { val } : {}),
     ...(fill ? { fill } : {}),
     ...(color ? { color } : {}),
+    ...(themeFill ? { themeFill } : {}),
+    ...(themeFillTint ? { themeFillTint } : {}),
+    ...(themeFillShade ? { themeFillShade } : {}),
+    ...(themeColor ? { themeColor } : {}),
+    ...(themeColorTint ? { themeColorTint } : {}),
+    ...(themeColorShade ? { themeColorShade } : {}),
   };
 }
 

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

@@ -3,6 +3,7 @@ import type {
   ClrSchemeMapping,
   ClrSchemeMappingSlot,
   DocumentSettings,
+  FootnoteProperties,
   ThemeColorSlot,
 } from "../../model/canonical-document.ts";
 import { parseXml } from "./xml-parser.ts";
@@ -51,6 +52,13 @@ export function parseSettingsXml(xml: string): DocumentSettings {
   const compatPartition = compat ? partitionCompat(compat) : undefined;
   const rootCompatFlags = readRootCompatFlags(settingsElement);
   const themeFontLangElement = findChildElementOptional(settingsElement, "themeFontLang");
+  const defaultTabStop = readDefaultTabStop(settingsElement);
+  const footnotePr = readFootnoteLikeProperties(
+    findChildElementOptional(settingsElement, "footnotePr"),
+  );
+  const endnotePr = readFootnoteLikeProperties(
+    findChildElementOptional(settingsElement, "endnotePr"),
+  );
   const clrSchemeMapping = parseClrSchemeMapping(settingsElement);
   const unmodelled = readUnmodelledSettingsChildren(settingsElement);
 
@@ -71,6 +79,9 @@ export function parseSettingsXml(xml: string): DocumentSettings {
     ...(themeFontLangElement
       ? { themeFontLang: { ...themeFontLangElement.attributes } }
       : {}),
+    ...(defaultTabStop !== undefined ? { defaultTabStop } : {}),
+    ...(footnotePr ? { footnotePr } : {}),
+    ...(endnotePr ? { endnotePr } : {}),
     ...(clrSchemeMapping !== undefined ? { clrSchemeMapping } : {}),
     ...(unmodelled.length > 0 ? { unmodelledSettingsChildren: unmodelled } : {}),
   };
@@ -86,6 +97,9 @@ const MODELLED_SETTINGS_CHILD_NAMES = new Set<string>([
   "zoom",
   "compat",
   "themeFontLang",
+  "defaultTabStop",
+  "footnotePr",
+  "endnotePr",
   "clrSchemeMapping",
 ]);
 
@@ -130,6 +144,83 @@ function readRootCompatFlags(
   return flags;
 }
 
+function readDefaultTabStop(
+  settingsElement: XmlElementNode,
+): number | undefined {
+  const element = findChildElementOptional(settingsElement, "defaultTabStop");
+  if (!element) return undefined;
+  const rawValue = element.attributes["w:val"] ?? element.attributes.val;
+  if (!rawValue) return undefined;
+  const parsed = Number.parseInt(rawValue, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function readFootnoteLikeProperties(
+  element: XmlElementNode | undefined,
+): FootnoteProperties | undefined {
+  if (!element) return undefined;
+
+  const result: FootnoteProperties = {};
+  for (const child of element.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+    const val = child.attributes["w:val"] ?? child.attributes.val;
+
+    if (name === "pos") {
+      if (
+        val === "pageBottom" ||
+        val === "beneathText" ||
+        val === "sectEnd" ||
+        val === "docEnd"
+      ) {
+        result.pos = val;
+      }
+      continue;
+    }
+
+    if (name === "numFmt") {
+      if (
+        val === "decimal" ||
+        val === "upperRoman" ||
+        val === "lowerRoman" ||
+        val === "upperLetter" ||
+        val === "lowerLetter" ||
+        val === "ordinal" ||
+        val === "cardinalText" ||
+        val === "ordinalText" ||
+        val === "hex" ||
+        val === "chicago" ||
+        val === "bullet" ||
+        val === "ideographDigital" ||
+        val === "japaneseCounting" ||
+        val === "arabicAbjad" ||
+        val === "arabicAlpha" ||
+        val === "none"
+      ) {
+        result.numFmt = val;
+      }
+      continue;
+    }
+
+    if (name === "numStart") {
+      const parsed = Number.parseInt(val ?? "", 10);
+      if (Number.isFinite(parsed)) {
+        result.numStart = Math.max(1, parsed);
+      }
+      continue;
+    }
+
+    if (
+      name === "numRestart" &&
+      (val === "continuous" || val === "eachSect" || val === "eachPage")
+    ) {
+      result.numRestart = val;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 interface CompatPartition {
   compatSettings: CompatSetting[];
   compatFlags: Record<string, boolean>;
@@ -218,4 +309,3 @@ function readZoomLevel(
 
   return { zoomLevel: parsed };
 }
-

package/src/model/canonical-document.ts

@@ -346,14 +346,20 @@ export interface FootnoteDefinition {
  * footnote/endnote entries with `w:type="separator"` and
  * `w:type="continuationSeparator"`.
  *
- * Content is stored as raw inner XML (the run children of the <w:p>) so
- * Lane 3a page-chrome can render the horizontal rule without re-parsing.
+ * The canonical model keeps both the legacy run-only payload and the full
+ * first-paragraph XML. The paragraph form closes round-trip fidelity for
+ * imported separator paragraph properties, while the run form remains for
+ * back-compat with the current note-separator runtime helpers.
  */
 export interface FootnoteSeparators {
   /** Raw XML of the <w:r> children inside the separator paragraph. */
   separatorContent?: string;
+  /** Full XML of the first separator paragraph. */
+  separatorParagraphXml?: string;
   /** Raw XML of the <w:r> children inside the continuationSeparator paragraph. */
   continuationSeparatorContent?: string;
+  /** Full XML of the first continuation-separator paragraph. */
+  continuationSeparatorParagraphXml?: string;
 }
 
 export interface FootnoteCollection {
@@ -399,6 +405,22 @@ export interface CompatSetting {
 export interface DocumentSettings {
   evenAndOddHeaders?: boolean;
   zoomLevel?: "pageWidth" | "onePage" | number;
+  /**
+   * Document-wide default tab stop interval from `<w:defaultTabStop w:val>`.
+   * Value is stored in twips and feeds layout measurement whenever a paragraph
+   * does not declare an explicit next tab stop.
+   */
+  defaultTabStop?: number;
+  /**
+   * Settings-level default footnote configuration from `<w:footnotePr>`.
+   * Section-level `SectionProperties.footnotePr` overrides this when present.
+   */
+  footnotePr?: FootnoteProperties;
+  /**
+   * Settings-level default endnote configuration from `<w:endnotePr>`.
+   * Section-level `SectionProperties.endnotePr` overrides this when present.
+   */
+  endnotePr?: EndnoteProperties;
   /**
    * Ordered list of <w:compatSetting> entries inside <w:compat>. Insertion
    * order is preserved for serializer diff stability.
@@ -606,6 +628,18 @@ export interface ParagraphShading {
   fill?: string;
   color?: string;
   val?: string;
+  /**
+   * Theme shading references (§17.3.5). When `themeFill` is set and `fill`
+   * is absent or `"auto"`, render-time shading resolves through the theme
+   * color resolver. The raw theme attrs remain on the canonical model so
+   * export can round-trip the original `<w:shd>` byte-for-byte.
+   */
+  themeFill?: string;
+  themeFillTint?: string;
+  themeFillShade?: string;
+  themeColor?: string;
+  themeColorTint?: string;
+  themeColorShade?: string;
 }
 
 /** Body of an OOXML `<w:rPr>` (run properties). All fields optional; absence = "not specified at this level". */