@otomate/docx 0.2.0 → 0.3.0

package/dist/writer.js

@@ -1,6 +1,7 @@
 // ---------------------------------------------------------------------------
 // docx Writer — UDM tree → .docx buffer
 // ---------------------------------------------------------------------------
+import { createHash } from "node:crypto";
 import { isParent, isText } from "@otomate/core";
 import { buildStyleElement, cssToRunProps, cssToParaProps, parseLengthTwips, parseColor } from "@otomate/css-docx";
 import { packDocx } from "./zip.js";
@@ -14,16 +15,28 @@ export async function writeDocx(tree, options) {
     const cssData = tree.data?.css;
     const mergedClassCss = { ...cssData?.classRules, ...options?.cssClasses };
     const elementCss = cssData?.elementRules ?? {};
+    const docxDataPre = tree.data?.docx;
+    const existingRels = docxDataPre?.relationships;
     const ctx = {
         cssClasses: mergedClassCss,
         cssElements: elementCss,
         customStyles: [],
         generatedStyleIds: new Set(),
         nextNumId: 3,
+        allocatedNums: new Map(),
         hyperlinks: new Map(),
-        nextRId: 100,
+        // Seed past any existing rIds to avoid collisions on round-trip.
+        nextRId: nextRIdFor(existingRels),
     };
-    const bodyXml = tree.children.map(child => convertBlock(child, ctx, 0)).join("\n");
+    const renderedBlocks = tree.children.map(child => convertBlock(child, ctx, 0));
+    // OOXML allows w:tbl as the last body child, but Word always inserts a trailing
+    // empty paragraph after a final table. Match that behavior so re-opening in Word
+    // produces no diff.
+    const lastBlock = tree.children[tree.children.length - 1];
+    if (lastBlock?.type === "table") {
+        renderedBlocks.push("<w:p/>");
+    }
+    const bodyXml = renderedBlocks.join("\n");
     const docxData = tree.data?.docx;
     // Build styles.xml with any generated custom styles
     let stylesXml = docxData?.styles ?? DEFAULT_STYLES;
@@ -46,17 +59,29 @@ ${bodyXml}
         // Inject before closing </Relationships>
         relsXml = relsXml.replace("</Relationships>", `  ${hlRels}\n</Relationships>`);
     }
+    // Inject any newly-allocated <w:num> entries into numbering.xml so each
+    // top-level list has its own num definition (independent counters & styles).
+    let numberingXml = docxData?.numbering ?? DEFAULT_NUMBERING;
+    if (ctx.allocatedNums.size > 0) {
+        const newNums = [...ctx.allocatedNums]
+            .map(([numId, abstractId]) => `<w:num w:numId="${numId}"><w:abstractNumId w:val="${abstractId}"/></w:num>`)
+            .join("\n  ");
+        numberingXml = numberingXml.replace("</w:numbering>", `  ${newNums}\n</w:numbering>`);
+    }
     const parts = {
         document: docXml,
         styles: stylesXml,
-        numbering: docxData?.numbering ?? DEFAULT_NUMBERING,
+        numbering: numberingXml,
         relationships: relsXml,
         contentTypes: docxData?.contentTypes ?? undefined,
         media: new Map(),
         rawParts: new Map(),
     };
-    // Embed UDM tree as custom part for lossless round-trip with otomate
+    // Embed UDM tree as custom part for lossless round-trip with otomate.
+    // The hash binds the snapshot to this exact document.xml so the reader
+    // can detect external edits (Word saves) and fall back to OOXML parsing.
     const udmSnapshot = stripDataForSnapshot(tree);
+    udmSnapshot.__docHash = hashString(docXml);
     parts.rawParts.set("word/otomate-udm.json", JSON.stringify(udmSnapshot));
     // Embed CSS rules if present
     if (cssData && (Object.keys(cssData.classRules ?? {}).length > 0 || Object.keys(cssData.elementRules ?? {}).length > 0)) {
@@ -76,6 +101,37 @@ ${bodyXml}
     }
     return packDocx(parts);
 }
