@usejunior/docx-core 0.9.1 → 0.11.0

package/dist/primitives/comments.js

@@ -6,8 +6,11 @@
  */
 import { OOXML, W } from './namespaces.js';
 import { parseXml, serializeXml } from './xml.js';
-import { getParagraphRuns, getParagraphText } from './text.js';
+import { getParagraphRuns, getParagraphText, splitRunAtVisibleOffset } from './text.js';
 import { getParagraphBookmarkId } from './bookmarks.js';
+import { childElements, getLeafText, isW } from './dom-helpers.js';
+import { getAttributeSafe } from './xml-helpers.js';
+import { createRevisionContainer, prepareElementForDeletion, } from './track-changes-emitter.js';
 // ── Relationship types ──────────────────────────────────────────────────
 const REL_TYPE_COMMENTS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments';
 const REL_TYPE_COMMENTS_EXTENDED = 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended';
@@ -16,6 +19,8 @@ const REL_TYPE_PEOPLE = 'http://schemas.microsoft.com/office/2011/relationships/
 const CT_COMMENTS = 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml';
 const CT_COMMENTS_EXTENDED = 'application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml';
 const CT_PEOPLE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml';
+// XML Namespaces namespace — used when binding/declaring prefixes via setAttributeNS.
+const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
 // ── Minimal XML templates ───────────────────────────────────────────────
 const COMMENTS_XML_TEMPLATE = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
     `<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"` +
