@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/src/io/export/serialize-styles.ts

@@ -0,0 +1,212 @@
+/**
+ * Serialize a `StylesCatalog` to an OOXML `<w:styles>` document fragment.
+ *
+ * ⚠️ NOT YET WIRED INTO THE EXPORT PIPELINE. As of the Task 7 commit (bullet-list
+ * fidelity Phase 1), the real docx export path (`reattach-preserved-parts.ts`)
+ * copies `word/styles.xml` verbatim from the source package — this module is
+ * reachable only from tests. That is fine for Phases 2–3 (the cascade resolver
+ * reads the parsed catalog fields; it doesn't require re-emission).
+ *
+ * Before wiring this serializer into `docx-session.ts` / `ownedOutputPaths`, the
+ * following gaps MUST be closed — otherwise wiring it in will silently destroy
+ * user data:
+ *
+ *   1. `StylesCatalog.latentStyles` is not emitted. Add a `buildLatentStylesXml`
+ *      counterpart and call it inside `<w:styles>` after `<w:docDefaults>`.
+ *   2. `StylesCatalog.tables` is not emitted. Table styles round-trip through
+ *      the existing `serialize-table-styles` path today only because styles.xml
+ *      passes through verbatim; wiring this serializer would drop them.
+ *   3. The `<w:style>` metadata fields `<w:aliases>`, `<w:link>`, `<w:autoRedefine>`,
+ *      `<w:hidden>`, `<w:uiPriority>`, `<w:semiHidden>`, `<w:unhideWhenUsed>`,
+ *      `<w:qFormat>`, `<w:locked>`, `<w:personal>`, `<w:personal{Compose,Reply}>`,
+ *      `<w:rsid>`, plus the `<w:customStyle>` attribute, are not modeled on
+ *      `ParagraphStyleDefinition`/`CharacterStyleDefinition` yet. Extend the
+ *      canonical model first, parse them, and emit them here.
+ *   4. Root-level `<w:styles>` metadata (`<w:docId>`, `<w:rsids>`) is not
+ *      modeled or emitted.
+ *
+ * Until those are closed, wiring this in would be a regression.
+ */
+
+import type { StylesCatalog } from "../../model/canonical-document.ts";
+import { buildRunPropertiesXml } from "./serialize-run-formatting.ts";
+import { buildParagraphPropertiesXml } from "./serialize-paragraph-formatting.ts";
+
+export const WORD_STYLES_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml";
+
+function escXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function buildDocDefaultsXml(catalog: StylesCatalog): string {
+  const { docDefaults } = catalog;
+  if (!docDefaults) return "";
+
+  const rPrXml = buildRunPropertiesXml(docDefaults.run);
+  const pPrXml = buildParagraphPropertiesXml(docDefaults.paragraph);
+
+  if (!rPrXml && !pPrXml) return "";
+
+  const rPrDefault = rPrXml
+    ? `<w:rPrDefault>${rPrXml}</w:rPrDefault>`
+    : "";
+  const pPrDefault = pPrXml
+    ? `<w:pPrDefault>${pPrXml}</w:pPrDefault>`
+    : "";
+
+  return `<w:docDefaults>${rPrDefault}${pPrDefault}</w:docDefaults>`;
+}
+
+function buildParagraphStyleXml(
+  style: StylesCatalog["paragraphs"][string],
+): string {
+  const defaultAttr = style.isDefault ? ` w:default="1"` : "";
+  const nameEl = `<w:name w:val="${escXml(style.displayName)}"/>`;
+  const basedOnEl = style.basedOn
+    ? `<w:basedOn w:val="${escXml(style.basedOn)}"/>`
+    : "";
+  const nextEl = style.nextStyle
+    ? `<w:next w:val="${escXml(style.nextStyle)}"/>`
+    : "";
+
+  // Build pPr: may contain numPr (from numbering) and any canonical formatting.
+  // We reconstruct the pPr children in canonical order:
+  // pStyle handled externally; numPr; then pPr formatting body (which includes
+  // outlineLvl at position 14 in the canonical order).
+  const numPrXml = style.numbering
+    ? buildStyleNumPrXml(style.numbering)
+    : "";
+
+  // Build pPr body — merge numPr into the formatting pPr.
+  // The canonical pPr formatter handles everything except numPr.
+  // We inject numPr after keepNext/keepLines/pageBreakBefore, before pBdr
+  // (position 3 in ECMA-376 pPr schema order).
+  const pPrBodyXml = buildParagraphPropertiesXmlWithNumPr(style.paragraphProperties, numPrXml);
+
+  const rPrXml = buildRunPropertiesXml(style.runProperties);
+
+  return (
+    `<w:style w:type="paragraph" w:styleId="${escXml(style.styleId)}"${defaultAttr}>` +
+    nameEl +
+    basedOnEl +
+    nextEl +
+    pPrBodyXml +
+    rPrXml +
+    `</w:style>`
+  );
+}
+
+function buildStyleNumPrXml(
+  numbering: NonNullable<StylesCatalog["paragraphs"][string]["numbering"]>,
+): string {
+  // Strip canonical "num:" prefix to get the raw numId value.
+  const rawId = numbering.numberingInstanceId.startsWith("num:")
+    ? numbering.numberingInstanceId.slice(4)
+    : numbering.numberingInstanceId;
+  const ilvlEl =
+    numbering.level !== undefined
+      ? `<w:ilvl w:val="${numbering.level}"/>`
+      : "";
+  return `<w:numPr>${ilvlEl}<w:numId w:val="${escXml(rawId)}"/></w:numPr>`;
+}
+
+/**
+ * Build a `<w:pPr>` that folds in an optional `<w:numPr>` at the canonical
+ * schema position (after keepNext/keepLines/pageBreakBefore, before pBdr).
+ *
+ * When there is no canonical paragraph formatting AND no numPr, returns "".
+ */
+function buildParagraphPropertiesXmlWithNumPr(
+  pPr: StylesCatalog["paragraphs"][string]["paragraphProperties"],
+  numPrXml: string,
+): string {
+  if (!numPrXml) {
+    // Delegate entirely to the shared formatter.
+    return buildParagraphPropertiesXml(pPr);
+  }
+
+  // We need to inject numPr into the correct position.
+  // Use the shared formatter's output if pPr exists, then splice numPr in
+  // after the toggle booleans (keepNext/keepLines/pageBreakBefore) and
+  // before pBdr. The simplest approach: re-build manually with full control.
+  if (!pPr) {
+    return `<w:pPr>${numPrXml}</w:pPr>`;
+  }
+
+  // Rebuild with the same order as buildParagraphPropertiesXml, inserting numPr
+  // after the first three toggles (positions 1-3) per ECMA-376 pPr schema.
+  const parts: string[] = [];
+  const fn = (tag: string, v: boolean | undefined) =>
+    v === undefined ? "" : v ? `<w:${tag}/>` : `<w:${tag} w:val="0"/>`;
+
+  parts.push(fn("keepNext", pPr.keepNext));
+  parts.push(fn("keepLines", pPr.keepLines));
+  parts.push(fn("pageBreakBefore", pPr.pageBreakBefore));
+  parts.push(numPrXml);
+  // Remaining fields delegated through the helper for pBdr, shd, tabs, etc.
+  // We do this by generating the full pPr body and stripping the outer <w:pPr> wrapper,
+  // then removing any duplicate keepNext/keepLines/pageBreakBefore already emitted.
+  const innerXml = buildParagraphPropertiesXml(pPr);
+  if (innerXml) {
+    // Strip outer <w:pPr>...</w:pPr> wrapper.
+    const inner = innerXml.replace(/^<w:pPr>/, "").replace(/<\/w:pPr>$/, "");
+    // Remove the three toggles we already emitted above to avoid duplication.
+    const deduped = inner
+      .replace(/<w:keepNext(?:\s[^>]*)?\/?>/g, "")
+      .replace(/<w:keepLines(?:\s[^>]*)?\/?>/g, "")
+      .replace(/<w:pageBreakBefore(?:\s[^>]*)?\/?>/g, "");
+    parts.push(deduped);
+  }
+
+  const body = parts.filter(Boolean).join("");
+  return body.length > 0 ? `<w:pPr>${body}</w:pPr>` : "";
+}
+
+function buildCharacterStyleXml(
+  style: StylesCatalog["characters"][string],
+): string {
+  const defaultAttr = style.isDefault ? ` w:default="1"` : "";
+  const nameEl = `<w:name w:val="${escXml(style.displayName)}"/>`;
+  const basedOnEl = style.basedOn
+    ? `<w:basedOn w:val="${escXml(style.basedOn)}"/>`
+    : "";
+  const rPrXml = buildRunPropertiesXml(style.runProperties);
+
+  return (
+    `<w:style w:type="character" w:styleId="${escXml(style.styleId)}"${defaultAttr}>` +
+    nameEl +
+    basedOnEl +
+    rPrXml +
+    `</w:style>`
+  );
+}
+
+/**
+ * Serialize a `StylesCatalog` to a `<w:styles>` XML string.
+ *
+ * Only paragraph and character styles are emitted. Table styles are skipped
+ * (they are preserved as opaque package fragments in round-trip workflows).
+ */
+export function serializeStylesXml(catalog: StylesCatalog): string {
+  const docDefaultsXml = buildDocDefaultsXml(catalog);
+
+  const paragraphStyles = Object.values(catalog.paragraphs)
+    .map((style) => buildParagraphStyleXml(style))
+    .join("");
+
+  const characterStyles = Object.values(catalog.characters)
+    .map((style) => buildCharacterStyleXml(style))
+    .join("");
+
+  const body = docDefaultsXml + paragraphStyles + characterStyles;
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">${body}</w:styles>`,
+  ].join("\n");
+}

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