+/**
+ * Compute the smallest unused rId for a hyperlink, given the round-tripped
+ * relationships file. Falls back to 100 (well above the default rId1/rId2)
+ * when there is no source rels.
+ */
+function nextRIdFor(existingRels) {
+    if (!existingRels)
+        return 100;
+    let max = 0;
+    const re = /Id="rId(\d+)"/g;
+    let m;
+    while ((m = re.exec(existingRels)) !== null) {
+        const n = Number(m[1]);
+        if (n > max)
+            max = n;
+    }
+    return Math.max(max + 1, 100);
+}
+/**
+ * Allocate a fresh w:numId for a top-level list, recording it so the writer
+ * can inject a matching <w:num> entry into numbering.xml.
+ *
+ * Each top-level list gets its own numId so that ordered lists restart at 1
+ * instead of continuing the previous list's numbering, and bullet styles
+ * applied to one list don't bleed into all others.
+ */
+function allocNumId(ctx, ordered) {
+    const numId = String(ctx.nextNumId++);
+    ctx.allocatedNums.set(numId, ordered ? 1 : 0);
+    return numId;
+}
 function allocHyperlinkRId(ctx, url) {
     // Reuse existing rId for same URL
     for (const [rId, existingUrl] of ctx.hyperlinks) {
@@ -129,7 +185,7 @@ function convertBlock(node, ctx, listIlvl) {
         case "div":
         case "figure":
             return convertDiv(node, ctx, listIlvl);
-        case "html": return `<w:p><w:r><w:t>${esc(node.value)}</w:t></w:r></w:p>`;
+        case "html": return `<w:p><w:r><w:t xml:space="preserve">${esc(node.value)}</w:t></w:r></w:p>`;
         default: return "";
     }
 }
@@ -154,12 +210,16 @@ function convertDiv(node, ctx, listIlvl) {
     const runProps = cssToRunProps(containerCss);
     const containerRPr = buildRunPropsXml(runProps);
     const bg = containerCss["background-color"] ? parseColorSafe(containerCss["background-color"]) : undefined;
-    // Build extra pPr elements to inject into child paragraphs
-    let extraPPr = "";
+    // Build extra pPr elements to inject into child paragraphs.
+    // Order doesn't matter here — injectPPr re-sorts via serializePPr.
+    const extraPPrParts = [];
+    const pBdrXml = buildPBdrXml(paraProps.pBdr);
+    if (pBdrXml)
+        extraPPrParts.push(pBdrXml);
     if (bg && bg !== "auto")
-        extraPPr += `<w:shd w:val="clear" w:color="auto" w:fill="${bg}"/>`;
+        extraPPrParts.push(`<w:shd w:val="clear" w:color="auto" w:fill="${bg}"/>`);
     if (paraProps.jc)
-        extraPPr += `<w:jc w:val="${paraProps.jc}"/>`;
+        extraPPrParts.push(`<w:jc w:val="${paraProps.jc}"/>`);
     if (paraProps.ind) {
         const attrs = [];
         if (paraProps.ind.left)
@@ -167,14 +227,14 @@ function convertDiv(node, ctx, listIlvl) {
         if (paraProps.ind.right)
             attrs.push(`w:right="${paraProps.ind.right}"`);
         if (attrs.length)
-            extraPPr += `<w:ind ${attrs.join(" ")}/>`;
+            extraPPrParts.push(`<w:ind ${attrs.join(" ")}/>`);
     }
     // Create a temporary modified context that includes the container's styles
     // so child paragraphs inherit them
     const childCtx = {
         ...ctx,
         _containerRPr: containerRPr,
-        _containerPPr: extraPPr,
+        _containerPPrParts: extraPPrParts,
     };
     return node.children.map(c => convertBlockWithContainer(c, childCtx, listIlvl)).join("\n");
 }
@@ -182,17 +242,16 @@ function convertDiv(node, ctx, listIlvl) {
 function convertBlockWithContainer(node, ctx, listIlvl) {
     const containerCtx = ctx;
     const extraRPr = containerCtx._containerRPr ?? "";
-    const extraPPr = containerCtx._containerPPr ?? "";
+    const extraPPrParts = containerCtx._containerPPrParts ?? [];
     // Helper: resolve all CSS run props for this node (element + own classes)
     const nodeRPr = resolveBlockCssRunProps(node, ctx);
     const mergedRPr = extraRPr + nodeRPr;
-    // Helper: inject container pPr into a pPr string
+    // Helper: merge container pPr parts into an existing pPr string with schema ordering.
     function injectPPr(pPr) {
-        if (!extraPPr)
+        if (extraPPrParts.length === 0)
             return pPr;
-        if (pPr)
-            return pPr.replace("</w:pPr>", `${extraPPr}</w:pPr>`);
-        return `<w:pPr>${extraPPr}</w:pPr>`;
+        const baseChildren = pPr ? extractPPrChildren(pPr) : [];
+        return serializePPr([...baseChildren, ...extraPPrParts]);
     }
     if (node.type === "paragraph") {
         const para = node;
@@ -218,11 +277,12 @@ function convertBlockWithContainer(node, ctx, listIlvl) {
         const classes = h.classes;
         if (classes?.length) {
             for (const cls of classes) {
-                if (ctx.cssClasses[cls] && !ctx.generatedStyleIds.has(cls)) {
-                    ctx.generatedStyleIds.add(cls);
+                const clsId = sanitizeStyleId(cls);
+                if (ctx.cssClasses[cls] && !ctx.generatedStyleIds.has(clsId)) {
+                    ctx.generatedStyleIds.add(clsId);
                     const rp = cssToRunProps(ctx.cssClasses[cls]);
                     const pp = cssToParaProps(ctx.cssClasses[cls]);
-                    ctx.customStyles.push(buildStyleElement(cls, cls, "paragraph", rp, pp));
+                    ctx.customStyles.push(buildStyleElement(clsId, cls, "paragraph", rp, pp));
                 }
             }
         }
@@ -232,7 +292,7 @@ function convertBlockWithContainer(node, ctx, listIlvl) {
     if (node.type === "list") {
         // Pass container formatting down to list items
         const list = node;
-        const numId = list.ordered ? "2" : "1";
+        const numId = allocNumId(ctx, list.ordered);
         const parts = [];
         for (const item of list.children) {
             if (item.type !== "listItem")
@@ -258,7 +318,8 @@ function convertBlockWithContainer(node, ctx, listIlvl) {
                     parts.push(`<w:p>${pPr}${runs}</w:p>`);
                 }
                 else if (child.type === "list") {
-                    parts.push(convertBlockWithContainer(child, ctx, listIlvl + 1));
+                    // Inherit parent numId so nested levels share the same w:num entry.
+                    parts.push(convertList(child, ctx, listIlvl + 1, numId));
                 }
                 else {
                     // div, blockquote, codeBlock, etc. — recurse with container inheritance
@@ -271,7 +332,7 @@ function convertBlockWithContainer(node, ctx, listIlvl) {
     // For other children, use normal conversion with container props cleared
     const cleanCtx = { ...ctx };
     delete cleanCtx._containerRPr;
-    delete cleanCtx._containerPPr;
+    delete cleanCtx._containerPPrParts;
     return convertBlock(node, cleanCtx, listIlvl);
 }
 function convertParagraph(node, ctx) {
@@ -311,13 +372,11 @@ function convertHeading(node, ctx) {
 function convertInsertedParagraph(node, pPr, cssRPr, ctx) {
     const diff = ctx.diff;
     const author = esc(diff.author);
-    const date = diff.date;
-    // Track the paragraph mark itself as inserted (inject into pPr)
+    const date = esc(diff.date);
+    // Track the paragraph mark itself as inserted (inject into pPr's rPr).
     const markId = diff.revId.value++;
-    const insMarkXml = `<w:rPr><w:ins w:id="${markId}" w:author="${author}" w:date="${date}"/></w:rPr>`;
-    const trackedPPr = pPr
-        ? pPr.replace("</w:pPr>", `${insMarkXml}</w:pPr>`)
-        : `<w:pPr>${insMarkXml}</w:pPr>`;
+    const insMark = `<w:ins w:id="${markId}" w:author="${author}" w:date="${date}"/>`;
+    const trackedPPr = mergeParaMarkChild(pPr, insMark);
     // Wrap each inline child's run in its own w:ins
     const runs = node.children.map(c => {
         const runXml = convertInline(c, ctx, cssRPr);
@@ -346,8 +405,163 @@ function resolveBlockCssRunProps(node, ctx) {
         return "";
     return buildRunPropsXml(cssToRunProps(merged));
 }
-/** Build w:rPr XML string from OoxmlRunProps (without the <w:rPr> wrapper) */
+// ---------------------------------------------------------------------------
+// ECMA-376 schema-order maps for w:rPr and w:pPr children
+// (validators reject out-of-order elements in strict mode)
+// ---------------------------------------------------------------------------
+const RPR_ORDER = {
+    "w:rStyle": 1, "w:rFonts": 2, "w:b": 3, "w:bCs": 4, "w:i": 5, "w:iCs": 6,
+    "w:caps": 7, "w:smallCaps": 8, "w:strike": 9, "w:dstrike": 10,
+    "w:outline": 11, "w:shadow": 12, "w:emboss": 13, "w:imprint": 14,
+    "w:noProof": 15, "w:snapToGrid": 16, "w:vanish": 17, "w:webHidden": 18,
+    "w:color": 19, "w:spacing": 20, "w:w": 21, "w:kern": 22, "w:position": 23,
+    "w:sz": 24, "w:szCs": 25, "w:highlight": 26, "w:u": 27, "w:effect": 28,
+    "w:bdr": 29, "w:shd": 30, "w:fitText": 31, "w:vertAlign": 32, "w:rtl": 33,
+    "w:cs": 34, "w:em": 35, "w:lang": 36, "w:eastAsianLayout": 37,
+    "w:specVanish": 38, "w:oMath": 39,
+};
+const PPR_ORDER = {
+    "w:pStyle": 1, "w:keepNext": 2, "w:keepLines": 3, "w:pageBreakBefore": 4,
+    "w:framePr": 5, "w:widowControl": 6, "w:numPr": 7, "w:suppressLineNumbers": 8,
+    "w:pBdr": 9, "w:shd": 10, "w:tabs": 11, "w:suppressAutoHyphens": 12,
+    "w:kinsoku": 13, "w:wordWrap": 14, "w:overflowPunct": 15, "w:topLinePunct": 16,
+    "w:autoSpaceDE": 17, "w:autoSpaceDN": 18, "w:bidi": 19, "w:adjustRightInd": 20,
+    "w:snapToGrid": 21, "w:spacing": 22, "w:ind": 23, "w:contextualSpacing": 24,
+    "w:mirrorIndents": 25, "w:suppressOverlap": 26, "w:jc": 27, "w:textDirection": 28,
+    "w:textAlignment": 29, "w:textboxTightWrap": 30, "w:outlineLvl": 31,
+    "w:divId": 32, "w:cnfStyle": 33, "w:rPr": 34, "w:sectPr": 35, "w:pPrChange": 36,
+};
+function getElementTag(xml) {
+    const m = xml.match(/^<(w:[A-Za-z]+)/);
+    return m ? m[1] : "";
+}
+/** Tokenize the children of an OOXML container — handles both self-closing and parent elements. */
+function tokenizeOoxmlChildren(xml) {
+    const tokens = [];
+    let i = 0;
+    while (i < xml.length) {
+        if (xml[i] !== "<") {
+            i++;
+            continue;
+        }
+        const nameMatch = xml.slice(i).match(/^<(w:[A-Za-z]+)/);
+        if (!nameMatch) {
+            i++;
+            continue;
+        }
+        const name = nameMatch[1];
+        // Find end of opening tag (skipping over quoted attribute values)
+        let j = i + 1;
+        let inQuote = false;
+        while (j < xml.length) {
+            const ch = xml[j];
+            if (ch === '"')
+                inQuote = !inQuote;
+            if (!inQuote && ch === ">")
+                break;
+            j++;
+        }
+        if (j >= xml.length)
+            break;
+        if (xml[j - 1] === "/") {
+            tokens.push(xml.slice(i, j + 1));
+            i = j + 1;
+        }
+        else {
+            const closeTag = `</${name}>`;
+            let depth = 1;
+            let k = j + 1;
+            while (k < xml.length && depth > 0) {
+                if (xml.startsWith(`<${name}`, k)) {
+                    const after = xml[k + name.length + 1];
+                    if (after === " " || after === ">" || after === "/")
+                        depth++;
+                }
+                if (xml.startsWith(closeTag, k)) {
+                    depth--;
+                    if (depth === 0) {
+                        k += closeTag.length;
+                        break;
+                    }
+                }
+                k++;
+            }
+            tokens.push(xml.slice(i, k));
+            i = k;
+        }
+    }
+    return tokens;
+}
+/** Stable-sort + tag-dedup a list of rPr/pPr child element strings by ECMA-376 order. */
+function orderElements(elements, order) {
+    const byTag = new Map();
+    for (const el of elements) {
+        const tag = getElementTag(el);
+        if (tag)
+            byTag.set(tag, el); // last write wins (later sources override earlier)
+    }
+    return [...byTag.entries()]
+        .sort(([a], [b]) => (order[a] ?? 999) - (order[b] ?? 999))
+        .map(([, el]) => el);
+}
+/** Wrap rPr children in <w:rPr> with schema-correct ordering. Returns "" if empty. */
+function serializeRPr(parts) {
+    const ordered = orderElements(parts, RPR_ORDER);
+    return ordered.length > 0 ? `<w:rPr>${ordered.join("")}</w:rPr>` : "";
+}
+/** Wrap pPr children in <w:pPr> with schema-correct ordering. Returns "" if empty. */
+function serializePPr(parts) {
+    const ordered = orderElements(parts, PPR_ORDER);
+    return ordered.length > 0 ? `<w:pPr>${ordered.join("")}</w:pPr>` : "";
+}
+/** Extract the children of an existing <w:pPr>...</w:pPr> wrapper as raw element strings. */
+function extractPPrChildren(pPr) {
+    const m = pPr.match(/<w:pPr>([\s\S]*?)<\/w:pPr>/);
+    return m ? tokenizeOoxmlChildren(m[1]) : [];
+}
+/**
+ * Merge a paragraph-mark child (w:ins/w:del/w:rPrChange/etc.) into the
+ * paragraph's pPr/rPr, creating either or both wrappers as needed and
+ * preserving any existing rPr children. Avoids the duplicate-`<w:rPr>`
+ * trap that string-replace produces.
+ */
+function mergeParaMarkChild(pPr, child) {
+    const baseChildren = pPr ? extractPPrChildren(pPr) : [];
+    // Find an existing inner <w:rPr>…</w:rPr> (paragraph mark properties).
+    let foundRPr = false;
+    const merged = baseChildren.map(el => {
+        if (el.startsWith("<w:rPr>") || el.startsWith("<w:rPr ")) {
+            foundRPr = true;
+            // Inject the child at the start (w:ins/w:del are tracked-change marks
+            // that appear first inside CT_ParaRPr per ECMA-376).
+            return el.replace(/^<w:rPr(\s[^>]*)?>/, m => `${m}${child}`);
+        }
+        return el;
+    });
+    if (!foundRPr)
+        merged.push(`<w:rPr>${child}</w:rPr>`);
+    return serializePPr(merged);
+}
+/** Extract the children of an existing <w:rPr>...</w:rPr> wrapper as raw element strings. */
+function extractRPrChildren(rPr) {
+    const m = rPr.match(/<w:rPr>([\s\S]*?)<\/w:rPr>/);
+    return m ? tokenizeOoxmlChildren(m[1]) : [];
+}
+/** Build a `<w:pBdr>` element from a parsed pBdr definition. Returns "" if no sides set. */
+function buildPBdrXml(pBdr) {
+    if (!pBdr)
+        return "";
+    const sides = [];
+    for (const side of ["top", "bottom", "left", "right"]) {
+        const bd = pBdr[side];
+        if (bd)
+            sides.push(`<w:${side} w:val="${bd.val}" w:sz="${bd.sz}" w:space="0" w:color="${bd.color}"/>`);
+    }
+    return sides.length > 0 ? `<w:pBdr>${sides.join("")}</w:pBdr>` : "";
+}
+/** Build w:rPr child elements from OoxmlRunProps (without the wrapper, in schema order). */
 function buildRunPropsXml(props) {
+    // Order per ECMA-376 CT_RPr: rFonts(2), b(3), i(5), strike(9), color(19), sz(24), u(27), shd(30)
     const parts = [];
     if (props.rFonts) {
         const attrs = [];
@@ -361,14 +575,14 @@ function buildRunPropsXml(props) {
         parts.push("<w:b/>");
     if (props.i)
         parts.push("<w:i/>");
-    if (props.sz)
-        parts.push(`<w:sz w:val="${props.sz}"/>`);
+    if (props.strike)
+        parts.push("<w:strike/>");
     if (props.color)
         parts.push(`<w:color w:val="${props.color}"/>`);
+    if (props.sz)
+        parts.push(`<w:sz w:val="${props.sz}"/>`);
     if (props.u)
         parts.push(`<w:u w:val="${props.u}"/>`);
-    if (props.strike)
-        parts.push("<w:strike/>");
     if (props.shd)
         parts.push(`<w:shd w:val="clear" w:color="auto" w:fill="${props.shd}"/>`);
     return parts.join("");
@@ -386,6 +600,7 @@ function convertBlockquote(node, ctx) {
     }).join("\n");
 }
 function buildBlockquotePPr(css) {
+    // Collect in any order — serializePPr applies ECMA-376 ordering.
     const parts = [];
     // Left border (vertical line) — always add for blockquotes
     parts.push(`<w:pBdr><w:left w:val="single" w:sz="18" w:space="4" w:color="${css["border-color"] ? parseColorSafe(css["border-color"]) : "AAAAAA"}"/></w:pBdr>`);
@@ -409,10 +624,13 @@ function buildBlockquotePPr(css) {
         if (attrs.length)
             parts.push(`<w:spacing ${attrs.join(" ")}/>`);
     }
-    return `<w:pPr>${parts.join("")}</w:pPr>`;
+    return serializePPr(parts);
 }
-function convertList(node, ctx, baseIlvl) {
-    const numId = node.ordered ? "2" : "1";
+function convertList(node, ctx, baseIlvl, parentNumId) {
+    // Top-level lists get a fresh numId; nested lists inherit their parent's
+    // numId so the abstract numbering definition (bullet vs ordered) and
+    // counter continuity stay consistent across levels.
+    const numId = parentNumId ?? allocNumId(ctx, node.ordered);
     const liRPr = ctx.cssElements["li"] ? buildRunPropsXml(cssToRunProps(ctx.cssElements["li"])) : "";
     const parts = [];
     for (const item of node.children) {
@@ -425,7 +643,7 @@ function convertList(node, ctx, baseIlvl) {
                 parts.push(`<w:p><w:pPr><w:numPr><w:ilvl w:val="${baseIlvl}"/><w:numId w:val="${numId}"/></w:numPr></w:pPr>${runs}</w:p>`);
             }
             else if (child.type === "list") {
-                parts.push(convertList(child, ctx, baseIlvl + 1));
+                parts.push(convertList(child, ctx, baseIlvl + 1, numId));
             }
             else {
                 parts.push(convertBlock(child, ctx, baseIlvl));
@@ -438,36 +656,62 @@ function convertCodeBlock(node, ctx) {
     const preCss = ctx?.cssElements["pre"] ?? {};
     const bg = preCss["background-color"] ? parseColorSafe(preCss["background-color"]) : undefined;
     const preRPr = Object.keys(preCss).length > 0 ? buildRunPropsXml(cssToRunProps(preCss)) : "";
-    // Build pPr with Code style + optional background shading
-    let pPr = `<w:pPr><w:pStyle w:val="Code"/>`;
+    // pPr: pStyle(1) before shd(10) — already in correct order
+    const pPrParts = [`<w:pStyle w:val="Code"/>`];
     if (bg)
-        pPr += `<w:shd w:val="clear" w:color="auto" w:fill="${bg}"/>`;
-    pPr += `</w:pPr>`;
+        pPrParts.push(`<w:shd w:val="clear" w:color="auto" w:fill="${bg}"/>`);
+    const pPr = serializePPr(pPrParts);
+    // rPr: code rFonts + any pre-element CSS (rFonts override is intentional, last write wins)
+    const rPrParts = [`<w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/>`];
+    if (preRPr)
+        rPrParts.push(...tokenizeOoxmlChildren(preRPr));
+    const rPr = serializeRPr(rPrParts);
     const lines = node.value.split("\n");
-    return lines.map(line => `<w:p>${pPr}<w:r><w:rPr><w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/>${preRPr}</w:rPr><w:t xml:space="preserve">${esc(line)}</w:t></w:r></w:p>`).join("\n");
+    return lines.map(line => `<w:p>${pPr}<w:r>${rPr}<w:t xml:space="preserve">${esc(line)}</w:t></w:r></w:p>`).join("\n");
+}
+function countTableColumns(node) {
+    let max = 0;
+    for (const row of node.children) {
+        if (row.type !== "tableRow")
+            continue;
+        const count = row.children.reduce((n, cell) => n + (cell.colspan ?? 1), 0);
+        if (count > max)
+            max = count;
+    }
+    return Math.max(max, 1);
 }
 function convertTable(node, ctx) {
+    const colCount = countTableColumns(node);
+    // Content width: 9360 twips (12240 page − 2×1440 margins)
+    const colWidth = Math.round(9360 / colCount);
+    const tblGrid = `<w:tblGrid>${Array.from({ length: colCount }, () => `<w:gridCol w:w="${colWidth}"/>`).join("")}</w:tblGrid>`;
     const rows = node.children.map(row => {
         if (row.type !== "tableRow")
             return "";
         const tr = row;
+        // ISO 29500 requires every w:tr to contain at least one w:tc.
+        // Skip rows with no tableCell children entirely (e.g. an empty <thead><tr/></thead>).
+        const cellNodes = tr.children.filter(c => c.type === "tableCell");
+        if (cellNodes.length === 0)
+            return "";
         const trPr = tr.isHeader ? "<w:trPr><w:tblHeader/></w:trPr>" : "";
-        const cells = tr.children.map(cell => {
-            if (cell.type !== "tableCell")
-                return "";
+        const cells = cellNodes.map(cell => {
             const tc = cell;
+            const span = tc.colspan ?? 1;
             let tcPr = "<w:tcPr>";
-            if (tc.colspan && tc.colspan > 1)
-                tcPr += `<w:gridSpan w:val="${tc.colspan}"/>`;
+            tcPr += `<w:tcW w:w="${colWidth * span}" w:type="dxa"/>`;
+            if (span > 1)
+                tcPr += `<w:gridSpan w:val="${span}"/>`;
             tcPr += "</w:tcPr>";
+            const emptyPara = { type: "paragraph", children: [] };
             const content = tc.children.length > 0
                 ? tc.children.map(c => convertBlock(c, ctx, 0)).join("")
-                : "<w:p/>";
+                : convertParagraph(emptyPara, ctx);
             return `<w:tc>${tcPr}${content}</w:tc>`;
         }).join("");
         return `<w:tr>${trPr}${cells}</w:tr>`;
-    }).join("\n");
-    return `<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/><w:tblBorders><w:top w:val="single" w:sz="4" w:color="auto"/><w:left w:val="single" w:sz="4" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:color="auto"/><w:right w:val="single" w:sz="4" w:color="auto"/><w:insideH w:val="single" w:sz="4" w:color="auto"/><w:insideV w:val="single" w:sz="4" w:color="auto"/></w:tblBorders></w:tblPr>${rows}</w:tbl>`;
+    }).filter(Boolean).join("\n");
+    return `<w:tbl><w:tblPr><w:tblW w:w="0" w:type="auto"/><w:tblBorders><w:top w:val="single" w:sz="4" w:color="auto"/><w:left w:val="single" w:sz="4" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:color="auto"/><w:right w:val="single" w:sz="4" w:color="auto"/><w:insideH w:val="single" w:sz="4" w:color="auto"/><w:insideV w:val="single" w:sz="4" w:color="auto"/></w:tblBorders></w:tblPr>${tblGrid}${rows}</w:tbl>`;
 }
 // ---------------------------------------------------------------------------
 // Inline conversion
@@ -478,11 +722,14 @@ function convertInline(node, ctx, inheritedRPr = "") {
     if (node.type === "break")
         return `<w:r><w:br/></w:r>`;
     if (node.type === "inlineCode") {
-        return `<w:r><w:rPr><w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/>${inheritedRPr}</w:rPr><w:t>${esc(node.value)}</w:t></w:r>`;
+        const parts = [`<w:rFonts w:ascii="Courier New" w:hAnsi="Courier New"/>`];
+        if (inheritedRPr)
+            parts.push(...tokenizeOoxmlChildren(inheritedRPr));
+        return `<w:r>${serializeRPr(parts)}<w:t xml:space="preserve">${esc(node.value)}</w:t></w:r>`;
     }
     if (node.type === "image") {
         const img = node;
-        return `<w:r><w:t>[image: ${esc(img.alt ?? img.url)}]</w:t></w:r>`;
+        return `<w:r><w:t xml:space="preserve">[image: ${esc(img.alt ?? img.url)}]</w:t></w:r>`;
     }
     return "";
 }
@@ -491,11 +738,8 @@ function convertText(node, ctx, inheritedRPr = "") {
     const otherMarks = node.marks?.filter(m => m.type !== "link") ?? [];
     // Build rPr: inherited CSS props first, then mark-specific overrides
     const parts = [];
-    // Split inherited XML into individual elements for dedup
-    if (inheritedRPr) {
-        const elems = inheritedRPr.match(/<w:[^/]*\/>/g) ?? [];
-        parts.push(...elems);
-    }
+    if (inheritedRPr)
+        parts.push(...tokenizeOoxmlChildren(inheritedRPr));
     for (const mark of otherMarks) {
         switch (mark.type) {
             case "strong":
@@ -521,16 +765,8 @@ function convertText(node, ctx, inheritedRPr = "") {
                 break;
         }
     }
-    // Deduplicate rPr elements (e.g. multiple <w:b/> from container + class CSS)
-    const seen = new Set();
-    const dedupedParts = [];
-    for (const p of parts) {
-        if (!seen.has(p)) {
-            seen.add(p);
-            dedupedParts.push(p);
-        }
-    }
-    const rPr = dedupedParts.length > 0 ? `<w:rPr>${dedupedParts.join("")}</w:rPr>` : "";
+    // Schema-order + tag-dedup (later sources override earlier).
+    const rPr = serializeRPr(parts);
     // Track-changes: check diff context (skip for linked text to avoid nesting complexity)
     if (ctx.diff && ctx.nodePathKeys && !linkMark) {
         const key = ctx.nodePathKeys.get(node);
@@ -575,21 +811,24 @@ function convertText(node, ctx, inheritedRPr = "") {
 // ---------------------------------------------------------------------------
 // Paragraph property builder
 // ---------------------------------------------------------------------------
-function buildPPr(node, ctx) {
+function buildPPrParts(node, ctx) {
+    // Collect parts in any order — serializePPr applies ECMA-376 ordering at the end.
     const parts = [];
     // Classes → pStyle + generate CSS-based Word styles
     const classes = node.classes;
     if (classes && classes.length > 0) {
-        const styleId = classes[0]; // Primary class becomes the paragraph style
-        parts.push(`<w:pStyle w:val="${esc(styleId)}"/>`);
+        // Style IDs must be valid OOXML identifiers — sanitize the CSS class name.
+        const styleId = sanitizeStyleId(classes[0]);
+        parts.push(`<w:pStyle w:val="${styleId}"/>`);
         // Generate custom style from CSS rules (once per styleId)
         for (const cls of classes) {
-            if (ctx.cssClasses[cls] && !ctx.generatedStyleIds.has(cls)) {
-                ctx.generatedStyleIds.add(cls);
+            const clsId = sanitizeStyleId(cls);
+            if (ctx.cssClasses[cls] && !ctx.generatedStyleIds.has(clsId)) {
+                ctx.generatedStyleIds.add(clsId);
                 const cssDecls = ctx.cssClasses[cls];
                 const runProps = cssToRunProps(cssDecls);
                 const paraProps = cssToParaProps(cssDecls);
-                ctx.customStyles.push(buildStyleElement(cls, cls, "paragraph", runProps, paraProps));
+                ctx.customStyles.push(buildStyleElement(clsId, cls, "paragraph", runProps, paraProps));
             }
         }
     }
@@ -616,13 +855,14 @@ function buildPPr(node, ctx) {
     if (elTag) {
         ensureElementStyle(elTag, ctx);
         // If no class style was set, use the element style
-        if (!classes || classes.length === 0) {
-            parts.unshift(`<w:pStyle w:val="_el_${esc(elTag)}"/>`);
+        if ((!classes || classes.length === 0) && ctx.cssElements[elTag]) {
+            parts.push(`<w:pStyle w:val="_el_${esc(elTag)}"/>`);
         }
-        // If class style was set, element CSS is already baked into the base —
-        // we could chain basedOn, but for simplicity element styles are standalone
     }
-    return parts.length > 0 ? `<w:pPr>${parts.join("")}</w:pPr>` : "";
+    return parts;
+}
+function buildPPr(node, ctx) {
+    return serializePPr(buildPPrParts(node, ctx));
 }
 /** Map UDM type to the HTML tag name for CSS element selector lookup */
 function udmTypeToHtmlTag(type, node) {
@@ -689,6 +929,16 @@ function stripDataForSnapshot(node) {
 function parseColorSafe(val) {
     return parseColor(val) ?? "auto";
 }
+/**
+ * Deterministic short hash of a string. Used to bind the embedded UDM
+ * snapshot to a specific document.xml so the reader can detect external
+ * edits (e.g. the user opened the file in Word and saved). 64 bits of
+ * SHA-256 is plenty for change detection — we don't need cryptographic
+ * collision resistance.
+ */
+function hashString(s) {
+    return createHash("sha256").update(s).digest("hex").slice(0, 16);
+}
 // ---------------------------------------------------------------------------
 // Deleted-block rendering (for writeDiffDocx)
 // ---------------------------------------------------------------------------
@@ -707,7 +957,7 @@ function convertDeletedBlock(op, ctx) {
     const node = op.node;
     const diff = ctx.diff;
     const author = esc(diff.author);
-    const date = diff.date;
+    const date = esc(diff.date);
     const textContent = extractTextContent(node);
     if (!textContent)
         return "";
@@ -719,13 +969,35 @@ function convertDeletedBlock(op, ctx) {
         const depth = node.depth;
         pStyle = `<w:pStyle w:val="Heading${depth}"/>`;
     }
-    const delMarkXml = `<w:del w:id="${delMarkId}" w:author="${author}" w:date="${date}"/>`;
-    const pPr = `<w:pPr>${pStyle}<w:rPr>${delMarkXml}</w:rPr></w:pPr>`;
+    const delMark = `<w:del w:id="${delMarkId}" w:author="${author}" w:date="${date}"/>`;
+    const basePPr = pStyle ? `<w:pPr>${pStyle}</w:pPr>` : "";
+    const pPr = mergeParaMarkChild(basePPr, delMark);
     const delContent = `<w:del w:id="${delContentId}" w:author="${author}" w:date="${date}"><w:r><w:delText xml:space="preserve">${esc(textContent)}</w:delText></w:r></w:del>`;
     return `<w:p>${pPr}${delContent}</w:p>`;
 }
 function esc(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+    return sanitizeText(s)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Strip XML 1.0 forbidden control characters (U+0000–U+001F except \t \n \r,
+ * plus U+007F). ECMA-376 inherits this restriction; leaving these in causes
+ * `document.xml` to be unparseable and Word refuses to open the file.
+ */
+function sanitizeText(s) {
+    return s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, "");
+}
+/**
+ * Normalize a CSS class name into a valid OOXML style ID.
+ * Per ECMA-376 §17.7.4.9, style IDs must match `[a-zA-Z0-9_\-:]` and be
+ * ≤ 31 characters. Anything else is stripped.
+ */
+function sanitizeStyleId(id) {
+    const cleaned = id.replace(/[^a-zA-Z0-9_\-:]/g, "").slice(0, 31);
+    return cleaned || "Normal";
 }
 // ---------------------------------------------------------------------------
 // writeDiffDocx — serialize a diff result as a .docx with track-changes markup
@@ -749,14 +1021,17 @@ export async function writeDiffDocx(newTree, diffResult, options) {
     const date = options?.date ?? "2024-01-01T00:00:00Z";
     const diffCtx = buildDiffCtx(diffResult, author, date);
     const nodePathKeys = buildNodePathMap(newTree);
+    const docxDataPre = newTree.data?.docx;
+    const existingRels = docxDataPre?.relationships;
     const ctx = {
         cssClasses: mergedClassCss,
         cssElements: elementCss,
         customStyles: [],
         generatedStyleIds: new Set(),
         nextNumId: 3,
+        allocatedNums: new Map(),
         hyperlinks: new Map(),
-        nextRId: 100,
+        nextRId: nextRIdFor(existingRels),
         diff: diffCtx,
         nodePathKeys,
     };
@@ -774,6 +1049,12 @@ export async function writeDiffDocx(newTree, diffResult, options) {
             offset++;
         }
     }
+    // Match writeDocx's trailing-paragraph-after-table behaviour so the body
+    // doesn't end with </w:tbl> immediately before <w:sectPr>.
+    const lastBlock = newTree.children[newTree.children.length - 1];
+    if (lastBlock?.type === "table") {
+        renderedBlocks.push("<w:p/>");
+    }
     const bodyXml = renderedBlocks.join("\n");
     const docxData = newTree.data?.docx;
     let stylesXml = docxData?.styles ?? DEFAULT_STYLES;
@@ -793,16 +1074,24 @@ ${bodyXml}
         const hlRels = [...ctx.hyperlinks].map(([rId, url]) => `<Relationship Id="${rId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink" Target="${esc(url)}" TargetMode="External"/>`).join("\n  ");
         relsXml = relsXml.replace("</Relationships>", `  ${hlRels}\n</Relationships>`);
     }
+    let numberingXml = docxData?.numbering ?? DEFAULT_NUMBERING;
+    if (ctx.allocatedNums.size > 0) {
+        const newNums = [...ctx.allocatedNums]
+            .map(([numId, abstractId]) => `<w:num w:numId="${numId}"><w:abstractNumId w:val="${abstractId}"/></w:num>`)
+            .join("\n  ");
+        numberingXml = numberingXml.replace("</w:numbering>", `  ${newNums}\n</w:numbering>`);
+    }
     const parts = {
         document: docXml,
         styles: stylesXml,
-        numbering: docxData?.numbering ?? DEFAULT_NUMBERING,
+        numbering: numberingXml,
         relationships: relsXml,
         contentTypes: docxData?.contentTypes ?? undefined,
         media: new Map(),
         rawParts: new Map(),
     };
     const udmSnapshot = stripDataForSnapshot(newTree);
+    udmSnapshot.__docHash = hashString(docXml);
     parts.rawParts.set("word/otomate-udm.json", JSON.stringify(udmSnapshot));
     if (cssData && (Object.keys(cssData.classRules ?? {}).length > 0 || Object.keys(cssData.elementRules ?? {}).length > 0)) {
         parts.rawParts.set("word/otomate-css.json", JSON.stringify(cssData));