@ansonlai/docx-redline-js 0.8.0 → 0.8.1

package/document/docx-document.js

@@ -7,10 +7,12 @@
  */
 
 import { getDefaultAuthor } from '../adapters/config.js';
+import { applyThreadResolutionToParts, commentParaId, reconcileCommentSiblingParts } from '../services/comment-thread-parts.js';
+import { collectRevisionIds, countRevisionsInsideFields, discoverHeaderFooterParts, isHeaderFooterPath, renumberCollidingRevisionIds, resolvePartSelector } from '../services/headers-footers.js';
 import { inspectDocumentParts } from '../services/document-inspection.js';
 import { applyOperationsToDocumentXml, preflightOperations } from '../services/standalone-operation-runner.js';
 import { createDynamicNumberingIdState, mergeNumberingXmlBySchemaOrder } from '../services/numbering-helpers.js';
-import { ensureCommentsArtifactsInZip, ensureCommentsExtendedArtifactsInZip, ensureNumberingArtifactsInZip, validateDocxPackage } from '../services/standalone-docx-plumbing.js';
+import { ensureCommentsArtifactsInZip, ensureCommentsExtendedArtifactsInZip, ensureNumberingArtifactsInZip, repairKnownContentTypes, validateDocxPackage } from '../services/standalone-docx-plumbing.js';
 import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
 import { acceptTrackedChangesInOoxml, rejectTrackedChangesInOoxml, deleteCommentsByAuthorInOoxml } from '../services/revision-comment-management.js';
@@ -30,6 +32,17 @@ const text = (entries, path) => {
     return textDecoder.decode(entry);
 };
 
+/** Keeps commentsIds/commentsExtensible in step with comments.xml after comments were added or removed. */
+function reconcileCommentSiblings(working) {
+    const updated = reconcileCommentSiblingParts({
+        commentsXml: text(working, 'word/comments.xml'),
+        commentsIdsXml: text(working, 'word/commentsIds.xml'),
+        commentsExtensibleXml: text(working, 'word/commentsExtensible.xml')
+    });
+    if (updated.commentsIdsXml) working.set('word/commentsIds.xml', textEncoder.encode(updated.commentsIdsXml));
+    if (updated.commentsExtensibleXml) working.set('word/commentsExtensible.xml', textEncoder.encode(updated.commentsExtensibleXml));
+}
+
 const cloneEntries = entries => new Map([...entries].map(([name, data]) => [name, new Uint8Array(data)]));
 
 function toBufferCompatible(uint8Arr) {
@@ -108,6 +121,9 @@ export function computePackageRevisionToken(input) {
     });
 }
 