@@ -215,7 +215,14 @@ import type {
 const FIELD_FAMILY_PATTERN =
   /^\s*(REF|PAGEREF|NOTEREF|TOC|PAGE|NUMPAGES|DATE|TIME|AUTHOR|FILENAME|MERGEFIELD|IF|SEQ|INDEX|TC|STYLEREF)\b/i;
 
-const SUPPORTED_FAMILIES = new Set<string>(["REF", "PAGEREF", "NOTEREF", "TOC"]);
+const SUPPORTED_FAMILIES = new Set<string>([
+  "REF",
+  "PAGEREF",
+  "NOTEREF",
+  "TOC",
+  "PAGE",
+  "NUMPAGES",
+]);
 
 /**
  * Classify a field instruction into its field family.
@@ -257,8 +264,8 @@ export function isSupportedFieldFamily(family: FieldFamily): family is Supported
  * Build a field registry from a canonical document, cataloging every field
  * instance with its classification, dependency metadata, and refresh status.
  *
- * The registry partitions fields into `supported` (REF, PAGEREF, NOTEREF, TOC)
- * and `preserveOnly` (all others) slices.
+ * The registry partitions fields into `supported` (REF, PAGEREF, NOTEREF,
+ * TOC, PAGE, NUMPAGES) and `preserveOnly` (all others) slices.
  */
 export function buildFieldRegistry(
   document: Pick<CanonicalDocument, "content" | "styles"> & {

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

@@ -8,6 +8,7 @@ import type {
   ParagraphIndentation,
   TabStop,
 } from "../../model/canonical-document.ts";
+import { readRunProperties } from "./parse-run-formatting.ts";
 
 export interface ParsedParagraphNumberingReference {
   paragraphIndex: number;
@@ -48,9 +49,32 @@ export function parseNumberingXml(xml: string): NumberingCatalog {
         }
 
         const abstractNumberingId = toCanonicalAbstractNumberingId(rawId);
+        const nsidEl = findChildElementOptional(child, "nsid");
+        const nsid = nsidEl ? (nsidEl.attributes["w:val"] ?? nsidEl.attributes.val) : undefined;
+        const mltEl = findChildElementOptional(child, "multiLevelType");
+        const mltRaw = mltEl ? (mltEl.attributes["w:val"] ?? mltEl.attributes.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 styleLinkEl = findChildElementOptional(child, "styleLink");
+        const styleLink = styleLinkEl
+          ? (styleLinkEl.attributes["w:val"] ?? styleLinkEl.attributes.val)
+          : undefined;
+        const numStyleLinkEl = findChildElementOptional(child, "numStyleLink");
+        const numStyleLink = numStyleLinkEl
+          ? (numStyleLinkEl.attributes["w:val"] ?? numStyleLinkEl.attributes.val)
+          : undefined;
         abstractDefinitions[abstractNumberingId] = {
           abstractNumberingId,
           levels: readLevels(child),
+          ...(nsid ? { nsid } : {}),
+          ...(multiLevelType ? { multiLevelType } : {}),
+          ...(tplc ? { tplc } : {}),
+          ...(styleLink ? { styleLink } : {}),
+          ...(numStyleLink ? { numStyleLink } : {}),
         };
         break;
       }
@@ -219,6 +243,11 @@ function readLevelDefinition(
         ? "tab"
         : undefined;
   const paragraphGeometry = readLevelParagraphGeometry(levelNode);
+  const lvlRestartNode = findChildElementOptional(levelNode, "lvlRestart");
+  const rawRestart = lvlRestartNode?.attributes["w:val"] ?? lvlRestartNode?.attributes.val;
+  const restartAfterLevel = rawRestart !== undefined ? parseInteger(rawRestart) : undefined;
+  const rPrNode = findChildElementOptional(levelNode, "rPr");
+  const runProperties = readRunProperties(rPrNode);
 
   return {
     level,
@@ -229,6 +258,8 @@ function readLevelDefinition(
     ...(isLegalNumbering ? { isLegalNumbering: true } : {}),
     ...(suffix ? { suffix } : {}),
     ...(paragraphGeometry ? { paragraphGeometry } : {}),
+    ...(runProperties ? { runProperties } : {}),
+    ...(restartAfterLevel !== undefined ? { restartAfterLevel } : {}),
   };
 }
 
@@ -263,6 +294,11 @@ function readLevelOverrideDefinition(
         ? "tab"
         : undefined;
   const paragraphGeometry = readLevelParagraphGeometry(levelNode);
+  const lvlRestartNode = findChildElementOptional(levelNode, "lvlRestart");
+  const rawRestart = lvlRestartNode?.attributes["w:val"] ?? lvlRestartNode?.attributes.val;
+  const restartAfterLevel = rawRestart !== undefined ? parseInteger(rawRestart) : undefined;
+  const rPrNode = findChildElementOptional(levelNode, "rPr");
+  const runProperties = readRunProperties(rPrNode);
 
   const hasExplicitFields =
     startAt !== undefined ||
@@ -271,7 +307,9 @@ function readLevelOverrideDefinition(
     paragraphStyleId !== undefined ||
     isLegalNumbering !== undefined ||
     suffix !== undefined ||
-    paragraphGeometry !== undefined;
+    paragraphGeometry !== undefined ||
+    runProperties !== undefined ||
+    restartAfterLevel !== undefined;
 
   if (!hasExplicitFields) {
     return undefined;
@@ -286,6 +324,8 @@ function readLevelOverrideDefinition(
     ...(isLegalNumbering !== undefined ? { isLegalNumbering } : {}),
     ...(suffix ? { suffix } : {}),
     ...(paragraphGeometry ? { paragraphGeometry } : {}),
+    ...(runProperties ? { runProperties } : {}),
+    ...(restartAfterLevel !== undefined ? { restartAfterLevel } : {}),
   };
 }
 

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

@@ -0,0 +1,188 @@
+/**
+ * Read `<w:pPr>` (paragraph properties) into a `CanonicalParagraphFormatting` value.
+ *
+ * Returns `undefined` when the input is `undefined` or when the pPr is empty (no recognized
+ * child produces a field). Delegates the paragraph-mark `<w:rPr>` to `readRunProperties`
+ * so every rPr in the project is parsed through one code path.
+ */
+
+import type {
+  CanonicalParagraphFormatting,
+  ParagraphBorders,
+  ParagraphIndentation,
+  ParagraphShading,
+  ParagraphSpacing,
+  TabStop,
+} from "../../model/canonical-document.ts";
+import { readRunProperties } from "./parse-run-formatting.ts";
+import { findChildOptional, localName, readIntAttr, readIntVal, readOnOff } from "./xml-attr-helpers.ts";
+import type { XmlElementNode } from "./xml-element.ts";
+
+function readSpacing(node: XmlElementNode): ParagraphSpacing | undefined {
+  const out: ParagraphSpacing = {};
+  const before = readIntAttr(node, "w:before");
+  const after = readIntAttr(node, "w:after");
+  const line = readIntAttr(node, "w:line");
+  const rule = node.attributes["w:lineRule"] ?? node.attributes.lineRule;
+  if (before !== undefined) out.before = before;
+  if (after !== undefined) out.after = after;
+  if (line !== undefined) out.line = line;
+  if (rule) {
+    const n = rule.toLowerCase();
+    if (n === "auto" || n === "exact") out.lineRule = n;
+    else if (n === "atleast") out.lineRule = "atLeast";
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function readIndent(node: XmlElementNode): ParagraphIndentation | undefined {
+  const out: ParagraphIndentation = {};
+  const left = readIntAttr(node, "w:left") ?? readIntAttr(node, "w:start");
+  const right = readIntAttr(node, "w:right") ?? readIntAttr(node, "w:end");
+  const firstLine = readIntAttr(node, "w:firstLine");
+  const hanging = readIntAttr(node, "w:hanging");
+  if (left !== undefined) out.left = left;
+  if (right !== undefined) out.right = right;
+  if (firstLine !== undefined) out.firstLine = firstLine;
+  if (hanging !== undefined) out.hanging = hanging;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function readTabStops(node: XmlElementNode): TabStop[] | undefined {
+  const tabs: TabStop[] = [];
+  for (const c of node.children) {
+    if (c.type !== "element" || localName(c.name) !== "tab") continue;
+    const pos = Number.parseInt(c.attributes["w:pos"] ?? c.attributes.pos ?? "", 10);
+    if (!Number.isFinite(pos)) continue;
+    const val = (c.attributes["w:val"] ?? c.attributes.val ?? "left").toLowerCase();
+    const leader = (c.attributes["w:leader"] ?? c.attributes.leader ?? "none").toLowerCase();
+    const align: TabStop["align"] =
+      val === "center" || val === "right" || val === "decimal" || val === "bar" || val === "num" || val === "clear"
+        ? (val as TabStop["align"])
+        : "left";
+    const mappedLeader: TabStop["leader"] | undefined =
+      leader === "dot" || leader === "hyphen" || leader === "underscore" || leader === "heavy"
+        ? (leader as TabStop["leader"])
+        : leader === "middledot"
+          ? "middleDot"
+          : undefined;
+    tabs.push({
+      position: pos,
+      align,
+      ...(mappedLeader && mappedLeader !== "none" ? { leader: mappedLeader } : {}),
+    });
+  }
+  return tabs.length > 0 ? tabs : undefined;
+}
+
+function readBorders(node: XmlElementNode): ParagraphBorders | undefined {
+  const out: ParagraphBorders = {};
+  const sides = ["top", "bottom", "left", "right", "between", "bar"] as const;
+  for (const side of sides) {
+    const child = findChildOptional(node, side);
+    if (!child) continue;
+    const val = child.attributes["w:val"] ?? child.attributes.val;
+    const sz = readIntAttr(child, "w:sz");
+    const space = readIntAttr(child, "w:space");
+    const color = child.attributes["w:color"] ?? child.attributes.color;
+    out[side] = {
+      ...(val ? { value: val } : {}),
+      ...(sz !== undefined ? { size: sz } : {}),
+      ...(space !== undefined ? { space } : {}),
+      ...(color ? { color } : {}),
+    };
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+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;
+  return {
+    ...(val ? { val } : {}),
+    ...(fill ? { fill } : {}),
+    ...(color ? { color } : {}),
+  };
+}
+
+export function readParagraphProperties(
+  node: XmlElementNode | undefined,
+): CanonicalParagraphFormatting | undefined {
+  if (!node) return undefined;
+
+  const out: CanonicalParagraphFormatting = {};
+
+  const spacingNode = findChildOptional(node, "spacing");
+  if (spacingNode) {
+    const spacing = readSpacing(spacingNode);
+    if (spacing) out.spacing = spacing;
+  }
+
+  const indNode = findChildOptional(node, "ind");
+  if (indNode) {
+    const ind = readIndent(indNode);
+    if (ind) out.indentation = ind;
+  }
+
+  const jcNode = findChildOptional(node, "jc");
+  if (jcNode) {
+    const raw = jcNode.attributes["w:val"] ?? jcNode.attributes.val;
+    if (
+      raw === "left" ||
+      raw === "center" ||
+      raw === "right" ||
+      raw === "both" ||
+      raw === "distribute" ||
+      raw === "start" ||
+      raw === "end"
+    ) {
+      out.alignment = raw;
+    }
+  }
+
+  const bordersNode = findChildOptional(node, "pBdr");
+  if (bordersNode) {
+    const borders = readBorders(bordersNode);
+    if (borders) out.borders = borders;
+  }
+
+  const shdNode = findChildOptional(node, "shd");
+  if (shdNode) {
+    const shading = readShading(shdNode);
+    if (shading) out.shading = shading;
+  }
+
+  const tabsNode = findChildOptional(node, "tabs");
+  if (tabsNode) {
+    const tabs = readTabStops(tabsNode);
+    if (tabs) out.tabStops = tabs;
+  }
+
+  const keepNext = readOnOff(findChildOptional(node, "keepNext"));
+  if (keepNext !== undefined) out.keepNext = keepNext;
+  const keepLines = readOnOff(findChildOptional(node, "keepLines"));
+  if (keepLines !== undefined) out.keepLines = keepLines;
+  const widow = readOnOff(findChildOptional(node, "widowControl"));
+  if (widow !== undefined) out.widowControl = widow;
+  const pbb = readOnOff(findChildOptional(node, "pageBreakBefore"));
+  if (pbb !== undefined) out.pageBreakBefore = pbb;
+  const ctx = readOnOff(findChildOptional(node, "contextualSpacing"));
+  if (ctx !== undefined) out.contextualSpacing = ctx;
+  const bidi = readOnOff(findChildOptional(node, "bidi"));
+  if (bidi !== undefined) out.bidi = bidi;
+  const suppressLn = readOnOff(findChildOptional(node, "suppressLineNumbers"));
+  if (suppressLn !== undefined) out.suppressLineNumbers = suppressLn;
+  const suppressAh = readOnOff(findChildOptional(node, "suppressAutoHyphens"));
+  if (suppressAh !== undefined) out.suppressAutoHyphens = suppressAh;
+
+  const outline = readIntVal(findChildOptional(node, "outlineLvl"));
+  if (outline !== undefined) out.outlineLevel = outline;
+
+  const rPrNode = findChildOptional(node, "rPr");
+  const markRpr = readRunProperties(rPrNode);
+  if (markRpr) out.paragraphMarkRunProperties = markRpr;
+
+  return Object.keys(out).length > 0 ? out : undefined;
+}

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

@@ -0,0 +1,129 @@
+import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+import { findChildOptional, readIntVal, readOnOff, readStringAttr } from "./xml-attr-helpers.ts";
+import type { XmlElementNode } from "./xml-element.ts";
+
+/**
+ * Read `<w:rPr>` (run properties) into a `CanonicalRunFormatting` value.
+ *
+ * Returns `undefined` when the input is `undefined` or when the rPr is empty
+ * (i.e., no recognized child produces a field). `colorHex` may carry the
+ * sentinel `"auto"`; `fontFamily` is the alias of the first-available
+ * `fontFamily{Ascii,HAnsi,EastAsia,Cs}`.
+ *
+ * Caller-side: route every `<w:rPr>` from styles.xml, numbering.xml, and
+ * the paragraph mark in document.xml through this helper so the cascade
+ * sees the same shape.
+ */
+export function readRunProperties(
+  node: XmlElementNode | undefined,
+): CanonicalRunFormatting | undefined {
+  if (!node) return undefined;
+
+  const rPr: CanonicalRunFormatting = {};
+
+  const bold = readOnOff(findChildOptional(node, "b"));
+  if (bold !== undefined) rPr.bold = bold;
+
+  const italic = readOnOff(findChildOptional(node, "i"));
+  if (italic !== undefined) rPr.italic = italic;
+
+  const strike = readOnOff(findChildOptional(node, "strike"));
+  if (strike !== undefined) rPr.strikethrough = strike;
+
+  const dstrike = readOnOff(findChildOptional(node, "dstrike"));
+  if (dstrike !== undefined) rPr.doubleStrikethrough = dstrike;
+
+  const vanish = readOnOff(findChildOptional(node, "vanish"));
+  if (vanish !== undefined) rPr.vanish = vanish;
+
+  const allCaps = readOnOff(findChildOptional(node, "caps"));
+  if (allCaps !== undefined) rPr.allCaps = allCaps;
+
+  const smallCaps = readOnOff(findChildOptional(node, "smallCaps"));
+  if (smallCaps !== undefined) rPr.smallCaps = smallCaps;
+
+  const u = findChildOptional(node, "u");
+  if (u) {
+    const val =
+      u.attributes["w:val"] ?? u.attributes["val"] ?? "single";
+    if (val === "none") {
+      rPr.underline = "none";
+    } else if (
+      val === "single" ||
+      val === "double" ||
+      val === "thick" ||
+      val === "dotted" ||
+      val === "dash" ||
+      val === "wave"
+    ) {
+      rPr.underline = val;
+    } else {
+      // Unknown underline type — coerce to "single"
+      rPr.underline = "single";
+    }
+  }
+
+  const vertAlign = findChildOptional(node, "vertAlign");
+  if (vertAlign) {
+    const val =
+      vertAlign.attributes["w:val"] ?? vertAlign.attributes["val"];
+    if (
+      val === "superscript" ||
+      val === "subscript" ||
+      val === "baseline"
+    ) {
+      rPr.verticalAlign = val;
+    }
+  }
+
+  const rFonts = findChildOptional(node, "rFonts");
+  if (rFonts) {
+    const ascii = rFonts.attributes["w:ascii"] ?? rFonts.attributes.ascii;
+    const hAnsi = rFonts.attributes["w:hAnsi"] ?? rFonts.attributes.hAnsi;
+    const eastAsia = rFonts.attributes["w:eastAsia"] ?? rFonts.attributes.eastAsia;
+    const cs = rFonts.attributes["w:cs"] ?? rFonts.attributes.cs;
+    if (ascii) rPr.fontFamilyAscii = ascii;
+    if (hAnsi) rPr.fontFamilyHAnsi = hAnsi;
+    if (eastAsia) rPr.fontFamilyEastAsia = eastAsia;
+    if (cs) rPr.fontFamilyCs = cs;
+    const primary = ascii ?? hAnsi ?? eastAsia ?? cs;
+    if (primary) rPr.fontFamily = primary;
+  }
+
+  const sz = readIntVal(findChildOptional(node, "sz"));
+  if (sz !== undefined) rPr.fontSizeHalfPoints = sz;
+
+  const szCs = readIntVal(findChildOptional(node, "szCs"));
+  if (szCs !== undefined) rPr.fontSizeCsHalfPoints = szCs;
+
+  const color = findChildOptional(node, "color");
+  if (color) {
+    const val = color.attributes["w:val"] ?? color.attributes["val"];
+    const theme =
+      color.attributes["w:themeColor"] ?? color.attributes["themeColor"];
+    if (val) rPr.colorHex = val;
+    if (theme) rPr.colorThemeSlot = theme;
+  }
+
+  const highlight = findChildOptional(node, "highlight");
+  if (highlight) {
+    const val =
+      highlight.attributes["w:val"] ?? highlight.attributes["val"];
+    if (val) rPr.highlight = val;
+  }
+
+  const spacing = readIntVal(findChildOptional(node, "spacing"));
+  if (spacing !== undefined) rPr.characterSpacingTwips = spacing;
+
+  const rStyleNode = findChildOptional(node, "rStyle");
+  const rStyle = rStyleNode ? readStringAttr(rStyleNode, "w:val") : undefined;
+  if (rStyle) rPr.characterStyleId = rStyle;
+
+  const lang = findChildOptional(node, "lang");
+  if (lang) {
+    const val = lang.attributes["w:val"] ?? lang.attributes["val"];
+    if (val) rPr.languageCode = val;
+  }
+
+  return Object.keys(rPr).length > 0 ? rPr : undefined;
+}