open-agreements 0.7.7 → 0.8.0

package/node_modules/@usejunior/docx-core/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 { buildNodesForDocumentView } from './document_view.js';
+import { allocateRevisionId, createRevisionContainer, } from './track-changes-emitter.js';
+import { buildNodesForDocumentView, collectViewParagraphs } 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) {
@@ -34,191 +114,6 @@ function nextElementSibling(node) {
     }
     return null;
 }
-/**
- * Collect all w:tr descendants of a table element, descending through
- * w:ins/w:del/w:sdt wrappers but not into nested w:tbl elements.
- */
-function collectTableRows(tbl) {
-    const rows = [];
-    function walk(parent) {
-        for (let i = 0; i < parent.childNodes.length; i++) {
-            const child = parent.childNodes[i];
-            if (child.nodeType !== 1)
-                continue;
-            const el = child;
-            if (isW(el, W.tr)) {
-                rows.push(el);
-            }
-            else if (!isW(el, W.tbl)) {
-                walk(el);
-            }
-        }
-    }
-    walk(tbl);
-    return rows;
-}
-/**
- * Collect all w:tc descendants of a row element, descending through
- * w:ins/w:del/w:sdt wrappers but not into nested w:tr or w:tbl elements.
- */
-function collectRowCells(tr) {
-    const cells = [];
-    function walk(parent) {
-        for (let i = 0; i < parent.childNodes.length; i++) {
-            const child = parent.childNodes[i];
-            if (child.nodeType !== 1)
-                continue;
-            const el = child;
-            if (isW(el, W.tc)) {
-                cells.push(el);
-            }
-            else if (!isW(el, W.tr) && !isW(el, W.tbl)) {
-                walk(el);
-            }
-        }
-    }
-    walk(tr);
-    return cells;
-}
-/** Get the gridSpan value for a table cell (default 1). */
-function getCellGridSpan(tc) {
-    const tcPrList = getDirectChildrenByName(tc, W.tcPr);
-    if (tcPrList.length === 0)
-        return 1;
-    const gridSpanEls = getDirectChildrenByName(tcPrList[0], 'gridSpan');
-    if (gridSpanEls.length === 0)
-        return 1;
-    const val = gridSpanEls[0].getAttributeNS(OOXML.W_NS, W.val) ??
-        gridSpanEls[0].getAttribute('w:val') ??
-        gridSpanEls[0].getAttribute(W.val);
-    if (!val)
-        return 1;
-    const n = parseInt(val, 10);
-    return n > 0 ? n : 1;
-}
-/** Get visible text from a cell's direct paragraphs (excludes nested tables). */
-function getCellHeaderText(tc) {
-    const parts = [];
-    for (let i = 0; i < tc.childNodes.length; i++) {
-        const child = tc.childNodes[i];
-        if (child.nodeType === 1 && isW(child, W.p)) {
-            parts.push(getParagraphText(child).trim());
-        }
-    }
-    return parts.join(' ').trim();
-}
-/**
- * Build metadata map for body-level tables.
- * Only indexes direct w:tbl children of w:body (consistent with extractTables).
- */
-function buildTableMetaMap(body) {
-    const map = new Map();
-    const tables = getDirectChildrenByName(body, W.tbl);
-    for (let tableIndex = 0; tableIndex < tables.length; tableIndex++) {
-        const tbl = tables[tableIndex];
-        const rows = collectTableRows(tbl);
-        if (rows.length === 0)
-            continue;
-        // Compute max grid columns across all rows
-        let maxGridCols = 0;
-        for (const row of rows) {
-            const cells = collectRowCells(row);
-            let gridCols = 0;
-            for (const cell of cells) {
-                gridCols += getCellGridSpan(cell);
-            }
-            if (gridCols > maxGridCols)
-                maxGridCols = gridCols;
-        }
-        // Extract headers from row 0
-        const headerRow = rows[0];
-        const headerCells = collectRowCells(headerRow);
-        const headers = [];
-        for (const cell of headerCells) {
-            const span = getCellGridSpan(cell);
-            const text = getCellHeaderText(cell);
-            headers.push(text);
-            for (let s = 1; s < span; s++)
-                headers.push('');
-        }
-        while (headers.length < maxGridCols)
-            headers.push('');
-        if (headers.length > maxGridCols)
-            headers.length = maxGridCols;
-        map.set(tbl, {
-            tableIndex,
-            tableId: `_tbl_${tableIndex}`,
-            rows,
-            headers,
-            totalCols: maxGridCols,
-        });
-    }
-    return map;
-}
-/**
- * Derive table context for a paragraph by walking up the DOM.
- * Returns undefined if the paragraph is not inside a body-level table.
- */
-function deriveTableContext(p, tableMetaMap) {
-    let tc = null;
-    let tr = null;
-    let tbl = null;
-    let current = p.parentNode;
-    while (current && current.nodeType === 1) {
-        const el = current;
-        if (isW(el, W.body))
-            break;
-        if (isW(el, W.tc))
-            tc = el;
-        if (isW(el, W.tr))
-            tr = el;
-        if (isW(el, W.tbl)) {
-            if (tableMetaMap.has(el)) {
-                tbl = el;
-                break;
-            }
-            // Nested table: reset tc/tr, keep walking to find body-level table
-            tc = null;
-            tr = null;
-        }
-        current = el.parentNode;
-    }
-    if (!tbl || !tr || !tc)
-        return undefined;
-    const meta = tableMetaMap.get(tbl);
-    // Compute row_index
-    const rowIndex = meta.rows.indexOf(tr);
-    if (rowIndex < 0)
-        return undefined;
-    // Compute grid-aware col_index by summing gridSpan for preceding cells
-    const rowCells = collectRowCells(tr);
-    let gridCol = 0;
-    let cellFound = false;
-    for (const cell of rowCells) {
-        if (cell === tc) {
-            cellFound = true;
-            break;
-        }
-        gridCol += getCellGridSpan(cell);
-    }
-    if (!cellFound)
-        return undefined;
-    // Compute para_in_cell and cell_para_count
-    const allCellPs = Array.from(tc.getElementsByTagNameNS(OOXML.W_NS, W.p));
-    const paraInCell = allCellPs.indexOf(p);
-    return {
-        table_id: meta.tableId,
-        table_index: meta.tableIndex,
-        row_index: rowIndex,
-        col_index: gridCol,
-        col_header: meta.headers[gridCol] ?? '',
-        total_rows: meta.rows.length,
-        total_cols: meta.totalCols,
-        is_header_row: rowIndex === 0,
-        para_in_cell: paraInCell >= 0 ? paraInCell : 0,
-        cell_para_count: allCellPs.length,
-    };
-}
 export class DocxDocument {
     zip;
     documentXml;
@@ -228,7 +123,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 +138,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 +155,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 +212,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 +338,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;
@@ -368,18 +363,9 @@ export class DocxDocument {
         if (!this.dirty && cached && cached.includeSemanticTags === includeSemanticTags && cached.showFormatting === showFormatting && cached.formattingMode === formattingMode) {
             return { nodes: cached.nodes, styles: cached.styles };
         }
-        // Pre-pass: build metadata for body-level tables
-        const body = this.documentXml.getElementsByTagNameNS(OOXML.W_NS, W.body).item(0);
-        const tableMetaMap = body ? buildTableMetaMap(body) : new Map();
-        const paragraphs = this.getParagraphs()
-            .map((p) => {
-            const id = getParagraphBookmarkId(p);
-            if (!id)
-                return null;
-            const tableContext = deriveTableContext(p, tableMetaMap);
-            return tableContext ? { id, p, tableContext } : { id, p };
-        })
-            .filter((x) => x !== null);
+        // Shared paragraph-collection core (also used by the free buildDocumentView):
+        // attaches each bookmarked paragraph's table context.
+        const paragraphs = collectViewParagraphs(this.documentXml);
         const { nodes, styles } = buildNodesForDocumentView({
             paragraphs,
             stylesXml: this.stylesXml,
@@ -425,7 +411,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 +491,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 +602,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 +631,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 +665,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 +682,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 +694,7 @@ export class DocxDocument {
             author: params.author,
             text: params.text,
             initials: params.initials,
-        });
+        }, ctx);
         this.dirty = true;
         this.documentViewCache = null;
         return result;
@@ -629,14 +705,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 +723,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 +736,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 +786,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 +795,7 @@ export class DocxDocument {
             paragraphEl: p,
             afterText: params.afterText,
             text: params.text,
-        });
+        }, ctx);
         await this.refreshFootnotesXml();
         this.dirty = true;
         this.documentViewCache = null;
@@ -687,8 +804,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 +813,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 +837,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