@beyondwork/docx-react-component 1.0.58 → 1.0.60

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

@@ -10,6 +10,14 @@ import type {
   TabStop,
 } from "../../model/canonical-document.ts";
 import { readRunProperties } from "./parse-run-formatting.ts";
+import type { OpcRelationship } from "./part-manifest.ts";
+import { normalizePartPath, resolveRelationshipTarget } from "./part-manifest.ts";
+import { serializeXmlElementToString } from "./xml-element-serialize.ts";
+import { parseXml } from "./xml-parser.ts";
+import { localName, readStringAttr } from "./xml-attr-helpers.ts";
+
+const TAB_ALIGN_VOCAB = new Set<TabStop["align"]>(["left", "center", "right", "decimal", "num", "bar", "clear"]);
+const TAB_LEADER_VOCAB = new Set<TabStop["leader"]>(["none", "dot", "hyphen", "underscore", "heavy", "middleDot"]);
 
 export interface ParsedParagraphNumberingReference {
   paragraphIndex: number;
@@ -31,7 +39,12 @@ interface XmlTextNode {
 
 type XmlNode = XmlElementNode | XmlTextNode;
 
-export function parseNumberingXml(xml: string): NumberingCatalog {
+export interface ParseNumberingContext {
+  relationships?: readonly OpcRelationship[];
+  partPath?: string;
+}
+
+export function parseNumberingXml(xml: string, context?: ParseNumberingContext): NumberingCatalog {
   const root = parseXml(xml);
   const numberingElement = findChildElement(root, "numbering");
   const abstractDefinitions: NumberingCatalog["abstractDefinitions"] = {};
@@ -48,40 +61,35 @@ export function parseNumberingXml(xml: string): NumberingCatalog {
     // as a catalog entry keyed by numPicBulletId; raw XML is preserved for
     // byte-identical round-trip.
     if (localName(child.name) === "numPicBullet") {
-      const rawId =
-        child.attributes["w:numPicBulletId"] ?? child.attributes.numPicBulletId;
+      const rawId = readStringAttr(child, "w:numPicBulletId");
       if (rawId) {
-        numPicBullets[rawId] = readNumPicBullet(child, rawId);
+        numPicBullets[rawId] = readNumPicBullet(child, rawId, context);
       }
       continue;
     }
 
     switch (localName(child.name)) {
       case "abstractNum": {
-        const rawId = child.attributes["w:abstractNumId"] ?? child.attributes.abstractNumId;
+        const rawId = readStringAttr(child, "w:abstractNumId");
         if (!rawId) {
           continue;
         }
 
         const abstractNumberingId = toCanonicalAbstractNumberingId(rawId);
         const nsidEl = findChildElementOptional(child, "nsid");
-        const nsid = nsidEl ? (nsidEl.attributes["w:val"] ?? nsidEl.attributes.val) : undefined;
+        const nsid = nsidEl ? readStringAttr(nsidEl, "w:val") : undefined;
         const mltEl = findChildElementOptional(child, "multiLevelType");
-        const mltRaw = mltEl ? (mltEl.attributes["w:val"] ?? mltEl.attributes.val) : undefined;
+        const mltRaw = mltEl ? readStringAttr(mltEl, "w:val") : undefined;
         const multiLevelType =
           mltRaw === "singleLevel" || mltRaw === "multilevel" || mltRaw === "hybridMultilevel"
             ? mltRaw
             : undefined;
         const tmplEl = findChildElementOptional(child, "tmpl");
-        const tplc = tmplEl ? (tmplEl.attributes["w:val"] ?? tmplEl.attributes.val) : undefined;
+        const tplc = tmplEl ? readStringAttr(tmplEl, "w:val") : undefined;
         const styleLinkEl = findChildElementOptional(child, "styleLink");
-        const styleLink = styleLinkEl
-          ? (styleLinkEl.attributes["w:val"] ?? styleLinkEl.attributes.val)
-          : undefined;
+        const styleLink = styleLinkEl ? readStringAttr(styleLinkEl, "w:val") : undefined;
         const numStyleLinkEl = findChildElementOptional(child, "numStyleLink");
-        const numStyleLink = numStyleLinkEl
-          ? (numStyleLinkEl.attributes["w:val"] ?? numStyleLinkEl.attributes.val)
-          : undefined;
+        const numStyleLink = numStyleLinkEl ? readStringAttr(numStyleLinkEl, "w:val") : undefined;
         abstractDefinitions[abstractNumberingId] = {
           abstractNumberingId,
           levels: readLevels(child),
@@ -94,10 +102,9 @@ export function parseNumberingXml(xml: string): NumberingCatalog {
         break;
       }
       case "num": {
-        const rawId = child.attributes["w:numId"] ?? child.attributes.numId;
+        const rawId = readStringAttr(child, "w:numId");
         const abstractReference = findChildElementOptional(child, "abstractNumId");
-        const rawAbstractId =
-          abstractReference?.attributes["w:val"] ?? abstractReference?.attributes.val;
+        const rawAbstractId = abstractReference ? readStringAttr(abstractReference, "w:val") : undefined;
 
         if (!rawId || !rawAbstractId) {
           continue;
@@ -126,17 +133,24 @@ export function parseNumberingXml(xml: string): NumberingCatalog {
  * inner `wp:extent` when present (drawingML path); the raw XML is
  * preserved verbatim so the export round-trips byte-for-byte regardless
  * of whether the bullet uses drawing or VML markup.
+ *
+ * Word 2016+ wraps the bullet content in mc:AlternateContent; we prefer
+ * the mc:Choice branch (DrawingML) and fall back to mc:Fallback (VML).
  */
 function readNumPicBullet(
   node: XmlElementNode,
   numPicBulletId: string,
+  context?: ParseNumberingContext,
 ): NumPicBullet {
   let widthEmu: number | undefined;
   let heightEmu: number | undefined;
+  let mediaId: string | undefined;
+
+  // Unwrap mc:AlternateContent if present (Word 2016+).
+  const contentNode = unwrapNumPicBulletContent(node);
 
-  // Walk drawing → inline/anchor → extent for the EMU dimensions. VML
-  // paths skip this branch; rendering will fall back to a default size.
-  const drawing = findChildElementOptional(node, "drawing");
+  // DrawingML path: walk drawing → inline/anchor → extent for EMU dims.
+  const drawing = findChildElementOptional(contentNode, "drawing");
   if (drawing) {
     const inline = findChildElementOptional(drawing, "inline");
     const anchor = findChildElementOptional(drawing, "anchor");
@@ -149,54 +163,65 @@ function readNumPicBullet(
         if (cx !== undefined) widthEmu = cx;
         if (cy !== undefined) heightEmu = cy;
       }
+
+      // Resolve mediaId via blip r:embed → relationships map.
+      // Walk: inline/anchor → a:graphic → a:graphicData → pic:pic → pic:blipFill → a:blip
+      if (context?.relationships && context.relationships.length > 0) {
+        const graphic = findChildElementOptional(envelope, "graphic");
+        const graphicData = graphic ? findChildElementOptional(graphic, "graphicData") : undefined;
+        const pic = graphicData ? findChildElementOptional(graphicData, "pic") : undefined;
+        const blipFill = pic ? findChildElementOptional(pic, "blipFill") : undefined;
+        const blip = blipFill ? findChildElementOptional(blipFill, "blip") : undefined;
+        const rEmbed = blip?.attributes["r:embed"] ?? blip?.attributes.embed;
+        if (rEmbed) {
+          const rel = context.relationships.find((r) => r.id === rEmbed);
+          if (rel) {
+            const packagePartName = normalizePartPath(
+              resolveRelationshipTarget(context.partPath ?? "/word/numbering.xml", rel),
+            );
+            mediaId = `media:${packagePartName.slice(1)}`;
+          }
+        }
+      }
+    }
+  }
+
+  // VML path: <w:pict> → <v:shape> → <v:imagedata r:id="rIdN">.
+  // Also parses width/height from the VML style attribute (1 pt = 12700 EMU).
+  if (mediaId === undefined) {
+    const pict = findChildElementOptional(contentNode, "pict");
+    if (pict) {
+      const shape = findChildElementOptional(pict, "shape");
+      const imagedata = shape ? findChildElementOptional(shape, "imagedata") : undefined;
+      const rId = imagedata?.attributes["r:id"] ?? imagedata?.attributes.id;
+      if (rId && context?.relationships && context.relationships.length > 0) {
+        const rel = context.relationships.find((r) => r.id === rId);
+        if (rel) {
+          const packagePartName = normalizePartPath(
+            resolveRelationshipTarget(context.partPath ?? "/word/numbering.xml", rel),
+          );
+          mediaId = `media:${packagePartName.slice(1)}`;
+        }
+      }
+      if (widthEmu === undefined && shape?.attributes.style) {
+        const style = shape.attributes.style;
+        const wMatch = /width:\s*([\d.]+)pt/.exec(style);
+        const hMatch = /height:\s*([\d.]+)pt/.exec(style);
+        if (wMatch) widthEmu = Math.round(parseFloat(wMatch[1]) * 12700);
+        if (hMatch) heightEmu = Math.round(parseFloat(hMatch[1]) * 12700);
+      }
     }
   }
 
   return {
     numPicBulletId,
-    rawXml: reconstructElementXml(node),
+    rawXml: serializeXmlElementToString(node),
     ...(widthEmu !== undefined ? { widthEmu } : {}),
     ...(heightEmu !== undefined ? { heightEmu } : {}),
+    ...(mediaId !== undefined ? { mediaId } : {}),
   };
 }
 
-/**
- * Best-effort reconstruction of the source XML for a `<w:numPicBullet>`.
- * Mirrors `buildGrabBagSourceChildFromParsed` in property-grab-bag.ts —
- * attribute/element semantic content round-trips, whitespace between
- * elements + quote styles normalize. For the Lane 3b scope this is the
- * right trade-off: picture-bullet catalog entries usually round-trip
- * once-per-document and their mediaId lookup is what matters.
- */
-function reconstructElementXml(node: XmlElementNode): string {
-  const attrs = Object.entries(node.attributes)
-    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
-    .join("");
-  if (node.children.length === 0) {
-    return `<${node.name}${attrs}/>`;
-  }
-  const body = node.children
-    .map((child) => {
-      if (child.type === "text") return escapeText(child.text);
-      if (child.type === "element") return reconstructElementXml(child);
-      return "";
-    })
-    .join("");
-  return `<${node.name}${attrs}>${body}</${node.name}>`;
-}
-
-function escapeAttr(value: string): string {
-  return value
-    .replace(/&/gu, "&amp;")
-    .replace(/</gu, "&lt;")
-    .replace(/>/gu, "&gt;")
-    .replace(/"/gu, "&quot;");
-}
-
-function escapeText(value: string): string {
-  return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
-}
-
 export function parseParagraphNumberingReferences(
   documentXml: string,
 ): ParsedParagraphNumberingReference[] {
@@ -219,8 +244,8 @@ export function parseParagraphNumberingReferences(
     if (numberingProperties) {
       const levelNode = findChildElementOptional(numberingProperties, "ilvl");
       const instanceNode = findChildElementOptional(numberingProperties, "numId");
-      const rawLevel = levelNode?.attributes["w:val"] ?? levelNode?.attributes.val;
-      const rawInstanceId = instanceNode?.attributes["w:val"] ?? instanceNode?.attributes.val;
+      const rawLevel = levelNode ? readStringAttr(levelNode, "w:val") : undefined;
+      const rawInstanceId = instanceNode ? readStringAttr(instanceNode, "w:val") : undefined;
 
       if (rawLevel !== undefined && rawInstanceId) {
         const level = parseInteger(rawLevel);
@@ -256,7 +281,7 @@ function readLevels(abstractNode: XmlElementNode): NumberingLevelDefinition[] {
       continue;
     }
 
-    const rawLevel = child.attributes["w:ilvl"] ?? child.attributes.ilvl;
+    const rawLevel = readStringAttr(child, "w:ilvl");
     const level = rawLevel === undefined ? undefined : parseInteger(rawLevel);
     if (level === undefined) {
       continue;
@@ -280,14 +305,14 @@ function readOverrides(numNode: XmlElementNode): NumberingLevelOverride[] {
       continue;
     }
 
-    const rawLevel = child.attributes["w:ilvl"] ?? child.attributes.ilvl;
+    const rawLevel = readStringAttr(child, "w:ilvl");
     const level = rawLevel === undefined ? undefined : parseInteger(rawLevel);
     if (level === undefined) {
       continue;
     }
 
     const startOverrideNode = findChildElementOptional(child, "startOverride");
-    const rawStart = startOverrideNode?.attributes["w:val"] ?? startOverrideNode?.attributes.val;
+    const rawStart = startOverrideNode ? readStringAttr(startOverrideNode, "w:val") : undefined;
     const startAt = rawStart === undefined ? undefined : parseInteger(rawStart);
     const levelDefinitionNode = findChildElementOptional(child, "lvl");
     const levelDefinition = levelDefinitionNode
@@ -308,7 +333,7 @@ function readLevelDefinition(
   levelNode: XmlElementNode,
   fallbackLevel?: number,
 ): NumberingLevelDefinition | undefined {
-  const rawLevel = levelNode.attributes["w:ilvl"] ?? levelNode.attributes.ilvl;
+  const rawLevel = readStringAttr(levelNode, "w:ilvl");
   const level = rawLevel === undefined ? fallbackLevel : parseInteger(rawLevel);
   if (level === undefined) {
     return undefined;
@@ -318,16 +343,21 @@ function readLevelDefinition(
   const formatNode = findChildElementOptional(levelNode, "numFmt");
   const textNode = findChildElementOptional(levelNode, "lvlText");
   const paragraphStyleNode = findChildElementOptional(levelNode, "pStyle");
-  const rawStart = startNode?.attributes["w:val"] ?? startNode?.attributes.val;
+  const rawStart = startNode ? readStringAttr(startNode, "w:val") : undefined;
   const startAt = rawStart === undefined ? undefined : parseInteger(rawStart);
-  const format = formatNode?.attributes["w:val"] ?? formatNode?.attributes.val ?? "decimal";
-  const text = textNode?.attributes["w:val"] ?? textNode?.attributes.val ?? `%${level + 1}.`;
-  const paragraphStyleId =
-    paragraphStyleNode?.attributes["w:val"] ?? paragraphStyleNode?.attributes.val;
+  const format = (formatNode ? readStringAttr(formatNode, "w:val") : undefined) ?? "decimal";
+  // ECMA-376 §17.9.11: w:null="1" means no text displayed; treat as empty string.
+  const lvlTextIsNull =
+    (textNode?.attributes["w:null"] ?? textNode?.attributes["null"]) === "1";
+  const text = lvlTextIsNull
+    ? ""
+    : ((textNode ? readStringAttr(textNode, "w:val") : undefined) ??
+       (format === "bullet" ? "•" : `%${level + 1}.`));
+  const paragraphStyleId = paragraphStyleNode ? readStringAttr(paragraphStyleNode, "w:val") : undefined;
   const isLegalNode = findChildElementOptional(levelNode, "isLgl");
   const isLegalNumbering = readIsLegalNumberingValue(isLegalNode);
   const suffixNode = findChildElementOptional(levelNode, "suff");
-  const suffixVal = suffixNode?.attributes["w:val"] ?? suffixNode?.attributes.val;
+  const suffixVal = suffixNode ? readStringAttr(suffixNode, "w:val") : undefined;
   const suffix =
     suffixVal === "space" || suffixVal === "nothing"
       ? suffixVal
@@ -336,13 +366,12 @@ function readLevelDefinition(
         : undefined;
   const paragraphGeometry = readLevelParagraphGeometry(levelNode);
   const lvlRestartNode = findChildElementOptional(levelNode, "lvlRestart");
-  const rawRestart = lvlRestartNode?.attributes["w:val"] ?? lvlRestartNode?.attributes.val;
+  const rawRestart = lvlRestartNode ? readStringAttr(lvlRestartNode, "w:val") : undefined;
   const restartAfterLevel = rawRestart !== undefined ? parseInteger(rawRestart) : undefined;
   const rPrNode = findChildElementOptional(levelNode, "rPr");
   const runProperties = readRunProperties(rPrNode);
   const lvlPicBulletNode = findChildElementOptional(levelNode, "lvlPicBulletId");
-  const picBulletId =
-    lvlPicBulletNode?.attributes["w:val"] ?? lvlPicBulletNode?.attributes.val;
+  const picBulletId = lvlPicBulletNode ? readStringAttr(lvlPicBulletNode, "w:val") : undefined;
 
   return {
     level,
@@ -355,7 +384,7 @@ function readLevelDefinition(
     ...(paragraphGeometry ? { paragraphGeometry } : {}),
     ...(runProperties ? { runProperties } : {}),
     ...(restartAfterLevel !== undefined ? { restartAfterLevel } : {}),
-    ...(picBulletId ? { picBulletId } : {}),
+    ...(picBulletId !== undefined ? { picBulletId } : {}),
   };
 }
 
@@ -363,7 +392,7 @@ function readLevelOverrideDefinition(
   levelNode: XmlElementNode,
   fallbackLevel?: number,
 ): NumberingLevelOverrideDefinition | undefined {
-  const rawLevel = levelNode.attributes["w:ilvl"] ?? levelNode.attributes.ilvl;
+  const rawLevel = readStringAttr(levelNode, "w:ilvl");
   const level = rawLevel === undefined ? fallbackLevel : parseInteger(rawLevel);
   if (level === undefined) {
     return undefined;
@@ -373,16 +402,19 @@ function readLevelOverrideDefinition(
   const formatNode = findChildElementOptional(levelNode, "numFmt");
   const textNode = findChildElementOptional(levelNode, "lvlText");
   const paragraphStyleNode = findChildElementOptional(levelNode, "pStyle");
-  const rawStart = startNode?.attributes["w:val"] ?? startNode?.attributes.val;
+  const rawStart = startNode ? readStringAttr(startNode, "w:val") : undefined;
   const startAt = rawStart === undefined ? undefined : parseInteger(rawStart);
-  const format = formatNode?.attributes["w:val"] ?? formatNode?.attributes.val;
-  const text = textNode?.attributes["w:val"] ?? textNode?.attributes.val;
-  const paragraphStyleId =
-    paragraphStyleNode?.attributes["w:val"] ?? paragraphStyleNode?.attributes.val;
+  const format = formatNode ? readStringAttr(formatNode, "w:val") : undefined;
+  const lvlTextIsNull =
+    (textNode?.attributes["w:null"] ?? textNode?.attributes["null"]) === "1";
+  const text = lvlTextIsNull
+    ? ""
+    : (textNode ? readStringAttr(textNode, "w:val") : undefined);
+  const paragraphStyleId = paragraphStyleNode ? readStringAttr(paragraphStyleNode, "w:val") : undefined;
   const isLegalNode = findChildElementOptional(levelNode, "isLgl");
   const isLegalNumbering = readIsLegalNumberingValue(isLegalNode);
   const suffixNode = findChildElementOptional(levelNode, "suff");
-  const suffixVal = suffixNode?.attributes["w:val"] ?? suffixNode?.attributes.val;
+  const suffixVal = suffixNode ? readStringAttr(suffixNode, "w:val") : undefined;
   const suffix =
     suffixVal === "space" || suffixVal === "nothing"
       ? suffixVal
@@ -391,10 +423,12 @@ function readLevelOverrideDefinition(
         : undefined;
   const paragraphGeometry = readLevelParagraphGeometry(levelNode);
   const lvlRestartNode = findChildElementOptional(levelNode, "lvlRestart");
-  const rawRestart = lvlRestartNode?.attributes["w:val"] ?? lvlRestartNode?.attributes.val;
+  const rawRestart = lvlRestartNode ? readStringAttr(lvlRestartNode, "w:val") : undefined;
   const restartAfterLevel = rawRestart !== undefined ? parseInteger(rawRestart) : undefined;
   const rPrNode = findChildElementOptional(levelNode, "rPr");
   const runProperties = readRunProperties(rPrNode);
+  const lvlPicBulletNode = findChildElementOptional(levelNode, "lvlPicBulletId");
+  const picBulletId = lvlPicBulletNode ? readStringAttr(lvlPicBulletNode, "w:val") : undefined;
 
   const hasExplicitFields =
     startAt !== undefined ||
@@ -405,7 +439,8 @@ function readLevelOverrideDefinition(
     suffix !== undefined ||
     paragraphGeometry !== undefined ||
     runProperties !== undefined ||
-    restartAfterLevel !== undefined;
+    restartAfterLevel !== undefined ||
+    picBulletId !== undefined;
 
   if (!hasExplicitFields) {
     return undefined;
@@ -422,6 +457,7 @@ function readLevelOverrideDefinition(
     ...(paragraphGeometry ? { paragraphGeometry } : {}),
     ...(runProperties ? { runProperties } : {}),
     ...(restartAfterLevel !== undefined ? { restartAfterLevel } : {}),
+    ...(picBulletId !== undefined ? { picBulletId } : {}),
   };
 }
 
@@ -456,11 +492,7 @@ function readLevelJustification(
     return undefined;
   }
 
-  const rawValue = (
-    justificationNode.attributes["w:val"] ??
-    justificationNode.attributes.val ??
-    ""
-  ).toLowerCase();
+  const rawValue = (readStringAttr(justificationNode, "w:val") ?? "").toLowerCase();
 
   if (rawValue === "start") {
     return "left";
@@ -488,18 +520,10 @@ function readParagraphIndentation(node: XmlElementNode): ParagraphIndentation |
   }
 
   const indentation: ParagraphIndentation = {};
-  const left =
-    indNode.attributes["w:start"] ??
-    indNode.attributes.start ??
-    indNode.attributes["w:left"] ??
-    indNode.attributes.left;
-  const right =
-    indNode.attributes["w:end"] ??
-    indNode.attributes.end ??
-    indNode.attributes["w:right"] ??
-    indNode.attributes.right;
-  const firstLine = indNode.attributes["w:firstLine"] ?? indNode.attributes.firstLine;
-  const hanging = indNode.attributes["w:hanging"] ?? indNode.attributes.hanging;
+  const left = readStringAttr(indNode, "w:start") ?? readStringAttr(indNode, "w:left");
+  const right = readStringAttr(indNode, "w:end") ?? readStringAttr(indNode, "w:right");
+  const firstLine = readStringAttr(indNode, "w:firstLine");
+  const hanging = readStringAttr(indNode, "w:hanging");
 
   if (left !== undefined) {
     const value = Number.parseInt(left, 10);
@@ -537,10 +561,10 @@ function readParagraphSpacing(node: XmlElementNode): ParagraphSpacing | undefine
   }
 
   const spacing: ParagraphSpacing = {};
-  const before = spacingNode.attributes["w:before"] ?? spacingNode.attributes.before;
-  const after = spacingNode.attributes["w:after"] ?? spacingNode.attributes.after;
-  const line = spacingNode.attributes["w:line"] ?? spacingNode.attributes.line;
-  const lineRule = spacingNode.attributes["w:lineRule"] ?? spacingNode.attributes.lineRule;
+  const before = readStringAttr(spacingNode, "w:before");
+  const after = readStringAttr(spacingNode, "w:after");
+  const line = readStringAttr(spacingNode, "w:line");
+  const lineRule = readStringAttr(spacingNode, "w:lineRule");
 
   if (before !== undefined) {
     const value = Number.parseInt(before, 10);
@@ -587,9 +611,9 @@ function readParagraphTabStops(node: XmlElementNode): TabStop[] | undefined {
       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();
+    const pos = readStringAttr(child, "w:pos");
+    const val = (readStringAttr(child, "w:val") ?? "left").toLowerCase();
+    const leader = (readStringAttr(child, "w:leader") ?? "none").toLowerCase();
     if (pos === undefined) {
       continue;
     }
@@ -599,21 +623,10 @@ function readParagraphTabStops(node: XmlElementNode): TabStop[] | undefined {
       continue;
     }
 
-    const align = (["left", "center", "right", "decimal", "num", "bar", "clear"] as const).includes(
-      val as TabStop["align"],
-    )
-      ? (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;
+    const alignCandidate = val as TabStop["align"];
+    const align: TabStop["align"] = TAB_ALIGN_VOCAB.has(alignCandidate) ? alignCandidate : "left";
+    const leaderNorm = leader === "middledot" ? "middleDot" : (leader as TabStop["leader"]);
+    const leaderValue: TabStop["leader"] | undefined = TAB_LEADER_VOCAB.has(leaderNorm) ? leaderNorm : undefined;
 
     tabStops.push({
       position,
@@ -632,11 +645,7 @@ function readIsLegalNumberingValue(
     return undefined;
   }
 
-  const rawValue = (
-    isLegalNode.attributes["w:val"] ??
-    isLegalNode.attributes.val ??
-    "1"
-  ).toLowerCase();
+  const rawValue = (readStringAttr(isLegalNode, "w:val") ?? "1").toLowerCase();
 
   if (rawValue === "0" || rawValue === "false" || rawValue === "off") {
     return false;
@@ -664,11 +673,26 @@ function findChildElementOptional(
   );
 }
 
-function localName(name: string): string {
-  const separatorIndex = name.indexOf(":");
-  return separatorIndex >= 0 ? name.slice(separatorIndex + 1) : name;
+/**
+ * If the numPicBullet node has an mc:AlternateContent child (Word 2016+),
+ * return the mc:Choice branch when it contains recognizable bullet content
+ * (w:drawing or w:pict), otherwise fall back to mc:Fallback or the original
+ * node. This mirrors parse-drawing.ts's pickAlternateContentBranch strategy.
+ */
+function unwrapNumPicBulletContent(node: XmlElementNode): XmlElementNode {
+  const alt = findChildElementOptional(node, "AlternateContent");
+  if (!alt) return node;
+  const choice = findChildElementOptional(alt, "Choice");
+  const fallback = findChildElementOptional(alt, "Fallback");
+  if (choice) {
+    const hasDrawing = findChildElementOptional(choice, "drawing") !== undefined;
+    const hasPict = findChildElementOptional(choice, "pict") !== undefined;
+    if (hasDrawing || hasPict) return choice;
+  }
+  return fallback ?? node;
 }
 
+
 function parseInteger(value: string): number | undefined {
   if (!/^-?\d+$/.test(value)) {
     return undefined;
@@ -676,208 +700,3 @@ function parseInteger(value: string): number | undefined {
 
   return Number.parseInt(value, 10);
 }
-
-function parseXml(xml: string): XmlElementNode {
-  const root: XmlElementNode = {
-    type: "element",
-    name: "__root__",
-    attributes: {},
-    children: [],
-  };
-  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),
-      });
-      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.length > 0) {
-        stack[stack.length - 1]?.children.push({
-          type: "text",
-          text,
-        });
-      }
-      cursor = end;
-      continue;
-    }
-
-    if (xml[cursor + 1] === "/") {
-      const end = xml.indexOf(">", cursor);
-      if (end < 0) {
-        throw new Error("Malformed XML: missing closing >.");
-      }
-
-      const name = xml.slice(cursor + 2, end).trim();
-      const current = stack.pop();
-      if (!current || localName(current.name) !== localName(name)) {
-        throw new Error(`Malformed XML: unexpected closing tag </${name}>.`);
-      }
-
-      cursor = end + 1;
-      continue;
-    }
-
-    const tagEnd = findTagEnd(xml, cursor);
-    const tagBody = xml.slice(cursor + 1, tagEnd);
-    const selfClosing = /\/\s*$/.test(tagBody);
-    const { name, attributes } = parseTag(tagBody.replace(/\/\s*$/, "").trim());
-    const element: XmlElementNode = {
-      type: "element",
-      name,
-      attributes,
-      children: [],
-    };
-    stack[stack.length - 1]?.children.push(element);
-
-    if (!selfClosing) {
-      stack.push(element);
-    }
-
-    cursor = tagEnd + 1;
-  }
-
-  if (stack.length !== 1) {
-    throw new Error("Malformed XML: unclosed element.");
-  }
-
-  return root;
-}
-
-function parseTag(tagBody: string): { name: string; attributes: Record<string, string> } {
-  let cursor = 0;
-  while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-    cursor += 1;
-  }
-
-  const nameStart = cursor;
-  while (cursor < tagBody.length && !/\s/.test(tagBody[cursor] ?? "")) {
-    cursor += 1;
-  }
-
-  const name = tagBody.slice(nameStart, cursor);
-  const attributes: Record<string, string> = {};
-
-  while (cursor < tagBody.length) {
-    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-    if (cursor >= tagBody.length) {
-      break;
-    }
-
-    const keyStart = cursor;
-    while (cursor < tagBody.length && !/[\s=]/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-    const key = tagBody.slice(keyStart, cursor);
-
-    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-
-    if (tagBody[cursor] !== "=") {
-      attributes[key] = "";
-      continue;
-    }
-    cursor += 1;
-
-    while (cursor < tagBody.length && /\s/.test(tagBody[cursor] ?? "")) {
-      cursor += 1;
-    }
-
-    const quote = tagBody[cursor];
-    if (quote !== `"` && quote !== `'`) {
-      throw new Error(`Malformed XML attribute ${key}.`);
-    }
-    cursor += 1;
-
-    const valueStart = cursor;
-    while (cursor < tagBody.length && tagBody[cursor] !== quote) {
-      cursor += 1;
-    }
-    const rawValue = tagBody.slice(valueStart, cursor);
-    attributes[key] = decodeXmlEntities(rawValue);
-    cursor += 1;
-  }
-
-  return { name, attributes };
-}
-
-function findTagEnd(xml: string, start: number): number {
-  let cursor = start + 1;
-  let quote: string | null = null;
-
-  while (cursor < xml.length) {
-    const current = xml[cursor];
-    if (quote) {
-      if (current === quote) {
-        quote = null;
-      }
-      cursor += 1;
-      continue;
-    }
-
-    if (current === `"` || current === `'`) {
-      quote = current;
-      cursor += 1;
-      continue;
-    }
-
-    if (current === ">") {
-      return cursor;
-    }
-
-    cursor += 1;
-  }
-
-  throw new Error("Malformed XML: missing >.");
-}
-
-function decodeXmlEntities(value: string): string {
-  return value.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (match, entity) => {
-    switch (entity) {
-      case "amp":
-        return "&";
-      case "lt":
-        return "<";
-      case "gt":
-        return ">";
-      case "quot":
-        return `"`;
-      case "apos":
-        return "'";
-      default:
-        if (entity.startsWith("#x")) {
-          return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
-        }
-        if (entity.startsWith("#")) {
-          return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
-        }
-        return match;
-    }
-  });
-}