@usejunior/docx-core 0.20.1 → 0.21.2

package/dist/primitives/document.js

@@ -2,9 +2,10 @@ 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 { assertTransitionalWordprocessingML } from './conformance.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 { findParagraphByBookmarkId, insertParagraphBookmarks, cleanupInternalBookmarks, collectBookmarkReservation, getParagraphBookmarkId, insertSingleParagraphBookmark, } from './bookmarks.js';
+import { formatParagraphTextRange, getParagraphRuns, getParagraphText, replaceParagraphTextRange } from './text.js';
 import { allocateRevisionId, createRevisionContainer, } from './track-changes-emitter.js';
 import { buildNodesForDocumentView, collectViewParagraphs } from './document_view.js';
 import { serializeToMarkdown } from './serialize_markdown.js';
@@ -15,7 +16,7 @@ import { parseNumberingXml } from './numbering.js';
 import { getDirectParagraphNumbering, setDirectParagraphNumbering, } from './paragraph_numbering.js';
 import { getDocumentSections, insertSectionBreak, setSectionPageNumberStart, updateSectionProperties, } from './sections.js';
 import { findUniqueSubstringMatch } from './matching.js';
-import { parseDocumentRels } from './relationships.js';
+import { parseDocumentRels, relationshipPartPath } from './relationships.js';
 import { setParagraphSpacing, setTableCellPadding, setTableRowHeight, } from './layout.js';
 import { extractTables, } from './tables.js';
 import { mergeRuns } from './merge_runs.js';
@@ -24,13 +25,16 @@ 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 { enumerateSelectedHeaderFooterPartPaths, enumerateSelectedRevisionStoryPartPaths, } from './revision-parts.js';
 import { acceptChanges as acceptChangesImpl } from './accept_changes.js';
 import { rejectChanges as rejectChangesImpl } from './reject_changes.js';
 import { collectRevisionElements, resolveSelectedIds, detectAmbiguousOverlaps, selectedIdFilter, AmbiguousRevisionOverlapError, } from './accept_ai_edits.js';
 import { revisionElementId } from './accept_changes.js';
 import { TRACKED_CHANGE_ELEMENT_NAME_SET } from './revision-vocabulary.js';
-import { bootstrapCommentParts, addComment as addCommentImpl, addCommentReply as addCommentReplyImpl, getComments as getCommentsImpl, getComment as getCommentImpl, deleteComment as deleteCommentImpl, } from './comments.js';
+import { insertTableRow as insertTableRowImpl, deleteTableRow as deleteTableRowImpl, removeOrphanedRangeEndpointsForSubtree, } from './table_rows.js';
+import { insertTableColumn as insertTableColumnImpl, deleteTableColumn as deleteTableColumnImpl, } from './table_columns.js';
+import { splitTableCell as splitTableCellImpl, absorbTableCell as absorbTableCellImpl, } from './table_cells.js';
+import { bootstrapCommentParts, addComment as addCommentImpl, addCommentReply as addCommentReplyImpl, getComments as getCommentsImpl, getComment as getCommentImpl, deleteComment as deleteCommentImpl, updateCommentBody as updateCommentBodyImpl, } 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 {
@@ -154,6 +158,74 @@ function nextElementSibling(node) {
     }
     return null;
 }