@@ -150,20 +155,24 @@ async function ensureRelationships(zip, newParts) {
  * - Adds comment entry to comments.xml
  * - Adds author to people.xml if not present
  */
-export async function addComment(documentXml, zip, params) {
+export async function addComment(documentXml, zip, params, ctx) {
     const { paragraphEl, author, text, initials } = params;
+    const visibleLen = getParagraphText(paragraphEl).length;
     const start = params.start ?? 0;
-    const end = params.end ?? getParagraphText(paragraphEl).length;
+    const end = params.end ?? visibleLen;
     if (start > end) {
         throw new Error(`Invalid comment range: start (${start}) must be <= end (${end})`);
     }
+    if (start < 0 || end > visibleLen) {
+        throw new Error(`Invalid comment range: [${start}, ${end}) is outside paragraph visible text [0, ${visibleLen})`);
+    }
     // Load comments.xml
     const commentsXml = await zip.readText('word/comments.xml');
     const commentsDoc = parseXml(commentsXml);
     // Allocate next comment ID
     const commentId = allocateNextCommentId(commentsDoc);
     // Insert range markers and reference in document body
-    insertCommentMarkers(documentXml, paragraphEl, commentId, start, end);
+    insertCommentMarkers(documentXml, paragraphEl, commentId, start, end, ctx);
     // Add comment element to comments.xml
     const paraId = generateParaId();
     addCommentElement(commentsDoc, {
@@ -183,8 +192,11 @@ export async function addComment(documentXml, zip, params) {
  *
  * Replies don't have range markers in the document body.
  * Thread linkage is stored in commentsExtended.xml via paraIdParent.
+ * `ctx` is accepted for API consistency with other comment mutations, but this
+ * primitive only updates comment side parts for replies, so no body revision
+ * markup is emitted here.
  */
-export async function addCommentReply(_documentXml, zip, params) {
+export async function addCommentReply(_documentXml, zip, params, _ctx) {
     const { parentCommentId, author, text, initials } = params;
     // Load comments.xml
     const commentsXml = await zip.readText('word/comments.xml');
@@ -219,7 +231,7 @@ function allocateNextCommentId(commentsDoc) {
     let maxId = -1;
     for (let i = 0; i < commentEls.length; i++) {
         const el = commentEls.item(i);
-        const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         if (idStr) {
             const id = parseInt(idStr, 10);
             if (id > maxId)
@@ -232,19 +244,42 @@ function findCommentParaId(commentsDoc, commentId) {
     const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment);
     for (let i = 0; i < commentEls.length; i++) {
         const el = commentEls.item(i);
-        const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         if (idStr && parseInt(idStr, 10) === commentId) {
             // paraId is on the w:p child inside the comment
             const paras = el.getElementsByTagNameNS(OOXML.W_NS, W.p);
             if (paras.length > 0) {
                 const p = paras.item(0);
-                return p.getAttributeNS(OOXML.W14_NS, 'paraId') ?? p.getAttribute('w14:paraId') ?? null;
+                return getAttributeSafe(p, OOXML.W14_NS, 'paraId', 'w14', { bareFallback: false });
             }
         }
     }
     return null;
 }
+/**
+ * Ensure a comment-related document root binds the w14 and w15 prefixes before any
+ * w14:* / w15:* attribute is written into it. Real-world docx files often ship a
+ * pre-existing comments.xml (or commentsExtended.xml / people.xml) that omits one or
+ * both declarations; without a real namespace binding, xmldom would reject the
+ * round-tripped XML with `NamespaceError: prefix is non-null and namespace is null`.
+ *
+ * Uses `setAttributeNS(XMLNS_NS, …)` so the prefix is actually bound on the live DOM
+ * (not just serialized as a literal attribute) — that means subsequent `createElementNS`
+ * / `setAttributeNS` / `lookupNamespaceURI` calls on the same Document resolve correctly
+ * without depending on a serialize/reparse round trip. Idempotent — guards on the real
+ * binding via `lookupNamespaceURI`, not on a same-named plain attribute.
+ */
+function ensureCommentPartNamespaceAliases(commentsDoc) {
+    const root = commentsDoc.documentElement;
+    if (root.lookupNamespaceURI('w14') !== OOXML.W14_NS) {
+        root.setAttributeNS(XMLNS_NS, 'xmlns:w14', OOXML.W14_NS);
+    }
+    if (root.lookupNamespaceURI('w15') !== OOXML.W15_NS) {
+        root.setAttributeNS(XMLNS_NS, 'xmlns:w15', OOXML.W15_NS);
+    }
+}
 function addCommentElement(commentsDoc, params) {
+    ensureCommentPartNamespaceAliases(commentsDoc);
     const root = commentsDoc.documentElement;
     const commentEl = commentsDoc.createElementNS(OOXML.W_NS, 'w:comment');
     commentEl.setAttribute('w:id', String(params.id));
@@ -253,7 +288,9 @@ function addCommentElement(commentsDoc, params) {
     commentEl.setAttribute('w:initials', params.initials);
     // Comment body: <w:p w14:paraId="..."><w:pPr><w:pStyle w:val="CommentText"/></w:pPr><w:r><w:annotationRef/></w:r><w:r><w:t>text</w:t></w:r></w:p>
     const p = commentsDoc.createElementNS(OOXML.W_NS, 'w:p');
-    p.setAttribute('w14:paraId', params.paraId);
+    // Use setAttributeNS so the attribute carries a real namespace URI — otherwise xmldom
+    // serializes a prefix it cannot resolve and reparse throws NamespaceError (#154).
+    p.setAttributeNS(OOXML.W14_NS, 'w14:paraId', params.paraId);
     // Annotation reference run
     const refRun = commentsDoc.createElementNS(OOXML.W_NS, 'w:r');
     const annotRef = commentsDoc.createElementNS(OOXML.W_NS, 'w:annotationRef');
@@ -271,10 +308,8 @@ function addCommentElement(commentsDoc, params) {
     commentEl.appendChild(p);
     root.appendChild(commentEl);
 }
-function insertCommentMarkers(documentXml, paragraphEl, commentId, start, end) {
-    // Find the runs in the paragraph and map string offsets to DOM positions
+function insertCommentMarkers(documentXml, paragraphEl, commentId, start, end, ctx) {
     const runs = getParagraphRuns(paragraphEl);
-    // Create marker elements
     const rangeStart = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeStart');
     rangeStart.setAttribute('w:id', String(commentId));
     const rangeEnd = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeEnd');
@@ -288,93 +323,180 @@ function insertCommentMarkers(documentXml, paragraphEl, commentId, start, end) {
     const commentRef = documentXml.createElementNS(OOXML.W_NS, 'w:commentReference');
     commentRef.setAttribute('w:id', String(commentId));
     refRun.appendChild(commentRef);
-    // Map string offsets to run positions
+    const refAnchor = ctx ? createRevisionContainer(documentXml, 'ins', ctx) : refRun;
+    if (ctx) {
+        refAnchor.appendChild(refRun);
+    }
+    if (runs.length === 0) {
+        paragraphEl.appendChild(rangeStart);
+        paragraphEl.appendChild(rangeEnd);
+        paragraphEl.appendChild(refAnchor);
+        return;
+    }
+    const mapping = mapOffsetsToRuns(runs, start, end);
+    const { startRunIdx, startOffset, endRunIdx, endOffset } = mapping;
+    // Collapsed range (start === end): insert both markers at the same boundary.
+    // Splitting again here would create an empty <w:r> inside the marker pair —
+    // replaceParagraphTextRange() avoids this by deleting the temporary run, which
+    // we can't do for comments. Handle the boundary directly.
+    if (startRunIdx === endRunIdx && startOffset === endOffset) {
+        insertCollapsedRangeMarkers(runs[startRunIdx], startOffset, rangeStart, rangeEnd, refAnchor);
+        return;
+    }
+    // Split boundary runs at the exact visible-text offsets so the markers can sit
+    // on true sub-paragraph boundaries instead of being snapped to whole-run edges.
+    // Choreography mirrors replaceParagraphTextRange() in text.ts:404.
+    let startRunEl = runs[startRunIdx].r;
+    let endRunEl = runs[endRunIdx].r;
+    if (startRunIdx === endRunIdx) {
+        const runLen = runs[startRunIdx].text.length;
+        if (endOffset < runLen) {
+            const { left } = splitRunAtVisibleOffset(startRunEl, endOffset);
+            startRunEl = left;
+            endRunEl = left;
+        }
+        if (startOffset > 0) {
+            const { right } = splitRunAtVisibleOffset(startRunEl, startOffset);
+            startRunEl = right;
+            endRunEl = right;
+        }
+    }
+    else {
+        if (startOffset > 0) {
+            const { right } = splitRunAtVisibleOffset(startRunEl, startOffset);
+            startRunEl = right;
+        }
+        const endLen = runs[endRunIdx].text.length;
+        if (endOffset < endLen) {
+            const { left } = splitRunAtVisibleOffset(endRunEl, endOffset);
+            endRunEl = left;
+        }
+    }
+    // Insert relative to each run's parent so anchors inside w:hyperlink, w:ins,
+    // w:del, w:sdtContent, etc. keep the markers inside the wrapper.
+    const startParent = startRunEl.parentNode;
+    const endParent = endRunEl.parentNode;
+    if (!startParent || !endParent) {
+        throw new Error('Split run has no parent');
+    }
+    startParent.insertBefore(rangeStart, startRunEl);
+    endParent.insertBefore(rangeEnd, endRunEl.nextSibling);
+    endParent.insertBefore(refAnchor, rangeEnd.nextSibling);
+}
+function mapOffsetsToRuns(runs, start, end) {
+    // Map visible-text offsets to (runIndex, offsetInRun). Caller validates that
+    // 0 <= start <= end <= sum(runs[i].text.length).
     let pos = 0;
     let startRunIdx = -1;
     let endRunIdx = -1;
+    let startOffset = 0;
+    let endOffset = 0;
     for (let i = 0; i < runs.length; i++) {
-        const runEnd = pos + runs[i].text.length;
-        if (startRunIdx < 0 && start < runEnd)
+        const len = runs[i].text.length;
+        if (startRunIdx === -1 && start >= pos && start <= pos + len) {
             startRunIdx = i;
-        if (endRunIdx < 0 && end <= runEnd)
+            startOffset = start - pos;
+        }
+        if (endRunIdx === -1 && end >= pos && end <= pos + len) {
             endRunIdx = i;
-        pos = runEnd;
-    }
-    // Fallback: if offsets don't map cleanly, wrap the whole paragraph
-    if (startRunIdx < 0)
-        startRunIdx = 0;
-    if (endRunIdx < 0)
-        endRunIdx = runs.length - 1;
-    // Insert commentRangeStart before the start run
-    if (runs.length > 0 && startRunIdx < runs.length) {
-        paragraphEl.insertBefore(rangeStart, runs[startRunIdx].r);
-    }
-    else {
-        // No runs — insert at end of paragraph
-        paragraphEl.appendChild(rangeStart);
+            endOffset = end - pos;
+            break;
+        }
+        pos += len;
     }
-    // Insert commentRangeEnd and reference run after the end run
-    if (runs.length > 0 && endRunIdx < runs.length) {
-        const afterEndRun = runs[endRunIdx].r.nextSibling;
-        paragraphEl.insertBefore(rangeEnd, afterEndRun);
-        paragraphEl.insertBefore(refRun, afterEndRun);
-    }
-    else {
-        paragraphEl.appendChild(rangeEnd);
-        paragraphEl.appendChild(refRun);
+    if (startRunIdx === -1 || endRunIdx === -1) {
+        throw new Error(`Could not map offsets [${start}, ${end}) to runs`);
     }
+    return { startRunIdx, startOffset, endRunIdx, endOffset };
+}
+function insertCollapsedRangeMarkers(run, offsetInRun, rangeStart, rangeEnd, refAnchor) {
+    const runEl = run.r;
+    const parent = runEl.parentNode;
+    if (!parent)
+        throw new Error('Run has no parent');
+    const runLen = run.text.length;
+    if (offsetInRun === 0) {
+        // Insert before the run.
+        parent.insertBefore(rangeStart, runEl);
+        parent.insertBefore(rangeEnd, runEl);
+        parent.insertBefore(refAnchor, runEl);
+        return;
+    }
+    if (offsetInRun === runLen) {
+        // Insert after the run. Capture nextSibling once because insertBefore
+        // shifts it (rangeStart would otherwise land last instead of first).
+        const ref = runEl.nextSibling;
+        parent.insertBefore(rangeStart, ref);
+        parent.insertBefore(rangeEnd, ref);
+        parent.insertBefore(refAnchor, ref);
+        return;
+    }
+    // Mid-run: split once so the markers sit between the two halves.
+    const { right } = splitRunAtVisibleOffset(runEl, offsetInRun);
+    parent.insertBefore(rangeStart, right);
+    parent.insertBefore(rangeEnd, right);
+    parent.insertBefore(refAnchor, right);
 }
 async function linkReplyInCommentsExtended(zip, replyParaId, parentParaId) {
     const extXml = await zip.readText('word/commentsExtended.xml');
     const extDoc = parseXml(extXml);
+    ensureCommentPartNamespaceAliases(extDoc);
     const root = extDoc.documentElement;
     const exEl = extDoc.createElementNS(OOXML.W15_NS, 'w15:commentEx');
-    exEl.setAttribute('w15:paraId', replyParaId);
-    exEl.setAttribute('w15:paraIdParent', parentParaId);
-    exEl.setAttribute('w15:done', '0');
+    exEl.setAttributeNS(OOXML.W15_NS, 'w15:paraId', replyParaId);
+    exEl.setAttributeNS(OOXML.W15_NS, 'w15:paraIdParent', parentParaId);
+    exEl.setAttributeNS(OOXML.W15_NS, 'w15:done', '0');
     root.appendChild(exEl);
     zip.writeText('word/commentsExtended.xml', serializeXml(extDoc));
 }
 async function ensureCommentExEntry(zip, paraId) {
     const extXml = await zip.readText('word/commentsExtended.xml');
     const extDoc = parseXml(extXml);
+    ensureCommentPartNamespaceAliases(extDoc);
     const root = extDoc.documentElement;
     // Check if entry already exists
     const existing = root.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx');
     for (let i = 0; i < existing.length; i++) {
         const el = existing.item(i);
-        const pid = el.getAttributeNS(OOXML.W15_NS, 'paraId') ?? el.getAttribute('w15:paraId');
+        const pid = getAttributeSafe(el, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false });
         if (pid === paraId)
             return; // Already present
     }
     const exEl = extDoc.createElementNS(OOXML.W15_NS, 'w15:commentEx');
-    exEl.setAttribute('w15:paraId', paraId);
-    exEl.setAttribute('w15:done', '0');
+    exEl.setAttributeNS(OOXML.W15_NS, 'w15:paraId', paraId);
+    exEl.setAttributeNS(OOXML.W15_NS, 'w15:done', '0');
     root.appendChild(exEl);
     zip.writeText('word/commentsExtended.xml', serializeXml(extDoc));
 }
 async function ensureAuthorInPeople(zip, author) {
     const peopleXml = await zip.readText('word/people.xml');
     const peopleDoc = parseXml(peopleXml);
+    ensureCommentPartNamespaceAliases(peopleDoc);
     const root = peopleDoc.documentElement;
     // Check if author already exists
     const persons = root.getElementsByTagNameNS(OOXML.W15_NS, 'person');
     for (let i = 0; i < persons.length; i++) {
         const el = persons.item(i);
-        const name = el.getAttributeNS(OOXML.W15_NS, 'author') ?? el.getAttribute('w15:author');
+        const name = getAttributeSafe(el, OOXML.W15_NS, 'author', 'w15', { bareFallback: false });
         if (name === author)
             return; // Already present
     }
     const personEl = peopleDoc.createElementNS(OOXML.W15_NS, 'w15:person');
-    personEl.setAttribute('w15:author', author);
+    personEl.setAttributeNS(OOXML.W15_NS, 'w15:author', author);
     // Add a presenceInfo child (required by Word)
     const presenceInfo = peopleDoc.createElementNS(OOXML.W15_NS, 'w15:presenceInfo');
-    presenceInfo.setAttribute('w15:providerId', 'None');
-    presenceInfo.setAttribute('w15:userId', author);
+    presenceInfo.setAttributeNS(OOXML.W15_NS, 'w15:providerId', 'None');
+    presenceInfo.setAttributeNS(OOXML.W15_NS, 'w15:userId', author);
     personEl.appendChild(presenceInfo);
     root.appendChild(personEl);
     zip.writeText('word/people.xml', serializeXml(peopleDoc));
 }
+var FieldState;
+(function (FieldState) {
+    FieldState[FieldState["OUTSIDE_FIELD"] = 0] = "OUTSIDE_FIELD";
+    FieldState[FieldState["IN_FIELD_CODE"] = 1] = "IN_FIELD_CODE";
+    FieldState[FieldState["IN_FIELD_RESULT"] = 2] = "IN_FIELD_RESULT";
+})(FieldState || (FieldState = {}));
 /**
  * Read all comments from a document, building a threaded tree.
  *
@@ -390,27 +512,30 @@ export async function getComments(zip, documentXml) {
     const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment);
     if (commentEls.length === 0)
         return [];
+    const rangeMetadata = resolveCommentRangeMetadata(documentXml);
     // Build a map of commentId → { paraId, Comment }
     const byParaId = new Map();
     const byId = new Map();
     for (let i = 0; i < commentEls.length; i++) {
         const el = commentEls.item(i);
-        const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         const id = idStr ? parseInt(idStr, 10) : -1;
         if (id < 0)
             continue;
-        const author = el.getAttributeNS(OOXML.W_NS, 'author') ?? el.getAttribute('w:author') ?? '';
-        const date = el.getAttributeNS(OOXML.W_NS, 'date') ?? el.getAttribute('w:date') ?? '';
-        const initials = el.getAttributeNS(OOXML.W_NS, 'initials') ?? el.getAttribute('w:initials') ?? '';
+        const author = getAttributeSafe(el, OOXML.W_NS, 'author', 'w', { bareFallback: false }) ?? '';
+        const date = getAttributeSafe(el, OOXML.W_NS, 'date', 'w', { bareFallback: false }) ?? '';
+        const initials = getAttributeSafe(el, OOXML.W_NS, 'initials', 'w', { bareFallback: false }) ?? '';
         // Extract text from <w:t> elements, skipping annotationRef runs
         const text = extractCommentText(el);
-        // Get paraId from first <w:p> child
+        // Get paraId from first <w:p> child (namespace-aware to handle non-`w` prefixes)
         const paras = el.getElementsByTagNameNS(OOXML.W_NS, W.p);
         let paragraphId = null;
         if (paras.length > 0) {
             const p = paras.item(0);
-            paragraphId = p.getAttributeNS(OOXML.W14_NS, 'paraId') ?? p.getAttribute('w14:paraId') ?? null;
+            paragraphId = getAttributeSafe(p, OOXML.W14_NS, 'paraId', 'w14', { bareFallback: false });
         }
+        const startPoint = rangeMetadata.startById.get(id);
+        const endPoint = rangeMetadata.endById.get(id);
         const comment = {
             id,
             author,
@@ -418,35 +543,18 @@ export async function getComments(zip, documentXml) {
             initials,
             text,
             paragraphId,
-            anchoredParagraphId: null,
+            anchoredParagraphId: startPoint?.paragraphId ?? null,
+            endParagraphId: endPoint?.paragraphId ?? startPoint?.paragraphId ?? null,
+            startRunIndex: startPoint?.runIndex,
+            startCharOffset: startPoint?.charOffset,
+            endRunIndex: endPoint?.runIndex,
+            endCharOffset: endPoint?.charOffset,
             replies: [],
         };
         byId.set(id, comment);
         if (paragraphId)
             byParaId.set(paragraphId, comment);
     }
-    // Resolve anchoredParagraphId by scanning documentXml for commentRangeStart elements
-    const rangeStarts = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.commentRangeStart);
-    for (let i = 0; i < rangeStarts.length; i++) {
-        const rs = rangeStarts.item(i);
-        const cidStr = rs.getAttributeNS(OOXML.W_NS, 'id') ?? rs.getAttribute('w:id');
-        if (!cidStr)
-            continue;
-        const cid = parseInt(cidStr, 10);
-        const comment = byId.get(cid);
-        if (!comment)
-            continue;
-        // Walk up to find enclosing <w:p>
-        let parent = rs.parentNode;
-        while (parent && parent.nodeType === 1) {
-            const pel = parent;
-            if (pel.localName === W.p && pel.namespaceURI === OOXML.W_NS) {
-                comment.anchoredParagraphId = getParagraphBookmarkId(pel);
-                break;
-            }
-            parent = parent.parentNode;
-        }
-    }
     // Build thread tree from commentsExtended.xml
     const extText = await zip.readTextOrNull('word/commentsExtended.xml');
     if (extText) {
@@ -454,8 +562,8 @@ export async function getComments(zip, documentXml) {
         const exEls = extDoc.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx');
         for (let i = 0; i < exEls.length; i++) {
             const ex = exEls.item(i);
-            const childParaId = ex.getAttributeNS(OOXML.W15_NS, 'paraId') ?? ex.getAttribute('w15:paraId');
-            const parentParaId = ex.getAttributeNS(OOXML.W15_NS, 'paraIdParent') ?? ex.getAttribute('w15:paraIdParent');
+            const childParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false });
+            const parentParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraIdParent', 'w15', { bareFallback: false });
             if (!childParaId || !parentParaId)
                 continue;
             const child = byParaId.get(childParaId);
@@ -472,8 +580,8 @@ export async function getComments(zip, documentXml) {
         const exEls = extDoc.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx');
         for (let i = 0; i < exEls.length; i++) {
             const ex = exEls.item(i);
-            const childParaId = ex.getAttributeNS(OOXML.W15_NS, 'paraId') ?? ex.getAttribute('w15:paraId');
-            const parentParaId = ex.getAttributeNS(OOXML.W15_NS, 'paraIdParent') ?? ex.getAttribute('w15:paraIdParent');
+            const childParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false });
+            const parentParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraIdParent', 'w15', { bareFallback: false });
             if (childParaId && parentParaId) {
                 replyParaIds.add(childParaId);
             }
@@ -487,6 +595,155 @@ export async function getComments(zip, documentXml) {
     }
     return roots;
 }
+function resolveCommentRangeMetadata(documentXml) {
+    const startById = new Map();
+    const endById = new Map();
+    const root = documentXml.documentElement;
+    if (!root)
+        return { startById, endById };
+    const paragraphList = root.getElementsByTagNameNS(OOXML.W_NS, W.p);
+    for (let i = 0; i < paragraphList.length; i++) {
+        resolveCommentRangeMetadataInParagraph(paragraphList.item(i), startById, endById);
+    }
+    return { startById, endById };
+}
+function resolveCommentRangeMetadataInParagraph(paragraph, startById, endById) {
+    const walkState = {
+        charPos: 0,
+        fieldState: FieldState.OUTSIDE_FIELD,
+        allRuns: [],
+        currentRunIndex: 0,
+        startMarkers: [],
+        endMarkers: [],
+    };
+    walkParagraphForCommentMarkers(paragraph, paragraph, walkState);
+    const paragraphId = getParagraphBookmarkId(paragraph);
+    for (const marker of walkState.startMarkers) {
+        if (startById.has(marker.id))
+            continue;
+        startById.set(marker.id, {
+            paragraphId,
+            ...resolveMarkerToRunBoundary(walkState.allRuns, marker, 'start'),
+        });
+    }
+    for (const marker of walkState.endMarkers) {
+        if (endById.has(marker.id))
+            continue;
+        endById.set(marker.id, {
+            paragraphId,
+            ...resolveMarkerToRunBoundary(walkState.allRuns, marker, 'end'),
+        });
+    }
+}
+function walkParagraphForCommentMarkers(rootParagraph, node, state) {
+    for (const child of childElements(node)) {
+        if (child !== rootParagraph && isW(child, W.p))
+            continue;
+        if (isW(child, W.commentRangeStart)) {
+            recordParagraphLevelMarker(child, state.startMarkers, state);
+            continue;
+        }
+        if (isW(child, W.commentRangeEnd)) {
+            recordParagraphLevelMarker(child, state.endMarkers, state);
+            continue;
+        }
+        if (isW(child, W.r)) {
+            walkRunForCommentMarkers(child, state);
+            continue;
+        }
+        walkParagraphForCommentMarkers(rootParagraph, child, state);
+    }
+}
+function walkRunForCommentMarkers(run, state) {
+    const runIndex = state.currentRunIndex;
+    state.currentRunIndex += 1;
+    const runVisibleStart = state.charPos;
+    for (const child of childElements(run)) {
+        if (isW(child, W.commentRangeStart)) {
+            recordInRunMarker(child, state.startMarkers, runIndex, state.charPos - runVisibleStart);
+            continue;
+        }
+        if (isW(child, W.commentRangeEnd)) {
+            recordInRunMarker(child, state.endMarkers, runIndex, state.charPos - runVisibleStart);
+            continue;
+        }
+        if (!child.namespaceURI || child.namespaceURI !== OOXML.W_NS)
+            continue;
+        if (child.localName === W.fldChar) {
+            const type = getWordAttribute(child, 'fldCharType') ?? '';
+            if (type === 'begin')
+                state.fieldState = FieldState.IN_FIELD_CODE;
+            else if (type === 'separate')
+                state.fieldState = FieldState.IN_FIELD_RESULT;
+            else if (type === 'end')
+                state.fieldState = FieldState.OUTSIDE_FIELD;
+            continue;
+        }
+        if (state.fieldState === FieldState.IN_FIELD_CODE)
+            continue;
+        if (child.localName === W.t) {
+            state.charPos += (getLeafText(child) ?? '').length;
+            continue;
+        }
+        if (child.localName === W.tab || child.localName === W.br) {
+            state.charPos += 1;
+        }
+    }
+    state.allRuns.push({ visibleLength: state.charPos - runVisibleStart });
+}
+function recordInRunMarker(markerEl, bucket, runIndex, charOffset) {
+    const id = getCommentMarkerId(markerEl);
+    if (id == null)
+        return;
+    bucket.push({ id, inside: { runIndex, charOffset } });
+}
+function recordParagraphLevelMarker(markerEl, bucket, state) {
+    const id = getCommentMarkerId(markerEl);
+    if (id == null)
+        return;
+    bucket.push({ id, between: { afterRunIndex: state.currentRunIndex - 1 } });
+}
+function getCommentMarkerId(markerEl) {
+    const idStr = getAttributeSafe(markerEl, OOXML.W_NS, 'id', 'w', { bareFallback: false });
+    if (!idStr)
+        return null;
+    const id = parseInt(idStr, 10);
+    return Number.isNaN(id) ? null : id;
+}
+function getWordAttribute(el, localName) {
+    return getAttributeSafe(el, OOXML.W_NS, localName, 'w');
+}
+function resolveMarkerToRunBoundary(allRuns, marker, boundary) {
+    // Marker seen INSIDE a run already carries the exact runIndex + charOffset.
+    if (marker.inside) {
+        return { runIndex: marker.inside.runIndex, charOffset: marker.inside.charOffset };
+    }
+    if (!marker.between)
+        return {};
+    if (allRuns.length === 0)
+        return {};
+    const { afterRunIndex } = marker.between;
+    const lastIndex = allRuns.length - 1;
+    if (boundary === 'start') {
+        // Marker sits between run `afterRunIndex` and run `afterRunIndex + 1`.
+        // For a `start` marker, the range opens at offset 0 of the next run if it exists.
+        const nextIdx = afterRunIndex + 1;
+        if (nextIdx <= lastIndex) {
+            return { runIndex: nextIdx, charOffset: 0 };
+        }
+        // Marker is past the last run — clamp to end of last run.
+        return { runIndex: lastIndex, charOffset: allRuns[lastIndex].visibleLength };
+    }
+    // boundary === 'end': range closes at the end of the previous run if one exists.
+    if (afterRunIndex < 0) {
+        // Marker is before the first run — empty range starting at run 0.
+        return { runIndex: 0, charOffset: 0 };
+    }
+    if (afterRunIndex <= lastIndex) {
+        return { runIndex: afterRunIndex, charOffset: allRuns[afterRunIndex].visibleLength };
+    }
+    return { runIndex: lastIndex, charOffset: allRuns[lastIndex].visibleLength };
+}
 /**
  * Get a single comment by ID, searching the full tree including replies.
  */
@@ -514,7 +771,7 @@ function findCommentById(comments, id) {
  *   commentReference from document.xml (element-level; run removed only if empty)
  * - Transitive cascade: deleting any node also deletes all descendants
  */
-export async function deleteComment(documentXml, zip, params) {
+export async function deleteComment(documentXml, zip, params, ctx) {
     const { commentId } = params;
     const commentsText = await zip.readTextOrNull('word/comments.xml');
     if (!commentsText)
@@ -535,7 +792,7 @@ export async function deleteComment(documentXml, zip, params) {
     const allCommentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment);
     for (let i = 0; i < allCommentEls.length; i++) {
         const el = allCommentEls.item(i);
-        const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         const id = idStr ? parseInt(idStr, 10) : -1;
         if (id < 0)
             continue;
@@ -552,8 +809,8 @@ export async function deleteComment(documentXml, zip, params) {
         const childrenOf = new Map();
         for (let i = 0; i < exEls.length; i++) {
             const ex = exEls.item(i);
-            const childPid = ex.getAttributeNS(OOXML.W15_NS, 'paraId') ?? ex.getAttribute('w15:paraId');
-            const parentPid = ex.getAttributeNS(OOXML.W15_NS, 'paraIdParent') ?? ex.getAttribute('w15:paraIdParent');
+            const childPid = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false });
+            const parentPid = getAttributeSafe(ex, OOXML.W15_NS, 'paraIdParent', 'w15', { bareFallback: false });
             if (childPid && parentPid) {
                 const arr = childrenOf.get(parentPid);
                 if (arr)
@@ -584,7 +841,7 @@ export async function deleteComment(documentXml, zip, params) {
     const elsToRemove = [];
     for (let i = 0; i < allCommentEls.length; i++) {
         const el = allCommentEls.item(i);
-        const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         const id = idStr ? parseInt(idStr, 10) : -1;
         if (idsToDelete.has(id))
             elsToRemove.push(el);
@@ -600,7 +857,7 @@ export async function deleteComment(documentXml, zip, params) {
         const exToRemove = [];
         for (let i = 0; i < exEls.length; i++) {
             const ex = exEls.item(i);
-            const pid = ex.getAttributeNS(OOXML.W15_NS, 'paraId') ?? ex.getAttribute('w15:paraId');
+            const pid = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false });
             if (pid && paraIdsToDelete.has(pid))
                 exToRemove.push(ex);
         }
@@ -611,14 +868,14 @@ export async function deleteComment(documentXml, zip, params) {
     }
     // 3. Remove range markers and commentReference from document.xml (for root comments)
     for (const cid of idsToDelete) {
-        removeCommentMarkersFromDocument(documentXml, cid);
+        removeCommentMarkersFromDocument(documentXml, cid, ctx);
     }
 }
 function findCommentElementById(commentsDoc, commentId) {
     const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment);
     for (let i = 0; i < commentEls.length; i++) {
         const el = commentEls.item(i);
-        const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         if (idStr && parseInt(idStr, 10) === commentId)
             return el;
     }
@@ -629,16 +886,16 @@ function getCommentElParaId(commentEl) {
     if (paras.length === 0)
         return null;
     const p = paras.item(0);
-    return p.getAttributeNS(OOXML.W14_NS, 'paraId') ?? p.getAttribute('w14:paraId') ?? null;
+    return getAttributeSafe(p, OOXML.W14_NS, 'paraId', 'w14', { bareFallback: false });
 }
-function removeCommentMarkersFromDocument(documentXml, commentId) {
+function removeCommentMarkersFromDocument(documentXml, commentId, ctx) {
     const cidStr = String(commentId);
     // Remove commentRangeStart elements
     const rangeStarts = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.commentRangeStart);
     const startsToRemove = [];
     for (let i = 0; i < rangeStarts.length; i++) {
         const el = rangeStarts.item(i);
-        const id = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const id = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         if (id === cidStr)
             startsToRemove.push(el);
     }
@@ -649,18 +906,19 @@ function removeCommentMarkersFromDocument(documentXml, commentId) {
     const endsToRemove = [];
     for (let i = 0; i < rangeEnds.length; i++) {
         const el = rangeEnds.item(i);
-        const id = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const id = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         if (id === cidStr)
             endsToRemove.push(el);
     }
     for (const el of endsToRemove)
         el.parentNode?.removeChild(el);
-    // Remove commentReference elements (safe: remove element, then run only if empty)
+    // Remove commentReference elements, or preserve their containing run under
+    // a deletion wrapper when tracked changes are requested.
     const refs = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.commentReference);
     const refsToRemove = [];
     for (let i = 0; i < refs.length; i++) {
         const el = refs.item(i);
-        const id = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
+        const id = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false });
         if (id === cidStr)
             refsToRemove.push(el);
     }
@@ -668,10 +926,29 @@ function removeCommentMarkersFromDocument(documentXml, commentId) {
         const run = ref.parentNode;
         if (!run)
             continue;
+        if (ctx) {
+            const parent = run.parentNode;
+            if (!parent)
+                continue;
+            const deletion = createRevisionContainer(documentXml, 'del', ctx);
+            parent.replaceChild(deletion, run);
+            deletion.appendChild(prepareElementForDeletion(run));
+            continue;
+        }
         run.removeChild(ref);
         // Remove run only if it has no visible content after removing the reference
         if (!hasVisibleRunContent(run)) {
-            run.parentNode?.removeChild(run);
+            const runParent = run.parentNode;
+            runParent?.removeChild(run);
+            // If the run lived inside a tracked-change wrapper (e.g., the comment
+            // was added with ctx earlier and is now being deleted without ctx),
+            // the wrapper is left orphaned with no content. Clean it up.
+            if (runParent && isW(runParent, 'ins')) {
+                runParent.parentNode?.removeChild(runParent);
+            }
+            else if (runParent && isW(runParent, 'del')) {
+                runParent.parentNode?.removeChild(runParent);
+            }
         }
     }
 }