@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/services/revision-comment-management.js

@@ -62,19 +62,37 @@ function authorMatchesNode(node, filter) {
 }
 
 function parseXmlWithWarnings(oxml, parseFailurePrefix) {
-    const parsed = parseOoxmlSafe(oxml, 'application/xml');
+    let rawOxml = typeof oxml === 'string' ? oxml.replace(/^\uFEFF/, '').trim() : '';
+    let isFragmentWrapped = false;
+    let parsed = parseOoxmlSafe(rawOxml, 'application/xml');
+    if (parsed.error && (parsed.error.message.includes('HierarchyRequestError') || parsed.error.message.includes('Only one element'))) {
+        const wrapped = `<w:body xmlns:w="${NS_W}">${rawOxml}</w:body>`;
+        const wrappedParsed = parseOoxmlSafe(wrapped, 'application/xml');
+        if (!wrappedParsed.error) {
+            parsed = wrappedParsed;
+            isFragmentWrapped = true;
+        }
+    }
     const parseError = parsed.doc ? getXmlParseError(parsed.doc) : null;
     if (parsed.error || parseError) {
         const message = parsed.error?.message || parseError?.textContent || 'parse error';
         return {
             xmlDoc: null,
             serializer: null,
+            isFragmentWrapped: false,
             warning: `${parseFailurePrefix}: ${message}`,
             warnings: parsed.warnings,
             error: { code: 'PARSE_ERROR', message }
         };
     }
-    return { xmlDoc: parsed.doc, serializer: createSerializer(), warning: null, warnings: parsed.warnings, error: null };
+    return {
+        xmlDoc: parsed.doc,
+        serializer: createSerializer(),
+        isFragmentWrapped,
+        warning: null,
+        warnings: parsed.warnings,
+        error: null
+    };
 }
 
 function removeNode(node) {
@@ -124,11 +142,17 @@ function mergeParagraphIntoNextAndRemove(paragraph) {
     if (!paragraph?.parentNode) return false;
     const nextParagraph = getNextWordParagraph(paragraph);
     if (!nextParagraph) {
+        if (isWordElement(paragraph.parentNode, 'tc') && getWordElementsByLocalName(paragraph.parentNode, 'p').length <= 1) {
+            return false;
+        }
         return removeNode(paragraph);
     }
 
     const childrenToMove = Array.from(paragraph.childNodes || []).filter(child => !isWordElement(child, 'pPr'));
-    const insertionPoint = nextParagraph.firstChild || null;
+    let insertionPoint = nextParagraph.firstChild || null;
+    if (isWordElement(insertionPoint, 'pPr')) {
+        insertionPoint = insertionPoint.nextSibling || null;
+    }
     for (const child of childrenToMove) {
         nextParagraph.insertBefore(child, insertionPoint);
     }
@@ -214,8 +238,12 @@ export function acceptTrackedChangesInOoxml(oxml, options = {}) {
         }
     }
 
+    const serializedOxml = parseResult.isFragmentWrapped
+        ? Array.from(xmlDoc.documentElement.childNodes).map(n => serializer.serializeToString(n)).join('')
+        : serializer.serializeToString(xmlDoc);
+
     return {
-        oxml: serializer.serializeToString(xmlDoc),
+        oxml: serializedOxml,
         hasChanges: acceptedCount > 0,
         acceptedCount,
         warnings
@@ -395,8 +423,12 @@ export function rejectTrackedChangesInOoxml(oxml, options = {}) {
         }
     }
 
+    const serializedOxml = parseResult.isFragmentWrapped
+        ? Array.from(xmlDoc.documentElement.childNodes).map(n => serializer.serializeToString(n)).join('')
+        : serializer.serializeToString(xmlDoc);
+
     return {
-        oxml: serializer.serializeToString(xmlDoc),
+        oxml: serializedOxml,
         hasChanges: rejectedCount > 0,
         rejectedCount,
         warnings

package/services/revision-token.js

@@ -0,0 +1,290 @@
+/**
+ * Revision token framing and calculation for docx-redline-js.
+ *
+ * Implements unambiguous big-endian binary framing to generate cryptographic
+ * revision tokens over package entries or document parts.
+ */
+
+const textEncoder = new TextEncoder();
+
+/**
+ * Normalizes an OPC entry or part name to canonical forward-slash form.
+ *
+ * @param {string} name - Raw entry name
+ * @returns {string} Normalized entry name
+ */
+export function normalizeOpcEntryName(name) {
+    if (typeof name !== 'string') {
+        throw new TypeError(`Entry name must be a string, got ${typeof name}`);
+    }
+    let normalized = name.replace(/\\/g, '/');
+    normalized = normalized.replace(/^\/+/, '');
+    while (normalized.startsWith('./')) {
+        normalized = normalized.slice(2);
+    }
+    normalized = normalized.replace(/\/+/g, '/');
+    if (!normalized) {
+        throw new Error(`Invalid empty entry name: "${name}"`);
+    }
+    return normalized;
+}
+
+/**
+ * Builds the binary framing buffer for a revision token according to the specification:
+ *
+ * magic = "docx-redline-revision-token\0"
+ * version = uint32be(1)
+ * scopeLength + scope
+ * entryCount
+ * for each entry sorted by normalized name:
+ *   nameLength + name
+ *   payloadLength + payload
+ *
+ * @param {{ scope: string, entries: Array<{ name: string, payload: Uint8Array|string|Buffer }|Array> }} options
+ * @returns {{ framing: Uint8Array, scope: string, version: number, coveredParts: string[] }}
+ */
+export function buildRevisionTokenFraming({ scope, entries = [] }) {
+    if (typeof scope !== 'string' || !scope) {
+        throw new TypeError('Revision token scope must be a non-empty string.');
+    }
+    const magicBytes = textEncoder.encode('docx-redline-revision-token\0');
+    const version = 1;
+    const scopeBytes = textEncoder.encode(scope);
+
+    const normalizedEntries = [];
+    const seenNames = new Set();
+
+    const rawList = Array.isArray(entries)
+        ? entries
+        : (entries instanceof Map ? Array.from(entries.entries()) : Object.entries(entries || {}));
+
+    for (const item of rawList) {
+        if (!item) continue;
+        const rawName = Array.isArray(item) ? item[0] : item.name;
+        const rawPayload = Array.isArray(item) ? item[1] : (item.payload ?? item.bytes);
+
+        if (rawName == null) continue;
+        const normName = normalizeOpcEntryName(String(rawName));
+        if (seenNames.has(normName)) {
+            throw new Error(`Duplicate normalized entry path detected: "${normName}"`);
+        }
+        seenNames.add(normName);
+
+        let payloadBytes;
+        if (typeof rawPayload === 'string') {
+            payloadBytes = textEncoder.encode(rawPayload);
+        } else if (rawPayload instanceof Uint8Array) {
+            payloadBytes = rawPayload;
+        } else if (rawPayload && typeof rawPayload.length === 'number') {
+            payloadBytes = new Uint8Array(rawPayload);
+        } else {
+            payloadBytes = new Uint8Array(0);
+        }
+
+        normalizedEntries.push({
+            name: normName,
+            nameBytes: textEncoder.encode(normName),
+            payloadBytes
+        });
+    }
+
+    // Sort entries by normalized name in binary codepoint order
+    normalizedEntries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    let totalSize = magicBytes.length + 4 + 4 + scopeBytes.length + 4;
+    for (const e of normalizedEntries) {
+        totalSize += 4 + e.nameBytes.length + 4 + e.payloadBytes.length;
+    }
+
+    const buffer = new Uint8Array(totalSize);
+    const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    let offset = 0;
+
+    // magic
+    buffer.set(magicBytes, offset);
+    offset += magicBytes.length;
+
+    // version uint32be
+    view.setUint32(offset, version, false);
+    offset += 4;
+
+    // scopeLength uint32be
+    view.setUint32(offset, scopeBytes.length, false);
+    offset += 4;
+
+    // scope
+    buffer.set(scopeBytes, offset);
+    offset += scopeBytes.length;
+
+    // entryCount uint32be
+    view.setUint32(offset, normalizedEntries.length, false);
+    offset += 4;
+
+    for (const e of normalizedEntries) {
+        // nameLength uint32be
+        view.setUint32(offset, e.nameBytes.length, false);
+        offset += 4;
+        buffer.set(e.nameBytes, offset);
+        offset += e.nameBytes.length;
+
+        // payloadLength uint32be
+        view.setUint32(offset, e.payloadBytes.length, false);
+        offset += 4;
+        buffer.set(e.payloadBytes, offset);
+        offset += e.payloadBytes.length;
+    }
+
+    return {
+        framing: buffer,
+        scope,
+        version,
+        coveredParts: normalizedEntries.map(e => e.name)
+    };
+}
+
+/**
+ * Calculates a SHA-256 revision token asynchronously using Web Crypto or a custom digest function.
+ *
+ * @param {{ scope: string, entries: Array<any>, digestFn?: (bytes: Uint8Array) => Promise<string> }} options
+ * @returns {Promise<{ algorithm: 'sha256', version: number, scope: string, value: string, coveredParts: string[] }>}
+ */
+export async function computeRevisionToken({ scope, entries = [], digestFn = null }) {
+    const { framing, coveredParts, version } = buildRevisionTokenFraming({ scope, entries });
+
+    let hashHex = '';
+    if (typeof digestFn === 'function') {
+        hashHex = await digestFn(framing);
+    } else if (typeof globalThis.crypto?.subtle?.digest === 'function') {
+        const hashBuf = await globalThis.crypto.subtle.digest('SHA-256', framing);
+        const hashBytes = new Uint8Array(hashBuf);
+        hashHex = Array.from(hashBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+    } else {
+        throw new Error('No crypto provider available for SHA-256 revision token computation.');
+    }
+
+    return {
+        algorithm: 'sha256',
+        version,
+        scope,
+        value: hashHex,
+        coveredParts
+    };
+}
+
+/**
+ * Calculates a SHA-256 revision token synchronously using a provided digest function.
+ *
+ * @param {{ scope: string, entries: Array<any>, digestFn: (bytes: Uint8Array) => string }} options
+ * @returns {{ algorithm: 'sha256', version: number, scope: string, value: string, coveredParts: string[] }}
+ */
+export function computeRevisionTokenSync({ scope, entries = [], digestFn }) {
+    if (typeof digestFn !== 'function') {
+        throw new TypeError('computeRevisionTokenSync requires a synchronous digestFn.');
+    }
+    const { framing, coveredParts, version } = buildRevisionTokenFraming({ scope, entries });
+    const hashHex = digestFn(framing);
+    return {
+        algorithm: 'sha256',
+        version,
+        scope,
+        value: hashHex,
+        coveredParts
+    };
+}
+
+/**
+ * Extracts entry records from document parts descriptor.
+ *
+ * @param {object} parts - Document parts object
+ * @returns {Array<{ name: string, payload: any }>}
+ */
+export function extractDocumentPartsEntries(parts) {
+    const entries = [];
+    if (parts?.documentXml) {
+        entries.push({ name: 'word/document.xml', payload: parts.documentXml });
+    }
+    if (parts?.commentsXml) {
+        entries.push({ name: 'word/comments.xml', payload: parts.commentsXml });
+    }
+    if (parts?.commentsExtendedXml) {
+        entries.push({ name: 'word/commentsExtended.xml', payload: parts.commentsExtendedXml });
+    }
+    if (parts?.numberingXml) {
+        entries.push({ name: 'word/numbering.xml', payload: parts.numberingXml });
+    }
+    if (parts?.stylesXml) {
+        entries.push({ name: 'word/styles.xml', payload: parts.stylesXml });
+    }
+    if (parts?.parts instanceof Map) {
+        for (const [name, payload] of parts.parts.entries()) {
+            entries.push({ name, payload });
+        }
+    } else if (parts?.additionalParts && typeof parts.additionalParts === 'object') {
+        for (const [name, payload] of Object.entries(parts.additionalParts)) {
+            entries.push({ name, payload });
+        }
+    }
+    return entries;
+}
+
+/**
+ * Computes a revision token for document parts asynchronously.
+ *
+ * @param {object} parts - Document parts
+ * @param {object} [options={}] - Options
+ * @returns {Promise<{ algorithm: 'sha256', version: number, scope: 'document-parts', value: string, coveredParts: string[] }>}
+ */
+export async function computeDocumentPartsRevisionToken(parts, options = {}) {
+    const entries = extractDocumentPartsEntries(parts);
+    return computeRevisionToken({
+        scope: 'document-parts',
+        entries,
+        digestFn: options.digestFn
+    });
+}
+
+/**
+ * Validates the structure and syntax of an incoming revision token object.
+ *
+ * @param {any} token
+ * @returns {{ valid: boolean, error?: { code: string, message: string } }}
+ */
+export function validateRevisionToken(token) {
+    if (!token || typeof token !== 'object') {
+        return { valid: false, error: { code: 'INVALID_REVISION_TOKEN', message: 'Revision token must be an object.' } };
+    }
+    if (token.algorithm !== 'sha256') {
+        return { valid: false, error: { code: 'INVALID_REVISION_TOKEN', message: `Unsupported revision token algorithm: "${token.algorithm}". Expected "sha256".` } };
+    }
+    if (token.version !== 1) {
+        return { valid: false, error: { code: 'INVALID_REVISION_TOKEN', message: `Unsupported revision token version: "${token.version}". Expected 1.` } };
+    }
+    if (token.scope !== 'document-parts' && token.scope !== 'package') {
+        return { valid: false, error: { code: 'INVALID_REVISION_TOKEN', message: `Unsupported revision token scope: "${token.scope}". Expected "document-parts" or "package".` } };
+    }
+    if (typeof token.value !== 'string' || !/^[0-9a-f]{64}$/i.test(token.value.trim())) {
+        return { valid: false, error: { code: 'INVALID_REVISION_TOKEN', message: 'Revision token value must be a 64-character hex string.' } };
+    }
+    return { valid: true };
+}
+
+/**
+ * Compares two revision token values using timing-safe byte comparison.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function areRevisionTokensEqual(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string') return false;
+    const aNorm = a.trim().toLowerCase();
+    const bNorm = b.trim().toLowerCase();
+    if (aNorm.length !== bNorm.length) return false;
+    const aBuf = textEncoder.encode(aNorm);
+    const bBuf = textEncoder.encode(bNorm);
+    let diff = 0;
+    for (let i = 0; i < aBuf.length; i++) {
+        diff |= aBuf[i] ^ bBuf[i];
+    }
+    return diff === 0;
+}

package/services/standalone-docx-plumbing.js

@@ -3,6 +3,7 @@
  */
 
 import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import { warn as logWarning } from '../adapters/logger.js';
 
 const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
 const NS_CT = 'http://schemas.openxmlformats.org/package/2006/content-types';
@@ -11,10 +12,13 @@ const NUMBERING_REL_TYPE = 'http://schemas.openxmlformats.org/officeDocument/200
 const NUMBERING_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml';
 const COMMENTS_REL_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments';
 const COMMENTS_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml';
+const COMMENTS_EXTENDED_REL_TYPE = 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended';
+const COMMENTS_EXTENDED_CONTENT_TYPE = 'application/vnd.ms-word.commentsExtended+xml';
 
 const DOCUMENT_PATH = 'word/document.xml';
 const NUMBERING_PATH = 'word/numbering.xml';
 const COMMENTS_PATH = 'word/comments.xml';
+const COMMENTS_EXTENDED_PATH = 'word/commentsExtended.xml';
 const CONTENT_TYPES_PATH = '[Content_Types].xml';
 const DOCUMENT_RELS_PATH = 'word/_rels/document.xml.rels';
 
@@ -193,10 +197,14 @@ export function extractReplacementNodesFromOoxml(outputOxml) {
 
 function upsertContentTypeOverride(ctDoc, partName, contentType) {
     const overrides = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override'));
-    const hasOverride = overrides.some(
+    const existingOverride = overrides.find(
         override => (override.getAttribute('PartName') || '').toLowerCase() === String(partName).toLowerCase()
     );
-    if (hasOverride) return false;
+    if (existingOverride) {
+        if ((existingOverride.getAttribute('ContentType') || '') === contentType) return false;
+        existingOverride.setAttribute('ContentType', contentType);
+        return true;
+    }
 
     const override = ctDoc.createElementNS(NS_CT, 'Override');
     override.setAttribute('PartName', partName);
@@ -205,7 +213,7 @@ function upsertContentTypeOverride(ctDoc, partName, contentType) {
     return true;
 }
 
-function upsertDocumentRelationship(relsDoc, relType, target) {
+function upsertDocumentRelationship(relsDoc, relType, target, options = {}) {
     const relsRoot = relsDoc.getElementsByTagNameNS('*', 'Relationships')[0] || relsDoc.documentElement;
     const rels = Array.from(relsRoot.getElementsByTagNameNS('*', 'Relationship'));
     const hasRel = rels.some(rel => (rel.getAttribute('Type') || '') === relType);
@@ -220,11 +228,17 @@ function upsertDocumentRelationship(relsDoc, relType, target) {
         }
     }
 
+    const newId = `rId${maxId + 1}`;
     const rel = relsDoc.createElementNS(NS_RELS, 'Relationship');
-    rel.setAttribute('Id', `rId${maxId + 1}`);
+    rel.setAttribute('Id', newId);
     rel.setAttribute('Type', relType);
     rel.setAttribute('Target', target);
     relsRoot.appendChild(rel);
+    if (options?._receiptCollector) {
+        options._receiptCollector.recordRelationship(newId);
+    } else if (options?._documentOperationSession?.receiptCollector) {
+        options._documentOperationSession.receiptCollector.recordRelationship(newId);
+    }
     return true;
 }
 
@@ -249,10 +263,14 @@ export async function ensureNumberingArtifactsInZip(zip, numberingXmlList, optio
     const mergeNumberingXml = typeof options?.mergeNumberingXml === 'function'
         ? options.mergeNumberingXml
         : null;
+    const onWarn = typeof options?.onWarn === 'function' ? options.onWarn : logWarning;
     const incomingPayloads = (Array.isArray(numberingXmlList) ? numberingXmlList : [numberingXmlList]).filter(Boolean);
     if (incomingPayloads.length === 0) return;
 
     const existing = await readZipText(zip, NUMBERING_PATH);
+    if (existing && !mergeNumberingXml) {
+        onWarn('[Deprecation] Replacing an existing numbering.xml without mergeNumberingXml is deprecated and will throw in the next major version.');
+    }
     let mergedNumberingXml = existing || null;
     for (const incomingNumberingXml of incomingPayloads) {
         if (!mergedNumberingXml) {
@@ -284,7 +302,7 @@ export async function ensureNumberingArtifactsInZip(zip, numberingXmlList, optio
     const relsText = await readZipText(zip, DOCUMENT_RELS_PATH);
     if (relsText) {
         const relsDoc = parseXmlStrictStandalone(relsText, DOCUMENT_RELS_PATH);
-        if (upsertDocumentRelationship(relsDoc, NUMBERING_REL_TYPE, 'numbering.xml')) {
+        if (upsertDocumentRelationship(relsDoc, NUMBERING_REL_TYPE, 'numbering.xml', options)) {
             zip.file(DOCUMENT_RELS_PATH, serializer.serializeToString(relsDoc));
         }
     }
@@ -303,7 +321,7 @@ export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {
 
     const serializer = createSerializer();
     const existingText = await readZipText(zip, COMMENTS_PATH);
-    if (!existingText) {
+    if (!existingText || options.replaceExisting === true) {
         onInfo('[Demo] Adding comments.xml');
         zip.file(COMMENTS_PATH, commentsXml);
     } else {
@@ -336,7 +354,29 @@ export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {
     const relsText = await readZipText(zip, DOCUMENT_RELS_PATH);
     if (relsText) {
         const relsDoc = parseXmlStrictStandalone(relsText, DOCUMENT_RELS_PATH);
-        if (upsertDocumentRelationship(relsDoc, COMMENTS_REL_TYPE, 'comments.xml')) {
+        if (upsertDocumentRelationship(relsDoc, COMMENTS_REL_TYPE, 'comments.xml', options)) {
+            zip.file(DOCUMENT_RELS_PATH, serializer.serializeToString(relsDoc));
+        }
+    }
+}
+
+/** Ensures the modern Word comment-threading part and package metadata exist. */
+export async function ensureCommentsExtendedArtifactsInZip(zip, commentsExtendedXml, options = {}) {
+    if (!commentsExtendedXml) return;
+    parseXmlStrictStandalone(commentsExtendedXml, 'word/commentsExtended.xml');
+    zip.file(COMMENTS_EXTENDED_PATH, commentsExtendedXml);
+    const serializer = createSerializer();
+    const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
+    if (ctText) {
+        const ctDoc = parseXmlStrictStandalone(ctText, CONTENT_TYPES_PATH);
+        if (upsertContentTypeOverride(ctDoc, '/word/commentsExtended.xml', COMMENTS_EXTENDED_CONTENT_TYPE)) {
+            zip.file(CONTENT_TYPES_PATH, serializer.serializeToString(ctDoc));
+        }
+    }
+    const relsText = await readZipText(zip, DOCUMENT_RELS_PATH);
+    if (relsText) {
+        const relsDoc = parseXmlStrictStandalone(relsText, DOCUMENT_RELS_PATH);
+        if (upsertDocumentRelationship(relsDoc, COMMENTS_EXTENDED_REL_TYPE, 'commentsExtended.xml', options)) {
             zip.file(DOCUMENT_RELS_PATH, serializer.serializeToString(relsDoc));
         }
     }
@@ -395,6 +435,10 @@ export async function validateDocxPackage(zip) {
 
     const numberingXml = await readZipText(zip, NUMBERING_PATH);
     const commentsXml = await readZipText(zip, COMMENTS_PATH);
+    const commentsExtendedXml = await readZipText(zip, COMMENTS_EXTENDED_PATH);
+    if (commentsExtendedXml && !commentsXml) {
+        throw new Error('Validation failed: commentsExtended part exists but comments part is missing');
+    }
 
     if (numberingXml) {
         parseXmlStrictStandalone(numberingXml, NUMBERING_PATH);
@@ -403,7 +447,66 @@ export async function validateDocxPackage(zip) {
     }
 
     if (commentsXml) {
-        parseXmlStrictStandalone(commentsXml, COMMENTS_PATH);
+        const commentsDoc = parseXmlStrictStandalone(commentsXml, COMMENTS_PATH);
+        const idsFor = (doc, localName) => Array.from(doc.getElementsByTagNameNS(NS_W, localName))
+            .map(node => node.getAttribute('w:id') || node.getAttribute('id'))
+            .filter(id => id !== '');
+        const starts = new Set(idsFor(documentDoc, 'commentRangeStart'));
+        const ends = new Set(idsFor(documentDoc, 'commentRangeEnd'));
+        const references = new Set(idsFor(documentDoc, 'commentReference'));
+        const definitionIds = idsFor(commentsDoc, 'comment');
+        const definitions = new Set(definitionIds);
+        const sorted = ids => Array.from(ids).sort((a, b) => Number(a) - Number(b) || a.localeCompare(b));
+        const difference = (left, right) => sorted(new Set(Array.from(left).filter(id => !right.has(id))));
+
+        const duplicateDefinitions = sorted(new Set(definitionIds.filter((id, index) => definitionIds.indexOf(id) !== index)));
+        if (duplicateDefinitions.length > 0) {
+            throw new Error(`Validation failed: duplicate comment definitions for id(s): ${duplicateDefinitions.join(', ')}`);
+        }
+        const startsWithoutEnds = difference(starts, ends);
+        const endsWithoutStarts = difference(ends, starts);
+        if (startsWithoutEnds.length > 0 || endsWithoutStarts.length > 0) {
+            const parts = [];
+            if (startsWithoutEnds.length > 0) parts.push(`start without end: ${startsWithoutEnds.join(', ')}`);
+            if (endsWithoutStarts.length > 0) parts.push(`end without start: ${endsWithoutStarts.join(', ')}`);
+            throw new Error(`Validation failed: unbalanced comment range marker(s) (${parts.join('; ')})`);
+        }
+        const rangesWithoutReferences = difference(new Set([...starts, ...ends]), references);
+        if (rangesWithoutReferences.length > 0) {
+            throw new Error(`Validation failed: comment range has no reference for id(s): ${rangesWithoutReferences.join(', ')}`);
+        }
+        const usagesWithoutDefinitions = difference(new Set([...starts, ...ends, ...references]), definitions);
+        if (usagesWithoutDefinitions.length > 0) {
+            throw new Error(`Validation failed: comment usage has no definition for id(s): ${usagesWithoutDefinitions.join(', ')}`);
+        }
+        const replyCommentIds = new Set();
+        if (commentsExtendedXml) {
+            const extendedDoc = parseXmlStrictStandalone(commentsExtendedXml, COMMENTS_EXTENDED_PATH);
+            const paraIdToCommentId = new Map();
+            for (const comment of Array.from(commentsDoc.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) paraIdToCommentId.set(paraId.toUpperCase(), id);
+            }
+            const knownParaIds = new Set(paraIdToCommentId.keys());
+            const extendedParaIds = new Set();
+            for (const entry of Array.from(extendedDoc.getElementsByTagNameNS('*', 'commentEx'))) {
+                const paraId = entry.getAttribute('w15:paraId') || entry.getAttribute('paraId');
+                const parentParaId = entry.getAttribute('w15:paraIdParent') || entry.getAttribute('paraIdParent');
+                if (!paraId || !knownParaIds.has(paraId.toUpperCase())) throw new Error(`Validation failed: commentsExtended entry has no matching comment paragraph: ${paraId || '(missing)'}`);
+                if (extendedParaIds.has(paraId.toUpperCase())) throw new Error(`Validation failed: duplicate commentsExtended entry for paraId: ${paraId}`);
+                extendedParaIds.add(paraId.toUpperCase());
+                if (parentParaId) {
+                    if (!knownParaIds.has(parentParaId.toUpperCase())) throw new Error(`Validation failed: commentsExtended parent paragraph was not found: ${parentParaId}`);
+                    replyCommentIds.add(paraIdToCommentId.get(paraId.toUpperCase()));
+                }
+            }
+        }
+        const definitionsWithoutReferences = difference(new Set([...definitions].filter(id => !replyCommentIds.has(id))), references);
+        if (definitionsWithoutReferences.length > 0) {
+            throw new Error(`Validation failed: comment definition has no document reference for id(s): ${definitionsWithoutReferences.join(', ')}`);
+        }
     } else if (hasCommentUsage) {
         throw new Error('Validation failed: comments used but part missing');
     }
@@ -451,4 +554,16 @@ export async function validateDocxPackage(zip) {
             throw new Error('Validation failed: comments rel missing');
         }
     }
+
+    if (commentsExtendedXml) {
+        const hasContentType = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override')).some(override =>
+            (override.getAttribute('PartName') || '').toLowerCase() === '/word/commentsextended.xml'
+            && (override.getAttribute('ContentType') || '') === COMMENTS_EXTENDED_CONTENT_TYPE
+        );
+        const hasRelationship = Array.from(relsDoc.getElementsByTagNameNS('*', 'Relationship')).some(rel =>
+            (rel.getAttribute('Type') || '') === COMMENTS_EXTENDED_REL_TYPE
+        );
+        if (!hasContentType) throw new Error('Validation failed: commentsExtended CT override missing');
+        if (!hasRelationship) throw new Error('Validation failed: commentsExtended rel missing');
+    }
 }