@usejunior/docx-core 0.9.0 → 0.10.0

package/dist/baselines/atomizer/pipeline.js

@@ -215,19 +215,140 @@ function buildFailureSummary(failureDetails) {
     }
     return Object.keys(summary).length > 0 ? summary : undefined;
 }
+// Declared above splitStories so the function body never observes an
+// uninitialized binding under circular imports.
+const serializer = new XMLSerializer();
+/**
+ * Split a docx into per-story XML fragments for field-closure validation.
+ *
+ * Each footnote/endnote entry is treated as an isolated story: a complex
+ * field whose `begin` and `end` markers straddle stories breaks Word's
+ * field state machine. We therefore validate each `<w:footnote>` and
+ * `<w:endnote>` entry independently rather than treating the whole
+ * `footnotes.xml`/`endnotes.xml` as one stream.
+ *
+ * Accepts arrays of sidecar XMLs (one per source archive) so callers can
+ * validate the union of entries from every archive that may contribute to the
+ * final result. Step 12 of `compareDocumentsAtomizer` merges entries from a
+ * mode-dependent source archive into the base archive; passing both archives'
+ * sidecars guarantees that whichever path the merge takes, the entries it
+ * could publish have already been screened. Duplicates (same `w:id` in both
+ * archives) yield redundant but harmless validation work.
+ *
+ * Header/footer stories are not yet covered — they require relationship
+ * walking to enumerate `headerN.xml`/`footerN.xml`.
+ *
+ * @conformance ECMA-376 edition 5, Part 4 § 17.16.5
+ * @see https://github.com/UseJunior/safe-docx/issues/212
+ */
+export function splitStories(documentXml, footnotesXmls, endnotesXmls) {
+    const stories = [{ label: 'document', xml: documentXml }];
+    const collectEntries = (sidecars, entryTag, labelPrefix) => {
+        for (let s = 0; s < sidecars.length; s++) {
+            const sidecarXml = sidecars[s];
+            if (!sidecarXml)
+                continue;
+            const doc = parseXml(sidecarXml);
+            const entries = doc.getElementsByTagName(entryTag);
+            for (let i = 0; i < entries.length; i++) {
+                const entry = entries[i];
+                const id = entry.getAttribute('w:id') ?? String(i);
+                stories.push({
+                    label: `${labelPrefix}[${s}]:${id}`,
+                    xml: serializer.serializeToString(entry),
+                });
+            }
+        }
+    };
+    collectEntries(footnotesXmls, 'w:footnote', 'footnote');
+    collectEntries(endnotesXmls, 'w:endnote', 'endnote');
+    return stories;
+}
+/**
+ * Validate field structure integrity across one or more document stories.
+ *
+ * Enforces three constraints on complex fields **per story**:
+ *   1. `w:fldChar` begin/end count balance within the story.
+ *   2. Every `w:instrText` AND `w:delInstrText` sits inside an open field body
+ *      (between `begin` and `separate`). Orphaned instruction text renders as
+ *      literal text in Word.
+ *   3. `w:delInstrText` is nested inside a `<w:del>` ancestor (DeletedFieldCode
+ *      schema constraint), and conversely `w:fldChar` is NEVER inside `<w:del>`
+ *      (Word treats this as fatal and discards the field state machine).
+ *
+ * Called on both pre-accept/reject combined XML (with track-change wrappers)
+ * and on post-accept/reject XML (wrappers removed). Both cases must satisfy the
+ * field placement check; constraint (3) is vacuous post-accept/reject.
+ *
+ * Accepts either a single XML string (legacy single-story call) or an array of
+ * `FieldStory` fragments. Stories are validated independently and short-circuit
+ * on the first failure.
+ *
+ * @conformance ECMA-376 edition 5, Part 4 § 17.16.5
+ */
 /**
- * Validate field structure integrity in document XML.
+ * Targeted check for one of the constraints above: `w:fldChar` MUST NOT appear
+ * inside any `<w:del>` element. Word treats this violation as fatal — the
+ * field state machine is discarded and the field renders as literal-text
+ * fallback.
+ *
+ * Used as a combined-output safety gate alongside the per-projection
+ * `validateFieldStructure` checks. Kept narrower than the full structural
+ * validation so that legacy shapes (e.g. `delInstrText` inside `<w:moveFrom>`)
+ * don't trigger fallback when the inplace candidate is otherwise sound on its
+ * accept/reject projections.
  *
- * Checks that fldChar begin/end are balanced and that w:instrText only
- * appears inside a proper field sequence (between begin and separate).
- * Orphaned instrText elements render as visible text in Word.
+ * @conformance ECMA-376 edition 5, Part 4 § 17.16.5
+ * @see https://github.com/UseJunior/safe-docx/issues/217
  */
