@usejunior/docx-core 0.9.1 → 0.11.0

package/dist/primitives/document.js

@@ -1,21 +1,101 @@
 import { DocxZip } from './zip.js';
 import { parseXml, serializeXml } from './xml.js';
+import { maybeCaptureEmittedDocumentXml } from './schema-corpus-capture.js';
 import { OOXML, W } from './namespaces.js';
-import { isW, getDirectChildrenByName } from './dom-helpers.js';
+import { createWmlElement, isW, getDirectChildrenByName } from './dom-helpers.js';
 import { findParagraphByBookmarkId, insertParagraphBookmarks, cleanupInternalBookmarks, getParagraphBookmarkId, insertSingleParagraphBookmark, } from './bookmarks.js';
 import { getParagraphRuns, getParagraphText, replaceParagraphTextRange } from './text.js';
+import { allocateRevisionId, createRevisionContainer, } from './track-changes-emitter.js';
 import { buildNodesForDocumentView } from './document_view.js';
+import { serializeToMarkdown } from './serialize_markdown.js';
+import { serializeToHtml } from './serialize_html.js';
+import { serializeToPlainText } from './serialize_plaintext.js';
+import { parseStylesXml } from './styles.js';
+import { parseNumberingXml } from './numbering.js';
 import { findUniqueSubstringMatch } from './matching.js';
 import { parseDocumentRels } from './relationships.js';
 import { setParagraphSpacing, setTableCellPadding, setTableRowHeight, } from './layout.js';
 import { extractTables, } from './tables.js';
 import { mergeRuns } from './merge_runs.js';
+import { restoreUntouchedBlocks } from './minimal_save.js';
 import { simplifyRedlines } from './simplify_redlines.js';
 import { preventDoubleElevation } from './prevent_double_elevation.js';
 import { validateDocument } from './validate_document.js';
+import { validateAiRevisions as validateAiRevisionsImpl, } from './validate_ai_revisions.js';
+import { enumerateRevisionStoryPartPaths, REVISION_STORY_PART_PATHS, } from './revision-parts.js';
 import { acceptChanges as acceptChangesImpl } from './accept_changes.js';
+import { rejectChanges as rejectChangesImpl } from './reject_changes.js';
 import { bootstrapCommentParts, addComment as addCommentImpl, addCommentReply as addCommentReplyImpl, getComments as getCommentsImpl, getComment as getCommentImpl, deleteComment as deleteCommentImpl, } from './comments.js';
 import { bootstrapFootnoteParts, getFootnotes as getFootnotesImpl, getFootnote as getFootnoteImpl, addFootnote as addFootnoteImpl, updateFootnoteText as updateFootnoteTextImpl, deleteFootnote as deleteFootnoteImpl, } from './footnotes.js';
