@usejunior/docx-core 0.19.1 → 0.21.2

package/dist/primitives/comments.js

@@ -4,12 +4,20 @@
  * Creates comment XML parts when missing, inserts comment range markers,
  * and supports threaded replies via commentsExtended.xml.
  */
+import { createHash } from 'node:crypto';
 import { OOXML, W } from './namespaces.js';
 import { parseXml, serializeXml } from './xml.js';
+import { DocxZip } from './zip.js';
 import { getParagraphRuns, getParagraphText, splitRunAtVisibleOffset } from './text.js';
 import { getParagraphBookmarkId } from './bookmarks.js';
-import { childElements, getLeafText, isW } from './dom-helpers.js';
+import { isW } from './dom-helpers.js';
+import { buildParagraphIndex } from './paragraph-index.js';
 import { getAttributeSafe } from './xml-helpers.js';
+import { getFirstChild } from './xml-helpers.js';
+import { extractEffectiveRunFormatting, parseStylesXml, parseThemeXml } from './styles.js';
+import { emitFormattingTags, mergeAdjacentTags } from './formatting_tags.js';
+import { ensureExternalHyperlinkRelationships } from './relationships.js';
+import { SafeDocxError } from './errors.js';
 import { createRevisionContainer, prepareElementForDeletion, } from './track-changes-emitter.js';
 // ── Relationship types ──────────────────────────────────────────────────
 const REL_TYPE_COMMENTS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments';
@@ -146,6 +154,86 @@ async function ensureRelationships(zip, newParts) {
     }
     zip.writeText(relsPath, serializeXml(relsDoc));
 }
