@ansonlai/docx-redline-js 0.8.0 → 0.8.1

package/services/standalone-docx-plumbing.js

@@ -1,569 +1,631 @@
-/**
- * Standalone OOXML/Docx plumbing helpers shared by browser and Node hosts.
- */
-
-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';
-const NS_RELS = 'http://schemas.openxmlformats.org/package/2006/relationships';
-const NUMBERING_REL_TYPE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering';
-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';
-
-export function parseXmlStrictStandalone(xmlText, label = 'xml') {
-    const parsed = parseOoxmlSafe(xmlText, 'application/xml');
-    if (parsed.error || !parsed.doc) {
-        const error = new Error(`[XML parse error] ${label}: ${parsed.error?.message || 'Unknown'}`);
-        error.code = 'PARSE_ERROR';
-        throw error;
-    }
-    return parsed.doc;
-}
-
-function isSectionPropertiesElement(node) {
-    return !!node && node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'sectPr';
-}
-
-export function getBodyElementFromDocument(xmlDoc) {
-    return xmlDoc.getElementsByTagNameNS('*', 'body')[0] || null;
-}
-
-function getDirectSectionProperties(body) {
-    for (const child of Array.from(body.childNodes || [])) {
-        if (isSectionPropertiesElement(child)) return child;
-    }
-    return null;
-}
-
-export function insertBodyElementBeforeSectPr(body, element) {
-    const sectPr = getDirectSectionProperties(body);
-    if (sectPr) {
-        body.insertBefore(element, sectPr);
-    } else {
-        body.appendChild(element);
-    }
-}
-
-export function normalizeBodySectionOrderStandalone(xmlDoc) {
-    const body = getBodyElementFromDocument(xmlDoc);
-    if (!body) return;
-    const sectPr = getDirectSectionProperties(body);
-    if (!sectPr) return;
-    let cursor = sectPr.nextSibling;
-    while (cursor) {
-        const next = cursor.nextSibling;
-        if (cursor.nodeType === 1) {
-            body.insertBefore(cursor, sectPr);
-        }
-        cursor = next;
-    }
-}
-
-/**
- * Flattens nested table-cell paragraphs (`w:tc > w:p > w:p`) by promoting
- * inner paragraphs to direct `w:tc` children.
- *
- * @param {Document} xmlDoc
- * @param {{ onInfo?: (message: string) => void }} [options]
- * @returns {number} number of nested paragraphs fixed
- */
-export function sanitizeNestedParagraphsInTables(xmlDoc, options = {}) {
-    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
-    const tcs = xmlDoc.getElementsByTagNameNS(NS_W, 'tc');
-    let fixed = 0;
-    for (const tc of Array.from(tcs)) {
-        const outerParagraphs = Array.from(tc.childNodes || []).filter(
-            node => node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
-        );
-        for (const outerParagraph of outerParagraphs) {
-            const innerParagraphs = Array.from(outerParagraph.childNodes || []).filter(
-                node => node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
-            );
-            for (const innerParagraph of innerParagraphs) {
-                tc.insertBefore(innerParagraph, outerParagraph);
-                fixed += 1;
-            }
-        }
-    }
-    if (fixed > 0) {
-        onInfo(`[Sanitize] Fixed ${fixed} nested w:p element(s) in table cells`);
-    }
-    return fixed;
-}
-
-export function getPackagePartName(partElement) {
-    return partElement.getAttribute('pkg:name') || partElement.getAttribute('name') || '';
-}
-
-function extractFromPackageXml(packageXml) {
-    const serializer = createSerializer();
-    const pkgDoc = parseXmlStrictStandalone(packageXml, 'package OOXML');
-    const parts = Array.from(pkgDoc.getElementsByTagNameNS('*', 'part'));
-    const documentPart = parts.find(part => getPackagePartName(part) === '/word/document.xml');
-    if (!documentPart) {
-        throw new Error('Package output missing /word/document.xml part');
-    }
-
-    const xmlData = documentPart.getElementsByTagNameNS('*', 'xmlData')[0];
-    if (!xmlData) {
-        throw new Error('Package document part missing pkg:xmlData');
-    }
-    const documentNode = Array.from(xmlData.childNodes || []).find(node => node.nodeType === 1);
-    if (!documentNode) {
-        throw new Error('Package document part missing XML payload');
-    }
-
-    const body = documentNode.getElementsByTagNameNS('*', 'body')[0];
-    const replacementNodes = body
-        ? Array.from(body.childNodes || []).filter(node => node.nodeType === 1 && !isSectionPropertiesElement(node))
-        : [documentNode];
-
-    const numberingPart = parts.find(part => getPackagePartName(part) === '/word/numbering.xml');
-    let numberingXml = null;
-    if (numberingPart) {
-        const numberingXmlData = numberingPart.getElementsByTagNameNS('*', 'xmlData')[0];
-        const numberingNode = numberingXmlData
-            ? Array.from(numberingXmlData.childNodes || []).find(node => node.nodeType === 1)
-            : null;
-        if (numberingNode) {
-            numberingXml = serializer.serializeToString(numberingNode);
-        }
-    }
-
-    return {
-        replacementNodes,
-        numberingXml,
-        sourceType: 'package'
-    };
-}
-
-/**
- * Extracts replacement nodes and optional numbering payload from engine output.
- *
- * @param {string} outputOxml
- * @returns {{ replacementNodes: Element[], numberingXml: string|null, sourceType: 'package'|'document'|'fragment' }}
- */
-export function extractReplacementNodesFromOoxml(outputOxml) {
-    if (typeof outputOxml !== 'string' || !outputOxml.trim()) {
-        return {
-            replacementNodes: [],
-            numberingXml: null,
-            sourceType: 'fragment',
-            status: 'error',
-            error: { code: 'PARSE_ERROR', message: 'Reconciliation engine returned no OOXML payload for this operation' }
-        };
-    }
-
-    try {
-        if (outputOxml.includes('<pkg:package')) {
-            return extractFromPackageXml(outputOxml);
-        }
-
-        if (outputOxml.includes('<w:document')) {
-            const doc = parseXmlStrictStandalone(outputOxml, 'document OOXML');
-            const body = doc.getElementsByTagNameNS('*', 'body')[0];
-            const replacementNodes = body
-                ? Array.from(body.childNodes || []).filter(node => node.nodeType === 1 && !isSectionPropertiesElement(node))
-                : Array.from(doc.childNodes || []).filter(node => node.nodeType === 1);
-            return { replacementNodes, numberingXml: null, sourceType: 'document' };
-        }
-
-        const wrapped = `<root xmlns:w="${NS_W}">${outputOxml}</root>`;
-        const fragmentDoc = parseXmlStrictStandalone(wrapped, 'OOXML fragment');
-        const replacementNodes = Array.from(fragmentDoc.documentElement.childNodes || []).filter(node => node.nodeType === 1);
-        return { replacementNodes, numberingXml: null, sourceType: 'fragment' };
-    } catch (caught) {
-        return {
-            replacementNodes: [],
-            numberingXml: null,
-            sourceType: 'fragment',
-            status: 'error',
-            error: { code: 'PARSE_ERROR', message: caught?.message || 'Could not parse OOXML payload.' }
-        };
-    }
-}
-
-function upsertContentTypeOverride(ctDoc, partName, contentType) {
-    const overrides = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override'));
-    const existingOverride = overrides.find(
-        override => (override.getAttribute('PartName') || '').toLowerCase() === String(partName).toLowerCase()
-    );
-    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);
-    override.setAttribute('ContentType', contentType);
-    ctDoc.documentElement.appendChild(override);
-    return true;
-}
-
-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);
-    if (hasRel) return false;
-
-    let maxId = 0;
-    for (const rel of rels) {
-        const idValue = rel.getAttribute('Id') || '';
-        const idNum = Number.parseInt(idValue.replace(/^rId/i, ''), 10);
-        if (Number.isFinite(idNum)) {
-            maxId = Math.max(maxId, idNum);
-        }
-    }
-
-    const newId = `rId${maxId + 1}`;
-    const rel = relsDoc.createElementNS(NS_RELS, 'Relationship');
-    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;
-}
-
-async function readZipText(zip, filePath) {
-    const entry = zip.file(filePath);
-    if (!entry) return null;
-    return entry.async('string');
-}
-
-/**
- * Ensures numbering part + package metadata exist and merges numbering payloads.
- *
- * @param {any} zip
- * @param {string|string[]|null|undefined} numberingXmlList
- * @param {{
- *   mergeNumberingXml?: ((existingXml: string, incomingXml: string) => string),
- *   onInfo?: (message: string) => void
- * }} [options]
- */
-export async function ensureNumberingArtifactsInZip(zip, numberingXmlList, options = {}) {
-    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
-    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) {
-            mergedNumberingXml = incomingNumberingXml;
-            continue;
-        }
-        mergedNumberingXml = mergeNumberingXml
-            ? mergeNumberingXml(mergedNumberingXml, incomingNumberingXml)
-            : incomingNumberingXml;
-    }
-
-    if (!existing) {
-        onInfo('[Demo] Adding numbering.xml');
-    } else {
-        onInfo('[Demo] Merging numbering.xml payload(s) into existing numbering definitions');
-    }
-    zip.file(NUMBERING_PATH, mergedNumberingXml);
-
-    const serializer = createSerializer();
-
-    const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
-    if (ctText) {
-        const ctDoc = parseXmlStrictStandalone(ctText, CONTENT_TYPES_PATH);
-        if (upsertContentTypeOverride(ctDoc, '/word/numbering.xml', NUMBERING_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, NUMBERING_REL_TYPE, 'numbering.xml', options)) {
-            zip.file(DOCUMENT_RELS_PATH, serializer.serializeToString(relsDoc));
-        }
-    }
-}
-
-/**
- * Ensures comments part + package metadata exist and merges incoming comments.
- *
- * @param {any} zip
- * @param {string|null|undefined} commentsXml
- * @param {{ onInfo?: (message: string) => void }} [options]
- */
-export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {}) {
-    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
-    if (!commentsXml) return;
-
-    const serializer = createSerializer();
-    const existingText = await readZipText(zip, COMMENTS_PATH);
-    if (!existingText || options.replaceExisting === true) {
-        onInfo('[Demo] Adding comments.xml');
-        zip.file(COMMENTS_PATH, commentsXml);
-    } else {
-        const existingDoc = parseXmlStrictStandalone(existingText, 'word/comments.xml (existing)');
-        const incomingDoc = parseXmlStrictStandalone(commentsXml, 'word/comments.xml (incoming)');
-        const existingRoot = existingDoc.documentElement;
-        const existingIds = new Set(
-            Array.from(existingRoot.getElementsByTagNameNS(NS_W, 'comment'))
-                .map(comment => comment.getAttribute('w:id') || comment.getAttribute('id'))
-                .filter(Boolean)
-        );
-        for (const incomingComment of Array.from(incomingDoc.documentElement.getElementsByTagNameNS(NS_W, 'comment'))) {
-            const id = incomingComment.getAttribute('w:id') || incomingComment.getAttribute('id');
-            if (id && existingIds.has(id)) {
-                throw new Error(`Duplicate comment id: ${id}`);
-            }
-            existingRoot.appendChild(existingDoc.importNode(incomingComment, true));
-        }
-        zip.file(COMMENTS_PATH, serializer.serializeToString(existingDoc));
-    }
-
-    const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
-    if (ctText) {
-        const ctDoc = parseXmlStrictStandalone(ctText, CONTENT_TYPES_PATH);
-        if (upsertContentTypeOverride(ctDoc, '/word/comments.xml', COMMENTS_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_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));
-        }
-    }
-}
-
-/**
- * Validates core package integrity for document/comments/numbering artifacts.
- *
- * @param {any} zip
- */
-export async function validateDocxPackage(zip) {
-    const documentXml = await readZipText(zip, DOCUMENT_PATH);
-    if (!documentXml) {
-        throw new Error('Validation failed: missing word/document.xml');
-    }
-
-    const documentDoc = parseXmlStrictStandalone(documentXml, DOCUMENT_PATH);
-    normalizeBodySectionOrderStandalone(documentDoc);
-    const body = getBodyElementFromDocument(documentDoc);
-    if (!body) {
-        throw new Error('Validation failed: word/document.xml has no w:body');
-    }
-
-    const directBodyElements = Array.from(body.childNodes || []).filter(node => node.nodeType === 1);
-    const sectPrIndexes = directBodyElements
-        .map((node, index) => ({ node, index }))
-        .filter(entry => isSectionPropertiesElement(entry.node))
-        .map(entry => entry.index);
-
-    if (sectPrIndexes.length > 1) {
-        throw new Error('Validation failed: multiple body-level w:sectPr');
-    }
-    if (sectPrIndexes.length === 1 && sectPrIndexes[0] !== directBodyElements.length - 1) {
-        throw new Error('Validation failed: w:sectPr not last');
-    }
-
-    const tcs = documentDoc.getElementsByTagNameNS(NS_W, 'tc');
-    for (const tc of Array.from(tcs)) {
-        for (const child of Array.from(tc.childNodes || []).filter(node => node.nodeType === 1)) {
-            if (child.namespaceURI === NS_W && child.localName === 'p') {
-                const hasNestedParagraph = Array.from(child.childNodes || []).some(
-                    node => node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
-                );
-                if (hasNestedParagraph) {
-                    throw new Error('Validation failed: nested w:p');
-                }
-            }
-        }
-    }
-
-    const hasNumberingUsage = documentDoc.getElementsByTagNameNS(NS_W, 'numPr').length > 0;
-    const hasCommentUsage =
-        documentDoc.getElementsByTagNameNS(NS_W, 'commentRangeStart').length > 0
-        || documentDoc.getElementsByTagNameNS(NS_W, 'commentRangeEnd').length > 0
-        || documentDoc.getElementsByTagNameNS(NS_W, 'commentReference').length > 0;
-
-    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);
-    } else if (hasNumberingUsage) {
-        throw new Error('Validation failed: numbering used but part missing');
-    }
-
-    if (commentsXml) {
-        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');
-    }
-
-    const ctXml = await readZipText(zip, CONTENT_TYPES_PATH);
-    if (!ctXml) {
-        throw new Error(`Validation failed: missing ${CONTENT_TYPES_PATH}`);
-    }
-    const ctDoc = parseXmlStrictStandalone(ctXml, CONTENT_TYPES_PATH);
-
-    const relsXml = await readZipText(zip, DOCUMENT_RELS_PATH);
-    if (!relsXml) {
-        throw new Error(`Validation failed: missing ${DOCUMENT_RELS_PATH}`);
-    }
-    const relsDoc = parseXmlStrictStandalone(relsXml, DOCUMENT_RELS_PATH);
-
-    if (numberingXml) {
-        const hasNumberingContentType = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override')).some(override =>
-            (override.getAttribute('PartName') || '').toLowerCase() === '/word/numbering.xml'
-            && (override.getAttribute('ContentType') || '') === NUMBERING_CONTENT_TYPE
-        );
-        const hasNumberingRel = Array.from(relsDoc.getElementsByTagNameNS('*', 'Relationship')).some(rel =>
-            (rel.getAttribute('Type') || '') === NUMBERING_REL_TYPE
-        );
-        if (!hasNumberingContentType) {
-            throw new Error('Validation failed: numbering CT override missing');
-        }
-        if (!hasNumberingRel) {
-            throw new Error('Validation failed: numbering rel missing');
-        }
-    }
-
-    if (commentsXml) {
-        const hasCommentsContentType = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override')).some(override =>
-            (override.getAttribute('PartName') || '').toLowerCase() === '/word/comments.xml'
-            && (override.getAttribute('ContentType') || '') === COMMENTS_CONTENT_TYPE
-        );
-        const hasCommentsRel = Array.from(relsDoc.getElementsByTagNameNS('*', 'Relationship')).some(rel =>
-            (rel.getAttribute('Type') || '') === COMMENTS_REL_TYPE
-        );
-        if (!hasCommentsContentType) {
-            throw new Error('Validation failed: comments CT override missing');
-        }
-        if (!hasCommentsRel) {
-            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');
-    }
-}
+/**
+ * Standalone OOXML/Docx plumbing helpers shared by browser and Node hosts.
+ */
+
+import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import { warn as logWarning } from '../adapters/logger.js';
+import { commentParaId } from './comment-thread-parts.js';
+import { correctedContentTypeFor, getPartSpec } from './package-parts.js';
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const NS_CT = 'http://schemas.openxmlformats.org/package/2006/content-types';
+const NS_RELS = 'http://schemas.openxmlformats.org/package/2006/relationships';
+const NUMBERING = getPartSpec('numbering');
+const COMMENTS = getPartSpec('comments');
+const COMMENTS_EXTENDED = getPartSpec('commentsExtended');
+const NUMBERING_REL_TYPE = NUMBERING.relType;
+const NUMBERING_CONTENT_TYPE = NUMBERING.contentType;
+const COMMENTS_REL_TYPE = COMMENTS.relType;
+const COMMENTS_CONTENT_TYPE = COMMENTS.contentType;
+const COMMENTS_EXTENDED_REL_TYPE = COMMENTS_EXTENDED.relType;
+// Word's own value. The old 'application/vnd.ms-word.commentsExtended+xml' label is a registered legacy value.
+const COMMENTS_EXTENDED_CONTENT_TYPE = COMMENTS_EXTENDED.contentType;
+
+const DOCUMENT_PATH = getPartSpec('document').path;
+const NUMBERING_PATH = NUMBERING.path;
+const COMMENTS_PATH = COMMENTS.path;
+const COMMENTS_EXTENDED_PATH = COMMENTS_EXTENDED.path;
+const CONTENT_TYPES_PATH = '[Content_Types].xml';
+const DOCUMENT_RELS_PATH = 'word/_rels/document.xml.rels';
+
+export function parseXmlStrictStandalone(xmlText, label = 'xml') {
+    const parsed = parseOoxmlSafe(xmlText, 'application/xml');
+    if (parsed.error || !parsed.doc) {
+        const error = new Error(`[XML parse error] ${label}: ${parsed.error?.message || 'Unknown'}`);
+        error.code = 'PARSE_ERROR';
+        throw error;
+    }
+    return parsed.doc;
+}
+
+function isSectionPropertiesElement(node) {
+    return !!node && node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'sectPr';
+}
+
+export function getBodyElementFromDocument(xmlDoc) {
+    return xmlDoc.getElementsByTagNameNS('*', 'body')[0] || null;
+}
+
+function getDirectSectionProperties(body) {
+    for (const child of Array.from(body.childNodes || [])) {
+        if (isSectionPropertiesElement(child)) return child;
+    }
+    return null;
+}
+
+export function insertBodyElementBeforeSectPr(body, element) {
+    const sectPr = getDirectSectionProperties(body);
+    if (sectPr) {
+        body.insertBefore(element, sectPr);
+    } else {
+        body.appendChild(element);
+    }
+}
+
+export function normalizeBodySectionOrderStandalone(xmlDoc) {
+    const body = getBodyElementFromDocument(xmlDoc);
+    if (!body) return;
+    const sectPr = getDirectSectionProperties(body);
+    if (!sectPr) return;
+    let cursor = sectPr.nextSibling;
+    while (cursor) {
+        const next = cursor.nextSibling;
+        if (cursor.nodeType === 1) {
+            body.insertBefore(cursor, sectPr);
+        }
+        cursor = next;
+    }
+}
+
+/**
+ * Flattens nested table-cell paragraphs (`w:tc > w:p > w:p`) by promoting
+ * inner paragraphs to direct `w:tc` children.
+ *
+ * @param {Document} xmlDoc
+ * @param {{ onInfo?: (message: string) => void }} [options]
+ * @returns {number} number of nested paragraphs fixed
+ */
+export function sanitizeNestedParagraphsInTables(xmlDoc, options = {}) {
+    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
+    const tcs = xmlDoc.getElementsByTagNameNS(NS_W, 'tc');
+    let fixed = 0;
+    for (const tc of Array.from(tcs)) {
+        const outerParagraphs = Array.from(tc.childNodes || []).filter(
+            node => node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
+        );
+        for (const outerParagraph of outerParagraphs) {
+            const innerParagraphs = Array.from(outerParagraph.childNodes || []).filter(
+                node => node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
+            );
+            for (const innerParagraph of innerParagraphs) {
+                tc.insertBefore(innerParagraph, outerParagraph);
+                fixed += 1;
+            }
+        }
+    }
+    if (fixed > 0) {
+        onInfo(`[Sanitize] Fixed ${fixed} nested w:p element(s) in table cells`);
+    }
+    return fixed;
+}
+
+export function getPackagePartName(partElement) {
+    return partElement.getAttribute('pkg:name') || partElement.getAttribute('name') || '';
+}
+
+function extractFromPackageXml(packageXml) {
+    const serializer = createSerializer();
+    const pkgDoc = parseXmlStrictStandalone(packageXml, 'package OOXML');
+    const parts = Array.from(pkgDoc.getElementsByTagNameNS('*', 'part'));
+    const documentPart = parts.find(part => getPackagePartName(part) === '/word/document.xml');
+    if (!documentPart) {
+        throw new Error('Package output missing /word/document.xml part');
+    }
+
+    const xmlData = documentPart.getElementsByTagNameNS('*', 'xmlData')[0];
+    if (!xmlData) {
+        throw new Error('Package document part missing pkg:xmlData');
+    }
+    const documentNode = Array.from(xmlData.childNodes || []).find(node => node.nodeType === 1);
+    if (!documentNode) {
+        throw new Error('Package document part missing XML payload');
+    }
+
+    const body = documentNode.getElementsByTagNameNS('*', 'body')[0];
+    const replacementNodes = body
+        ? Array.from(body.childNodes || []).filter(node => node.nodeType === 1 && !isSectionPropertiesElement(node))
+        : [documentNode];
+
+    const numberingPart = parts.find(part => getPackagePartName(part) === '/word/numbering.xml');
+    let numberingXml = null;
+    if (numberingPart) {
+        const numberingXmlData = numberingPart.getElementsByTagNameNS('*', 'xmlData')[0];
+        const numberingNode = numberingXmlData
+            ? Array.from(numberingXmlData.childNodes || []).find(node => node.nodeType === 1)
+            : null;
+        if (numberingNode) {
+            numberingXml = serializer.serializeToString(numberingNode);
+        }
+    }
+
+    return {
+        replacementNodes,
+        numberingXml,
+        sourceType: 'package'
+    };
+}
+
+/**
+ * Extracts replacement nodes and optional numbering payload from engine output.
+ *
+ * @param {string} outputOxml
+ * @returns {{ replacementNodes: Element[], numberingXml: string|null, sourceType: 'package'|'document'|'fragment' }}
+ */
+export function extractReplacementNodesFromOoxml(outputOxml) {
+    if (typeof outputOxml !== 'string' || !outputOxml.trim()) {
+        return {
+            replacementNodes: [],
+            numberingXml: null,
+            sourceType: 'fragment',
+            status: 'error',
+            error: { code: 'PARSE_ERROR', message: 'Reconciliation engine returned no OOXML payload for this operation' }
+        };
+    }
+
+    try {
+        if (outputOxml.includes('<pkg:package')) {
+            return extractFromPackageXml(outputOxml);
+        }
+
+        if (outputOxml.includes('<w:document')) {
+            const doc = parseXmlStrictStandalone(outputOxml, 'document OOXML');
+            const body = doc.getElementsByTagNameNS('*', 'body')[0];
+            const replacementNodes = body
+                ? Array.from(body.childNodes || []).filter(node => node.nodeType === 1 && !isSectionPropertiesElement(node))
+                : Array.from(doc.childNodes || []).filter(node => node.nodeType === 1);
+            return { replacementNodes, numberingXml: null, sourceType: 'document' };
+        }
+
+        const wrapped = `<root xmlns:w="${NS_W}">${outputOxml}</root>`;
+        const fragmentDoc = parseXmlStrictStandalone(wrapped, 'OOXML fragment');
+        const replacementNodes = Array.from(fragmentDoc.documentElement.childNodes || []).filter(node => node.nodeType === 1);
+        return { replacementNodes, numberingXml: null, sourceType: 'fragment' };
+    } catch (caught) {
+        return {
+            replacementNodes: [],
+            numberingXml: null,
+            sourceType: 'fragment',
+            status: 'error',
+            error: { code: 'PARSE_ERROR', message: caught?.message || 'Could not parse OOXML payload.' }
+        };
+    }
+}
+
+function upsertContentTypeOverride(ctDoc, partName, contentType) {
+    const overrides = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override'));
+    const existingOverride = overrides.find(
+        override => (override.getAttribute('PartName') || '').toLowerCase() === String(partName).toLowerCase()
+    );
+    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);
+    override.setAttribute('ContentType', contentType);
+    ctDoc.documentElement.appendChild(override);
+    return true;
+}
+
+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);
+    if (hasRel) return false;
+
+    let maxId = 0;
+    for (const rel of rels) {
+        const idValue = rel.getAttribute('Id') || '';
+        const idNum = Number.parseInt(idValue.replace(/^rId/i, ''), 10);
+        if (Number.isFinite(idNum)) {
+            maxId = Math.max(maxId, idNum);
+        }
+    }
+
+    const newId = `rId${maxId + 1}`;
+    const rel = relsDoc.createElementNS(NS_RELS, 'Relationship');
+    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;
+}
+
+async function readZipText(zip, filePath) {
+    const entry = zip.file(filePath);
+    if (!entry) return null;
+    return entry.async('string');
+}
+
+/**
+ * Ensures numbering part + package metadata exist and merges numbering payloads.
+ *
+ * @param {any} zip
+ * @param {string|string[]|null|undefined} numberingXmlList
+ * @param {{
+ *   mergeNumberingXml?: ((existingXml: string, incomingXml: string) => string),
+ *   onInfo?: (message: string) => void
+ * }} [options]
+ */
+export async function ensureNumberingArtifactsInZip(zip, numberingXmlList, options = {}) {
+    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
+    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) {
+            mergedNumberingXml = incomingNumberingXml;
+            continue;
+        }
+        mergedNumberingXml = mergeNumberingXml
+            ? mergeNumberingXml(mergedNumberingXml, incomingNumberingXml)
+            : incomingNumberingXml;
+    }
+
+    if (!existing) {
+        onInfo('[Demo] Adding numbering.xml');
+    } else {
+        onInfo('[Demo] Merging numbering.xml payload(s) into existing numbering definitions');
+    }
+    zip.file(NUMBERING_PATH, mergedNumberingXml);
+
+    const serializer = createSerializer();
+
+    const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
+    if (ctText) {
+        const ctDoc = parseXmlStrictStandalone(ctText, CONTENT_TYPES_PATH);
+        if (upsertContentTypeOverride(ctDoc, '/word/numbering.xml', NUMBERING_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, NUMBERING_REL_TYPE, 'numbering.xml', options)) {
+            zip.file(DOCUMENT_RELS_PATH, serializer.serializeToString(relsDoc));
+        }
+    }
+}
+
+/**
+ * Ensures comments part + package metadata exist and merges incoming comments.
+ *
+ * @param {any} zip
+ * @param {string|null|undefined} commentsXml
+ * @param {{ onInfo?: (message: string) => void }} [options]
+ */
+export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {}) {
+    const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
+    if (!commentsXml) return;
+
+    const serializer = createSerializer();
+    const existingText = await readZipText(zip, COMMENTS_PATH);
+    if (!existingText || options.replaceExisting === true) {
+        onInfo('[Demo] Adding comments.xml');
+        zip.file(COMMENTS_PATH, commentsXml);
+    } else {
+        const existingDoc = parseXmlStrictStandalone(existingText, 'word/comments.xml (existing)');
+        const incomingDoc = parseXmlStrictStandalone(commentsXml, 'word/comments.xml (incoming)');
+        const existingRoot = existingDoc.documentElement;
+        const existingIds = new Set(
+            Array.from(existingRoot.getElementsByTagNameNS(NS_W, 'comment'))
+                .map(comment => comment.getAttribute('w:id') || comment.getAttribute('id'))
+                .filter(Boolean)
+        );
+        for (const incomingComment of Array.from(incomingDoc.documentElement.getElementsByTagNameNS(NS_W, 'comment'))) {
+            const id = incomingComment.getAttribute('w:id') || incomingComment.getAttribute('id');
+            if (id && existingIds.has(id)) {
+                throw new Error(`Duplicate comment id: ${id}`);
+            }
+            existingRoot.appendChild(existingDoc.importNode(incomingComment, true));
+        }
+        zip.file(COMMENTS_PATH, serializer.serializeToString(existingDoc));
+    }
+
+    const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
+    if (ctText) {
+        const ctDoc = parseXmlStrictStandalone(ctText, CONTENT_TYPES_PATH);
+        if (upsertContentTypeOverride(ctDoc, '/word/comments.xml', COMMENTS_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_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));
+        }
+    }
+}
+
+/**
+ * Rewrites content-type overrides for known parts whose type is wrong (for example the
+ * `application/vnd.ms-word.commentsExtended+xml` value written by earlier versions of
+ * this package). Does not rewrite [Content_Types].xml when there is nothing to repair.
+ *
+ * @param {any} zip
+ * @returns {Promise<Array<{ partName: string, from: string, to: string }>>}
+ */
+export async function repairKnownContentTypes(zip) {
+    const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
+    if (!ctText) return [];
+    const ctDoc = parseXmlStrictStandalone(ctText, CONTENT_TYPES_PATH);
+    const repairs = [];
+    for (const override of Array.from(ctDoc.getElementsByTagNameNS('*', 'Override'))) {
+        const partName = override.getAttribute('PartName') || '';
+        const actual = override.getAttribute('ContentType') || '';
+        const expected = correctedContentTypeFor(partName, actual);
+        if (!expected) continue;
+        override.setAttribute('ContentType', expected);
+        repairs.push({ partName, from: actual, to: expected });
+    }
+    if (repairs.length > 0) zip.file(CONTENT_TYPES_PATH, createSerializer().serializeToString(ctDoc));
+    return repairs;
+}
+
+/**
+ * Validates core package integrity for document/comments/numbering artifacts.
+ *
+ * @param {any} zip
+ */
+export async function validateDocxPackage(zip) {
+    const documentXml = await readZipText(zip, DOCUMENT_PATH);
+    if (!documentXml) {
+        throw new Error('Validation failed: missing word/document.xml');
+    }
+
+    const documentDoc = parseXmlStrictStandalone(documentXml, DOCUMENT_PATH);
+    normalizeBodySectionOrderStandalone(documentDoc);
+    const body = getBodyElementFromDocument(documentDoc);
+    if (!body) {
+        throw new Error('Validation failed: word/document.xml has no w:body');
+    }
+
+    const directBodyElements = Array.from(body.childNodes || []).filter(node => node.nodeType === 1);
+    const sectPrIndexes = directBodyElements
+        .map((node, index) => ({ node, index }))
+        .filter(entry => isSectionPropertiesElement(entry.node))
+        .map(entry => entry.index);
+
+    if (sectPrIndexes.length > 1) {
+        throw new Error('Validation failed: multiple body-level w:sectPr');
+    }
+    if (sectPrIndexes.length === 1 && sectPrIndexes[0] !== directBodyElements.length - 1) {
+        throw new Error('Validation failed: w:sectPr not last');
+    }
+
+    const tcs = documentDoc.getElementsByTagNameNS(NS_W, 'tc');
+    for (const tc of Array.from(tcs)) {
+        for (const child of Array.from(tc.childNodes || []).filter(node => node.nodeType === 1)) {
+            if (child.namespaceURI === NS_W && child.localName === 'p') {
+                const hasNestedParagraph = Array.from(child.childNodes || []).some(
+                    node => node.nodeType === 1 && node.namespaceURI === NS_W && node.localName === 'p'
+                );
+                if (hasNestedParagraph) {
+                    throw new Error('Validation failed: nested w:p');
+                }
+            }
+        }
+    }
+
+    const hasNumberingUsage = documentDoc.getElementsByTagNameNS(NS_W, 'numPr').length > 0;
+    const hasCommentUsage =
+        documentDoc.getElementsByTagNameNS(NS_W, 'commentRangeStart').length > 0
+        || documentDoc.getElementsByTagNameNS(NS_W, 'commentRangeEnd').length > 0
+        || documentDoc.getElementsByTagNameNS(NS_W, 'commentReference').length > 0;
+
+    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);
+    } else if (hasNumberingUsage) {
+        throw new Error('Validation failed: numbering used but part missing');
+    }
+
+    if (commentsXml) {
+        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 paraId = commentParaId(comment);
+                if (paraId) paraIdToCommentId.set(paraId, 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');
+    }
+
+    const ctXml = await readZipText(zip, CONTENT_TYPES_PATH);
+    if (!ctXml) {
+        throw new Error(`Validation failed: missing ${CONTENT_TYPES_PATH}`);
+    }
+    const ctDoc = parseXmlStrictStandalone(ctXml, CONTENT_TYPES_PATH);
+
+    const relsXml = await readZipText(zip, DOCUMENT_RELS_PATH);
+    if (!relsXml) {
+        throw new Error(`Validation failed: missing ${DOCUMENT_RELS_PATH}`);
+    }
+    const relsDoc = parseXmlStrictStandalone(relsXml, DOCUMENT_RELS_PATH);
+
+    if (numberingXml) {
+        const hasNumberingContentType = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override')).some(override =>
+            (override.getAttribute('PartName') || '').toLowerCase() === '/word/numbering.xml'
+            && (override.getAttribute('ContentType') || '') === NUMBERING_CONTENT_TYPE
+        );
+        const hasNumberingRel = Array.from(relsDoc.getElementsByTagNameNS('*', 'Relationship')).some(rel =>
+            (rel.getAttribute('Type') || '') === NUMBERING_REL_TYPE
+        );
+        if (!hasNumberingContentType) {
+            throw new Error('Validation failed: numbering CT override missing');
+        }
+        if (!hasNumberingRel) {
+            throw new Error('Validation failed: numbering rel missing');
+        }
+    }
+
+    if (commentsXml) {
+        const hasCommentsContentType = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override')).some(override =>
+            (override.getAttribute('PartName') || '').toLowerCase() === '/word/comments.xml'
+            && (override.getAttribute('ContentType') || '') === COMMENTS_CONTENT_TYPE
+        );
+        const hasCommentsRel = Array.from(relsDoc.getElementsByTagNameNS('*', 'Relationship')).some(rel =>
+            (rel.getAttribute('Type') || '') === COMMENTS_REL_TYPE
+        );
+        if (!hasCommentsContentType) {
+            throw new Error('Validation failed: comments CT override missing');
+        }
+        if (!hasCommentsRel) {
+            throw new Error('Validation failed: comments rel missing');
+        }
+    }
+
+    // Header/footer wiring: every w:headerReference / w:footerReference must resolve through the document
+    // relationships to a part that exists, is well-formed, and is labeled with Word's content type.
+    {
+        const relationshipById = new Map();
+        for (const rel of Array.from(relsDoc.getElementsByTagNameNS('*', 'Relationship'))) {
+            relationshipById.set(rel.getAttribute('Id') || '', { type: rel.getAttribute('Type') || '', target: rel.getAttribute('Target') || '' });
+        }
+        const headerSpec = getPartSpec('header');
+        const footerSpec = getPartSpec('footer');
+        const overrideTypeByPart = new Map(Array.from(ctDoc.getElementsByTagNameNS('*', 'Override'))
+            .map(override => [(override.getAttribute('PartName') || '').toLowerCase(), override.getAttribute('ContentType') || '']));
+        for (const reference of [
+            ...Array.from(documentDoc.getElementsByTagNameNS(NS_W, 'headerReference')),
+            ...Array.from(documentDoc.getElementsByTagNameNS(NS_W, 'footerReference'))
+        ]) {
+            const relId = reference.getAttributeNS?.('http://schemas.openxmlformats.org/officeDocument/2006/relationships', 'id') || reference.getAttribute('r:id') || '';
+            const spec = reference.localName === 'headerReference' ? headerSpec : footerSpec;
+            const relationship = relationshipById.get(relId);
+            if (!relationship) throw new Error(`Validation failed: ${reference.localName} ${relId || '(no r:id)'} has no document relationship`);
+            if (relationship.type !== spec.relType) throw new Error(`Validation failed: ${reference.localName} ${relId} points at a relationship of the wrong type (${relationship.type})`);
+            const partName = relationship.target.startsWith('/') ? relationship.target : `/word/${relationship.target}`;
+            const partXml = await readZipText(zip, partName.slice(1));
+            if (!partXml) throw new Error(`Validation failed: ${reference.localName} ${relId} targets a missing part: ${partName}`);
+            parseXmlStrictStandalone(partXml, partName.slice(1));
+            const contentType = overrideTypeByPart.get(partName.toLowerCase());
+            if (contentType !== spec.contentType) throw new Error(`Validation failed: ${partName} content type is ${contentType ? `'${contentType}'` : 'missing'}; Word expects '${spec.contentType}'`);
+        }
+    }
+
+    if (commentsExtendedXml) {
+        const extendedOverride = Array.from(ctDoc.getElementsByTagNameNS('*', 'Override')).find(override =>
+            (override.getAttribute('PartName') || '').toLowerCase() === '/word/commentsextended.xml'
+        );
+        if (extendedOverride && extendedOverride.getAttribute('ContentType') !== COMMENTS_EXTENDED_CONTENT_TYPE) {
+            throw new Error(`Validation failed: commentsExtended CT override has wrong content type '${extendedOverride.getAttribute('ContentType')}' (Word expects '${COMMENTS_EXTENDED_CONTENT_TYPE}')`);
+        }
+        const hasContentType = !!extendedOverride;
+        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');
+    }
+}