@beyondwork/docx-react-component 1.0.38 → 1.0.39

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

@@ -3,6 +3,7 @@ import {
   isSyntheticDocxNullAbstractDefinition,
   isSyntheticDocxNullNumberingInstance,
 } from "../ooxml/numbering-sentinels.ts";
+import { buildRunPropertiesXml } from "./serialize-run-formatting.ts";
 import { twip } from "./twip.ts";
 
 export const WORD_NUMBERING_CONTENT_TYPE =
@@ -62,35 +63,61 @@ function serializeAbstractDefinition(definition: NumberingCatalog["abstractDefin
       stripCanonicalPrefix(definition.abstractNumberingId, "abstract-num:"),
     ),
   );
+
+  // ECMA-376 abstractNum child order: nsid, multiLevelType, tmpl, styleLink,
+  // numStyleLink — all before the <w:lvl> children.
+  const nsid = definition.nsid
+    ? `<w:nsid w:val="${escapeAttribute(definition.nsid)}"/>`
+    : "";
+  const multiLevelType = definition.multiLevelType
+    ? `<w:multiLevelType w:val="${escapeAttribute(definition.multiLevelType)}"/>`
+    : "";
+  const tmpl = definition.tplc
+    ? `<w:tmpl w:val="${escapeAttribute(definition.tplc)}"/>`
+    : "";
+  const styleLink = definition.styleLink
+    ? `<w:styleLink w:val="${escapeAttribute(definition.styleLink)}"/>`
+    : "";
+  const numStyleLink = definition.numStyleLink
+    ? `<w:numStyleLink w:val="${escapeAttribute(definition.numStyleLink)}"/>`
+    : "";
+
   const levels = [...definition.levels]
     .sort((left, right) => left.level - right.level)
     .map((level) => serializeLevel(level))
     .join("");
 
