@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/src/io/chart-preview-resolver.ts

@@ -74,7 +74,8 @@ interface PendingResolution {
   readonly heightEmu: number;
 }
 
-type Pointer = Array<number>;
+type PointerStep = number | { rowIndex: number; cellIndex: number };
+type Pointer = PointerStep[];
 
 export async function resolveChartPreviewsForDocument(
   doc: CanonicalDocument,
@@ -189,30 +190,92 @@ export function scheduleChartPreviewResolution(
 function collectUnresolvedChartPreviews(doc: CanonicalDocument, pkg: OpcPackage): PendingResolution[] {
   const out: PendingResolution[] = [];
   const documentRels = collectDocumentPartRelationships(pkg);
+  collectUnresolvedChartPreviewsFromBlocks(
+    doc.content.children,
+    [],
+    documentRels,
+    pkg,
+    out,
+  );
+  return out;
+}
 
-  const paragraphs = doc.content.children;
-  for (let i = 0; i < paragraphs.length; i++) {
-    const block = paragraphs[i]!;
-    if (block.type !== "paragraph") continue;
-    const paragraph = block as ParagraphNode;
-    for (let j = 0; j < paragraph.children.length; j++) {
-      const child = paragraph.children[j];
-      if (!child || child.type !== "chart_preview") continue;
-      const chartNode = child as ChartPreviewNode;
-      if (chartNode.previewMediaId) continue;
-      const resolved = resolveChartPart(chartNode, documentRels, pkg);
-      if (!resolved) continue;
-      out.push({
-        pointer: [i, j],
-        node: chartNode,
-        chartPartPath: resolved.chartPartPath,
-        chartXml: resolved.chartXml,
-        widthEmu: resolved.widthEmu,
-        heightEmu: resolved.heightEmu,
-      });
+function collectUnresolvedChartPreviewsFromBlocks(
+  blocks: readonly BlockNode[],
+  pointerPrefix: Pointer,
+  documentRels: Map<string, string>,
+  pkg: OpcPackage,
+  out: PendingResolution[],
+): void {
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex += 1) {
+    const block = blocks[blockIndex];
+    if (!block) continue;
+    switch (block.type) {
+      case "paragraph":
+        collectUnresolvedChartPreviewsFromParagraph(
+          block,
+          [...pointerPrefix, blockIndex],
+          documentRels,
+          pkg,
+          out,
+        );
+        break;
+      case "table":
+        for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+          const row = block.rows[rowIndex];
+          if (!row) continue;
+          for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+            const cell = row.cells[cellIndex];
+            if (!cell) continue;
+            collectUnresolvedChartPreviewsFromBlocks(
+              cell.children,
+              [...pointerPrefix, blockIndex, { rowIndex, cellIndex }],
+              documentRels,
+              pkg,
+              out,
+            );
+          }
+        }
+        break;
+      case "sdt":
+      case "custom_xml":
+        collectUnresolvedChartPreviewsFromBlocks(
+          block.children,
+          [...pointerPrefix, blockIndex],
+          documentRels,
+          pkg,
+          out,
+        );
+        break;
+      default:
+        break;
     }
   }
-  return out;
+}
+
+function collectUnresolvedChartPreviewsFromParagraph(
+  paragraph: ParagraphNode,
+  pointerPrefix: Pointer,
+  documentRels: Map<string, string>,
+  pkg: OpcPackage,
+  out: PendingResolution[],
+): void {
+  for (let childIndex = 0; childIndex < paragraph.children.length; childIndex += 1) {
+    const child = paragraph.children[childIndex];
+    if (!child || child.type !== "chart_preview") continue;
+    const chartNode = child as ChartPreviewNode;
+    if (chartNode.previewMediaId) continue;
+    const resolved = resolveChartPart(chartNode, documentRels, pkg);
+    if (!resolved) continue;
+    out.push({
+      pointer: [...pointerPrefix, childIndex],
+      node: chartNode,
+      chartPartPath: resolved.chartPartPath,
+      chartXml: resolved.chartXml,
+      widthEmu: resolved.widthEmu,
+      heightEmu: resolved.heightEmu,
+    });
+  }
 }
 
 function collectDocumentPartRelationships(pkg: OpcPackage): Map<string, string> {
@@ -323,7 +386,7 @@ function applyResolutions(
   resolutions: Array<{ entry: PendingResolution; bytes: Uint8Array }>,
 ): CanonicalDocument {
   const newMediaItems: Record<string, MediaItem> = { ...doc.media.items };
-  const updates = new Map<string, { previewMediaId: string }>();
+  let newBlocks = doc.content.children;
 
   let seq = 0;
   for (const { entry, bytes } of resolutions) {
@@ -340,31 +403,102 @@ function applyResolutions(
       widthEmu: entry.widthEmu,
       heightEmu: entry.heightEmu,
     };
-    const pointerKey = entry.pointer.join(",");
-    updates.set(pointerKey, { previewMediaId: mediaId });
+    newBlocks = updateChartPreviewAtPointer(newBlocks, entry.pointer, mediaId);
   }
 
-  if (updates.size === 0) return doc;
-
-  // Clone the content tree along pointer paths only — everything else
-  // keeps object identity so downstream React memoization stays stable.
-  const newParagraphs: BlockNode[] = doc.content.children.slice();
-  for (const [pointerKey, update] of updates) {
-    const [pi, ci] = pointerKey.split(",").map((s) => parseInt(s, 10)) as [number, number];
-    const paragraph = newParagraphs[pi];
-    if (!paragraph || paragraph.type !== "paragraph") continue;
-    const newChildren: InlineNode[] = (paragraph as ParagraphNode).children.slice();
-    const existing = newChildren[ci];
-    if (!existing || existing.type !== "chart_preview") continue;
-    newChildren[ci] = { ...(existing as ChartPreviewNode), previewMediaId: update.previewMediaId };
-    newParagraphs[pi] = { ...(paragraph as ParagraphNode), children: newChildren };
-  }
+  if (newBlocks === doc.content.children) return doc;
 
-  const newContent: DocumentRootNode = { ...doc.content, children: newParagraphs };
+  const newContent: DocumentRootNode = { ...doc.content, children: newBlocks };
   const newMedia = { items: newMediaItems };
   return { ...doc, content: newContent, media: newMedia };
 }
 
+function updateChartPreviewAtPointer(
+  blocks: readonly BlockNode[],
+  pointer: Pointer,
+  previewMediaId: string,
+): BlockNode[] {
+  if (pointer.length < 2) return blocks as BlockNode[];
+  const [head, ...rest] = pointer;
+  if (typeof head !== "number") return blocks as BlockNode[];
+  const targetBlock = blocks[head];
+  if (!targetBlock) return blocks as BlockNode[];
+
+  switch (targetBlock.type) {
+    case "paragraph": {
+      if (rest.length !== 1 || typeof rest[0] !== "number") {
+        return blocks as BlockNode[];
+      }
+      const inlineIndex = rest[0];
+      const child = targetBlock.children[inlineIndex];
+      if (!child || child.type !== "chart_preview") return blocks as BlockNode[];
+      const nextChildren: InlineNode[] = targetBlock.children.slice();
+      nextChildren[inlineIndex] = {
+        ...(child as ChartPreviewNode),
+        previewMediaId,
+      };
+      const nextBlocks = blocks.slice();
+      nextBlocks[head] = {
+        ...targetBlock,
+        children: nextChildren,
+      };
+      return nextBlocks;
+    }
+    case "table": {
+      const [cellPointer, ...nested] = rest;
+      if (
+        !cellPointer ||
+        typeof cellPointer === "number" ||
+        nested.length === 0
+      ) {
+        return blocks as BlockNode[];
+      }
+      const row = targetBlock.rows[cellPointer.rowIndex];
+      const cell = row?.cells[cellPointer.cellIndex];
+      if (!row || !cell) return blocks as BlockNode[];
+      const nextChildren = updateChartPreviewAtPointer(
+        cell.children,
+        nested,
+        previewMediaId,
+      );
+      if (nextChildren === cell.children) return blocks as BlockNode[];
+      const nextCells = row.cells.slice();
+      nextCells[cellPointer.cellIndex] = {
+        ...cell,
+        children: nextChildren,
+      };
+      const nextRows = targetBlock.rows.slice();
+      nextRows[cellPointer.rowIndex] = {
+        ...row,
+        cells: nextCells,
+      };
+      const nextBlocks = blocks.slice();
+      nextBlocks[head] = {
+        ...targetBlock,
+        rows: nextRows,
+      };
+      return nextBlocks;
+    }
+    case "sdt":
+    case "custom_xml": {
+      const nextChildren = updateChartPreviewAtPointer(
+        targetBlock.children,
+        rest,
+        previewMediaId,
+      );
+      if (nextChildren === targetBlock.children) return blocks as BlockNode[];
+      const nextBlocks = blocks.slice();
+      nextBlocks[head] = {
+        ...targetBlock,
+        children: nextChildren,
+      };
+      return nextBlocks;
+    }
+    default:
+      return blocks as BlockNode[];
+  }
+}
+
 /**
  * Content-type sniff from the first bytes of the rendered preview.
  * PNG magic is 0x89 0x50 0x4E 0x47; everything else is assumed to be

package/src/io/docx-session.ts

@@ -148,10 +148,10 @@ import {
   parseFooterXml,
 } from "./ooxml/parse-headers-footers.ts";
 import { parseFootnotesXml, parseEndnotesXml } from "./ooxml/parse-footnotes.ts";
-import { parseThemeXml } from "./ooxml/parse-theme.ts";
-import { resolveTheme } from "./ooxml/parse-theme.ts";
+import { materializeCanonicalTheme, parseThemeXml, resolveTheme } from "./ooxml/parse-theme.ts";
 import { parseSettingsXml } from "./ooxml/parse-settings.ts";
 import { parseStylesXml, type ParseStylesResult } from "./ooxml/parse-styles.ts";
+import { parseFontTable } from "./ooxml/parse-font-table.ts";
 import {
   serializeHeaderXml,
   serializeHeaderXmlWithRevisions,
@@ -224,6 +224,9 @@ const SETTINGS_RELATIONSHIP_TYPE =
 const STYLES_RELATIONSHIP_TYPE =
   "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
 const STYLES_PART_PATH = "/word/styles.xml";
+const FONT_TABLE_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
+const FONT_TABLE_PART_PATH = "/word/fontTable.xml";
 const FOOTNOTES_PART_PATH = "/word/footnotes.xml";
 const ENDNOTES_PART_PATH = "/word/endnotes.xml";
 const SETTINGS_PART_PATH = "/word/settings.xml";
@@ -717,6 +720,13 @@ export function loadDocxEditorSession(
             decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array()),
           )
         : undefined;
+    const canonicalTheme =
+      parsedTheme !== undefined
+        ? materializeCanonicalTheme(
+            parsedTheme,
+            parsedSettings?.clrSchemeMapping ?? {},
+          )
+        : undefined;
     const settingsXmlForProtection =
       settingsPartPath && sourcePackage.parts.has(settingsPartPath)
         ? decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array())
@@ -739,6 +749,21 @@ export function loadDocxEditorSession(
           )
         : parseStylesXml("");
 
+    // ---- Parse fontTable.xml for canonical font catalog ----
+    const fontTablePartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      FONT_TABLE_RELATIONSHIP_TYPE,
+      FONT_TABLE_PART_PATH,
+    );
+    const parsedFontTable =
+      fontTablePartPath && sourcePackage.parts.has(fontTablePartPath)
+        ? parseFontTable(
+            decodeUtf8(sourcePackage.parts.get(fontTablePartPath)?.bytes ?? new Uint8Array()),
+          )
+        : undefined;
+
     const subParts: SubPartsCatalog | undefined =
       parsedHeaders.length > 0 ||
       parsedFooters.length > 0 ||
@@ -746,6 +771,7 @@ export function loadDocxEditorSession(
       parsedTheme !== undefined ||
       normalizedDocument.finalSectionProperties !== undefined ||
       resolvedTheme !== undefined ||
+      canonicalTheme !== undefined ||
       parsedSettings !== undefined
         ? {
             headers: parsedHeaders,
@@ -756,6 +782,7 @@ export function loadDocxEditorSession(
               ? { finalSectionProperties: normalizedDocument.finalSectionProperties }
               : {}),
             ...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
+            ...(canonicalTheme !== undefined ? { canonicalTheme } : {}),
             ...(parsedSettings !== undefined ? { settings: parsedSettings } : {}),
           }
         : undefined;
@@ -775,6 +802,7 @@ export function loadDocxEditorSession(
       content: normalizedDocument.content,
       subParts,
       parsedStyles,
+      fontTable: parsedFontTable,
       preservation: {
         ...normalizedDocument.preservation,
         packageParts: {
@@ -1627,6 +1655,13 @@ export async function loadDocxEditorSessionAsync(
             decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array()),
           )
         : undefined;
+    const canonicalTheme =
+      parsedTheme !== undefined
+        ? materializeCanonicalTheme(
+            parsedTheme,
+            parsedSettings?.clrSchemeMapping ?? {},
+          )
+        : undefined;
     const settingsXmlForProtection =
       settingsPartPath && sourcePackage.parts.has(settingsPartPath)
         ? decodeUtf8(sourcePackage.parts.get(settingsPartPath)?.bytes ?? new Uint8Array())
@@ -1650,6 +1685,21 @@ export async function loadDocxEditorSessionAsync(
         : parseStylesXml("");
     await scheduler.yield();
 
+    // ---- Parse fontTable.xml for canonical font catalog ----
+    const fontTablePartPath = resolveDocumentRelatedPartPath(
+      sourcePackage,
+      mainDocumentPath,
+      documentPart.relationships,
+      FONT_TABLE_RELATIONSHIP_TYPE,
+      FONT_TABLE_PART_PATH,
+    );
+    const parsedFontTable =
+      fontTablePartPath && sourcePackage.parts.has(fontTablePartPath)
+        ? parseFontTable(
+            decodeUtf8(sourcePackage.parts.get(fontTablePartPath)?.bytes ?? new Uint8Array()),
+          )
+        : undefined;
+
     const subParts: SubPartsCatalog | undefined =
       parsedHeaders.length > 0 ||
       parsedFooters.length > 0 ||
@@ -1657,6 +1707,7 @@ export async function loadDocxEditorSessionAsync(
       parsedTheme !== undefined ||
       normalizedDocument.finalSectionProperties !== undefined ||
       resolvedTheme !== undefined ||
+      canonicalTheme !== undefined ||
       parsedSettings !== undefined
         ? {
             headers: parsedHeaders,
@@ -1667,6 +1718,7 @@ export async function loadDocxEditorSessionAsync(
               ? { finalSectionProperties: normalizedDocument.finalSectionProperties }
               : {}),
             ...(resolvedTheme !== undefined ? { resolvedTheme } : {}),
+            ...(canonicalTheme !== undefined ? { canonicalTheme } : {}),
             ...(parsedSettings !== undefined ? { settings: parsedSettings } : {}),
           }
         : undefined;
@@ -1686,6 +1738,7 @@ export async function loadDocxEditorSessionAsync(
       content: normalizedDocument.content,
       subParts,
       parsedStyles,
+      fontTable: parsedFontTable,
       preservation: {
         ...normalizedDocument.preservation,
         packageParts: {
@@ -2401,6 +2454,7 @@ function createImportedCanonicalDocument(input: {
   content: CanonicalDocumentEnvelope["content"];
   subParts?: SubPartsCatalog;
   parsedStyles?: ParseStylesResult;
+  fontTable?: CanonicalDocumentEnvelope["fontTable"];
   preservation: CanonicalDocumentEnvelope["preservation"];
   diagnostics: CanonicalDocumentEnvelope["diagnostics"];
   review: CanonicalDocumentEnvelope["review"];
@@ -2431,6 +2485,7 @@ function createImportedCanonicalDocument(input: {
     preservation: input.preservation,
     diagnostics: input.diagnostics,
     ...(input.subParts !== undefined ? { subParts: input.subParts } : {}),
+    ...(input.fontTable !== undefined ? { fontTable: input.fontTable } : {}),
   };
 }
 

package/src/io/export/serialize-main-document.ts

@@ -3,6 +3,7 @@ import type {
   BorderSpec,
   CustomXmlNode,
   DocumentRootNode,
+  FootnoteProperties,
   InlineNode,
   MediaCatalog,
   ParagraphNode,
@@ -530,6 +531,8 @@ function serializeTableInlineNode(
     case "wordart":
     case "vml_shape":
       return wrapInlineRawXml(node.rawXml);
+    case "drawing_frame":
+      return serializeDrawingFrameNode(node);
     case "hyperlink": {
       const hyperlinkOpen = node.href.startsWith("#")
         ? `<w:hyperlink w:anchor="${escapeXmlAttribute(node.href.slice(1))}">`
@@ -962,6 +965,21 @@ function serializeInlineNode(
         boundaries,
       };
     }
+    case "drawing_frame": {
+      // CO4 F4.1 — emit preserved rawXml from content (every DrawingFrame
+      // variant retains the original w:drawing slice on its content or is
+      // a picture that also keeps the slice on its parent). Matches the
+      // same "rawXml preservation" contract as shape/chart/smartart above.
+      const xml = serializeDrawingFrameNode(node);
+      const boundaries = new Map<number, number>();
+      boundaries.set(cursor, xmlOffset);
+      boundaries.set(cursor + 1, xmlOffset + xml.length);
+      return {
+        xml,
+        cursor: cursor + 1,
+        boundaries,
+      };
+    }
     case "hyperlink": {
       const hyperlinkOpen = node.href.startsWith("#")
         ? `<w:hyperlink w:anchor="${escapeXmlAttribute(node.href.slice(1))}">`
@@ -1125,6 +1143,42 @@ function serializeInlineNode(
   }
 }
 
+/**
+ * CO4 F4.1 — serialize a DrawingFrameNode by emitting the preserved rawXml.
+ *
+ * Every DrawingFrame variant carries a lossless original-XML reference:
+ * - shape, chart_preview, smartart_preview, opaque → `content.rawXml`
+ * - picture → the parse layer stores the containing drawing XML on the outer
+ *   DrawingFrame's context; for the MVP we reconstruct from the anchor +
+ *   blipRef if needed. In practice picture content also originates from a
+ *   larger drawingXml slice — the parent `w:drawing` substring — which we
+ *   don't retain explicitly yet. When `content.rawXml` is absent we emit a
+ *   minimal wp:inline/wp:anchor envelope preserving extent + relationship id.
+ *
+ * For the round-trip v1 contract: if any `rawXml` is present, round-trip is
+ * byte-stable modulo whitespace. If the picture-content path has no rawXml,
+ * a reconstructed minimal drawing is emitted.
+ */
+function serializeDrawingFrameNode(
+  node: Extract<InlineNode, { type: "drawing_frame" }>,
+): string {
+  const content = node.content;
+  if ("rawXml" in content && typeof content.rawXml === "string" && content.rawXml.length > 0) {
+    return wrapInlineRawXml(content.rawXml);
+  }
+  // Picture content with no rawXml — reconstruct a minimal inline image so the
+  // round-trip doesn't silently drop the image. Use the blipRef + anchor extent.
+  if (content.type === "picture") {
+    const { widthEmu, heightEmu } = node.anchor.extent;
+    const embed = escapeXmlAttribute(content.blipRef);
+    const envelope = node.anchor.display === "floating" ? "wp:anchor" : "wp:inline";
+    return `<w:r><w:drawing><${envelope} xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture" xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"><wp:extent cx="${widthEmu}" cy="${heightEmu}"/><wp:docPr id="1" name=""/><a:graphic><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic><pic:nvPicPr><pic:cNvPr id="0" name=""/><pic:cNvPicPr/></pic:nvPicPr><pic:blipFill><a:blip r:embed="${embed}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${widthEmu}" cy="${heightEmu}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr></pic:pic></a:graphicData></a:graphic></${envelope}></w:drawing></w:r>`;
+  }
+  // Shape/chart/smartart/opaque without rawXml — nothing to emit. Should not
+  // happen in practice since the parser always sets rawXml.
+  return "";
+}
+
 function serializeImageNode(
   node: Extract<InlineNode, { type: "image" }>,
   state: SerializationState,
@@ -1482,6 +1536,15 @@ export function serializeSectionPropertiesXml(props: SectionProperties): string
     }
   }
 
+  // Per-section footnote + endnote configuration. ECMA-376 §17.6.18 places
+  // these after the header/footer references and before <w:type>.
+  if (props.footnotePr) {
+    children.push(serializeFootnoteLikeProperties("w:footnotePr", props.footnotePr));
+  }
+  if (props.endnotePr) {
+    children.push(serializeFootnoteLikeProperties("w:endnotePr", props.endnotePr));
+  }
+
   // Section type
   if (props.sectionType) {
     children.push(`<w:type w:val="${escapeXmlAttribute(props.sectionType)}"/>`);
@@ -1623,6 +1686,25 @@ export function serializeSectionPropertiesXml(props: SectionProperties): string
   return `<w:sectPr>${children.join("")}</w:sectPr>`;
 }
 
+/**
+ * Emit `<w:footnotePr>` or `<w:endnotePr>` from the typed
+ * `FootnoteProperties` / `EndnoteProperties` shape. Child order follows
+ * ECMA-376 §17.11.11–.18: pos → numFmt → numStart → numRestart.
+ * Each child is emitted only when its typed field is present.
+ */
+function serializeFootnoteLikeProperties(
+  elementName: "w:footnotePr" | "w:endnotePr",
+  props: FootnoteProperties,
+): string {
+  const parts: string[] = [];
+  if (props.pos) parts.push(`<w:pos w:val="${escapeXmlAttribute(props.pos)}"/>`);
+  if (props.numFmt) parts.push(`<w:numFmt w:val="${escapeXmlAttribute(props.numFmt)}"/>`);
+  if (props.numStart !== undefined) parts.push(`<w:numStart w:val="${twip(props.numStart)}"/>`);
+  if (props.numRestart) parts.push(`<w:numRestart w:val="${escapeXmlAttribute(props.numRestart)}"/>`);
+  if (parts.length === 0) return `<${elementName}/>`;
+  return `<${elementName}>${parts.join("")}</${elementName}>`;
+}
+
 function wrapInlineRawXml(rawXml: string): string {
   const trimmed = rawXml.trimStart();
   return trimmed.startsWith("<w:r") ? rawXml : `<w:r>${rawXml}</w:r>`;

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

@@ -67,16 +67,18 @@ function buildParagraphStyleXml(
 ): string {
   const defaultAttr = style.isDefault ? ` w:default="1"` : "";
   const nameEl = `<w:name w:val="${escXml(style.displayName)}"/>`;
+  const aliasesEl = buildAliasesXml(style.aliases);
   const basedOnEl = style.basedOn
     ? `<w:basedOn w:val="${escXml(style.basedOn)}"/>`
     : "";
   const nextEl = style.nextStyle
     ? `<w:next w:val="${escXml(style.nextStyle)}"/>`
     : "";
-  // ECMA-376 §17.7 emit order: name → basedOn → next → link → ...
+  // ECMA-376 §17.7 emit order: name → aliases → basedOn → next → link → autoRedefine → ...
   const linkEl = style.linkedStyleId
     ? `<w:link w:val="${escXml(style.linkedStyleId)}"/>`
     : "";
+  const autoRedefineEl = buildOnOffEl("autoRedefine", style.autoRedefine);
 
   // Build pPr: may contain numPr (from numbering) and any canonical formatting.
   // We reconstruct the pPr children in canonical order:
@@ -97,15 +99,37 @@ function buildParagraphStyleXml(
   return (
     `<w:style w:type="paragraph" w:styleId="${escXml(style.styleId)}"${defaultAttr}>` +
     nameEl +
+    aliasesEl +
     basedOnEl +
     nextEl +
     linkEl +
+    autoRedefineEl +
     pPrBodyXml +
     rPrXml +
     `</w:style>`
   );
 }
 
+/**
+ * Emit an ST_OnOff element following A.3 discipline: undefined → "",
+ * true → `<w:tag/>`, false → `<w:tag w:val="false"/>`.
+ */
+function buildOnOffEl(tag: string, value: boolean | undefined): string {
+  if (value === undefined) return "";
+  return value ? `<w:${tag}/>` : `<w:${tag} w:val="false"/>`;
+}
+
+/**
+ * Emit `<w:aliases w:val="A,B"/>` — ECMA-376 §17.7.4.2. Returns empty when
+ * `aliases` is undefined or the array is empty. Commas are preserved verbatim;
+ * callers are responsible for not embedding commas inside alias names (Word
+ * does not escape them either).
+ */
+function buildAliasesXml(aliases: string[] | undefined): string {
+  if (!aliases || aliases.length === 0) return "";
+  return `<w:aliases w:val="${escXml(aliases.join(","))}"/>`;
+}
+
 function buildStyleNumPrXml(
   numbering: NonNullable<StylesCatalog["paragraphs"][string]["numbering"]>,
 ): string {
@@ -172,15 +196,44 @@ function buildParagraphPropertiesXmlWithNumPr(
   return body.length > 0 ? `<w:pPr>${body}</w:pPr>` : "";
 }
 
+function buildNumberingStyleXml(
+  style: NonNullable<StylesCatalog["numberingStyles"]>[string],
+): string {
+  const defaultAttr = style.isDefault ? ` w:default="1"` : "";
+  const nameEl = `<w:name w:val="${escXml(style.displayName)}"/>`;
+  const aliasesEl = buildAliasesXml(style.aliases);
+  const basedOnEl = style.basedOn
+    ? `<w:basedOn w:val="${escXml(style.basedOn)}"/>`
+    : "";
+  // Emit `<w:pPr><w:numPr><w:numId/></w:numPr></w:pPr>` when an instance ref
+  // was captured. Strip canonical "num:" prefix per serialize-numbering pattern.
+  let numPrXml = "";
+  if (style.numberingInstanceId) {
+    const rawId = style.numberingInstanceId.startsWith("num:")
+      ? style.numberingInstanceId.slice(4)
+      : style.numberingInstanceId;
+    numPrXml = `<w:pPr><w:numPr><w:numId w:val="${escXml(rawId)}"/></w:numPr></w:pPr>`;
+  }
+  return (
+    `<w:style w:type="numbering" w:styleId="${escXml(style.styleId)}"${defaultAttr}>` +
+    nameEl +
+    aliasesEl +
+    basedOnEl +
+    numPrXml +
+    `</w:style>`
+  );
+}
+
 function buildCharacterStyleXml(
   style: StylesCatalog["characters"][string],
 ): string {
   const defaultAttr = style.isDefault ? ` w:default="1"` : "";
   const nameEl = `<w:name w:val="${escXml(style.displayName)}"/>`;
+  const aliasesEl = buildAliasesXml(style.aliases);
   const basedOnEl = style.basedOn
     ? `<w:basedOn w:val="${escXml(style.basedOn)}"/>`
     : "";
-  // ECMA-376 §17.7 emit order: name → basedOn → link → ... → rPr
+  // ECMA-376 §17.7 emit order: name → aliases → basedOn → link → ... → rPr
   const linkEl = style.linkedStyleId
     ? `<w:link w:val="${escXml(style.linkedStyleId)}"/>`
     : "";
@@ -189,6 +242,7 @@ function buildCharacterStyleXml(
   return (
     `<w:style w:type="character" w:styleId="${escXml(style.styleId)}"${defaultAttr}>` +
     nameEl +
+    aliasesEl +
     basedOnEl +
     linkEl +
     rPrXml +
@@ -213,7 +267,11 @@ export function serializeStylesXml(catalog: StylesCatalog): string {
     .map((style) => buildCharacterStyleXml(style))
     .join("");
 
-  const body = docDefaultsXml + paragraphStyles + characterStyles;
+  const numberingStyles = Object.values(catalog.numberingStyles ?? {})
+    .map((style) => buildNumberingStyleXml(style))
+    .join("");
+
+  const body = docDefaultsXml + paragraphStyles + characterStyles + numberingStyles;
 
   return [
     `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,