+function emptyAcceptChangesResult() {
+    return { insertionsAccepted: 0, deletionsAccepted: 0, movesResolved: 0, propertyChangesResolved: 0 };
+}
+function hasAcceptedChanges(result) {
+    return (result.insertionsAccepted > 0 ||
+        result.deletionsAccepted > 0 ||
+        result.movesResolved > 0 ||
+        result.propertyChangesResolved > 0);
+}
+function addAcceptChangesResult(total, result) {
+    total.insertionsAccepted += result.insertionsAccepted;
+    total.deletionsAccepted += result.deletionsAccepted;
+    total.movesResolved += result.movesResolved;
+    total.propertyChangesResolved += result.propertyChangesResolved;
+}
+function emptyRejectChangesResult() {
+    return { insertionsRemoved: 0, deletionsRestored: 0, movesReverted: 0, propertyChangesReverted: 0 };
+}
+function hasRejectedChanges(result) {
+    return (result.insertionsRemoved > 0 ||
+        result.deletionsRestored > 0 ||
+        result.movesReverted > 0 ||
+        result.propertyChangesReverted > 0);
+}
+function addRejectChangesResult(total, result) {
+    total.insertionsRemoved += result.insertionsRemoved;
+    total.deletionsRestored += result.deletionsRestored;
+    total.movesReverted += result.movesReverted;
+    total.propertyChangesReverted += result.propertyChangesReverted;
+}
+function parseWId(el) {
+    const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+    if (!idStr)
+        return null;
+    const n = parseInt(idStr, 10);
+    return Number.isNaN(n) ? null : n;
+}
+function collectLiveFootnoteRefIds(doc) {
+    const ids = new Set();
+    const refs = doc.getElementsByTagNameNS(OOXML.W_NS, W.footnoteReference);
+    for (let i = 0; i < refs.length; i++) {
+        const id = parseWId(refs.item(i));
+        if (id !== null)
+            ids.add(id);
+    }
+    return ids;
+}
+// Side-effect of accept/reject on document.xml: a body w:footnoteReference that
+// lived inside a removed w:del (accept) or w:ins (reject) is gone afterwards.
+// The corresponding <w:footnote w:id=N> in footnotes.xml is then unreachable —
+// remove it so the side part matches the post-sweep body. Reserved separator /
+// continuationSeparator entries are preserved unconditionally.
+function pruneOrphanedFootnotes(footnotesDoc, liveRefIds) {
+    const entries = Array.from(footnotesDoc.getElementsByTagNameNS(OOXML.W_NS, W.footnote));
+    let pruned = 0;
+    for (const fn of entries) {
+        const typ = fn.getAttributeNS(OOXML.W_NS, 'type') ?? fn.getAttribute('w:type');
+        if (typ === W.separator || typ === W.continuationSeparator)
+            continue;
+        const id = parseWId(fn);
+        if (id === null)
+            continue;
+        if (liveRefIds.has(id))
+            continue;
+        fn.parentNode?.removeChild(fn);
+        pruned++;
+    }
+    return pruned;
+}
 function prevElementSibling(node) {
     let cur = node?.previousSibling ?? null;
     while (cur) {
@@ -228,7 +308,13 @@ export class DocxDocument {
     relsMap;
     dirty;
     documentViewCache;
-    constructor(zip, documentXml, stylesXml, numberingXml, footnotesXml, relsMap) {
+    /**
+     * Raw document.xml text as loaded, before normalize()/edits mutate the DOM.
+     * Reference for minimal re-serialization in toBuffer(); null for instances
+     * not created via load().
+     */
+    originalDocumentXmlText;
+    constructor(zip, documentXml, stylesXml, numberingXml, footnotesXml, relsMap, originalDocumentXmlText = null) {
         this.zip = zip;
         this.documentXml = documentXml;
         this.stylesXml = stylesXml;
@@ -237,6 +323,7 @@ export class DocxDocument {
         this.relsMap = relsMap;
         this.dirty = false;
         this.documentViewCache = null;
+        this.originalDocumentXmlText = originalDocumentXmlText;
     }
     static async load(buffer) {
         const zip = await DocxZip.load(buffer);
@@ -253,7 +340,7 @@ export class DocxDocument {
         // Load document relationships for hyperlink resolution.
         const relsText = await zip.readTextOrNull('word/_rels/document.xml.rels');
         const relsMap = relsText ? parseDocumentRels(parseXml(relsText)) : new Map();
-        return new DocxDocument(zip, doc, stylesXml, numberingXml, footnotesXml, relsMap);
+        return new DocxDocument(zip, doc, stylesXml, numberingXml, footnotesXml, relsMap, xml);
     }
     getParagraphs() {
         const body = this.documentXml.getElementsByTagNameNS(OOXML.W_NS, W.body).item(0);
@@ -310,20 +397,96 @@ export class DocxDocument {
     validate() {
         return validateDocument(this.documentXml);
     }
+    async validateAiRevisions(aiAuthor, touched) {
+        const stories = [{ part: 'word/document.xml', doc: this.documentXml }];
+        for (const partPath of enumerateRevisionStoryPartPaths(this.zip)) {
+            const xml = await this.zip.readTextOrNull(partPath);
+            if (!xml)
+                continue;
+            stories.push({ part: partPath, doc: parseXml(xml) });
+        }
+        return validateAiRevisionsImpl({
+            aiAuthor,
+            stories,
+            packageZip: this.zip,
+            touched,
+        });
+    }
     /**
-     * Accept all tracked changes in the document body, producing a clean
-     * document with no revision markup.
+     * Accept all tracked changes in document.xml plus supported revisionable
+     * side-story parts, producing clean XML with no revision markup.
      */
-    acceptChanges() {
-        const result = acceptChangesImpl(this.documentXml);
-        if (result.insertionsAccepted > 0 ||
-            result.deletionsAccepted > 0 ||
-            result.movesResolved > 0 ||
-            result.propertyChangesResolved > 0) {
+    async acceptChanges() {
+        const total = emptyAcceptChangesResult();
+        const bodyResult = acceptChangesImpl(this.documentXml);
+        addAcceptChangesResult(total, bodyResult);
+        // After accepting, footnotes whose body reference lived inside a removed
+        // w:del are orphaned. Only worth checking when the body sweep removed
+        // deletions (the only operation that can drop a footnoteReference).
+        const liveFootnoteRefIds = bodyResult.deletionsAccepted > 0
+            ? collectLiveFootnoteRefIds(this.documentXml)
+            : null;
+        for (const partPath of REVISION_STORY_PART_PATHS) {
+            const xml = await this.zip.readTextOrNull(partPath);
+            if (!xml)
+                continue;
+            const partDoc = parseXml(xml);
+            const partResult = acceptChangesImpl(partDoc);
+            addAcceptChangesResult(total, partResult);
+            let footnotesPruned = 0;
+            if (partPath === 'word/footnotes.xml' && liveFootnoteRefIds) {
+                footnotesPruned = pruneOrphanedFootnotes(partDoc, liveFootnoteRefIds);
+            }
+            if (hasAcceptedChanges(partResult) || footnotesPruned > 0) {
+                this.zip.writeText(partPath, serializeXml(partDoc));
+                if (partPath === 'word/footnotes.xml') {
+                    this.footnotesXml = partDoc;
+                }
+            }
+        }
+        if (hasAcceptedChanges(total)) {
             this.dirty = true;
             this.documentViewCache = null;
         }
-        return result;
+        return total;
+    }
+    /**
+     * Reject all tracked changes in document.xml plus supported revisionable
+     * side-story parts, restoring their pre-edit state where possible.
+     */
+    async rejectChanges() {
+        const total = emptyRejectChangesResult();
+        const bodyResult = rejectChangesImpl(this.documentXml);
+        addRejectChangesResult(total, bodyResult);
+        // After rejecting, footnotes whose body reference lived inside a removed
+        // w:ins are orphaned. Only worth checking when the body sweep removed
+        // insertions (the only operation that can drop a footnoteReference).
+        const liveFootnoteRefIds = bodyResult.insertionsRemoved > 0
+            ? collectLiveFootnoteRefIds(this.documentXml)
+            : null;
+        for (const partPath of REVISION_STORY_PART_PATHS) {
+            const xml = await this.zip.readTextOrNull(partPath);
+            if (!xml)
+                continue;
+            const partDoc = parseXml(xml);
+            const partResult = rejectChangesImpl(partDoc);
+            addRejectChangesResult(total, partResult);
+            let footnotesPruned = 0;
+            if (partPath === 'word/footnotes.xml' && liveFootnoteRefIds) {
+                footnotesPruned = pruneOrphanedFootnotes(partDoc, liveFootnoteRefIds);
+            }
+            if (hasRejectedChanges(partResult) || footnotesPruned > 0) {
+                this.zip.writeText(partPath, serializeXml(partDoc));
+                if (partPath === 'word/footnotes.xml') {
+                    this.footnotesXml = partDoc;
+                }
+            }
+        }
+        if (hasRejectedChanges(total)) {
+            this.dirty = true;
+            this.documentViewCache = null;
+        }
+        return total;
     }
     removeJuniorBookmarks() {
         const removed = cleanupInternalBookmarks(this.documentXml);
@@ -360,6 +523,23 @@ export class DocxDocument {
         const endIdx = typeof limit === 'number' ? Math.min(total, startIdx + limit) : total;
         return { paragraphs: all.slice(startIdx, endIdx), totalParagraphs: total };
     }
+    /**
+     * Parsed `word/numbering.xml` model (abstract numberings + instances), or null when the
+     * document has no numbering part. The document view's `numbering` field only carries
+     * `num_id`/`ilvl`; semantic converters (DOCX → ODT) need `numFmt`/`lvlText`/`start` to
+     * synthesize target-format list styles, so the full model is exposed here.
+     */
+    getNumberingModel() {
+        return this.numberingXml ? parseNumberingXml(this.numberingXml) : null;
+    }
+    /**
+     * Parsed named-style model of the loaded document (empty when the package has no
+     * `word/styles.xml`). Semantic converters (DOCX → ODT) resolve heading/body style chains
+     * through it to seed their own style templates from the source's definitions.
+     */
+    getStylesModel() {
+        return parseStylesXml(this.stylesXml);
+    }
     buildDocumentView(opts) {
         const includeSemanticTags = opts?.includeSemanticTags ?? true;
         const showFormatting = opts?.showFormatting ?? false;
@@ -425,7 +605,7 @@ export class DocxDocument {
         this.dirty = true;
         this.documentViewCache = null;
     }
-    insertParagraph(params) {
+    insertParagraph(params, ctx) {
         const { positionalAnchorNodeId, relativePosition, newText, newParagraphId: _newParagraphId, styleSourceId } = params;
         const anchor = findParagraphByBookmarkId(this.documentXml, positionalAnchorNodeId);
         if (!anchor)
@@ -505,8 +685,86 @@ export class DocxDocument {
                     continue;
                 newP.removeChild(child);
             }
+            // sectPr is the section terminator — must stay on the anchor, not propagate to the new paragraph.
+            const clonedPPr = getDirectChildrenByName(newP, W.pPr)[0];
+            if (clonedPPr) {
+                for (const sectPr of getDirectChildrenByName(clonedPPr, 'sectPr')) {
+                    clonedPPr.removeChild(sectPr);
+                }
+            }
             return newP;
         }
+        function ensureParagraphProperties(paragraph) {
+            const existing = getDirectChildrenByName(paragraph, W.pPr)[0];
+            if (existing)
+                return existing;
+            const pPr = createWmlElement(doc, W.pPr);
+            paragraph.insertBefore(pPr, paragraph.firstChild);
+            return pPr;
+        }
+        function ensureParagraphRunProperties(pPr) {
+            const existing = getDirectChildrenByName(pPr, W.rPr)[0];
+            if (existing)
+                return existing;
+            const rPr = createWmlElement(doc, W.rPr);
+            const sectPr = getDirectChildrenByName(pPr, 'sectPr')[0];
+            const pPrChange = getDirectChildrenByName(pPr, 'pPrChange')[0];
+            const insertBefore = sectPr ?? pPrChange ?? null;
+            if (insertBefore) {
+                pPr.insertBefore(rPr, insertBefore);
+            }
+            else {
+                pPr.appendChild(rPr);
+            }
+            return rPr;
+        }
+        function addParagraphInsertionMarker(paragraph, revisionCtx) {
+            const pPr = ensureParagraphProperties(paragraph);
+            const rPr = ensureParagraphRunProperties(pPr);
+            const marker = createWmlElement(doc, 'ins', {
+                'w:id': String(allocateRevisionId(revisionCtx.idState)),
+                'w:author': revisionCtx.author,
+                'w:date': revisionCtx.date,
+            });
+            rPr.insertBefore(marker, rPr.firstChild);
+        }
+        function clearRunPropertyRevisionMarkup(run) {
+            const rPr = getDirectChildrenByName(run, W.rPr)[0];
+            if (!rPr)
+                return;
+            for (const child of Array.from(rPr.childNodes)) {
+                if (child.nodeType !== 1)
+                    continue;
+                const element = child;
+                if (isW(element, 'rPrChange')) {
+                    rPr.removeChild(element);
+                }
+            }
+        }
+        function clearParagraphPropertyRevisionMarkup(paragraph) {
+            const pPr = getDirectChildrenByName(paragraph, W.pPr)[0];
+            if (!pPr)
+                return;
+            for (const pPrChange of getDirectChildrenByName(pPr, 'pPrChange')) {
+                pPr.removeChild(pPrChange);
+            }
+            const rPr = getDirectChildrenByName(pPr, W.rPr)[0];
+            if (!rPr)
+                return;
+            for (const child of Array.from(rPr.childNodes)) {
+                if (child.nodeType !== 1)
+                    continue;
+                const element = child;
+                // CT_ParaRPr revision children: w:ins, w:del, w:moveFrom, w:moveTo, w:rPrChange.
+                if (isW(element, 'ins') ||
+                    isW(element, 'del') ||
+                    isW(element, 'moveFrom') ||
+                    isW(element, 'moveTo') ||
+                    isW(element, 'rPrChange')) {
+                    rPr.removeChild(element);
+                }
+            }
+        }
         function getInsertionRefNode() {
             if (relativePosition === 'BEFORE') {
                 const prev = prevElementSibling(anchorP);
@@ -538,7 +796,17 @@ export class DocxDocument {
             const newP = cloneParagraphShell(formattingSource);
             const newRun = cloneRunFormattingOnly(templateRun);
             appendTextToRun(newRun, paraText);
-            newP.appendChild(newRun);
+            if (ctx) {
+                clearRunPropertyRevisionMarkup(newRun);
+                clearParagraphPropertyRevisionMarkup(newP);
+                addParagraphInsertionMarker(newP, ctx);
+                const insertion = createRevisionContainer(doc, 'ins', ctx);
+                insertion.appendChild(newRun);
+                newP.appendChild(insertion);
+            }
+            else {
+                newP.appendChild(newRun);
+            }
             parent.insertBefore(newP, cursor);
             const id = insertSingleParagraphBookmark(doc, newP);
             insertedIds.push(id);
@@ -557,24 +825,24 @@ export class DocxDocument {
             result.styleSourceFallback = true;
         return result;
     }
-    setParagraphSpacing(mutation) {
-        const result = setParagraphSpacing(this.documentXml, mutation);
+    setParagraphSpacing(mutation, ctx) {
+        const result = setParagraphSpacing(this.documentXml, mutation, ctx);
         if (result.affectedParagraphs > 0) {
             this.dirty = true;
             this.documentViewCache = null;
         }
         return result;
     }
-    setTableRowHeight(mutation) {
-        const result = setTableRowHeight(this.documentXml, mutation);
+    setTableRowHeight(mutation, ctx) {
+        const result = setTableRowHeight(this.documentXml, mutation, ctx);
         if (result.affectedRows > 0) {
             this.dirty = true;
             this.documentViewCache = null;
         }
         return result;
     }
-    setTableCellPadding(mutation) {
-        const result = setTableCellPadding(this.documentXml, mutation);
+    setTableCellPadding(mutation, ctx) {
+        const result = setTableCellPadding(this.documentXml, mutation, ctx);
         if (result.affectedCells > 0) {
             this.dirty = true;
             this.documentViewCache = null;
@@ -591,9 +859,11 @@ export class DocxDocument {
     /**
      * Merge format-identical adjacent runs only (no redline simplification).
      * Useful as a pre-processing step before text search when runs may be fragmented.
+     * Pass `{ preserveRsidIdentity: true }` from edit pipelines that must not
+     * disturb rsid attributes on runs the caller did not touch (#286).
      */
-    mergeRunsOnly() {
-        const result = mergeRuns(this.documentXml);
+    mergeRunsOnly(opts = {}) {
+        const result = mergeRuns(this.documentXml, opts);
         if (result.runsMerged > 0) {
             this.dirty = true;
             this.documentViewCache = null;
@@ -606,7 +876,7 @@ export class DocxDocument {
      * Bootstraps comment parts if missing (idempotent).
      * Returns the allocated comment ID.
      */
-    async addComment(params) {
+    async addComment(params, ctx) {
         const p = findParagraphByBookmarkId(this.documentXml, params.paragraphId);
         if (!p)
             throw new Error(`Paragraph not found: ${params.paragraphId}`);
@@ -618,7 +888,7 @@ export class DocxDocument {
             author: params.author,
             text: params.text,
             initials: params.initials,
-        });
+        }, ctx);
         this.dirty = true;
         this.documentViewCache = null;
         return result;
@@ -629,14 +899,14 @@ export class DocxDocument {
      * Bootstraps comment parts if missing (idempotent).
      * Returns the allocated comment ID and parent ID.
      */
-    async addCommentReply(params) {
+    async addCommentReply(params, ctx) {
         await bootstrapCommentParts(this.zip);
         const result = await addCommentReplyImpl(this.documentXml, this.zip, {
             parentCommentId: params.parentCommentId,
             author: params.author,
             text: params.text,
             initials: params.initials,
-        });
+        }, ctx);
         this.dirty = true;
         this.documentViewCache = null;
         return result;
@@ -647,8 +917,8 @@ export class DocxDocument {
     async getComment(commentId) {
         return getCommentImpl(this.zip, this.documentXml, commentId);
     }
-    async deleteComment(params) {
-        await deleteCommentImpl(this.documentXml, this.zip, params);
+    async deleteComment(params, ctx) {
+        await deleteCommentImpl(this.documentXml, this.zip, params, ctx);
         this.dirty = true;
         this.documentViewCache = null;
     }
@@ -660,6 +930,47 @@ export class DocxDocument {
     async getFootnotes() {
         return getFootnotesImpl(this.zip, this.documentXml);
     }
+    /**
+     * Serialize the document to GitHub-Flavored Markdown. Convenience wrapper that wires the
+     * structured document view (with inline formatting) and footnotes into
+     * {@link serializeToMarkdown}. Markdown is intentionally lossy — see that serializer.
+     *
+     * Async because footnote extraction reads the footnotes part from the zip.
+     */
+    async toMarkdown(opts) {
+        const { nodes } = this.buildDocumentView({ showFormatting: true });
+        const footnotes = await this.getFootnotes();
+        return serializeToMarkdown(nodes, footnotes, opts);
+    }
+    /**
+     * Serialize the document to semantic HTML. Convenience wrapper that wires the structured
+     * document view (with inline formatting) and footnotes into {@link serializeToHtml}. The
+     * default output is a complete `<!DOCTYPE html>` document; pass `{ fragment: true }` for the
+     * body-level elements only. This is the semantic tier — exact layout is not reproduced.
+     *
+     * Async because footnote extraction reads the footnotes part from the zip.
+     */
+    async toHtml(opts) {
+        const { nodes } = this.buildDocumentView({ showFormatting: true });
+        const footnotes = await this.getFootnotes();
+        return serializeToHtml(nodes, footnotes, opts);
+    }
+    /**
+     * Serialize the document to plain text (no markup). Convenience wrapper that wires the
+     * structured document view and footnotes into {@link serializeToPlainText}. All formatting
+     * is stripped; block structure survives as blank-line-separated paragraphs, `- ` bullets,
+     * and tab-separated table rows. Intentionally lossy — see that serializer.
+     *
+     * Uses the same `showFormatting: true` view as {@link toMarkdown} so the block structure
+     * and injected `[^n]` footnote markers match; the inline tags it produces are then stripped.
+     *
+     * Async because footnote extraction reads the footnotes part from the zip.
+     */
+    async toPlainText(opts) {
+        const { nodes } = this.buildDocumentView({ showFormatting: true });
+        const footnotes = await this.getFootnotes();
+        return serializeToPlainText(nodes, footnotes, opts);
+    }
     async getFootnote(noteId) {
         return getFootnoteImpl(this.zip, this.documentXml, noteId);
     }
@@ -669,7 +980,7 @@ export class DocxDocument {
      * Bootstraps footnote parts if missing (idempotent).
      * Returns the allocated footnote ID.
      */
-    async addFootnote(params) {
+    async addFootnote(params, ctx) {
         const p = findParagraphByBookmarkId(this.documentXml, params.paragraphId);
         if (!p)
             throw new Error(`Paragraph not found: ${params.paragraphId}`);
@@ -678,7 +989,7 @@ export class DocxDocument {
             paragraphEl: p,
             afterText: params.afterText,
             text: params.text,
-        });
+        }, ctx);
         await this.refreshFootnotesXml();
         this.dirty = true;
         this.documentViewCache = null;
@@ -687,8 +998,8 @@ export class DocxDocument {
     /**
      * Update the text content of an existing footnote.
      */
-    async updateFootnoteText(params) {
-        await updateFootnoteTextImpl(this.zip, params);
+    async updateFootnoteText(params, ctx) {
+        await updateFootnoteTextImpl(this.zip, params, ctx);
         await this.refreshFootnotesXml();
         this.dirty = true;
         this.documentViewCache = null;
@@ -696,8 +1007,8 @@ export class DocxDocument {
     /**
      * Delete a footnote and its references from the document.
      */
-    async deleteFootnote(params) {
-        await deleteFootnoteImpl(this.documentXml, this.zip, params);
+    async deleteFootnote(params, ctx) {
+        await deleteFootnoteImpl(this.documentXml, this.zip, params, ctx);
         await this.refreshFootnotesXml();
         this.dirty = true;
         this.documentViewCache = null;
@@ -720,23 +1031,49 @@ export class DocxDocument {
             return null;
         return parseXml(commentsText);
     }
+    /**
+     * Serialize the document to a .docx buffer.
+     *
+     * With `minimalReserialization` (requires `cleanBookmarks`), top-level body
+     * blocks that no edit touched are restored element-for-element from the
+     * original document.xml instead of carrying the open-time normalization
+     * (proofErr stripping, run merging) to disk — so output diffs reflect the
+     * actual edit blast radius. Edited/inserted blocks are emitted as-is.
+     * Falls back to full re-serialization (blocksRestored: 0) when no original
+     * text was captured or reconciliation fails.
+     *
+     * @see https://github.com/UseJunior/safe-docx/issues/408
+     */
     async toBuffer(opts) {
         // Always write the latest document.xml when saving.
         // Important: when cleanBookmarks=true (download), we must NOT mutate session state.
         const xmlWithBookmarks = serializeXml(this.documentXml);
+        maybeCaptureEmittedDocumentXml(xmlWithBookmarks);
         this.zip.writeText('word/document.xml', xmlWithBookmarks);
         if (opts?.cleanBookmarks) {
             const cloned = parseXml(xmlWithBookmarks);
             const bookmarksRemoved = cleanupInternalBookmarks(cloned);
+            let blocksRestored = 0;
+            if (opts.minimalReserialization && this.originalDocumentXmlText !== null) {
+                try {
+                    blocksRestored = restoreUntouchedBlocks(cloned, this.originalDocumentXmlText);
+                }
+                catch {
+                    // Reconciliation is best-effort; the fully re-serialized DOM is
+                    // always a correct (if non-minimal) save.
+                    blocksRestored = 0;
+                }
+            }
             const cleanedXml = serializeXml(cloned);
             // Temporarily swap document.xml in the zip for output, then restore.
+            maybeCaptureEmittedDocumentXml(cleanedXml);
             this.zip.writeText('word/document.xml', cleanedXml);
             const buffer = await this.zip.toBuffer();
             this.zip.writeText('word/document.xml', xmlWithBookmarks);
-            return { buffer, bookmarksRemoved };
+            return { buffer, bookmarksRemoved, blocksRestored };
         }
         const buffer = await this.zip.toBuffer();
-        return { buffer, bookmarksRemoved: 0 };
+        return { buffer, bookmarksRemoved: 0, blocksRestored: 0 };
     }
 }
 //# sourceMappingURL=document.js.map