-  return `<w:abstractNum w:abstractNumId="${abstractNumId}">${levels}</w:abstractNum>`;
+  return `<w:abstractNum w:abstractNumId="${abstractNumId}">${nsid}${multiLevelType}${tmpl}${styleLink}${numStyleLink}${levels}</w:abstractNum>`;
 }
 
 function serializeLevel(
   level: NumberingCatalog["abstractDefinitions"][string]["levels"][number],
   serializedLevel = level.level,
 ): string {
+  // ECMA-376 canonical lvl child order:
+  // start, numFmt, lvlRestart, pStyle, isLgl, suff, lvlText, lvlJc, pPr, rPr
   const start =
     level.startAt !== undefined
       ? `<w:start w:val="${clampStart(level.startAt)}"/>`
       : "";
+  const numFmt = `<w:numFmt w:val="${escapeAttribute(level.format)}"/>`;
+  const lvlRestart =
+    level.restartAfterLevel !== undefined
+      ? `<w:lvlRestart w:val="${level.restartAfterLevel}"/>`
+      : "";
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
   const isLegal = level.isLegalNumbering ? "<w:isLgl/>" : "";
   const suffix = level.suffix ? `<w:suff w:val="${escapeAttribute(level.suffix)}"/>` : "";
+  const lvlText = `<w:lvlText w:val="${escapeAttribute(level.text)}"/>`;
   const justification = level.paragraphGeometry?.justification
     ? `<w:lvlJc w:val="${escapeAttribute(level.paragraphGeometry.justification)}"/>`
     : "";
   const paragraphProperties = serializeLevelParagraphGeometry(level.paragraphGeometry);
+  const runProperties = buildRunPropertiesXml(level.runProperties);
 
-  return `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${start}<w:numFmt w:val="${escapeAttribute(
-    level.format,
-  )}"/><w:lvlText w:val="${escapeAttribute(level.text)}"/>${paragraphStyle}${isLegal}${suffix}${justification}${paragraphProperties}</w:lvl>`;
+  return `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${start}${numFmt}${lvlRestart}${paragraphStyle}${isLegal}${suffix}${lvlText}${justification}${paragraphProperties}${runProperties}</w:lvl>`;
 }
 
 function serializeLevelOverride(
@@ -101,14 +128,17 @@ function serializeLevelOverride(
     return "";
   }
 
+  // ECMA-376 canonical lvl child order (override subset):
+  // start, numFmt, lvlRestart, pStyle, isLgl, suff, lvlText, lvlJc, pPr, rPr
   const start =
     level.startAt !== undefined
       ? `<w:start w:val="${clampStart(level.startAt)}"/>`
       : "";
   const format = level.format ? `<w:numFmt w:val="${escapeAttribute(level.format)}"/>` : "";
-  const text = level.text !== undefined
-    ? `<w:lvlText w:val="${escapeAttribute(level.text)}"/>`
-    : "";
+  const lvlRestart =
+    level.restartAfterLevel !== undefined
+      ? `<w:lvlRestart w:val="${level.restartAfterLevel}"/>`
+      : "";
   const paragraphStyle = level.paragraphStyleId
     ? `<w:pStyle w:val="${escapeAttribute(level.paragraphStyleId)}"/>`
     : "";
@@ -124,11 +154,15 @@ function serializeLevelOverride(
         ? `<w:isLgl w:val="false"/>`
         : "";
   const suffix = level.suffix ? `<w:suff w:val="${escapeAttribute(level.suffix)}"/>` : "";
+  const text = level.text !== undefined
+    ? `<w:lvlText w:val="${escapeAttribute(level.text)}"/>`
+    : "";
   const justification = level.paragraphGeometry?.justification
     ? `<w:lvlJc w:val="${escapeAttribute(level.paragraphGeometry.justification)}"/>`
     : "";
   const paragraphProperties = serializeLevelParagraphGeometry(level.paragraphGeometry);
-  const body = `${start}${format}${text}${paragraphStyle}${isLegal}${suffix}${justification}${paragraphProperties}`;
+  const runProperties = buildRunPropertiesXml(level.runProperties);
+  const body = `${start}${format}${lvlRestart}${paragraphStyle}${isLegal}${suffix}${text}${justification}${paragraphProperties}${runProperties}`;
 
   return body.length > 0
     ? `<w:lvl w:ilvl="${clampIlvl(serializedLevel)}">${body}</w:lvl>`

package/src/io/export/serialize-paragraph-formatting.ts

@@ -0,0 +1,152 @@
+/**
+ * Serialize a `CanonicalParagraphFormatting` back into an OOXML `<w:pPr>` fragment.
+ * Returns empty when the input has no fields. Emits elements in ECMA-376 canonical
+ * order so the OpenXML SDK validator accepts the output.
+ */
+
+import type {
+  CanonicalParagraphFormatting,
+  ParagraphBorders,
+  ParagraphIndentation,
+  ParagraphShading,
+  ParagraphSpacing,
+  TabStop,
+} from "../../model/canonical-document.ts";
+import { buildRunPropertiesXml } from "./serialize-run-formatting.ts";
+
+function escXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function toggleEl(tag: string, value: boolean | undefined): string {
+  if (value === undefined) return "";
+  return value ? `<w:${tag}/>` : `<w:${tag} w:val="0"/>`;
+}
+
+function borderAttrs(b: {
+  value?: string;
+  size?: number;
+  space?: number;
+  color?: string;
+}): string {
+  const attrs: string[] = [];
+  if (b.value) attrs.push(`w:val="${escXml(b.value)}"`);
+  if (b.size !== undefined) attrs.push(`w:sz="${b.size}"`);
+  if (b.space !== undefined) attrs.push(`w:space="${b.space}"`);
+  if (b.color) attrs.push(`w:color="${escXml(b.color)}"`);
+  return attrs.join(" ");
+}
+
+function buildBordersXml(b: ParagraphBorders | undefined): string {
+  if (!b) return "";
+  const sides = ["top", "left", "bottom", "right", "between", "bar"] as const;
+  const parts: string[] = [];
+  for (const side of sides) {
+    const spec = b[side];
+    if (!spec) continue;
+    const attrs = borderAttrs(spec);
+    if (attrs) parts.push(`<w:${side} ${attrs}/>`);
+  }
+  return parts.length > 0 ? `<w:pBdr>${parts.join("")}</w:pBdr>` : "";
+}
+
+function buildShadingXml(s: ParagraphShading | undefined): string {
+  if (!s) return "";
+  const attrs: string[] = [];
+  if (s.val) attrs.push(`w:val="${escXml(s.val)}"`);
+  if (s.color) attrs.push(`w:color="${escXml(s.color)}"`);
+  if (s.fill) attrs.push(`w:fill="${escXml(s.fill)}"`);
+  return attrs.length > 0 ? `<w:shd ${attrs.join(" ")}/>` : "";
+}
+
+function buildTabsXml(tabs: TabStop[] | undefined): string {
+  if (!tabs || tabs.length === 0) return "";
+  const parts = tabs.map((t) => {
+    // Canonical "middleDot" → OOXML "middledot"
+    const leader = t.leader === "middleDot" ? "middledot" : t.leader;
+    const attrs: string[] = [`w:val="${escXml(t.align)}"`, `w:pos="${t.position}"`];
+    if (leader) attrs.push(`w:leader="${escXml(leader)}"`);
+    return `<w:tab ${attrs.join(" ")}/>`;
+  });
+  return `<w:tabs>${parts.join("")}</w:tabs>`;
+}
+
+function buildSpacingXml(s: ParagraphSpacing | undefined): string {
+  if (!s) return "";
+  const attrs: string[] = [];
+  if (s.before !== undefined) attrs.push(`w:before="${s.before}"`);
+  if (s.after !== undefined) attrs.push(`w:after="${s.after}"`);
+  if (s.line !== undefined) attrs.push(`w:line="${s.line}"`);
+  if (s.lineRule) attrs.push(`w:lineRule="${escXml(s.lineRule)}"`);
+  return attrs.length > 0 ? `<w:spacing ${attrs.join(" ")}/>` : "";
+}
+
+function buildIndentXml(i: ParagraphIndentation | undefined): string {
+  if (!i) return "";
+  const attrs: string[] = [];
+  if (i.left !== undefined) attrs.push(`w:left="${i.left}"`);
+  if (i.right !== undefined) attrs.push(`w:right="${i.right}"`);
+  if (i.firstLine !== undefined) attrs.push(`w:firstLine="${i.firstLine}"`);
+  if (i.hanging !== undefined) attrs.push(`w:hanging="${i.hanging}"`);
+  return attrs.length > 0 ? `<w:ind ${attrs.join(" ")}/>` : "";
+}
+
+export function buildParagraphPropertiesXml(
+  pPr: CanonicalParagraphFormatting | undefined,
+): string {
+  if (!pPr) return "";
+  const parts: string[] = [];
+
+  // ECMA-376 canonical pPr child order (subset we model):
+  // 1. keepNext, keepLines, pageBreakBefore
+  parts.push(toggleEl("keepNext", pPr.keepNext));
+  parts.push(toggleEl("keepLines", pPr.keepLines));
+  parts.push(toggleEl("pageBreakBefore", pPr.pageBreakBefore));
+
+  // 4. pBdr
+  parts.push(buildBordersXml(pPr.borders));
+
+  // 5. shd
+  parts.push(buildShadingXml(pPr.shading));
+
+  // 6. tabs
+  parts.push(buildTabsXml(pPr.tabStops));
+
+  // 7. spacing
+  parts.push(buildSpacingXml(pPr.spacing));
+
+  // 8. ind
+  parts.push(buildIndentXml(pPr.indentation));
+
+  // 9. contextualSpacing
+  parts.push(toggleEl("contextualSpacing", pPr.contextualSpacing));
+
+  // 10. widowControl
+  parts.push(toggleEl("widowControl", pPr.widowControl));
+
+  // 11. suppressLineNumbers, suppressAutoHyphens
+  parts.push(toggleEl("suppressLineNumbers", pPr.suppressLineNumbers));
+  parts.push(toggleEl("suppressAutoHyphens", pPr.suppressAutoHyphens));
+
+  // 12. bidi
+  parts.push(toggleEl("bidi", pPr.bidi));
+
+  // 13. jc
+  if (pPr.alignment) parts.push(`<w:jc w:val="${escXml(pPr.alignment)}"/>`);
+
+  // 14. outlineLvl
+  if (pPr.outlineLevel !== undefined) parts.push(`<w:outlineLvl w:val="${pPr.outlineLevel}"/>`);
+
+  // 15. rPr (paragraph mark)
+  if (pPr.paragraphMarkRunProperties) {
+    const markXml = buildRunPropertiesXml(pPr.paragraphMarkRunProperties);
+    if (markXml) parts.push(markXml);
+  }
+
+  const body = parts.filter(Boolean).join("");
+  return body.length > 0 ? `<w:pPr>${body}</w:pPr>` : "";
+}

package/src/io/export/serialize-run-formatting.ts

@@ -0,0 +1,90 @@
+/**
+ * Serialize a `CanonicalRunFormatting` back into an OOXML `<w:rPr>` fragment.
+ * Returns an empty string when the input has no fields, so callers can safely
+ * concatenate without emitting a `<w:rPr/>` husk.
+ *
+ * Elements are emitted in ECMA-376 canonical order so the OpenXML SDK
+ * validator accepts the output.
+ */
+
+import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+
+function escXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function toggleEl(tag: string, value: boolean | undefined): string {
+  if (value === undefined) return "";
+  return value ? `<w:${tag}/>` : `<w:${tag} w:val="0"/>`;
+}
+
+export function buildRunPropertiesXml(rPr: CanonicalRunFormatting | undefined): string {
+  if (!rPr) return "";
+  const parts: string[] = [];
+
+  // 1. rStyle
+  if (rPr.characterStyleId) parts.push(`<w:rStyle w:val="${escXml(rPr.characterStyleId)}"/>`);
+
+  // 2. rFonts
+  if (rPr.fontFamilyAscii || rPr.fontFamilyHAnsi || rPr.fontFamilyEastAsia || rPr.fontFamilyCs) {
+    const attrs: string[] = [];
+    if (rPr.fontFamilyAscii) attrs.push(`w:ascii="${escXml(rPr.fontFamilyAscii)}"`);
+    if (rPr.fontFamilyHAnsi) attrs.push(`w:hAnsi="${escXml(rPr.fontFamilyHAnsi)}"`);
+    if (rPr.fontFamilyEastAsia) attrs.push(`w:eastAsia="${escXml(rPr.fontFamilyEastAsia)}"`);
+    if (rPr.fontFamilyCs) attrs.push(`w:cs="${escXml(rPr.fontFamilyCs)}"`);
+    parts.push(`<w:rFonts ${attrs.join(" ")}/>`);
+  }
+
+  // 3. b, bCs (bCs not modeled, skip)
+  parts.push(toggleEl("b", rPr.bold));
+
+  // 4. i, iCs (iCs not modeled, skip)
+  parts.push(toggleEl("i", rPr.italic));
+
+  // 5. caps, smallCaps
+  parts.push(toggleEl("caps", rPr.allCaps));
+  parts.push(toggleEl("smallCaps", rPr.smallCaps));
+
+  // 6. strike, dstrike
+  parts.push(toggleEl("strike", rPr.strikethrough));
+  parts.push(toggleEl("dstrike", rPr.doubleStrikethrough));
+
+  // 7. vanish
+  parts.push(toggleEl("vanish", rPr.vanish));
+
+  // 8. color
+  if (rPr.colorHex || rPr.colorThemeSlot) {
+    const attrs: string[] = [];
+    if (rPr.colorHex) attrs.push(`w:val="${escXml(rPr.colorHex)}"`);
+    if (rPr.colorThemeSlot) attrs.push(`w:themeColor="${escXml(rPr.colorThemeSlot)}"`);
+    parts.push(`<w:color ${attrs.join(" ")}/>`);
+  }
+
+  // 9. spacing (character spacing)
+  if (rPr.characterSpacingTwips !== undefined) {
+    parts.push(`<w:spacing w:val="${rPr.characterSpacingTwips}"/>`);
+  }
+
+  // 10. highlight
+  if (rPr.highlight) parts.push(`<w:highlight w:val="${escXml(rPr.highlight)}"/>`);
+
+  // 11. u (underline)
+  if (rPr.underline) parts.push(`<w:u w:val="${escXml(rPr.underline)}"/>`);
+
+  // 12. vertAlign
+  if (rPr.verticalAlign) parts.push(`<w:vertAlign w:val="${escXml(rPr.verticalAlign)}"/>`);
+
+  // 13. lang
+  if (rPr.languageCode) parts.push(`<w:lang w:val="${escXml(rPr.languageCode)}"/>`);
+
+  // 14. sz, szCs
+  if (rPr.fontSizeHalfPoints !== undefined) parts.push(`<w:sz w:val="${rPr.fontSizeHalfPoints}"/>`);
+  if (rPr.fontSizeCsHalfPoints !== undefined) parts.push(`<w:szCs w:val="${rPr.fontSizeCsHalfPoints}"/>`);
+
+  const body = parts.filter(Boolean).join("");
+  return body.length > 0 ? `<w:rPr>${body}</w:rPr>` : "";
+}

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"> & {