+function commentBodyDestinations(body) {
+    return body?.flatMap((paragraph) => paragraph.runs.flatMap((run) => run.hyperlink ? [run.hyperlink.destination] : [])) ?? [];
+}
+function deterministicParaId(params, commentId) {
+    return createHash('sha256')
+        .update(`${commentId}\0${params.author}\0${params.initials}\0${params.date}\0${params.text}`)
+        .digest('hex')
+        .slice(0, 8)
+        .toUpperCase();
+}
+function findUniqueRevision(documentXml, locator) {
+    const matches = Array.from(documentXml.getElementsByTagNameNS(OOXML.W_NS, locator.type))
+        .filter((element) => getAttributeSafe(element, OOXML.W_NS, 'id', 'w', { bareFallback: false }) === locator.id);
+    if (matches.length !== 1) {
+        throw new Error(`Tracked revision ${locator.type}#${locator.id} must occur exactly once; found ${matches.length}.`);
+    }
+    return matches[0];
+}
+function createCommentReference(documentXml, commentId) {
+    const refRun = documentXml.createElementNS(OOXML.W_NS, 'w:r');
+    const rPr = documentXml.createElementNS(OOXML.W_NS, 'w:rPr');
+    const rStyle = documentXml.createElementNS(OOXML.W_NS, 'w:rStyle');
+    rStyle.setAttribute('w:val', 'CommentReference');
+    rPr.appendChild(rStyle);
+    refRun.appendChild(rPr);
+    const reference = documentXml.createElementNS(OOXML.W_NS, 'w:commentReference');
+    reference.setAttribute('w:id', String(commentId));
+    refRun.appendChild(reference);
+    return refRun;
+}
+/**
+ * Materialize root comments around an OOXML tracked-revision range. Markers
+ * are placed immediately outside the identified revision containers so
+ * accept/reject keeps a balanced annotation and naturally collapses it when
+ * that revision's text is removed.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.2
+ * @see https://github.com/UseJunior/safe-docx/issues/860
+ */
+export async function addTrackedRangeComments(buffer, comments) {
+    if (comments.length === 0)
+        return buffer;
+    const zip = await DocxZip.load(buffer);
+    await bootstrapCommentParts(zip);
+    const documentXml = parseXml(await zip.readText('word/document.xml'));
+    const commentsDoc = parseXml(await zip.readText('word/comments.xml'));
+    for (const params of comments) {
+        const startRevision = findUniqueRevision(documentXml, params.startRevision);
+        const endRevision = findUniqueRevision(documentXml, params.endRevision);
+        const startParent = startRevision.parentNode;
+        const endParent = endRevision.parentNode;
+        if (!startParent || !endParent)
+            throw new Error('Attributed revision container has no parent.');
+        for (const parent of [startParent, endParent]) {
+            if (parent.nodeType === 1 && ['trPr', 'rPr'].includes(parent.localName)) {
+                throw new Error('Tracked range comments cannot be anchored inside a property container.');
+            }
+        }
+        const commentId = allocateNextCommentId(commentsDoc);
+        const rangeStart = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeStart');
+        rangeStart.setAttribute('w:id', String(commentId));
+        const rangeEnd = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeEnd');
+        rangeEnd.setAttribute('w:id', String(commentId));
+        startParent.insertBefore(rangeStart, startRevision);
+        endParent.insertBefore(rangeEnd, endRevision.nextSibling);
+        endParent.insertBefore(createCommentReference(documentXml, commentId), rangeEnd.nextSibling);
+        addCommentElement(commentsDoc, {
+            id: commentId,
+            author: params.author,
+            initials: params.initials,
+            text: params.text,
+            paraId: deterministicParaId(params, commentId),
+            date: params.date,
+        });
+        await ensureAuthorInPeople(zip, params.author);
+    }
+    zip.writeText('word/document.xml', serializeXml(documentXml));
+    zip.writeText('word/comments.xml', serializeXml(commentsDoc));
+    return zip.toBuffer();
+}
 /**
  * Insert a root comment anchored to a text range within a paragraph.
  *
@@ -154,6 +242,10 @@ async function ensureRelationships(zip, newParts) {
  * - Inserts commentReference run after range end
  * - Adds comment entry to comments.xml
  * - Adds author to people.xml if not present
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.4
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.3
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.5
  */
 export async function addComment(documentXml, zip, params, ctx) {
     const { paragraphEl, author, text, initials } = params;
@@ -175,28 +267,44 @@ export async function addComment(documentXml, zip, params, ctx) {
     insertCommentMarkers(documentXml, paragraphEl, commentId, start, end, ctx);
     // Add comment element to comments.xml
     const paraId = generateParaId();
+    const hyperlinkRelationshipIds = await ensureExternalHyperlinkRelationships(zip, 'word/comments.xml', commentBodyDestinations(params.body));
     addCommentElement(commentsDoc, {
         id: commentId,
         author,
         initials: initials ?? author.charAt(0).toUpperCase(),
         text,
         paraId,
+        date: resolveDefinitionDate(params.date, ctx),
+        body: params.body,
+        hyperlinkRelationshipIds,
     });
     zip.writeText('word/comments.xml', serializeXml(commentsDoc));
     // Add author to people.xml
     await ensureAuthorInPeople(zip, author);
     return { commentId };
 }
+/**
+ * Resolve the `w:date` a new comment definition should carry. An explicit
+ * `null` from the caller means "no `w:date`" and wins over `ctx.date`, exactly
+ * as an explicit string does; `undefined` defers to the revision context and
+ * then to the process clock inside `addCommentElement` (#961, #1103).
+ */
+function resolveDefinitionDate(date, ctx) {
+    return date === null ? null : (date ?? ctx?.date);
+}
 /**
  * Add a threaded reply to an existing comment.
  *
  * 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.
+ * Replies emit no body revision markup (there is nothing to anchor), but the
+ * reply's comment definition still claims creation metadata — so a
+ * caller-supplied `params.date` (or, failing that, `ctx.date`) stamps
+ * `w:date` exactly as it does for root comments, keeping reply timestamps
+ * deterministic alongside the rest of the operation. Author and initials
+ * intentionally stay sourced from `params`.
  */
-export async function addCommentReply(_documentXml, zip, params, _ctx) {
+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');
@@ -209,12 +317,16 @@ export async function addCommentReply(_documentXml, zip, params, _ctx) {
     // Allocate ID and add reply comment
     const commentId = allocateNextCommentId(commentsDoc);
     const replyParaId = generateParaId();
+    const hyperlinkRelationshipIds = await ensureExternalHyperlinkRelationships(zip, 'word/comments.xml', commentBodyDestinations(params.body));
     addCommentElement(commentsDoc, {
         id: commentId,
         author,
         initials: initials ?? author.charAt(0).toUpperCase(),
         text,
         paraId: replyParaId,
+        date: resolveDefinitionDate(params.date, ctx),
+        body: params.body,
+        hyperlinkRelationshipIds,
     });
     zip.writeText('word/comments.xml', serializeXml(commentsDoc));
     // Link reply in commentsExtended.xml
@@ -225,6 +337,66 @@ export async function addCommentReply(_documentXml, zip, params, _ctx) {
     await ensureAuthorInPeople(zip, author);
     return { commentId, parentCommentId };
 }
+/**
+ * Replace only the editable body payload of an existing comment definition.
+ * Comment identity, authorship metadata, threading metadata, and every anchor
+ * in document.xml remain untouched. The admitted topology intentionally
+ * matches the comment-body subset exposed by getComments(); unfamiliar direct
+ * children fail closed before comments.xml is mutated.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.2
+ * @see https://github.com/UseJunior/safe-docx/issues/960
+ */
+export async function updateCommentBody(zip, params) {
+    const commentsText = await zip.readTextOrNull('word/comments.xml');
+    if (!commentsText)
+        throw new Error(`Comment ID ${params.commentId} not found`);
+    const commentsDoc = parseXml(commentsText);
+    const commentEl = findCommentElementById(commentsDoc, params.commentId);
+    if (!commentEl)
+        throw new Error(`Comment ID ${params.commentId} not found`);
+    const paragraphs = Array.from(commentEl.childNodes)
+        .filter((node) => node.nodeType === 1);
+    if (paragraphs.length === 0 || paragraphs.some((element) => !isW(element, W.p))) {
+        throw new SafeDocxError('UNSUPPORTED_EDIT', `Comment ID ${params.commentId} has unsupported body topology`, 'Only direct w:p comment-body children can be updated in place.');
+    }
+    const first = paragraphs[0];
+    const markerRuns = paragraphs.flatMap((paragraph) => Array.from(paragraph.childNodes)
+        .filter((node) => node.nodeType === 1 && isW(node, W.r))
+        .filter((run) => run.getElementsByTagNameNS(OOXML.W_NS, W.annotationRef).length > 0));
+    const annotationReferenceCount = paragraphs.reduce((count, paragraph) => count + paragraph.getElementsByTagNameNS(OOXML.W_NS, W.annotationRef).length, 0);
+    if (annotationReferenceCount > 1 || (markerRuns.length === 1 && markerRuns[0]?.parentNode !== first)) {
+        throw new SafeDocxError('UNSUPPORTED_EDIT', `Comment ID ${params.commentId} has unsupported annotation-reference topology`, 'At most one annotation-reference run is admitted, and it must be in the first comment paragraph.');
+    }
+    for (const paragraph of paragraphs) {
+        const children = Array.from(paragraph.childNodes).filter((node) => node.nodeType === 1);
+        const unsupported = children.find((child) => !isW(child, W.pPr)
+            && !isW(child, W.r)
+            && !isW(child, W.hyperlink));
+        if (unsupported) {
+            throw new SafeDocxError('UNSUPPORTED_EDIT', `Comment ID ${params.commentId} contains unsupported ${unsupported.nodeName}`, 'The existing comment body was left unchanged.');
+        }
+    }
+    const body = params.body ?? [{ runs: [{ text: params.text }] }];
+    const hyperlinkRelationshipIds = await ensureExternalHyperlinkRelationships(zip, 'word/comments.xml', commentBodyDestinations(body));
+    for (let index = 0; index < body.length; index++) {
+        const paragraph = paragraphs[index] ?? commentsDoc.createElementNS(OOXML.W_NS, 'w:p');
+        if (!paragraph.parentNode)
+            commentEl.appendChild(paragraph);
+        for (const child of Array.from(paragraph.childNodes)) {
+            if (child.nodeType !== 1)
+                continue;
+            const element = child;
+            if (isW(element, W.pPr) || (index === 0 && element === markerRuns[0]))
+                continue;
+            paragraph.removeChild(element);
+        }
+        appendCommentBodyRuns(paragraph, body[index].runs, commentsDoc, hyperlinkRelationshipIds);
+    }
+    for (const paragraph of paragraphs.slice(body.length))
+        commentEl.removeChild(paragraph);
+    zip.writeText('word/comments.xml', serializeXml(commentsDoc));
+}
 // ── Internal helpers ────────────────────────────────────────────────────
 function allocateNextCommentId(commentsDoc) {
     const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment);
@@ -278,13 +450,39 @@ function ensureCommentPartNamespaceAliases(commentsDoc) {
         root.setAttributeNS(XMLNS_NS, 'xmlns:w15', OOXML.W15_NS);
     }
 }
+/**
+ * Append a `w:comment` definition to the comments part.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.13.4.2
+ * The `w:date` creation stamp uses the caller-supplied date when one is
+ * provided — an explicit `AddCommentParams.date`, or else the revision
+ * context's date — so the comment definition and any body revision markup
+ * emitted for the same operation agree on the calendar date Word displays,
+ * even across a UTC/local day boundary. Only when the caller supplies no date
+ * does the process clock remain the default. An explicit `null` writes no
+ * `w:date` attribute at all, which is how a source comment that never carried
+ * one is re-emitted without gaining the compile time (#1103); `w:date` is
+ * optional on `w:comment`. Author and initials always come
+ * from `AddCommentParams` / `AddCommentReplyParams`, never from
+ * `RevisionContext`: the comment's attribution is the commenting author, which
+ * is allowed to differ from the tracked-change author wrapping the reference
+ * run. A date alone never produces revision markup; only a `RevisionContext`
+ * does.
+ * @see #859
+ * @see #961
+ * @see #1103
+ */
 function addCommentElement(commentsDoc, params) {
     ensureCommentPartNamespaceAliases(commentsDoc);
     const root = commentsDoc.documentElement;
+    if (params.hyperlinkRelationshipIds?.size && root.lookupNamespaceURI('r') !== OOXML.R_NS) {
+        root.setAttributeNS(XMLNS_NS, 'xmlns:r', OOXML.R_NS);
+    }
     const commentEl = commentsDoc.createElementNS(OOXML.W_NS, 'w:comment');
     commentEl.setAttribute('w:id', String(params.id));
     commentEl.setAttribute('w:author', params.author);
-    commentEl.setAttribute('w:date', isoNow());
+    if (params.date !== null)
+        commentEl.setAttribute('w:date', params.date ?? isoNow());
     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');
@@ -296,18 +494,88 @@ function addCommentElement(commentsDoc, params) {
     const annotRef = commentsDoc.createElementNS(OOXML.W_NS, 'w:annotationRef');
     refRun.appendChild(annotRef);
     p.appendChild(refRun);
-    // Text run
-    const textRun = commentsDoc.createElementNS(OOXML.W_NS, 'w:r');
-    const t = commentsDoc.createElementNS(OOXML.W_NS, 'w:t');
-    if (params.text.startsWith(' ') || params.text.endsWith(' ')) {
-        t.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve');
-    }
-    t.appendChild(commentsDoc.createTextNode(params.text));
-    textRun.appendChild(t);
-    p.appendChild(textRun);
+    const body = params.body ?? [{ runs: [{ text: params.text }] }];
+    appendCommentBodyRuns(p, body[0]?.runs ?? [], commentsDoc, params.hyperlinkRelationshipIds);
     commentEl.appendChild(p);
+    for (const paragraph of body.slice(1)) {
+        const bodyParagraph = commentsDoc.createElementNS(OOXML.W_NS, 'w:p');
+        appendCommentBodyRuns(bodyParagraph, paragraph.runs, commentsDoc, params.hyperlinkRelationshipIds);
+        commentEl.appendChild(bodyParagraph);
+    }
     root.appendChild(commentEl);
 }
+/**
+ * Emit annotation runs while retaining external hyperlink boundaries.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.16.22
+ * @see #956
+ */
+function appendCommentBodyRuns(paragraph, runs, doc, relationshipIds) {
+    let activeDestination;
+    let activeHyperlink;
+    for (const bodyRun of runs) {
+        const destination = bodyRun.hyperlink?.destination;
+        if (!destination) {
+            activeDestination = undefined;
+            activeHyperlink = undefined;
+            paragraph.appendChild(buildCommentBodyRun(doc, bodyRun));
+            continue;
+        }
+        const relationshipId = relationshipIds?.get(destination);
+        if (!relationshipId)
+            throw new Error(`Missing comment hyperlink relationship for ${destination}`);
+        if (activeDestination !== destination || !activeHyperlink) {
+            activeDestination = destination;
+            activeHyperlink = doc.createElementNS(OOXML.W_NS, 'w:hyperlink');
+            activeHyperlink.setAttributeNS(OOXML.R_NS, 'r:id', relationshipId);
+            paragraph.appendChild(activeHyperlink);
+        }
+        activeHyperlink.appendChild(buildCommentBodyRun(doc, bodyRun));
+    }
+}
+function buildCommentBodyRun(doc, bodyRun) {
+    const run = doc.createElementNS(OOXML.W_NS, 'w:r');
+    const style = bodyRun.style;
+    if (style && Object.values(style).some((value) => value !== undefined && value !== false)) {
+        const rPr = doc.createElementNS(OOXML.W_NS, 'w:rPr');
+        if (style.styleId) {
+            const rStyle = doc.createElementNS(OOXML.W_NS, 'w:rStyle');
+            rStyle.setAttributeNS(OOXML.W_NS, 'w:val', style.styleId);
+            rPr.appendChild(rStyle);
+        }
+        if (style.fontSizeHalfPoints !== undefined) {
+            const size = doc.createElementNS(OOXML.W_NS, 'w:sz');
+            size.setAttributeNS(OOXML.W_NS, 'w:val', String(style.fontSizeHalfPoints));
+            rPr.appendChild(size);
+        }
+        if (style.bold)
+            rPr.appendChild(doc.createElementNS(OOXML.W_NS, 'w:b'));
+        if (style.italic)
+            rPr.appendChild(doc.createElementNS(OOXML.W_NS, 'w:i'));
+        if (style.underline) {
+            const underline = doc.createElementNS(OOXML.W_NS, 'w:u');
+            underline.setAttributeNS(OOXML.W_NS, 'w:val', 'single');
+            rPr.appendChild(underline);
+        }
+        if (style.color) {
+            const color = doc.createElementNS(OOXML.W_NS, 'w:color');
+            color.setAttributeNS(OOXML.W_NS, 'w:val', style.color);
+            rPr.appendChild(color);
+        }
+        if (style.highlight && style.highlight !== 'none') {
+            const highlight = doc.createElementNS(OOXML.W_NS, 'w:highlight');
+            highlight.setAttributeNS(OOXML.W_NS, 'w:val', style.highlight);
+            rPr.appendChild(highlight);
+        }
+        run.appendChild(rPr);
+    }
+    const text = doc.createElementNS(OOXML.W_NS, 'w:t');
+    if (bodyRun.text.startsWith(' ') || bodyRun.text.endsWith(' '))
+        text.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve');
+    text.appendChild(doc.createTextNode(bodyRun.text));
+    run.appendChild(text);
+    return run;
+}
 function insertCommentMarkers(documentXml, paragraphEl, commentId, start, end, ctx) {
     const runs = getParagraphRuns(paragraphEl);
     const rangeStart = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeStart');
@@ -491,12 +759,6 @@ async function ensureAuthorInPeople(zip, author) {
     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.
  *
@@ -504,7 +766,7 @@ var FieldState;
  * their parent's `replies` array. Thread linkage is resolved via
  * commentsExtended.xml paraIdParent relationships.
  */
-export async function getComments(zip, documentXml) {
+export async function getComments(zip, documentXml, styles = parseStylesXml(null), theme = parseThemeXml(null)) {
     const commentsText = await zip.readTextOrNull('word/comments.xml');
     if (!commentsText)
         return [];
@@ -526,7 +788,8 @@ export async function getComments(zip, documentXml) {
         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);
+        const paragraphs = extractCommentParagraphs(el, styles, theme);
+        const text = paragraphs.map((paragraph) => paragraph.text).join('\n');
         // 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;
@@ -542,6 +805,7 @@ export async function getComments(zip, documentXml) {
             date,
             initials,
             text,
+            paragraphs,
             paragraphId,
             anchoredParagraphId: startPoint?.paragraphId ?? null,
             endParagraphId: endPoint?.paragraphId ?? startPoint?.paragraphId ?? null,
@@ -549,6 +813,8 @@ export async function getComments(zip, documentXml) {
             startCharOffset: startPoint?.charOffset,
             endRunIndex: endPoint?.runIndex,
             endCharOffset: endPoint?.charOffset,
+            startTextOffset: startPoint?.textOffset,
+            endTextOffset: endPoint?.textOffset,
             replies: [],
         };
         byId.set(id, comment);
@@ -608,101 +874,29 @@ function resolveCommentRangeMetadata(documentXml) {
     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 index = buildParagraphIndex(paragraph);
     const paragraphId = getParagraphBookmarkId(paragraph);
-    for (const marker of walkState.startMarkers) {
-        if (startById.has(marker.id))
+    for (const marker of index.nodes.filter((node) => node.kind === 'comment-range-start')) {
+        const id = getCommentMarkerId(marker.element);
+        if (id == null || startById.has(id))
             continue;
-        startById.set(marker.id, {
+        startById.set(id, {
             paragraphId,
-            ...resolveMarkerToRunBoundary(walkState.allRuns, marker, 'start'),
+            textOffset: marker.visibleStart,
+            ...resolveIndexedMarkerBoundary(index, marker, 'start'),
         });
     }
-    for (const marker of walkState.endMarkers) {
-        if (endById.has(marker.id))
+    for (const marker of index.nodes.filter((node) => node.kind === 'comment-range-end')) {
+        const id = getCommentMarkerId(marker.element);
+        if (id == null || endById.has(id))
             continue;
-        endById.set(marker.id, {
+        endById.set(id, {
             paragraphId,
-            ...resolveMarkerToRunBoundary(walkState.allRuns, marker, 'end'),
+            textOffset: marker.visibleStart,
+            ...resolveIndexedMarkerBoundary(index, 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)
@@ -710,39 +904,20 @@ function getCommentMarkerId(markerEl) {
     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)
+function resolveIndexedMarkerBoundary(index, marker, boundary) {
+    if (marker.runIndex !== null)
+        return { runIndex: marker.runIndex, charOffset: marker.runVisibleOffset };
+    if (index.runs.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 };
+    const before = [...index.runs].reverse().find((run) => run.structuralIndex < marker.structuralIndex);
+    const after = index.runs.find((run) => run.structuralIndex > marker.structuralIndex);
+    if (boundary === 'start' && after)
+        return { runIndex: after.runIndex, charOffset: 0 };
+    if (before)
+        return { runIndex: before.runIndex, charOffset: before.visibleText.length };
+    // At least one run exists, and a marker with no preceding run must sort
+    // before the first run, so `after` is necessarily defined here.
+    return { runIndex: after.runIndex, charOffset: 0 };
 }
 /**
  * Get a single comment by ID, searching the full tree including replies.
@@ -943,10 +1118,10 @@ function removeCommentMarkersFromDocument(documentXml, commentId, ctx) {
             // 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')) {
+            if (runParent && isW(runParent, 'ins') && !hasElementChildren(runParent)) {
                 runParent.parentNode?.removeChild(runParent);
             }
-            else if (runParent && isW(runParent, 'del')) {
+            else if (runParent && isW(runParent, 'del') && !hasElementChildren(runParent)) {
                 runParent.parentNode?.removeChild(runParent);
             }
         }
@@ -965,21 +1140,46 @@ function hasVisibleRunContent(run) {
     }
     return false;
 }
-function extractCommentText(commentEl) {
-    const parts = [];
-    const runs = commentEl.getElementsByTagNameNS(OOXML.W_NS, W.r);
-    for (let i = 0; i < runs.length; i++) {
-        const run = runs.item(i);
-        // Skip runs that contain annotationRef (they're metadata, not user text)
-        const annotRefs = run.getElementsByTagNameNS(OOXML.W_NS, W.annotationRef);
-        if (annotRefs.length > 0)
-            continue;
-        const ts = run.getElementsByTagNameNS(OOXML.W_NS, W.t);
-        for (let j = 0; j < ts.length; j++) {
-            const t = ts.item(j);
-            parts.push(t.textContent ?? '');
+function hasElementChildren(element) {
+    return Array.from(element.childNodes).some((child) => child.nodeType === 1);
+}
+function extractCommentParagraphs(commentEl, styles, theme) {
+    const paragraphs = commentEl.getElementsByTagNameNS(OOXML.W_NS, W.p);
+    const result = [];
+    for (let pi = 0; pi < paragraphs.length; pi++) {
+        const paragraph = paragraphs.item(pi);
+        const pPr = getFirstChild(paragraph, OOXML.W_NS, W.pPr);
+        const pStyle = pPr ? getFirstChild(pPr, OOXML.W_NS, W.pStyle) : null;
+        const style = pStyle ? getAttributeSafe(pStyle, OOXML.W_NS, 'val', 'w') : null;
+        const annotated = [];
+        const runs = paragraph.getElementsByTagNameNS(OOXML.W_NS, W.r);
+        for (let ri = 0; ri < runs.length; ri++) {
+            const run = runs.item(ri);
+            if (run.getElementsByTagNameNS(OOXML.W_NS, W.annotationRef).length > 0)
+                continue;
+            let text = '';
+            const ts = run.getElementsByTagNameNS(OOXML.W_NS, W.t);
+            for (let ti = 0; ti < ts.length; ti++)
+                text += ts.item(ti).textContent ?? '';
+            if (!text)
+                continue;
+            const formatting = extractEffectiveRunFormatting({
+                run,
+                paragraphPPr: pPr,
+                paragraphStyleId: style,
+                styles,
+                theme,
+            });
+            annotated.push({ text, formatting, hyperlinkUrl: null, charCount: text.length, isHeaderRun: false });
         }
+        const tagged_text = mergeAdjacentTags(emitFormattingTags({
+            runs: annotated,
+            baseline: { bold: false, italic: false, underline: false, suppressed: false },
+            fontBaseline: { modalColor: null, colorSuppressed: false, modalFontSizePt: 0, fontSizeSuppressed: true, modalFontName: '', fontNameSuppressed: true },
+            formattingMode: 'full',
+        }));
+        result.push({ text: annotated.map((run) => run.text).join(''), tagged_text, style });
     }
-    return parts.join('');
+    return result;
 }
 //# sourceMappingURL=comments.js.map