+function nearestWordAncestor(element, localName) {
+    for (let current = element.parentElement; current; current = current.parentElement) {
+        if (isW(current, localName))
+            return current;
+    }
+    return null;
+}
+/**
+ * Classify the physical table-cell constraints around a story paragraph.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.4.66
+ * @conformance ECMA-376 edition 5, Part 1 § 17.4.84
+ * @see https://github.com/UseJunior/safe-docx/issues/998
+ */
+function storyParagraphTableContext(paragraph) {
+    const cell = nearestWordAncestor(paragraph, W.tc);
+    if (!cell) {
+        return {
+            inTableCell: false,
+            verticalMergeContinuation: false,
+            directCellParagraphs: 0,
+            isTrailingDirectCellParagraph: false,
+        };
+    }
+    const directParagraphs = getDirectChildrenByName(cell, W.p);
+    const cellProperties = getDirectChildrenByName(cell, W.tcPr)[0];
+    const verticalMerge = cellProperties
+        ? getDirectChildrenByName(cellProperties, 'vMerge')[0]
+        : undefined;
+    const mergeValue = verticalMerge?.getAttributeNS(OOXML.W_NS, 'val')
+        ?? verticalMerge?.getAttribute('w:val')
+        ?? verticalMerge?.getAttribute('val');
+    return {
+        inTableCell: true,
+        verticalMergeContinuation: Boolean(verticalMerge && (!mergeValue || mergeValue === 'continue')),
+        directCellParagraphs: directParagraphs.length,
+        isTrailingDirectCellParagraph: directParagraphs.at(-1) === paragraph,
+    };
+}
+function assertStoryParagraphMutationSafe(paragraph, operation, styleSource) {
+    const parent = paragraph.parentElement;
+    const root = paragraph.ownerDocument.documentElement;
+    const cell = nearestWordAncestor(paragraph, W.tc);
+    if (parent !== root && parent !== cell) {
+        throw new Error('Story paragraph must be a direct child of the story root or table cell');
+    }
+    const context = storyParagraphTableContext(paragraph);
+    if (context.verticalMergeContinuation) {
+        throw new Error('Story paragraph mutation in a vertical-merge continuation cell is unsupported');
+    }
+    const table = cell ? nearestWordAncestor(cell, W.tbl) : null;
+    if (table && nearestWordAncestor(table, W.tc)) {
+        throw new Error('Story paragraph mutation inside a nested table is unsupported');
+    }
+    if (operation === 'insert' && styleSource) {
+        const styleCell = nearestWordAncestor(styleSource, W.tc);
+        if (styleCell !== cell)
+            throw new Error('Story paragraph style source must be in the anchor table cell');
+    }
+    if (operation !== 'delete' || !cell)
+        return;
+    const remainingBlocks = Array.from(cell.childNodes).filter((child) => child.nodeType === 1
+        && child !== paragraph
+        && ['p', 'tbl', 'sdt', 'customXml', 'altChunk'].includes(child.localName));
+    if (remainingBlocks.at(-1)?.localName !== W.p) {
+        throw new Error('Story paragraph deletion would leave a table cell without a trailing paragraph');
+    }
+}
 function collectNamedBookmarkIds(doc) {
     const ids = new Set();
     const starts = doc.getElementsByTagNameNS(OOXML.W_NS, W.bookmarkStart);
@@ -176,6 +248,7 @@ export class DocxDocument {
     relsMap;
     dirty;
     documentViewCache;
+    paragraphBookmarkReservation;
     /**
      * Raw document.xml text as loaded, before normalize()/edits mutate the DOM.
      * Reference for minimal re-serialization in toBuffer(); null for instances
@@ -192,12 +265,16 @@ export class DocxDocument {
         this.relsMap = relsMap;
         this.dirty = false;
         this.documentViewCache = null;
+        this.paragraphBookmarkReservation = undefined;
         this.originalDocumentXmlText = originalDocumentXmlText;
     }
     static async load(buffer) {
         const zip = await DocxZip.load(buffer);
         const xml = await zip.readText('word/document.xml');
         const doc = parseXml(xml);
+        // Refuse WML Strict packages here, before any Transitional-only lookup
+        // could read them as empty (#1025).
+        assertTransitionalWordprocessingML(doc);
         // Optional parts used for fidelity: list labels + style fingerprints.
         const stylesText = await zip.readTextOrNull('word/styles.xml');
         const themeText = await zip.readTextOrNull('word/theme/theme1.xml');
@@ -211,7 +288,15 @@ 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, themeXml, numberingXml, footnotesXml, relsMap, xml);
+        const document = new DocxDocument(zip, doc, stylesXml, themeXml, numberingXml, footnotesXml, relsMap, xml);
+        const storyDocuments = [];
+        for (const partPath of await enumerateSelectedHeaderFooterPartPaths(zip)) {
+            const storyXml = await zip.readTextOrNull(partPath);
+            if (storyXml)
+                storyDocuments.push(parseXml(storyXml));
+        }
+        document.paragraphBookmarkReservation = collectBookmarkReservation([doc, ...storyDocuments]);
+        return document;
     }
     getParagraphs() {
         const body = this.documentXml.getElementsByTagNameNS(OOXML.W_NS, W.body).item(0);
@@ -228,8 +313,184 @@ export class DocxDocument {
             return null;
         return getParagraphText(p);
     }
+    async selectedStoryDocument(partPath) {
+        const selected = await enumerateSelectedHeaderFooterPartPaths(this.zip);
+        if (!selected.includes(partPath)) {
+            throw new Error(`Header/footer story is not selected by a section relationship: ${partPath}`);
+        }
+        const xml = await this.zip.readTextOrNull(partPath);
+        if (!xml)
+            throw new Error(`Selected header/footer story part is missing: ${partPath}`);
+        return parseXml(xml);
+    }
+    withTemporaryDocumentXml(story, mutation, bookmarkReservation) {
+        const bodyDocument = this.documentXml;
+        const dirty = this.dirty;
+        const viewCache = this.documentViewCache;
+        const previousReservation = this.paragraphBookmarkReservation;
+        this.documentXml = story;
+        this.paragraphBookmarkReservation = bookmarkReservation;
+        try {
+            return mutation();
+        }
+        finally {
+            this.documentXml = bodyDocument;
+            this.dirty = dirty;
+            this.documentViewCache = viewCache;
+            this.paragraphBookmarkReservation = previousReservation;
+        }
+    }
+    async getStoryParagraphTextById(partPath, bookmarkId) {
+        const story = await this.selectedStoryDocument(partPath);
+        const paragraph = findParagraphByBookmarkId(story, bookmarkId);
+        return paragraph ? getParagraphText(paragraph) : null;
+    }
+    async getStoryParagraphById(partPath, bookmarkId) {
+        const text = await this.getStoryParagraphTextById(partPath, bookmarkId);
+        return text === null ? null : { id: bookmarkId, text };
+    }
+    async insertStoryParagraphBookmarks(partPath, attachmentId) {
+        const story = await this.selectedStoryDocument(partPath);
+        const reservation = this.paragraphBookmarkReservation;
+        const result = insertParagraphBookmarks(story, attachmentId, reservation);
+        if (result.indexedParagraphs > 0)
+            this.zip.writeText(partPath, serializeXml(story));
+        return { paragraphCount: result.indexedParagraphs };
+    }
+    async validateStoryParagraphTableCell(partPath, bookmarkId) {
+        const story = await this.selectedStoryDocument(partPath);
+        const paragraph = findParagraphByBookmarkId(story, bookmarkId);
+        if (!paragraph)
+            throw new Error(`Paragraph not found in ${partPath}: ${bookmarkId}`);
+        return storyParagraphTableContext(paragraph);
+    }
+    /** Mutate intended-clean story text; comparison is responsible for tracked output. */
+    async replaceStoryTextAtRange(params) {
+        const story = await this.selectedStoryDocument(params.partPath);
+        const paragraph = findParagraphByBookmarkId(story, params.targetParagraphId);
+        if (!paragraph)
+            throw new Error(`Paragraph not found in ${params.partPath}: ${params.targetParagraphId}`);
+        assertStoryParagraphMutationSafe(paragraph, 'replace');
+        replaceParagraphTextRange(paragraph, params.start, params.end, params.replaceText);
+        this.zip.writeText(params.partPath, serializeXml(story));
+    }
+    /** Mutate intended-clean story text; comparison is responsible for tracked output. */
+    async replaceStoryText(params) {
+        const story = await this.selectedStoryDocument(params.partPath);
+        const paragraph = findParagraphByBookmarkId(story, params.targetParagraphId);
+        if (!paragraph)
+            throw new Error(`Paragraph not found in ${params.partPath}: ${params.targetParagraphId}`);
+        assertStoryParagraphMutationSafe(paragraph, 'replace');
+        const match = findUniqueSubstringMatch(getParagraphText(paragraph), params.findText);
+        if (match.status === 'not_found') {
+            throw new Error(`Text not found in paragraph ${params.targetParagraphId}`);
+        }
+        if (match.status === 'multiple') {
+            throw new Error(`Multiple matches (${match.matchCount}) found in paragraph ${params.targetParagraphId} using ${match.mode} matching`);
+        }
+        replaceParagraphTextRange(paragraph, match.start, match.end, params.replaceText);
+        this.zip.writeText(params.partPath, serializeXml(story));
+    }
+    /**
+     * Apply a bounded run-format edit in one selected physical story paragraph.
+     *
+     * @conformance ECMA-376 edition 5, Part 1 § 17.3.2.28
+     * @see #1034
+     */
+    async formatStoryTextAtRange(params) {
+        const story = await this.selectedStoryDocument(params.partPath);
+        const paragraph = findParagraphByBookmarkId(story, params.targetParagraphId);
+        if (!paragraph)
+            throw new Error(`Paragraph not found in ${params.partPath}: ${params.targetParagraphId}`);
+        assertStoryParagraphMutationSafe(paragraph, 'replace');
+        formatParagraphTextRange(paragraph, params.start, params.end, params.format);
+        this.zip.writeText(params.partPath, serializeXml(story));
+    }
+    async insertStoryParagraph(params, ctx) {
+        const story = await this.selectedStoryDocument(params.partPath);
+        const anchor = findParagraphByBookmarkId(story, params.positionalAnchorNodeId);
+        if (!anchor)
+            throw new Error(`Anchor paragraph not found in ${params.partPath}: ${params.positionalAnchorNodeId}`);
+        const styleSource = params.styleSourceId
+            ? findParagraphByBookmarkId(story, params.styleSourceId)
+            : anchor;
+        if (params.styleSourceId && !styleSource) {
+            throw new Error(`Style source paragraph not found in ${params.partPath}: ${params.styleSourceId}`);
+        }
+        assertStoryParagraphMutationSafe(anchor, 'insert', styleSource ?? undefined);
+        const bookmarkReservation = this.paragraphBookmarkReservation;
+        const result = this.withTemporaryDocumentXml(story, () => this.insertParagraph({
+            positionalAnchorNodeId: params.positionalAnchorNodeId,
+            relativePosition: params.relativePosition,
+            newText: params.newText,
+            styleSourceId: params.styleSourceId,
+            runStyleSourceText: params.runStyleSourceText,
+        }, ctx), bookmarkReservation);
+        this.zip.writeText(params.partPath, serializeXml(story));
+        return result;
+    }
+    /** Remove an intended-clean story paragraph; comparison is responsible for tracked output. */
+    async deleteStoryParagraph(partPath, paragraphId) {
+        const story = await this.selectedStoryDocument(partPath);
+        const paragraph = findParagraphByBookmarkId(story, paragraphId);
+        if (!paragraph)
+            throw new Error(`Paragraph not found in ${partPath}: ${paragraphId}`);
+        assertStoryParagraphMutationSafe(paragraph, 'delete');
+        const bookmarkStart = Array.from(story.getElementsByTagNameNS(OOXML.W_NS, W.bookmarkStart))
+            .find((start) => (start.getAttributeNS(OOXML.W_NS, 'name') ?? start.getAttribute('w:name')) === paragraphId);
+        const bookmarkNumericId = bookmarkStart?.getAttributeNS(OOXML.W_NS, 'id')
+            ?? bookmarkStart?.getAttribute('w:id');
+        const bookmarkEnd = bookmarkNumericId
+            ? Array.from(story.getElementsByTagNameNS(OOXML.W_NS, W.bookmarkEnd)).find((end) => (end.getAttributeNS(OOXML.W_NS, 'id') ?? end.getAttribute('w:id')) === bookmarkNumericId)
+            : undefined;
+        removeOrphanedRangeEndpointsForSubtree(story.documentElement, paragraph);
+        paragraph.parentNode?.removeChild(paragraph);
+        bookmarkStart?.parentNode?.removeChild(bookmarkStart);
+        bookmarkEnd?.parentNode?.removeChild(bookmarkEnd);
+        this.zip.writeText(partPath, serializeXml(story));
+    }
+    insertTableRow(params, ctx) {
+        const result = insertTableRowImpl(this.documentXml, params, ctx, this.paragraphBookmarkReservation);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
+    deleteTableRow(params, ctx) {
+        const result = deleteTableRowImpl(this.documentXml, params, ctx);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
+    /** Apply a planned clean column edit to the existing DOM, preserving held element references. */
+    insertTableColumn(params, ctx) {
+        const result = insertTableColumnImpl(this.documentXml, params, ctx, this.paragraphBookmarkReservation);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
+    /** Apply a planned clean column deletion to the existing DOM. */
+    deleteTableColumn(params, ctx) {
+        const result = deleteTableColumnImpl(this.documentXml, params, ctx);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
+    /** Split one horizontal-spanning physical cell, preserving its authored content on the chosen side. */
+    splitTableCell(params, ctx) {
+        const result = splitTableCellImpl(this.documentXml, params, ctx, this.paragraphBookmarkReservation);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
+    /** Remove a physical cell and discard its content while an adjacent sibling absorbs its span. */
+    absorbTableCell(params, ctx) {
+        const result = absorbTableCellImpl(this.documentXml, params, ctx);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
     insertParagraphBookmarks(attachmentId) {
-        const res = insertParagraphBookmarks(this.documentXml, attachmentId);
+        const res = insertParagraphBookmarks(this.documentXml, attachmentId, this.paragraphBookmarkReservation);
         if (res.indexedParagraphs > 0)
             this.dirty = true;
         return { paragraphCount: res.indexedParagraphs };
@@ -270,7 +531,7 @@ export class DocxDocument {
     }
     async validateAiRevisions(aiAuthor, touched) {
         const stories = [{ part: 'word/document.xml', doc: this.documentXml }];
-        for (const partPath of enumerateRevisionStoryPartPaths(this.zip)) {
+        for (const partPath of await enumerateSelectedRevisionStoryPartPaths(this.zip)) {
             const xml = await this.zip.readTextOrNull(partPath);
             if (!xml)
                 continue;
@@ -298,7 +559,7 @@ export class DocxDocument {
         const liveFootnoteRefIds = bodyResult.deletionsAccepted > 0
             ? collectLiveFootnoteRefIds(this.documentXml)
             : null;
-        for (const partPath of REVISION_STORY_PART_PATHS) {
+        for (const partPath of await enumerateSelectedRevisionStoryPartPaths(this.zip)) {
             const xml = await this.zip.readTextOrNull(partPath);
             if (!xml)
                 continue;
@@ -336,7 +597,7 @@ export class DocxDocument {
         const liveFootnoteRefIds = bodyResult.insertionsRemoved > 0
             ? collectLiveFootnoteRefIds(this.documentXml)
             : null;
-        for (const partPath of REVISION_STORY_PART_PATHS) {
+        for (const partPath of await enumerateSelectedRevisionStoryPartPaths(this.zip)) {
             const xml = await this.zip.readTextOrNull(partPath);
             if (!xml)
                 continue;
@@ -370,7 +631,7 @@ export class DocxDocument {
         const stories = [
             { path: null, doc: this.documentXml },
         ];
-        for (const partPath of REVISION_STORY_PART_PATHS) {
+        for (const partPath of await enumerateSelectedRevisionStoryPartPaths(this.zip)) {
             const xml = await this.zip.readTextOrNull(partPath);
             if (xml)
                 stories.push({ path: partPath, doc: parseXml(xml) });
@@ -564,6 +825,14 @@ export class DocxDocument {
         this.dirty = true;
         this.documentViewCache = null;
     }
+    formatTextAtRange(params) {
+        const paragraph = findParagraphByBookmarkId(this.documentXml, params.targetParagraphId);
+        if (!paragraph)
+            throw new Error(`Paragraph not found: ${params.targetParagraphId}`);
+        formatParagraphTextRange(paragraph, params.start, params.end, params.format);
+        this.dirty = true;
+        this.documentViewCache = null;
+    }
     insertParagraph(params, ctx) {
         const { positionalAnchorNodeId, relativePosition, newText, newParagraphId: _newParagraphId, styleSourceId, runStyleSourceText } = params;
         const anchor = findParagraphByBookmarkId(this.documentXml, positionalAnchorNodeId);
@@ -794,7 +1063,7 @@ export class DocxDocument {
                 newP.appendChild(newRun);
             }
             parent.insertBefore(newP, cursor);
-            const id = insertSingleParagraphBookmark(doc, newP);
+            const id = insertSingleParagraphBookmark(doc, newP, this.paragraphBookmarkReservation);
             insertedIds.push(id);
             if (relativePosition === 'AFTER') {
                 const endEl = nextElementSibling(newP);
@@ -834,7 +1103,7 @@ export class DocxDocument {
         return getDocumentSections(this.documentXml);
     }
     insertSectionBreak(mutation, ctx) {
-        const result = insertSectionBreak(this.documentXml, mutation, ctx);
+        const result = insertSectionBreak(this.documentXml, mutation, ctx, this.paragraphBookmarkReservation);
         this.dirty = true;
         this.documentViewCache = null;
         return result;
@@ -910,6 +1179,8 @@ export class DocxDocument {
             author: params.author,
             text: params.text,
             initials: params.initials,
+            body: params.body,
+            date: params.date,
         }, ctx);
         this.dirty = true;
         this.documentViewCache = null;
@@ -928,13 +1199,15 @@ export class DocxDocument {
             author: params.author,
             text: params.text,
             initials: params.initials,
+            body: params.body,
+            date: params.date,
         }, ctx);
         this.dirty = true;
         this.documentViewCache = null;
         return result;
     }
     async getComments() {
-        return getCommentsImpl(this.zip, this.documentXml);
+        return getCommentsImpl(this.zip, this.documentXml, this.getStylesModel(), parseThemeXml(this.themeXml));
     }
     async getComment(commentId) {
         return getCommentImpl(this.zip, this.documentXml, commentId);
@@ -944,6 +1217,10 @@ export class DocxDocument {
         this.dirty = true;
         this.documentViewCache = null;
     }
+    async updateCommentBody(params) {
+        await updateCommentBodyImpl(this.zip, params);
+        this.dirty = true;
+    }
     /**
      * Convert selected root Word comments to footnotes in document order.
      * The method preflights the complete selection before mutating the package;
@@ -994,21 +1271,17 @@ export class DocxDocument {
             const paragraph = findParagraphByBookmarkId(this.documentXml, comment.anchoredParagraphId);
             if (!paragraph)
                 throw new Error(`Comment ID ${comment.id} anchor was not found`);
-            let afterText;
             if (comment.endTextOffset !== undefined) {
                 const paragraphText = getParagraphText(paragraph);
                 if (comment.endTextOffset > paragraphText.length) {
                     throw new Error(`Comment ID ${comment.id} has an invalid visible-text range endpoint`);
                 }
-                afterText = paragraphText.slice(0, comment.endTextOffset);
-                if (!afterText)
-                    afterText = undefined;
             }
             const replyText = comment.replies.map((reply) => `\n${reply.author ? `${reply.author}: ` : ''}${reply.text}`).join('');
             return {
                 comment,
                 paragraph,
-                afterText,
+                visibleOffset: comment.endTextOffset,
                 text: `${comment.text}${replyText}`,
             };
         });
@@ -1021,7 +1294,7 @@ export class DocxDocument {
             // not the adjacent footnote run introduced here.
             const result = await addFootnoteImpl(this.documentXml, this.zip, {
                 paragraphEl: item.paragraph,
-                afterText: item.afterText,
+                visibleOffset: item.visibleOffset,
                 text: item.text,
                 presentation: options.presentation,
             });
@@ -1110,6 +1383,7 @@ export class DocxDocument {
         const result = await addFootnoteImpl(this.documentXml, this.zip, {
             paragraphEl: p,
             afterText: params.afterText,
+            visibleOffset: params.visibleOffset,
             text: params.text,
             presentation: params.presentation,
         }, ctx);
@@ -1154,6 +1428,20 @@ export class DocxDocument {
             return null;
         return parseXml(commentsText);
     }
+    /** Return a deep clone of footnotes.xml, or null when the part is absent. */
+    async getFootnotesXmlClone() {
+        const footnotesText = await this.zip.readTextOrNull('word/footnotes.xml');
+        if (!footnotesText)
+            return null;
+        return parseXml(footnotesText);
+    }
+    /** Return a source part's Relationships DOM, or null when it has none. */
+    async getPartRelationshipsXmlClone(sourcePartPath) {
+        const relationshipsText = await this.zip.readTextOrNull(relationshipPartPath(sourcePartPath));
+        if (!relationshipsText)
+            return null;
+        return parseXml(relationshipsText);
+    }
     /**
      * Serialize the document to a .docx buffer.
      *
@@ -1165,9 +1453,14 @@ export class DocxDocument {
      * Falls back to full re-serialization (blocksRestored: 0) when no original
      * text was captured or reconciliation fails.
      *
+     * With `fileDate`, every ZIP entry is written with that date instead of the
+     * wall clock, so the bytes depend only on the document's content.
+     *
      * @see https://github.com/UseJunior/safe-docx/issues/408
+     * @see https://github.com/UseJunior/safe-docx/issues/1110
      */
     async toBuffer(opts) {
+        const zipOptions = opts?.fileDate ? { fileDate: opts.fileDate } : undefined;
         // Always write the latest document.xml when saving.
         // Important: when cleanBookmarks=true (download), we must NOT mutate session state.
         const xmlWithBookmarks = serializeXml(this.documentXml);
@@ -1194,11 +1487,11 @@ export class DocxDocument {
             // 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();
+            const buffer = await this.zip.toBuffer(zipOptions);
             this.zip.writeText('word/document.xml', xmlWithBookmarks);
             return { buffer, bookmarksRemoved, blocksRestored };
         }
-        const buffer = await this.zip.toBuffer();
+        const buffer = await this.zip.toBuffer(zipOptions);
         return { buffer, bookmarksRemoved: 0, blocksRestored: 0 };
     }
     /**