+// Word does not support comments in headers or footers, so these are refused when `part` is set.
+const COMMENT_OPERATION_TYPES = new Set(['comment', 'comment_reply', 'comment_resolve']);
+
 function nextCommentId(entries) {
     const ids = `${text(entries, 'word/document.xml') || ''} ${text(entries, 'word/comments.xml') || ''}`.match(/(?:w:)?id=["'](\d+)["']/g) || [];
     let next = ids.reduce((max, token) => Math.max(max, Number(token.match(/\d+/)?.[0] || 0)), 0) + 1;
@@ -127,7 +143,7 @@ function existingCommentDetails(entries) {
             id,
             author: comment.getAttribute('w:author') || comment.getAttribute('author') || '',
             text: String(comment.textContent || '').trim(),
-            paraId: Array.from(comment.getElementsByTagNameNS('*', 'p'))[0]?.getAttribute('w14:paraId') || null
+            paraId: commentParaId(comment) || null
         };
     }
     return details;
@@ -165,13 +181,35 @@ export class DocxDocument {
 
     inspect(options = {}) {
         const digestFn = options.digestFn || (bytes => sha256(bytes));
-        return inspectDocumentParts({
+        const inspection = inspectDocumentParts({
             documentXml: text(this.entries, 'word/document.xml'),
             commentsXml: text(this.entries, 'word/comments.xml'),
             commentsExtendedXml: text(this.entries, 'word/commentsExtended.xml'),
             numberingXml: text(this.entries, 'word/numbering.xml'),
             stylesXml: text(this.entries, 'word/styles.xml')
         }, { ...options, digestFn });
+        if (inspection.status === 'error') return inspection;
+        return { ...inspection, headersFooters: this.inspectHeadersFooters() };
+    }
+
+    /**
+     * Header and footer parts the document uses, with their paragraph text, so operations can target them with
+     * `part`. `hasFields` marks parts containing PAGE/NUMPAGES-style fields (edit around them, not inside).
+     */
+    inspectHeadersFooters() {
+        return discoverHeaderFooterParts({
+            documentXml: text(this.entries, 'word/document.xml'),
+            relsXml: text(this.entries, 'word/_rels/document.xml.rels'),
+            settingsXml: text(this.entries, 'word/settings.xml')
+        }).map(part => {
+            const xml = text(this.entries, part.path) || '';
+            const partInspection = xml ? inspectDocumentParts({ documentXml: xml }) : { paragraphs: [] };
+            return {
+                ...part,
+                hasFields: /<w:fldChar\b|<w:fldSimple\b/.test(xml),
+                paragraphs: (partInspection.paragraphs || []).map(paragraph => ({ index: paragraph.index, text: paragraph.text }))
+            };
+        });
     }
 
     getRevisionToken() {
@@ -183,12 +221,54 @@ export class DocxDocument {
     }
 
     preflight(operations, author = getDefaultAuthor(), options = {}) {
-        return preflightOperations(
+        const list = Array.isArray(operations) ? operations : [];
+        const runBody = ops => preflightOperations(
             text(this.entries, 'word/document.xml'),
-            operations,
+            ops,
             author || getDefaultAuthor(),
             { ...options, _existingCommentDetails: existingCommentDetails(this.entries) }
         );
+        if (!list.some(operation => operation && typeof operation === 'object' && operation.part != null)) return runBody(operations);
+
+        const parts = this.inspectHeadersFooters();
+        const bodyOps = [];
+        const results = [];
+        const conflicts = [];
+        const authorsUsed = new Set();
+        let valid = true;
+        list.forEach((operation, i) => {
+            if (!operation || typeof operation !== 'object' || operation.part == null) {
+                bodyOps.push({ operation, origIndex: i });
+                return;
+            }
+            const resolved = resolvePartSelector(parts, operation.part);
+            const refusal = COMMENT_OPERATION_TYPES.has(operation.type)
+                ? { code: 'COMMENT_IN_HEADER_FOOTER', message: 'Word does not support comments in headers or footers.' }
+                : resolved.error;
+            if (refusal) {
+                valid = false;
+                results.push({ index: i + 1, type: operation.type || 'redline', status: 'error', error: normalizeErrorWithRecovery({ ...refusal, operationIndex: i + 1 }) });
+                return;
+            }
+            const { part: _selector, ...rest } = operation;
+            const partResult = preflightOperations(text(this.entries, resolved.part.path), [rest], author || getDefaultAuthor(), { ...options, _existingCommentDetails: {} });
+            valid = valid && partResult.valid;
+            for (const result of partResult.results || []) results.push({ ...result, index: i + 1, part: resolved.part.path });
+            conflicts.push(...(partResult.conflicts || []));
+            for (const name of partResult.authorsUsed || []) authorsUsed.add(name);
+        });
+        let requiredArtifacts = { comments: false, numbering: false };
+        if (bodyOps.length) {
+            const body = runBody(bodyOps.map(item => item.operation));
+            valid = valid && body.valid;
+            for (const result of body.results || []) results.push({ ...result, index: bodyOps[result.index - 1].origIndex + 1 });
+            conflicts.push(...(body.conflicts || []));
+            for (const name of body.authorsUsed || []) authorsUsed.add(name);
+            requiredArtifacts = body.requiredArtifacts || requiredArtifacts;
+        }
+        results.sort((a, b) => a.index - b.index);
+        const ok = valid && conflicts.length === 0;
+        return { valid: ok, status: ok ? 'ok' : 'error', results, conflicts, authorsUsed: [...authorsUsed], requiredArtifacts };
     }
 
     toUint8Array() {
@@ -199,7 +279,230 @@ export class DocxDocument {
         return toBufferCompatible(this.toUint8Array());
     }
 
+    /**
+     * Applies operations to the document. Operations without `part` target the body (word/document.xml).
+     * An operation with `part` targets one header or footer part:
+     * `{ part: { kind: 'footer', type: 'default', section: 0 } | 'word/footer2.xml', target: { exactText }, ... }`.
+     * Discover parts with `inspect().headersFooters`.
+     */
     async applyOperations(operations, options = {}) {
+        const list = Array.isArray(operations) ? operations : [];
+        if (!list.some(operation => operation && typeof operation === 'object' && operation.part != null)) {
+            return this.applyBodyOperations(operations, options);
+        }
+        return this.applyOperationsWithParts(list, options);
+    }
+
+    async applyOperationsWithParts(operations, options = {}) {
+        const author = options.author || getDefaultAuthor();
+        const atomic = options.atomic === true;
+        const snapshotEntries = this.entries;
+        const snapshotBytes = this.originalBytes;
+        const total = operations.length;
+        const restore = () => { this.entries = snapshotEntries; this.originalBytes = snapshotBytes; };
+        const original = () => ({
+            uint8Array: snapshotBytes,
+            toUint8Array: () => new Uint8Array(snapshotBytes),
+            buffer: toBufferCompatible(snapshotBytes),
+            toBuffer: () => toBufferCompatible(snapshotBytes)
+        });
+        const refuse = (error, results = [], receipts = [], extra = {}) => ({
+            status: 'error', hasChanges: false, written: false, rolledBack: true, results, receipts, executionOrder: [], authorsUsed: [],
+            artifactsChanged: [],
+            error: normalizeErrorWithRecovery(error),
+            retryPlan: createRetryPlan({ atomic: true, rolledBack: true, results, receipts, operationCount: total }),
+            validation: { originalIssues: [], generatedIssues: [] },
+            ...extra,
+            ...original()
+        });
+
+        if (options.expectedRevision) {
+            const precondition = await this.applyBodyOperations([], { expectedRevision: options.expectedRevision });
+            if (precondition.status === 'error') return precondition;
+        }
+
+        // Resolve every selector before touching anything, so a bad selector fails the whole request.
+        const parts = discoverHeaderFooterParts({
+            documentXml: text(this.entries, 'word/document.xml'),
+            relsXml: text(this.entries, 'word/_rels/document.xml.rels'),
+            settingsXml: text(this.entries, 'word/settings.xml')
+        });
+        const bodyOps = [];
+        const partOps = [];
+        for (let i = 0; i < operations.length; i++) {
+            const operation = operations[i];
+            if (!operation || typeof operation !== 'object' || operation.part == null) {
+                bodyOps.push({ operation, origIndex: i });
+                continue;
+            }
+            if (COMMENT_OPERATION_TYPES.has(operation.type)) {
+                return refuse({ code: 'COMMENT_IN_HEADER_FOOTER', message: `Operation ${i + 1}: Word does not support comments in headers or footers.`, operationIndex: i + 1 });
+            }
+            const resolved = resolvePartSelector(parts, operation.part);
+            if (resolved.error) return refuse({ ...resolved.error, message: `Operation ${i + 1}: ${resolved.error.message}`, operationIndex: i + 1 });
+            const { part: _selector, ...rest } = operation;
+            partOps.push({ operation: rest, origIndex: i, part: resolved.part });
+        }
+
+        const results = [];
+        const receipts = [];
+        const executionOrder = [];
+        const authorsUsed = new Set();
+        const originalIssues = [];
+        let anyChange = false;
+        let anyFailure = false;
+        let bodyResult = null;
+
+        if (bodyOps.length) {
+            bodyResult = await this.applyBodyOperations(bodyOps.map(item => item.operation), { ...options, expectedRevision: undefined });
+            const toOriginal = index => bodyOps[index - 1]?.origIndex + 1;
+            for (const result of bodyResult.results || []) {
+                results.push({
+                    ...result,
+                    index: toOriginal(result.index),
+                    ...(result.receipt ? { receipt: { ...result.receipt, operationIndex: toOriginal(result.receipt.operationIndex) } } : {})
+                });
+            }
+            for (const receipt of bodyResult.receipts || []) receipts.push({ ...receipt, operationIndex: toOriginal(receipt.operationIndex) });
+            for (const index of bodyResult.executionOrder || []) executionOrder.push(toOriginal(index));
+            for (const name of bodyResult.authorsUsed || []) authorsUsed.add(name);
+            originalIssues.push(...(bodyResult.validation?.originalIssues || []));
+            if (bodyResult.status === 'error' || bodyResult.rolledBack) {
+                anyFailure = true;
+                if (atomic) {
+                    restore();
+                    return { ...bodyResult, results, receipts, executionOrder, written: false, artifactsChanged: [], rolledBack: true, ...original() };
+                }
+            }
+            anyChange = bodyResult.hasChanges === true;
+        }
+
+        const working = cloneEntries(this.entries);
+        const zip = new MemoryZip(working);
+        const changedParts = new Set();
+        const { expectedRevision: _ignored, ...runnerOptions } = options;
+        const failPart = (item, error) => {
+            anyFailure = true;
+            const failure = normalizeErrorWithRecovery({ ...error, operationIndex: item.origIndex + 1 });
+            results.push({ index: item.origIndex + 1, type: item.operation.type || 'redline', status: 'error', authorUsed: author, part: item.part.path, error: failure });
+        };
+
+        for (const item of partOps) {
+            const path = item.part.path;
+            const xml = text(working, path);
+            if (!xml) {
+                failPart(item, { code: 'PART_NOT_FOUND', message: `Part '${path}' is referenced but missing from the package.` });
+                if (atomic) break;
+                continue;
+            }
+            const numberingText = text(working, 'word/numbering.xml');
+            const outcome = await applyOperationsToDocumentXml(xml, [item.operation], author, { numberingIdState: createDynamicNumberingIdState(numberingText || undefined) }, {
+                ...runnerOptions, atomic: true, strictTargets: options.strictTargets !== false, _existingCommentDetails: {}
+            });
+            const single = outcome.results?.[0];
+            if (outcome.rolledBack || outcome.status === 'error') {
+                failPart(item, single?.error || outcome.error || { code: 'OPERATION_FAILED', message: 'Operation failed.' });
+                if (atomic) break;
+                continue;
+            }
+            if (!outcome.hasChanges) {
+                results.push({ ...single, index: item.origIndex + 1, part: path });
+                continue;
+            }
+            if (countRevisionsInsideFields(outcome.documentXml) > countRevisionsInsideFields(xml)) {
+                failPart(item, { code: 'FIELD_EDIT_REFUSED', message: `The edit would change a field (for example PAGE or NUMPAGES) in ${path}. Word recomputes fields; edit the text around them instead.` });
+                if (atomic) break;
+                continue;
+            }
+            const taken = new Set();
+            for (const [name, data] of working) {
+                if (name === path || !(name === 'word/document.xml' || isHeaderFooterPath(name))) continue;
+                for (const id of collectRevisionIds(textDecoder.decode(data))) taken.add(id);
+            }
+            const renumbered = renumberCollidingRevisionIds(outcome.documentXml, taken);
+            working.set(path, textEncoder.encode(renumbered.xml));
+            // Receipts must describe what is in the file: the part it lives in and its final revision ids.
+            const describeReceipt = receipt => (receipt?.revisionItems
+                ? { ...receipt, revisionItems: receipt.revisionItems.map(revision => ({ ...revision, id: renumbered.idMap.get(String(revision.id)) ?? revision.id, partName: path })) }
+                : receipt);
+            if (outcome.numberingXmlParts?.length) {
+                await ensureNumberingArtifactsInZip(zip, outcome.numberingXmlParts, { mergeNumberingXml: mergeNumberingXmlBySchemaOrder });
+            }
+            changedParts.add(path);
+            anyChange = true;
+            results.push({
+                ...single,
+                index: item.origIndex + 1,
+                part: path,
+                partSections: item.part.appliesToSections,
+                ...(single?.receipt ? { receipt: { ...describeReceipt(single.receipt), operationIndex: item.origIndex + 1 } } : {})
+            });
+            if (outcome.receipts?.[0]) receipts.push({ ...describeReceipt(outcome.receipts[0]), operationIndex: item.origIndex + 1 });
+            executionOrder.push(item.origIndex + 1);
+            for (const name of outcome.authorsUsed || []) authorsUsed.add(name);
+        }
+
+        // Each changed part must not introduce revision-markup problems, and the package must still validate.
+        const generatedIssues = [];
+        if (!(atomic && anyFailure)) {
+            for (const path of changedParts) {
+                const before = validateRedlineOoxml(text(this.entries, path)).issues.map(issue => ({ source: path, ...issue }));
+                const after = validateRedlineOoxml(text(working, path)).issues.map(issue => ({ source: path, ...issue }));
+                generatedIssues.push(...validationErrors(subtractValidationIssueMultiset(after, before)));
+            }
+            if (options.validate !== false && changedParts.size) {
+                try {
+                    await validateDocxPackage(zip);
+                } catch (error) {
+                    generatedIssues.push({ source: 'package', code: 'PACKAGE_VALIDATION', severity: 'error', message: error.message });
+                }
+            }
+        }
+        if ((atomic && anyFailure) || generatedIssues.length) {
+            restore();
+            const error = generatedIssues.length
+                ? { code: 'PACKAGE_OPERATION_FAILED', message: `Applied operations introduced invalid markup (${[...new Set(generatedIssues.map(issue => issue.code))].join(', ')}).`, issues: generatedIssues }
+                : { code: 'BATCH_OPERATION_FAILED', message: 'Atomic batch rolled back because one or more operations failed.' };
+            const rolledBackResults = results
+                .map(result => (result.receipt ? { ...result, receipt: { ...result.receipt, committed: false, finalDisposition: 'rolled_back' } } : result))
+                .sort((a, b) => a.index - b.index);
+            const rolledBackReceipts = receipts.map(receipt => ({ ...receipt, committed: false, finalDisposition: 'rolled_back' }));
+            return refuse(error, rolledBackResults, rolledBackReceipts, { validation: { originalIssues, generatedIssues }, issues: generatedIssues });
+        }
+
+        results.sort((a, b) => a.index - b.index);
+        receipts.sort((a, b) => a.operationIndex - b.operationIndex);
+        const status = !anyFailure ? 'ok' : (anyChange ? 'partial' : 'error');
+        const failureError = anyFailure
+            ? { error: normalizeErrorWithRecovery({ code: 'BATCH_OPERATION_FAILED', message: 'One or more operations failed; the others were applied.' }) }
+            : {};
+        if (!changedParts.size) {
+            // No part changed; the body call (if any) already committed its own result.
+            const buf = toBufferCompatible(this.originalBytes);
+            return {
+                ...(bodyResult || {}), results, receipts, executionOrder, authorsUsed: [...authorsUsed], status, hasChanges: anyChange,
+                written: bodyResult?.written === true, artifactsChanged: bodyResult?.artifactsChanged || [],
+                validation: { originalIssues, generatedIssues: [] }, ...failureError,
+                uint8Array: this.originalBytes, toUint8Array: () => new Uint8Array(this.originalBytes), buffer: buf, toBuffer: () => toBufferCompatible(this.originalBytes)
+            };
+        }
+
+        this.entries = working;
+        const outputBytes = this.toUint8Array();
+        this.originalBytes = outputBytes;
+        const artifactsChanged = [...working]
+            .filter(([name, data]) => !snapshotEntries.has(name) || !areByteArraysEqual(data, snapshotEntries.get(name)))
+            .map(([name]) => name);
+        return {
+            ...(bodyResult || {}),
+            status, hasChanges: true, written: true, results, receipts, executionOrder, authorsUsed: [...authorsUsed], artifactsChanged,
+            validation: { originalIssues, generatedIssues: [] }, ...failureError,
+            uint8Array: outputBytes, toUint8Array: () => new Uint8Array(outputBytes), buffer: toBufferCompatible(outputBytes),
+            inspection: this.inspect(), toBuffer: () => toBufferCompatible(outputBytes)
+        };
+    }
+
+    async applyBodyOperations(operations, options = {}) {
         const failedApply = error => {
             const results = [];
             const receipts = [];
@@ -317,7 +620,9 @@ export class DocxDocument {
                 };
             }
 
-            working.set('word/document.xml', textEncoder.encode(result.documentXml));
+            // Resolving a thread only changes the comment parts; keep document.xml byte-identical.
+            const bodyChanged = (result.results || []).some(item => item?.status !== 'error' && item?.operationType !== 'comment_resolve');
+            if (bodyChanged) working.set('word/document.xml', textEncoder.encode(result.documentXml));
             await ensureNumberingArtifactsInZip(zip, result.numberingXmlParts, { mergeNumberingXml: mergeNumberingXmlBySchemaOrder });
 
             const existingCommentsXml = text(working, 'word/comments.xml');
@@ -326,11 +631,16 @@ export class DocxDocument {
                 replaceExisting: result.commentsXmlMode === 'replace' || (!result.commentsXml && !!existingCommentsXml)
             });
 
-            const existingCommentsExtendedXml = text(working, 'word/commentsExtended.xml');
-            const commentsExtendedXmlForPackaging = result.commentsExtendedXml || existingCommentsExtendedXml;
-            await ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXmlForPackaging, {
-                replaceExisting: result.commentsExtendedXmlMode === 'replace' || (!result.commentsExtendedXml && !!existingCommentsExtendedXml)
-            });
+            // Only touch the extended part (and its content type/rel) when an operation changed it.
+            // Rewriting it on every save is what stamped a bad content type onto every
+            // already-commented document.
+            if (result.commentsExtendedXml) {
+                await ensureCommentsExtendedArtifactsInZip(zip, result.commentsExtendedXml, {
+                    replaceExisting: result.commentsExtendedXmlMode === 'replace'
+                });
+            }
+            await repairKnownContentTypes(zip);
+            reconcileCommentSiblings(working);
 
             if (options.validate !== false) {
                 const generated = validateRedlineOoxml(result.documentXml);
@@ -407,6 +717,7 @@ export class DocxDocument {
         if (!transform) return packageFailure(this.originalBytes, 'INVALID_ACTION', `Unknown revision action: ${action}`);
 
         const sourceBytes = this.originalBytes;
+        const originalEntries = this.entries;
         const working = cloneEntries(this.entries);
         const zip = new MemoryZip(working);
         const result = transform(text(working, 'word/document.xml'), { author: options.author, allAuthors: options.allAuthors === true });
@@ -415,7 +726,20 @@ export class DocxDocument {
             return packageFailure(sourceBytes, result.error?.code || 'REVISION_OPERATION_FAILED', result.error?.message || 'Revision operation failed.');
         }
 
-        if (!result.hasChanges) {
+        // Headers and footers carry their own tracked changes; resolve them with the same filter.
+        const partUpdates = new Map();
+        for (const part of this.inspectHeadersFooters()) {
+            const partXml = text(working, part.path);
+            if (!partXml) continue;
+            const partResult = transform(partXml, { author: options.author, allAuthors: options.allAuthors === true });
+            if (partResult.status === 'error' || partResult.error) {
+                return packageFailure(sourceBytes, partResult.error?.code || 'REVISION_OPERATION_FAILED', `${part.path}: ${partResult.error?.message || 'Revision operation failed.'}`);
+            }
+            if (partResult.hasChanges) partUpdates.set(part.path, partResult.oxml);
+        }
+        const hasChanges = result.hasChanges || partUpdates.size > 0;
+
+        if (!hasChanges) {
             const buf = toBufferCompatible(sourceBytes);
             return {
                 ...result,
@@ -429,8 +753,10 @@ export class DocxDocument {
             };
         }
 
-        working.set('word/document.xml', textEncoder.encode(result.oxml));
+        if (result.hasChanges) working.set('word/document.xml', textEncoder.encode(result.oxml));
+        for (const [path, xml] of partUpdates) working.set(path, textEncoder.encode(xml));
         try {
+            await repairKnownContentTypes(zip);
             if (options.validate !== false) await validateDocxPackage(zip);
         } catch (error) {
             return packageFailure(sourceBytes, 'PACKAGE_VALIDATION', error.message);
@@ -445,7 +771,10 @@ export class DocxDocument {
             ...result,
             status: 'ok',
             written: true,
-            artifactsChanged: ['word/document.xml'],
+            hasChanges: true,
+            artifactsChanged: [...working]
+                .filter(([name, data]) => !originalEntries.has(name) || !areByteArraysEqual(data, originalEntries.get(name)))
+                .map(([name]) => name),
             uint8Array: outputBytes,
             toUint8Array: () => new Uint8Array(outputBytes),
             buffer: outputBuf,
@@ -453,6 +782,55 @@ export class DocxDocument {
         };
     }
 
+    /**
+     * Resolves (or reopens) the comment thread containing `commentId`.
+     * Resolved is a thread-level state in Word, so the root and every reply are updated together.
+     */
+    async resolveComment(commentId, options = {}) {
+        const sourceBytes = this.originalBytes;
+        const working = cloneEntries(this.entries);
+        const resolved = options.resolved !== false;
+        const noChange = extra => {
+            const buf = toBufferCompatible(sourceBytes);
+            return {
+                status: 'ok', hasChanges: false, written: false, artifactsChanged: [], ...extra,
+                uint8Array: sourceBytes, toUint8Array: () => new Uint8Array(sourceBytes), buffer: buf, toBuffer: () => toBufferCompatible(sourceBytes)
+            };
+        };
+
+        const result = applyThreadResolutionToParts({
+            commentsXml: text(working, 'word/comments.xml'),
+            commentsExtendedXml: text(working, 'word/commentsExtended.xml'),
+            commentId,
+            resolved
+        });
+        if (result.status === 'error') return packageFailure(sourceBytes, result.error.code, result.error.message);
+        if (!result.hasChanges) return noChange({ resolved, threadRootId: result.threadRootId, commentIds: result.commentIds });
+
+        const zip = new MemoryZip(working);
+        try {
+            if (result.commentsXml) working.set('word/comments.xml', textEncoder.encode(result.commentsXml));
+            await ensureCommentsExtendedArtifactsInZip(zip, result.commentsExtendedXml, { replaceExisting: true });
+            await repairKnownContentTypes(zip);
+            if (options.validate !== false) await validateDocxPackage(zip);
+        } catch (error) {
+            return packageFailure(sourceBytes, 'PACKAGE_VALIDATION', error.message);
+        }
+
+        const artifactsChanged = [...working]
+            .filter(([name, data]) => !this.entries.has(name) || !areByteArraysEqual(data, this.entries.get(name)))
+            .map(([name]) => name);
+        this.entries = working;
+        const outputBytes = this.toUint8Array();
+        this.originalBytes = outputBytes;
+        return {
+            status: 'ok', hasChanges: true, written: true, resolved,
+            threadRootId: result.threadRootId, commentIds: result.commentIds, artifactsChanged,
+            uint8Array: outputBytes, toUint8Array: () => new Uint8Array(outputBytes),
+            buffer: toBufferCompatible(outputBytes), toBuffer: () => toBufferCompatible(outputBytes)
+        };
+    }
+
     async deleteComments(options = {}) {
         const sourceBytes = this.originalBytes;
         const working = cloneEntries(this.entries);
@@ -479,7 +857,16 @@ export class DocxDocument {
             return packageFailure(sourceBytes, 'PARSE_ERROR', parsed.error?.message || 'Could not parse comments.xml.');
         }
 
-        const matches = comment => options.allAuthors === true || (comment.getAttribute('w:author') || comment.getAttribute('author')) === options.author;
+        // `ids` deletes specific comments (a thread root also takes its replies); otherwise filter by author.
+        const requestedIds = Array.isArray(options.ids) ? new Set(options.ids.map(String)) : null;
+        if (requestedIds) {
+            const known = new Set(Array.from(parsed.doc.getElementsByTagNameNS('*', 'comment')).map(node => node.getAttribute('w:id') || node.getAttribute('id')));
+            const missing = [...requestedIds].filter(id => !known.has(id));
+            if (missing.length) return packageFailure(sourceBytes, 'COMMENT_NOT_FOUND', `Comment id(s) not found: ${missing.join(', ')}.`);
+        }
+        const matches = comment => (requestedIds
+            ? requestedIds.has(comment.getAttribute('w:id') || comment.getAttribute('id'))
+            : options.allAuthors === true || (comment.getAttribute('w:author') || comment.getAttribute('author')) === options.author);
         const ids = new Set(
             Array.from(parsed.doc.getElementsByTagNameNS('*', 'comment'))
                 .filter(matches)
@@ -514,9 +901,8 @@ export class DocxDocument {
             const idByParaId = new Map();
             for (const comment of Array.from(parsed.doc.getElementsByTagNameNS('*', 'comment'))) {
                 const id = comment.getAttribute('w:id') || comment.getAttribute('id');
-                const paragraph = Array.from(comment.getElementsByTagNameNS('*', 'p'))[0];
-                const paraId = paragraph?.getAttribute('w14:paraId') || paragraph?.getAttribute('paraId');
-                if (paraId) idByParaId.set(paraId.toUpperCase(), id);
+                const paraId = commentParaId(comment);
+                if (paraId) idByParaId.set(paraId, id);
             }
             for (const [paraId, id] of idByParaId) {
                 if (ids.has(id)) removedParaIds.add(paraId);
@@ -536,8 +922,10 @@ export class DocxDocument {
             }
         }
 
-        const commentsResult = deleteCommentsByAuthorInOoxml(commentsXml, { author: options.author, allAuthors: options.allAuthors === true });
-        const remainingParsed = parseOoxmlSafe(commentsResult.oxml, 'application/xml');
+        const remainingXml = requestedIds
+            ? commentsXml
+            : deleteCommentsByAuthorInOoxml(commentsXml, { author: options.author, allAuthors: options.allAuthors === true }).oxml;
+        const remainingParsed = parseOoxmlSafe(remainingXml, 'application/xml');
         if (!remainingParsed.doc || remainingParsed.error) {
             return packageFailure(sourceBytes, 'PARSE_ERROR', remainingParsed.error?.message || 'Could not parse updated comments.xml.');
         }
@@ -580,11 +968,17 @@ export class DocxDocument {
         working.set('word/document.xml', textEncoder.encode(serializer.serializeToString(documentParsed.doc)));
 
         try {
-            if (options.validate !== false) await validateDocxPackage(new MemoryZip(working));
+            reconcileCommentSiblings(working);
+            const finalZip = new MemoryZip(working);
+            await repairKnownContentTypes(finalZip);
+            if (options.validate !== false) await validateDocxPackage(finalZip);
         } catch (error) {
             return packageFailure(sourceBytes, 'PACKAGE_VALIDATION', error.message);
         }
 
+        const artifactsChanged = [...working]
+            .filter(([name, data]) => !this.entries.has(name) || !areByteArraysEqual(data, this.entries.get(name)))
+            .map(([name]) => name);
         this.entries = working;
         const outputBytes = this.toUint8Array();
         this.originalBytes = outputBytes;
@@ -596,7 +990,7 @@ export class DocxDocument {
             written: true,
             commentsRemoved: ids.size,
             referencesRemoved,
-            artifactsChanged: ['word/document.xml', 'word/comments.xml', ...(extendedParsed?.doc ? ['word/commentsExtended.xml'] : [])],
+            artifactsChanged,
             uint8Array: outputBytes,
             toUint8Array: () => new Uint8Array(outputBytes),
             buffer: outputBuf,

package/engine/reconstruction-writer.js

@@ -164,6 +164,24 @@ export function applyReconstructionDiffs(xmlDoc, diffs, context, serializer, aut
         }
     }
 
+    // Comment markers are emitted when a diff part starts at their offset. Markers at the very end of the
+    // paragraph text (commentRangeEnd and the reference run of a comment on the last words) are only reached
+    // when the final diff part is an insert; after an unchanged or deleted tail nothing starts there, so they
+    // were dropped and the comment lost its end anchor. Flush whatever is left, in original order.
+    for (const offset of Array.from(sentinelMapByStart.keys()).sort((a, b) => a - b)) {
+        for (const sentinel of sentinelMapByStart.get(offset)) {
+            if (!sentinel.isCommentMarker || emittedCommentMarkers.has(sentinel.node)) continue;
+            emittedCommentMarkers.add(sentinel.node);
+            if (isWordElement(sentinel.node, 'commentReference')) {
+                const run = createWordElement(xmlDoc, 'w:r');
+                run.appendChild(sentinel.node.cloneNode(true));
+                currentParagraph.appendChild(run);
+            } else {
+                currentParagraph.appendChild(sentinel.node.cloneNode(true));
+            }
+        }
+    }
+
     if (generateRedlines) {
         containerFragments.forEach(fragment => {
             Array.from(fragment.childNodes).forEach(node => {