-function validateFieldStructure(documentXml) {
+export function hasFldCharInsideDel(documentXml) {
+    const root = parseDocumentXml(documentXml);
+    let insideDelDepth = 0;
+    let violation = false;
+    function scan(node) {
+        if (violation)
+            return;
+        for (let child = node.firstChild; child; child = child.nextSibling) {
+            if (child.nodeType !== 1)
+                continue;
+            const el = child;
+            const tag = el.tagName;
+            if (tag === 'w:del') {
+                insideDelDepth++;
+                scan(el);
+                insideDelDepth--;
+                if (violation)
+                    return;
+                continue;
+            }
+            if (tag === 'w:fldChar' && insideDelDepth > 0) {
+                violation = true;
+                return;
+            }
+            scan(el);
+            if (violation)
+                return;
+        }
+    }
+    scan(root);
+    return violation;
+}
+export function validateFieldStructure(input) {
+    if (typeof input === 'string') {
+        return validateFieldStructureForStory(input);
+    }
+    for (const story of input) {
+        if (!validateFieldStructureForStory(story.xml))
+            return false;
+    }
+    return true;
+}
+function validateFieldStructureForStory(documentXml) {
     const root = parseDocumentXml(documentXml);
-    // Walk the document in order, tracking field nesting
     const allFldChars = findAllByTagName(root, 'w:fldChar');
     const allInstrTexts = findAllByTagName(root, 'w:instrText');
-    // Quick balance check
+    const allDelInstrTexts = findAllByTagName(root, 'w:delInstrText');
+    // Constraint (1): global fldChar begin/end balance.
     let begins = 0;
     let ends = 0;
     for (const fc of allFldChars) {
@@ -239,19 +360,33 @@ function validateFieldStructure(documentXml) {
     }
     if (begins !== ends)
         return false;
-    // Check that instrText elements are inside a field (between begin and separate).
-    // Walk all elements in document order using a recursive scan.
-    if (allInstrTexts.length === 0)
-        return true; // No instrText, nothing to validate
-    // Depth-first scan to check instrText placement
+    if (allFldChars.length === 0 &&
+        allInstrTexts.length === 0 &&
+        allDelInstrTexts.length === 0) {
+        return true;
+    }
+    // Depth-first scan tracking field nesting (for constraint 2) and <w:del>
+    // ancestor nesting (for constraint 3).
     let depth = 0;
-    const pastSeparatorAtDepth = []; // track separator state per depth
+    const pastSeparatorAtDepth = [];
+    let insideDelDepth = 0;
     function scan(node) {
         for (let child = node.firstChild; child; child = child.nextSibling) {
             if (child.nodeType !== 1)
-                continue; // skip non-elements
+                continue;
             const el = child;
-            if (el.tagName === 'w:fldChar') {
+            const tag = el.tagName;
+            if (tag === 'w:del') {
+                insideDelDepth++;
+                const ok = scan(el);
+                insideDelDepth--;
+                if (!ok)
+                    return false;
+                continue;
+            }
+            if (tag === 'w:fldChar') {
+                if (insideDelDepth > 0)
+                    return false;
                 const type = el.getAttribute('w:fldCharType');
                 if (type === 'begin') {
                     depth++;
@@ -266,8 +401,13 @@ function validateFieldStructure(documentXml) {
                         depth--;
                 }
             }
-            else if (el.tagName === 'w:instrText') {
-                // instrText must be inside a field (depth > 0) and before the separator
+            else if (tag === 'w:instrText') {
+                if (depth === 0 || pastSeparatorAtDepth[depth])
+                    return false;
+            }
+            else if (tag === 'w:delInstrText') {
+                if (insideDelDepth === 0)
+                    return false;
                 if (depth === 0 || pastSeparatorAtDepth[depth])
                     return false;
             }
@@ -278,7 +418,7 @@ function validateFieldStructure(documentXml) {
     }
     return scan(root);
 }
-function evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml) {
+function evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml, auxiliarySidecars) {
     const acceptedXml = acceptAllChanges(candidateXml);
     const rejectedXml = rejectAllChanges(candidateXml);
     const acceptedText = extractTextWithParagraphs(acceptedXml);
@@ -289,11 +429,28 @@ function evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip,
     const rejectTextComparison = compareTexts(originalTextForRoundTrip, rejectedText);
     const acceptBookmarksOk = bookmarkDiagnosticsSemanticallyEqual(revisedBookmarkDiagnostics, acceptedBookmarkDiagnostics);
     const rejectBookmarksOk = bookmarkDiagnosticsSemanticallyEqual(originalBookmarkDiagnostics, rejectedBookmarkDiagnostics);
-    // Validate field structure: after accept-all and reject-all, every
-    // w:instrText must be inside a proper field sequence (between fldChar
-    // begin and fldChar separate). Orphaned instrText renders as visible
-    // text in Word.
-    const fieldStructureOk = validateFieldStructure(acceptedXml) && validateFieldStructure(rejectedXml);
+    // Validate field structure per-story. Each footnote/endnote entry is its own
+    // ECMA-376 story; a complex field that crosses a story boundary breaks
+    // Word's field state machine even when global begin/end counts balance.
+    // Sidecars from BOTH archives are validated because Step 12's auxiliary-part
+    // merge picks its base and source archives by reconstruction mode (inplace
+    // base = revised; rebuild base = original) and validating only one side
+    // would miss field issues that would still ship in the merged result.
+    // `acceptAllChanges` / `rejectAllChanges` only transform document.xml, so
+    // the sidecar set is identical for both transforms.
+    const acceptedStories = splitStories(acceptedXml, auxiliarySidecars.footnotesXmls, auxiliarySidecars.endnotesXmls);
+    const rejectedStories = splitStories(rejectedXml, auxiliarySidecars.footnotesXmls, auxiliarySidecars.endnotesXmls);
+    // Issue #217 conformance gate on the COMBINED output: w:fldChar MUST NOT
+    // appear inside <w:del>. ECMA-376 Part 4 § 17.16.5 makes this fatal for
+    // Word's field state machine. The full validateFieldStructure check is run
+    // on the accept/reject projections (per-story); on the combined view we
+    // only gate the strict no-fldChar-in-del rule because some legacy emit
+    // paths (e.g. delInstrText inside <w:moveFrom>) are non-conformant in shape
+    // but out of scope for #217.
+    const combinedNoFldCharInDel = !hasFldCharInsideDel(candidateXml);
+    const fieldStructureOk = combinedNoFldCharInDel &&
+        validateFieldStructure(acceptedStories) &&
+        validateFieldStructure(rejectedStories);
     const checks = {
         acceptText: acceptTextComparison.normalizedIdentical,
         rejectText: rejectTextComparison.normalizedIdentical,
@@ -375,6 +532,22 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
     // Extract numbering.xml if available
     const originalNumberingXml = await originalArchive.getNumberingXml() ?? undefined;
     const revisedNumberingXml = await revisedArchive.getNumberingXml() ?? undefined;
+    // Extract footnote/endnote sidecars from BOTH archives for per-story
+    // field-closure validation (issue #212). Step 12 picks the base archive by
+    // reconstruction mode (inplace = revised, rebuild = original) and merges
+    // missing referenced entries from the opposite archive. Validating both
+    // archives' sidecars covers the union of entries that could ship without
+    // having to duplicate the merge logic at safety-check time.
+    const [originalFootnotesXml, originalEndnotesXml, revisedFootnotesXml, revisedEndnotesXml,] = await Promise.all([
+        originalArchive.getFile('word/footnotes.xml'),
+        originalArchive.getFile('word/endnotes.xml'),
+        revisedArchive.getFile('word/footnotes.xml'),
+        revisedArchive.getFile('word/endnotes.xml'),
+    ]);
+    const auxiliarySidecars = {
+        footnotesXmls: [originalFootnotesXml, revisedFootnotesXml],
+        endnotesXmls: [originalEndnotesXml, revisedEndnotesXml],
+    };
     const originalPart = {
         uri: 'word/document.xml',
         contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml',
@@ -383,8 +556,13 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         uri: 'word/document.xml',
         contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml',
     };
-    const originalTextForRoundTrip = extractTextWithParagraphs(originalXml);
-    const revisedTextForRoundTrip = extractTextWithParagraphs(revisedXml);
+    // Project each input through the SAME accept/reject operation the candidate is
+    // checked under, so the round-trip comparison is like-for-like even when an
+    // input already carries its own tracked changes (pre-tracked w:ins / w:del,
+    // comment anchors, multi-author stacks). For a clean input these equal the raw
+    // extraction, so behavior on the common case is unchanged. (#347)
+    const originalTextForRoundTrip = extractTextWithParagraphs(rejectAllChanges(originalXml));
+    const revisedTextForRoundTrip = extractTextWithParagraphs(acceptAllChanges(revisedXml));
     const originalBookmarkDiagnostics = collectBookmarkDiagnostics(originalXml);
     const revisedBookmarkDiagnostics = collectBookmarkDiagnostics(revisedXml);
     const runComparisonPass = (atomizeOptions, outputMode) => {
@@ -445,7 +623,7 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         }
         return { mergedAtoms, newDocumentXml, outputMode };
     };
-    const evaluateRoundTripSafety = (candidateXml) => evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml);
+    const evaluateRoundTripSafety = (candidateXml) => evaluateSafetyChecks(originalTextForRoundTrip, revisedTextForRoundTrip, originalBookmarkDiagnostics, revisedBookmarkDiagnostics, candidateXml, auxiliarySidecars);
     let comparisonResult;
     let fallbackReason;
     let fallbackDiagnostics;
@@ -530,7 +708,7 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
             comparisonResult = selected;
         }
         else {
-            comparisonResult = runComparisonPass(undefined, 'rebuild');
+            comparisonResult = runComparisonPass({ atomizeParagraphLevelMarkers: true }, 'rebuild');
             fallbackReason = 'round_trip_safety_check_failed';
             fallbackDiagnostics = {
                 attempts: failedAttempts,
@@ -538,30 +716,33 @@ export async function compareDocumentsAtomizer(original, revised, options = {})
         }
     }
     else {
-        comparisonResult = runComparisonPass(undefined, 'rebuild');
+        comparisonResult = runComparisonPass({ atomizeParagraphLevelMarkers: true }, 'rebuild');
     }
     const { mergedAtoms, newDocumentXml } = comparisonResult;
     // Step 12: Clone appropriate archive and update document.xml.
     // Use the revised archive only for true inplace output.
     const baseArchive = comparisonResult.outputMode === 'inplace' ? revisedArchive : originalArchive;
+    // The merge source is the *opposite* archive from the base: inplace pulls
+    // deleted-but-still-referenced definitions from the original, rebuild pulls
+    // added-but-still-referenced definitions from the revised. Without this,
+    // rebuild output ships dangling references when the original lacks an
+    // auxiliary part that the revised side introduced (issue #94).
+    const mergeSourceArchive = comparisonResult.outputMode === 'inplace' ? originalArchive : revisedArchive;
     const resultArchive = await baseArchive.clone();
     resultArchive.setDocumentXml(newDocumentXml);
-    // Step 12b: For inplace mode, merge auxiliary part definitions (footnotes,
-    // endnotes, comments) from the original document. Inplace reconstruction
-    // inserts deleted content that may reference definitions not present in the
-    // revised archive.
-    if (comparisonResult.outputMode === 'inplace') {
-        const mergeResults = new Map();
-        for (const descriptor of AUXILIARY_PARTS) {
-            const result = await mergeAuxiliaryPartDefinitions(originalArchive, resultArchive, newDocumentXml, descriptor);
-            if (result.mergedIds.size > 0) {
-                mergeResults.set(descriptor.label, result);
-            }
-        }
-        // Post-merge hook for comment ancillary parts
-        if (mergeResults.has('comment')) {
-            await mergeCommentAncillaryParts(originalArchive, resultArchive, mergeResults.get('comment'));
-        }
+    // Step 12b: Merge auxiliary part definitions (footnotes, endnotes, comments).
+    // Reconstruction may insert content (deleted in inplace, added in rebuild)
+    // whose definitions are missing from the base archive.
+    for (const descriptor of AUXILIARY_PARTS) {
+        await mergeAuxiliaryPartDefinitions(mergeSourceArchive, resultArchive, newDocumentXml, descriptor);
+    }
+    // Comment-specific post-pass: walk reply threads via commentsExtended.xml.
+    // Gated on root comment IDs in the *result* document (not on what the
+    // generic merge appended), so the pass runs even when the original already
+    // contains the root and revised only adds replies under it (issue #108).
+    const rootCommentIds = collectReferenceIds(newDocumentXml, 'w:commentReference');
+    if (rootCommentIds.size > 0) {
+        await mergeCommentAncillaryParts(mergeSourceArchive, resultArchive, rootCommentIds);
     }
     // Step 13: Save result and compute stats
     const resultBuffer = await resultArchive.save();
@@ -634,28 +815,29 @@ function parseEntries(xml, entryTag) {
     }
     return { doc, entries };
 }
-const serializer = new XMLSerializer();
 /**
  * Merge auxiliary part definitions (footnotes, endnotes, comments) from the
- * original archive into the result archive. When inplace mode inserts deleted
- * content, the corresponding definitions must exist in the auxiliary part.
+ * source archive into the result archive. The source archive is whichever
+ * side reconstruction may have introduced references to: original in inplace
+ * mode (deleted-but-referenced definitions), revised in rebuild mode
+ * (added-but-referenced definitions).
  */
-async function mergeAuxiliaryPartDefinitions(originalArchive, resultArchive, documentXml, descriptor) {
+async function mergeAuxiliaryPartDefinitions(sourceArchive, resultArchive, documentXml, descriptor) {
     const result = { mergedIds: new Set(), createdPart: false };
     const referencedIds = collectReferenceIds(documentXml, descriptor.referenceTag);
     if (referencedIds.size === 0)
         return result;
-    const originalPartXml = await originalArchive.getFile(descriptor.partPath);
-    if (!originalPartXml)
+    const sourcePartXml = await sourceArchive.getFile(descriptor.partPath);
+    if (!sourcePartXml)
         return result;
     const resultPartXml = await resultArchive.getFile(descriptor.partPath);
-    const originalParsed = parseEntries(originalPartXml, descriptor.entryTag);
+    const sourceParsed = parseEntries(sourcePartXml, descriptor.entryTag);
     const resultParsed = resultPartXml ? parseEntries(resultPartXml, descriptor.entryTag) : null;
     // Find missing entries: referenced in document.xml but not in result
     const missingElements = [];
     for (const id of referencedIds) {
-        if (!(resultParsed?.entries.has(id)) && originalParsed.entries.has(id)) {
-            missingElements.push(originalParsed.entries.get(id));
+        if (!(resultParsed?.entries.has(id)) && sourceParsed.entries.has(id)) {
+            missingElements.push(sourceParsed.entries.get(id));
             result.mergedIds.add(id);
         }
     }
@@ -673,27 +855,33 @@ async function mergeAuxiliaryPartDefinitions(originalArchive, resultArchive, doc
         }
     }
     else {
-        // Create part from scratch: clone root from original, insert missing entries
-        const newDoc = parseXml(originalPartXml);
+        // Create part from scratch: clone root from merge source, drop every
+        // non-reserved entry, then append the missing referenced ones.
+        // Reserved entries are footnote/endnote separators identified by
+        // w:type="separator" / w:type="continuationSeparator" — Word expects
+        // them to exist and they don't carry user content. Filtering by w:type
+        // (not by magic w:id values) keeps this robust across authoring tools.
+        const newDoc = parseXml(sourcePartXml);
         const rootEl = newDoc.getElementsByTagName(descriptor.rootTag)[0];
         if (rootEl) {
-            // Remove all existing entries — we only want the missing ones
             const existingEntries = rootEl.getElementsByTagName(descriptor.entryTag);
             const toRemove = [];
             for (let i = 0; i < existingEntries.length; i++) {
-                toRemove.push(existingEntries[i]);
+                const el = existingEntries[i];
+                const type = el.getAttribute('w:type');
+                if (type !== 'separator' && type !== 'continuationSeparator') {
+                    toRemove.push(el);
+                }
             }
             for (const el of toRemove) {
                 rootEl.removeChild(el);
             }
-            // Add back only the missing entries
             for (const el of missingElements) {
                 const imported = newDoc.importNode(el, true);
                 rootEl.appendChild(imported);
             }
             resultArchive.setFile(descriptor.partPath, serializer.serializeToString(newDoc));
             result.createdPart = true;
-            // Bootstrap OPC metadata for the newly created part
             await ensureOpcMetadata(resultArchive, descriptor);
         }
     }
@@ -765,52 +953,154 @@ async function ensureOpcMetadata(archive, descriptor) {
 // Comment Ancillary Parts Merging
 // =============================================================================
 /**
- * After merging comment definitions, copy related entries from
- * commentsExtended.xml and people.xml for author fidelity and reply threading.
+ * Walk the comment reply graph from each root referenced in the result
+ * document, merging reply <w:comment> entries, their commentsExtended.xml
+ * threading entries, and people.xml authors. Replies have no
+ * <w:commentReference> in document.xml — they're discoverable only via
+ * w15:paraIdParent in commentsExtended.xml. Without this expansion, rebuild
+ * mode silently drops reply threads (issue #108).
  */
-async function mergeCommentAncillaryParts(originalArchive, resultArchive, commentMergeResult) {
-    // Collect authors and paraIds from the merged comment entries
-    const originalCommentsXml = await originalArchive.getFile('word/comments.xml');
-    if (!originalCommentsXml)
+async function mergeCommentAncillaryParts(sourceArchive, resultArchive, rootCommentIds) {
+    const sourceCommentsXml = await sourceArchive.getFile('word/comments.xml');
+    if (!sourceCommentsXml)
         return;
-    const origDoc = parseXml(originalCommentsXml);
-    const mergedAuthors = new Set();
-    const mergedParaIds = new Set();
-    const commentEls = origDoc.getElementsByTagName('w:comment');
-    for (let i = 0; i < commentEls.length; i++) {
-        const el = commentEls[i];
+    const sourceDoc = parseXml(sourceCommentsXml);
+    // Build full source comment maps. Canonical paraId is the first <w:p>
+    // child's w14:paraId, matching getCommentElParaId() in primitives/comments.ts.
+    const commentById = new Map();
+    const paraIdByCommentId = new Map();
+    const commentIdByParaId = new Map();
+    const authorByCommentId = new Map();
+    const allCommentEls = sourceDoc.getElementsByTagName('w:comment');
+    for (let i = 0; i < allCommentEls.length; i++) {
+        const el = allCommentEls[i];
         const id = el.getAttribute('w:id');
-        if (!id || !commentMergeResult.mergedIds.has(id))
+        if (!id)
             continue;
+        commentById.set(id, el);
         const author = el.getAttribute('w:author');
         if (author)
-            mergedAuthors.add(author);
-        // Collect paraIds from <w:p> children inside the comment
-        const paras = el.getElementsByTagName('w:p');
-        for (let j = 0; j < paras.length; j++) {
-            const p = paras[j];
-            const paraId = p.getAttribute('w14:paraId');
-            if (paraId)
-                mergedParaIds.add(paraId);
-        }
-    }
-    // Merge commentsExtended.xml entries matching merged paraIds
-    await mergeCommentsExtended(originalArchive, resultArchive, mergedParaIds);
-    // Merge people.xml entries matching merged authors
-    await mergePeople(originalArchive, resultArchive, mergedAuthors);
+            authorByCommentId.set(id, author);
+        const firstP = el.getElementsByTagName('w:p')[0];
+        const paraId = firstP?.getAttribute('w14:paraId');
+        if (paraId) {
+            paraIdByCommentId.set(id, paraId);
+            commentIdByParaId.set(paraId, id);
+        }
+    }
+    // Seed inclusion sets from the root IDs that appear in the result document.
+    const includedCommentIds = new Set();
+    const includedParaIds = new Set();
+    const includedAuthors = new Set();
+    for (const id of rootCommentIds) {
+        if (!commentById.has(id))
+            continue;
+        includedCommentIds.add(id);
+        const pid = paraIdByCommentId.get(id);
+        if (pid)
+            includedParaIds.add(pid);
+        const author = authorByCommentId.get(id);
+        if (author)
+            includedAuthors.add(author);
+    }
+    // BFS over commentsExtended.xml's paraIdParent graph from each included
+    // root paraId. Skip entries that don't resolve to a real source comment so
+    // we never pull in dangling commentEx/people without a backing definition.
+    const sourceExtendedXml = await sourceArchive.getFile('word/commentsExtended.xml');
+    if (sourceExtendedXml) {
+        const exDoc = parseXml(sourceExtendedXml);
+        const exEls = exDoc.getElementsByTagName('w15:commentEx');
+        const childrenOf = new Map();
+        for (let i = 0; i < exEls.length; i++) {
+            const ex = exEls[i];
+            const childPid = ex.getAttribute('w15:paraId');
+            const parentPid = ex.getAttribute('w15:paraIdParent');
+            if (!childPid || !parentPid)
+                continue;
+            const arr = childrenOf.get(parentPid);
+            if (arr)
+                arr.push(childPid);
+            else
+                childrenOf.set(parentPid, [childPid]);
+        }
+        const queue = [...includedParaIds];
+        while (queue.length > 0) {
+            const pid = queue.shift();
+            const children = childrenOf.get(pid);
+            if (!children)
+                continue;
+            for (const childPid of children) {
+                if (includedParaIds.has(childPid))
+                    continue;
+                const childCommentId = commentIdByParaId.get(childPid);
+                if (!childCommentId)
+                    continue;
+                includedParaIds.add(childPid);
+                includedCommentIds.add(childCommentId);
+                const author = authorByCommentId.get(childCommentId);
+                if (author)
+                    includedAuthors.add(author);
+                queue.push(childPid);
+            }
+        }
+    }
+    // Append any reply <w:comment> definitions still missing from result.
+    // The generic merge already added roots when needed; we add the replies
+    // (and any roots not yet present in the result, defensively).
+    await mergeMissingCommentDefinitions(resultArchive, commentById, includedCommentIds);
+    // Merge commentsExtended and people for the expanded set.
+    await mergeCommentsExtended(sourceArchive, resultArchive, includedParaIds);
+    await mergePeople(sourceArchive, resultArchive, includedAuthors);
+}
+/**
+ * Append any source <w:comment> definitions in `includedCommentIds` that
+ * aren't already in result/word/comments.xml. Mirrors the append-with-importNode
+ * pattern used by mergeCommentsExtended below.
+ */
+async function mergeMissingCommentDefinitions(resultArchive, commentById, includedCommentIds) {
+    if (includedCommentIds.size === 0)
+        return;
+    const resultXml = await resultArchive.getFile('word/comments.xml');
+    if (!resultXml) {
+        // If result has no comments.xml at all, the generic merge would have
+        // bootstrapped it for any included root. Nothing to do here.
+        return;
+    }
+    const resultDoc = parseXml(resultXml);
+    const rootEl = resultDoc.documentElement;
+    const existingIds = new Set();
+    const existing = rootEl.getElementsByTagName('w:comment');
+    for (let i = 0; i < existing.length; i++) {
+        const id = existing[i].getAttribute('w:id');
+        if (id)
+            existingIds.add(id);
+    }
+    let appended = false;
+    for (const id of includedCommentIds) {
+        if (existingIds.has(id))
+            continue;
+        const sourceEl = commentById.get(id);
+        if (!sourceEl)
+            continue;
+        rootEl.appendChild(resultDoc.importNode(sourceEl, true));
+        appended = true;
+    }
+    if (appended) {
+        resultArchive.setFile('word/comments.xml', serializer.serializeToString(resultDoc));
+    }
 }
-async function mergeCommentsExtended(originalArchive, resultArchive, mergedParaIds) {
+async function mergeCommentsExtended(sourceArchive, resultArchive, mergedParaIds) {
     if (mergedParaIds.size === 0)
         return;
-    const originalXml = await originalArchive.getFile('word/commentsExtended.xml');
-    if (!originalXml)
+    const sourceXml = await sourceArchive.getFile('word/commentsExtended.xml');
+    if (!sourceXml)
         return;
-    const origDoc = parseXml(originalXml);
-    const origEntries = origDoc.getElementsByTagName('w15:commentEx');
+    const sourceDoc = parseXml(sourceXml);
+    const sourceEntries = sourceDoc.getElementsByTagName('w15:commentEx');
     // Collect entries whose paraId matches a merged comment's paragraph
     const entriesToMerge = [];
-    for (let i = 0; i < origEntries.length; i++) {
-        const el = origEntries[i];
+    for (let i = 0; i < sourceEntries.length; i++) {
+        const el = sourceEntries[i];
         const paraId = el.getAttribute('w15:paraId');
         if (paraId && mergedParaIds.has(paraId)) {
             entriesToMerge.push(el);
@@ -818,11 +1108,10 @@ async function mergeCommentsExtended(originalArchive, resultArchive, mergedParaI
     }
     if (entriesToMerge.length === 0)
         return;
-    let resultXml = await resultArchive.getFile('word/commentsExtended.xml');
+    const resultXml = await resultArchive.getFile('word/commentsExtended.xml');
     if (resultXml) {
         const resultDoc = parseXml(resultXml);
         const rootEl = resultDoc.documentElement;
-        // Check existing paraIds to avoid duplicates
         const existingParaIds = new Set();
         const existing = rootEl.getElementsByTagName('w15:commentEx');
         for (let i = 0; i < existing.length; i++) {
@@ -837,21 +1126,55 @@ async function mergeCommentsExtended(originalArchive, resultArchive, mergedParaI
             }
         }
         resultArchive.setFile('word/commentsExtended.xml', serializer.serializeToString(resultDoc));
+        return;
     }
-    // If commentsExtended.xml doesn't exist in result, we don't create it —
-    // the file is optional and its absence won't cause crashes.
+    // Bootstrap: result lacks commentsExtended.xml but the merged comments
+    // depend on it for reply threading / done state. Clone the source's root
+    // (preserves namespaces), drop non-matching entries, then add OPC metadata.
+    const newDoc = parseXml(sourceXml);
+    const newRoot = newDoc.documentElement;
+    const allEntries = newRoot.getElementsByTagName('w15:commentEx');
+    const toRemove = [];
+    for (let i = 0; i < allEntries.length; i++) {
+        const el = allEntries[i];
+        const paraId = el.getAttribute('w15:paraId');
+        if (!paraId || !mergedParaIds.has(paraId))
+            toRemove.push(el);
+    }
+    for (const el of toRemove)
+        newRoot.removeChild(el);
+    resultArchive.setFile('word/commentsExtended.xml', serializer.serializeToString(newDoc));
+    await ensureOpcMetadata(resultArchive, COMMENTS_EXTENDED_DESCRIPTOR);
 }
-async function mergePeople(originalArchive, resultArchive, mergedAuthors) {
+const COMMENTS_EXTENDED_DESCRIPTOR = {
+    label: 'commentsExtended',
+    partPath: 'word/commentsExtended.xml',
+    referenceTag: '',
+    entryTag: 'w15:commentEx',
+    rootTag: 'w15:commentsEx',
+    contentType: 'application/vnd.ms-word.commentsExtended+xml',
+    relationshipType: 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended',
+};
+const PEOPLE_DESCRIPTOR = {
+    label: 'people',
+    partPath: 'word/people.xml',
+    referenceTag: '',
+    entryTag: 'w15:person',
+    rootTag: 'w15:people',
+    contentType: 'application/vnd.ms-word.people+xml',
+    relationshipType: 'http://schemas.microsoft.com/office/2011/relationships/people',
+};
+async function mergePeople(sourceArchive, resultArchive, mergedAuthors) {
     if (mergedAuthors.size === 0)
         return;
-    const originalXml = await originalArchive.getFile('word/people.xml');
-    if (!originalXml)
+    const sourceXml = await sourceArchive.getFile('word/people.xml');
+    if (!sourceXml)
         return;
-    const origDoc = parseXml(originalXml);
-    const origPersons = origDoc.getElementsByTagName('w15:person');
+    const sourceDoc = parseXml(sourceXml);
+    const sourcePersons = sourceDoc.getElementsByTagName('w15:person');
     const personsToMerge = [];
-    for (let i = 0; i < origPersons.length; i++) {
-        const el = origPersons[i];
+    for (let i = 0; i < sourcePersons.length; i++) {
+        const el = sourcePersons[i];
         const author = el.getAttribute('w15:author');
         if (author && mergedAuthors.has(author)) {
             personsToMerge.push(el);
@@ -859,11 +1182,10 @@ async function mergePeople(originalArchive, resultArchive, mergedAuthors) {
     }
     if (personsToMerge.length === 0)
         return;
-    let resultXml = await resultArchive.getFile('word/people.xml');
+    const resultXml = await resultArchive.getFile('word/people.xml');
     if (resultXml) {
         const resultDoc = parseXml(resultXml);
         const rootEl = resultDoc.documentElement;
-        // Check existing authors to avoid duplicates
         const existingAuthors = new Set();
         const existing = rootEl.getElementsByTagName('w15:person');
         for (let i = 0; i < existing.length; i++) {
@@ -878,9 +1200,24 @@ async function mergePeople(originalArchive, resultArchive, mergedAuthors) {
             }
         }
         resultArchive.setFile('word/people.xml', serializer.serializeToString(resultDoc));
+        return;
+    }
+    // Bootstrap: result lacks people.xml. Clone source root (preserves
+    // namespaces), remove non-matching authors, then add OPC metadata.
+    const newDoc = parseXml(sourceXml);
+    const newRoot = newDoc.documentElement;
+    const allPersons = newRoot.getElementsByTagName('w15:person');
+    const toRemove = [];
+    for (let i = 0; i < allPersons.length; i++) {
+        const el = allPersons[i];
+        const author = el.getAttribute('w15:author');
+        if (!author || !mergedAuthors.has(author))
+            toRemove.push(el);
     }
-    // If people.xml doesn't exist in result, we don't create it —
-    // the file is optional and its absence won't cause crashes.
+    for (const el of toRemove)
+        newRoot.removeChild(el);
+    resultArchive.setFile('word/people.xml', serializer.serializeToString(newDoc));
+    await ensureOpcMetadata(resultArchive, PEOPLE_DESCRIPTOR);
 }
 /**
  * Compute comparison statistics from merged atoms.