@usejunior/docx-core 0.19.1 → 0.21.2

package/dist/primitives/document.js

@@ -2,18 +2,21 @@ 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';
 import { serializeToHtml } from './serialize_html.js';
 import { serializeToPlainText } from './serialize_plaintext.js';
-import { parseStylesXml } from './styles.js';
+import { parseStylesXml, parseThemeXml } from './styles.js';
 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';
@@ -22,16 +25,25 @@ 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 { insertionsAccepted: 0, deletionsAccepted: 0, movesResolved: 0, propertyChangesResolved: 0 };
+    return {
+        insertionsAccepted: 0,
+        deletionsAccepted: 0,
+        movesResolved: 0,
+        propertyChangesResolved: 0,
+        unresolvedRowRevisions: 0,
+    };
 }
 function hasAcceptedChanges(result) {
     return (result.insertionsAccepted > 0 ||
@@ -44,9 +56,16 @@ function addAcceptChangesResult(total, result) {
     total.deletionsAccepted += result.deletionsAccepted;
     total.movesResolved += result.movesResolved;
     total.propertyChangesResolved += result.propertyChangesResolved;
+    total.unresolvedRowRevisions += result.unresolvedRowRevisions;
 }
 function emptyRejectChangesResult() {
-    return { insertionsRemoved: 0, deletionsRestored: 0, movesReverted: 0, propertyChangesReverted: 0 };
+    return {
+        insertionsRemoved: 0,
+        deletionsRestored: 0,
+        movesReverted: 0,
+        propertyChangesReverted: 0,
+        unresolvedRowRevisions: 0,
+    };
 }
 function hasRejectedChanges(result) {
     return (result.insertionsRemoved > 0 ||
@@ -59,6 +78,7 @@ function addRejectChangesResult(total, result) {
     total.deletionsRestored += result.deletionsRestored;
     total.movesReverted += result.movesReverted;
     total.propertyChangesReverted += result.propertyChangesReverted;
+    total.unresolvedRowRevisions += result.unresolvedRowRevisions;
 }
 function parseWId(el) {
     const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
@@ -138,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);
@@ -154,36 +242,45 @@ export class DocxDocument {
     zip;
     documentXml;
     stylesXml;
+    themeXml;
     numberingXml;
     footnotesXml;
     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
      * not created via load().
      */
     originalDocumentXmlText;
-    constructor(zip, documentXml, stylesXml, numberingXml, footnotesXml, relsMap, originalDocumentXmlText = null) {
+    constructor(zip, documentXml, stylesXml, themeXml, numberingXml, footnotesXml, relsMap, originalDocumentXmlText = null) {
         this.zip = zip;
         this.documentXml = documentXml;
         this.stylesXml = stylesXml;
+        this.themeXml = themeXml;
         this.numberingXml = numberingXml;
         this.footnotesXml = footnotesXml;
         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');
         const numberingText = await zip.readTextOrNull('word/numbering.xml');
         const stylesXml = stylesText ? parseXml(stylesText) : null;
+        const themeXml = themeText ? parseXml(themeText) : null;
         const numberingXml = numberingText ? parseXml(numberingText) : null;
         // Load footnotes for [^N] marker rendering in document view.
         const footnotesText = await zip.readTextOrNull('word/footnotes.xml');
@@ -191,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, 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);
@@ -208,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 };
@@ -250,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;
@@ -278,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;
@@ -316,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;
@@ -350,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) });
@@ -501,6 +782,7 @@ export class DocxDocument {
         const { nodes, styles } = buildNodesForDocumentView({
             paragraphs,
             stylesXml: this.stylesXml,
+            themeXml: this.themeXml,
             numberingXml: this.numberingXml,
             include_semantic_tags: includeSemanticTags,
             show_formatting: showFormatting,
@@ -543,8 +825,16 @@ 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 } = params;
+        const { positionalAnchorNodeId, relativePosition, newText, newParagraphId: _newParagraphId, styleSourceId, runStyleSourceText } = params;
         const anchor = findParagraphByBookmarkId(this.documentXml, positionalAnchorNodeId);
         if (!anchor)
             throw new Error(`Anchor paragraph not found: ${positionalAnchorNodeId}`);
@@ -713,14 +1003,41 @@ export class DocxDocument {
                 return next.nextSibling;
             return anchorP.nextSibling;
         }
-        // Choose a run in the formatting source to use as formatting template: pick the run with the most visible text.
+        // Choose a run in the formatting source to use as formatting template. A
+        // caller may pin one unique visible source substring; legacy callers retain
+        // the predominant-run behavior.
         const sourceVisibleRuns = getParagraphRuns(formattingSource);
         let templateRun = null;
         let bestLen = -1;
-        for (const tr of sourceVisibleRuns) {
-            if (tr.text.length > bestLen) {
-                bestLen = tr.text.length;
-                templateRun = tr.r;
+        if (runStyleSourceText !== undefined) {
+            const sourceText = sourceVisibleRuns.map((run) => run.text).join('');
+            const start = sourceText.indexOf(runStyleSourceText);
+            if (!runStyleSourceText || start < 0 || sourceText.indexOf(runStyleSourceText, start + runStyleSourceText.length) >= 0) {
+                throw new Error('runStyleSourceText must identify one non-empty substring in the formatting source paragraph');
+            }
+            let offset = 0;
+            const selectedRuns = [];
+            for (const tr of sourceVisibleRuns) {
+                if (start < offset + tr.text.length && start + runStyleSourceText.length > offset) {
+                    selectedRuns.push(tr.r);
+                }
+                offset += tr.text.length;
+            }
+            const runPropertySignatures = new Set(selectedRuns.map((run) => {
+                const rPr = getDirectChildrenByName(run, W.rPr)[0];
+                return rPr?.toString() ?? '';
+            }));
+            if (selectedRuns.length === 0 || runPropertySignatures.size !== 1) {
+                throw new Error('runStyleSourceText must occupy one direct run-formatting class');
+            }
+            templateRun = selectedRuns[0];
+        }
+        else {
+            for (const tr of sourceVisibleRuns) {
+                if (tr.text.length > bestLen) {
+                    bestLen = tr.text.length;
+                    templateRun = tr.r;
+                }
             }
         }
         if (!templateRun) {
@@ -746,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);
@@ -771,6 +1088,42 @@ export class DocxDocument {
         }
         return result;
     }
+    getDirectParagraphNumbering(paragraphId) {
+        return getDirectParagraphNumbering(this.documentXml, paragraphId);
+    }
+    setDirectParagraphNumbering(mutation, ctx) {
+        const result = setDirectParagraphNumbering(this.documentXml, this.numberingXml, mutation, ctx);
+        if (result.changed) {
+            this.dirty = true;
+            this.documentViewCache = null;
+        }
+        return result;
+    }
+    getSections() {
+        return getDocumentSections(this.documentXml);
+    }
+    insertSectionBreak(mutation, ctx) {
+        const result = insertSectionBreak(this.documentXml, mutation, ctx, this.paragraphBookmarkReservation);
+        this.dirty = true;
+        this.documentViewCache = null;
+        return result;
+    }
+    setSectionPageNumberStart(mutation, ctx) {
+        const result = setSectionPageNumberStart(this.documentXml, mutation, ctx);
+        if (result.changed) {
+            this.dirty = true;
+            this.documentViewCache = null;
+        }
+        return result;
+    }
+    updateSectionProperties(mutation, ctx) {
+        const result = updateSectionProperties(this.documentXml, mutation, ctx);
+        if (result.changed) {
+            this.dirty = true;
+            this.documentViewCache = null;
+        }
+        return result;
+    }
     setTableRowHeight(mutation, ctx) {
         const result = setTableRowHeight(this.documentXml, mutation, ctx);
         if (result.affectedRows > 0) {
@@ -826,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;
@@ -844,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);
@@ -860,13 +1217,113 @@ 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;
+     * callers that need buffer-level atomicity should invoke it on a freshly
+     * loaded document and publish only the returned serialization.
+     *
+     * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.2
+     * @conformance ECMA-376 edition 5, Part 1 § 17.11.14
+     */
+    async convertCommentsToFootnotes(options = {}) {
+        const colors = [options.presentation?.prefixStyle?.color, options.presentation?.bodyStyle?.color];
+        for (const color of colors) {
+            if (color && !/^[0-9A-Fa-f]{6}$/.test(color)) {
+                throw new Error(`Invalid Word color '${color}'; expected six hexadecimal digits`);
+            }
+        }
+        const allowedHighlights = new Set([
+            'black', 'blue', 'cyan', 'green', 'magenta', 'red', 'yellow', 'white',
+            'darkBlue', 'darkCyan', 'darkGreen', 'darkMagenta', 'darkRed',
+            'darkYellow', 'darkGray', 'lightGray', 'none',
+        ]);
+        const highlights = [options.presentation?.prefixStyle?.highlight, options.presentation?.bodyStyle?.highlight];
+        for (const highlight of highlights) {
+            if (highlight && !allowedHighlights.has(highlight)) {
+                throw new Error(`Invalid Word highlight '${highlight}'`);
+            }
+        }
+        // Materialize stable paragraph bookmarks before comment-range extraction;
+        // source DOCX files are not required to carry Safe DOCX anchors already.
+        this.insertParagraphBookmarks('note-conversion');
+        const roots = await this.getComments();
+        const beforeFootnotes = (await this.getFootnotes()).length;
+        const requested = options.commentIds ? new Set(options.commentIds) : null;
+        const selected = requested ? roots.filter((comment) => requested.has(comment.id)) : roots;
+        if (requested) {
+            const found = new Set(selected.map((comment) => comment.id));
+            const missing = [...requested].filter((id) => !found.has(id));
+            if (missing.length)
+                throw new Error(`Root comment IDs not found: ${missing.join(', ')}`);
+        }
+        const prepared = selected.map((comment) => {
+            if (!comment.anchoredParagraphId || !comment.endParagraphId || comment.anchoredParagraphId !== comment.endParagraphId) {
+                throw new Error(`Comment ID ${comment.id} does not have one supported paragraph anchor`);
+            }
+            if (comment.replies.length && !options.flattenThreads) {
+                throw new Error(`Comment ID ${comment.id} has replies; pass flattenThreads to perform a lossy conversion`);
+            }
+            const paragraph = findParagraphByBookmarkId(this.documentXml, comment.anchoredParagraphId);
+            if (!paragraph)
+                throw new Error(`Comment ID ${comment.id} anchor was not found`);
+            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`);
+                }
+            }
+            const replyText = comment.replies.map((reply) => `\n${reply.author ? `${reply.author}: ` : ''}${reply.text}`).join('');
+            return {
+                comment,
+                paragraph,
+                visibleOffset: comment.endTextOffset,
+                text: `${comment.text}${replyText}`,
+            };
+        });
+        const converted = [];
+        if (prepared.length > 0)
+            await bootstrapFootnoteParts(this.zip);
+        for (const item of prepared) {
+            // Insert first while the preflighted comment markers still identify the
+            // source range. deleteComment removes only comment markers/references,
+            // not the adjacent footnote run introduced here.
+            const result = await addFootnoteImpl(this.documentXml, this.zip, {
+                paragraphEl: item.paragraph,
+                visibleOffset: item.visibleOffset,
+                text: item.text,
+                presentation: options.presentation,
+            });
+            await deleteCommentImpl(this.documentXml, this.zip, { commentId: item.comment.id });
+            converted.push({
+                commentId: item.comment.id,
+                footnoteId: result.noteId,
+                paragraphId: item.comment.anchoredParagraphId,
+                flattenedReplies: item.comment.replies.length,
+            });
+        }
+        await this.refreshFootnotesXml();
+        this.dirty = converted.length > 0;
+        this.documentViewCache = null;
+        return {
+            selected: selected.length,
+            converted,
+            before: { comments: roots.length, footnotes: beforeFootnotes },
+            after: { comments: (await this.getComments()).length, footnotes: (await this.getFootnotes()).length },
+            lossy: converted.some((entry) => entry.flattenedReplies > 0),
+        };
+    }
     // ── Footnote methods ──────────────────────────────────────────────────
     async refreshFootnotesXml() {
         const text = await this.zip.readTextOrNull('word/footnotes.xml');
         this.footnotesXml = text ? parseXml(text) : null;
     }
     async getFootnotes() {
-        return getFootnotesImpl(this.zip, this.documentXml, this.getStylesModel());
+        return getFootnotesImpl(this.zip, this.documentXml, this.getStylesModel(), parseThemeXml(this.themeXml));
     }
     /**
      * Serialize the document to GitHub-Flavored Markdown. Convenience wrapper that wires the
@@ -910,7 +1367,7 @@ export class DocxDocument {
         return serializeToPlainText(nodes, footnotes, opts);
     }
     async getFootnote(noteId) {
-        return getFootnoteImpl(this.zip, this.documentXml, noteId, this.getStylesModel());
+        return getFootnoteImpl(this.zip, this.documentXml, noteId, this.getStylesModel(), parseThemeXml(this.themeXml));
     }
     /**
      * Add a footnote anchored to a paragraph, optionally after specific text.
@@ -926,7 +1383,9 @@ 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);
         await this.refreshFootnotesXml();
         this.dirty = true;
@@ -969,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.
      *
@@ -980,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);
@@ -1009,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 };
     }
     /**