@usejunior/docx-core 0.19.1 → 0.21.2

package/dist/primitives/footnotes.js

@@ -6,17 +6,19 @@
  */
 import { OOXML, W } from './namespaces.js';
 import { parseXml, serializeXml } from './xml.js';
-import { getParagraphRuns } from './text.js';
+import { buildParagraphIndex } from './paragraph-index.js';
 import { getParagraphBookmarkId } from './bookmarks.js';
 import { findUniqueSubstringMatch } from './matching.js';
 import { childElements, isW } from './dom-helpers.js';
 import { getFirstChild } from './xml-helpers.js';
-import { extractEffectiveRunFormatting, parseStylesXml } from './styles.js';
+import { extractEffectiveRunFormatting, parseStylesXml, parseThemeXml, } from './styles.js';
 import { emitFormattingTags, mergeAdjacentTags } from './formatting_tags.js';
+import { ensureExternalHyperlinkRelationships } from './relationships.js';
 import { createRevisionContainer, prepareElementForDeletion, } from './track-changes-emitter.js';
 // ── Relationship & content types ────────────────────────────────────────
 const REL_TYPE_FOOTNOTES = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes';
 const CT_FOOTNOTES = 'application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml';
+const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
 // ── Minimal XML template ────────────────────────────────────────────────
 const FOOTNOTES_XML_TEMPLATE = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` +
     `<w:footnotes xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"` +
@@ -178,8 +180,10 @@ function buildDisplayNumberMap(documentXml, footnotesDoc) {
  * When omitted, formatting is read from direct `w:rPr` only — the flattened
  * `text` and the plural anchor map are unaffected either way, so existing
  * callers that pass `(zip, documentXml)` keep their exact behavior.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.11.14
  */
-export async function getFootnotes(zip, documentXml, styles) {
+export async function getFootnotes(zip, documentXml, styles, theme) {
     const footnotesText = await zip.readTextOrNull('word/footnotes.xml');
     if (!footnotesText)
         return [];
@@ -189,6 +193,8 @@ export async function getFootnotes(zip, documentXml, styles) {
         return [];
     const displayMap = buildDisplayNumberMap(documentXml, footnotesDoc);
     const stylesModel = styles ?? parseStylesXml(null);
+    const themeText = theme ? null : await zip.readTextOrNull('word/theme/theme1.xml');
+    const themeModel = theme ?? parseThemeXml(themeText ? parseXml(themeText) : null);
     // Build map of footnoteReference id → every anchored paragraph bookmark id, in
     // document order (deduplicated). The FIRST entry feeds the legacy
     // `anchoredParagraphId`; the whole ordered list feeds `refParagraphIds`.
@@ -196,6 +202,7 @@ export async function getFootnotes(zip, documentXml, styles) {
     // malformed one has been observed reusing an id across several — so we keep
     // them all rather than silently dropping the extras.
     const anchorMap = new Map();
+    const referencePointMap = new Map();
     const refs = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.footnoteReference);
     for (let i = 0; i < refs.length; i++) {
         const ref = refs.item(i);
@@ -214,6 +221,14 @@ export async function getFootnotes(zip, documentXml, styles) {
                     if (!existing.includes(bookmarkId))
                         existing.push(bookmarkId);
                     anchorMap.set(id, existing);
+                    const index = buildParagraphIndex(pel);
+                    const indexedReference = index.nodes.find((node) => node.element === ref);
+                    if (indexedReference) {
+                        referencePointMap.set(id, [
+                            ...(referencePointMap.get(id) ?? []),
+                            { paragraphId: bookmarkId, textOffset: indexedReference.visibleStart },
+                        ]);
+                    }
                 }
                 break;
             }
@@ -229,19 +244,20 @@ export async function getFootnotes(zip, documentXml, styles) {
         if (!idStr)
             continue;
         const id = parseInt(idStr, 10);
-        const paragraphs = extractFootnoteParagraphs(el, stylesModel);
+        const paragraphs = extractFootnoteParagraphs(el, stylesModel, themeModel);
         const text = paragraphs.map((p) => p.text).join('\n');
         const displayNumber = displayMap.get(id) ?? 0;
         const refParagraphIds = anchorMap.get(id) ?? [];
+        const referencePoints = referencePointMap.get(id) ?? [];
         const anchoredParagraphId = refParagraphIds[0] ?? null;
-        footnotes.push({ id, displayNumber, text, anchoredParagraphId, refParagraphIds, paragraphs });
+        footnotes.push({ id, displayNumber, text, anchoredParagraphId, refParagraphIds, referencePoints, paragraphs });
     }
     // Sort by display number (document order)
     footnotes.sort((a, b) => a.displayNumber - b.displayNumber);
     return footnotes;
 }
-export async function getFootnote(zip, documentXml, noteId, styles) {
-    const all = await getFootnotes(zip, documentXml, styles);
+export async function getFootnote(zip, documentXml, noteId, styles, theme) {
+    const all = await getFootnotes(zip, documentXml, styles, theme);
     return all.find((f) => f.id === noteId) ?? null;
 }
 function extractFootnoteText(footnoteEl) {
@@ -259,7 +275,7 @@ function extractFootnoteText(footnoteEl) {
  * skipped so the footnote number never leaks into the body text. The reserved
  * separator paragraphs are filtered out by the caller (`isReservedFootnote`).
  */
-function extractFootnoteParagraphs(footnoteEl, styles) {
+function extractFootnoteParagraphs(footnoteEl, styles, theme) {
     const paragraphs = footnoteEl.getElementsByTagNameNS(OOXML.W_NS, W.p);
     const out = [];
     for (let pi = 0; pi < paragraphs.length; pi++) {
@@ -288,12 +304,18 @@ function extractFootnoteParagraphs(footnoteEl, styles) {
                 paragraphPPr: paraPPr ?? null,
                 paragraphStyleId: style,
                 styles,
+                theme,
             });
             annotated.push({ text: runText, formatting, hyperlinkUrl: null, charCount: runText.length, isHeaderRun: false });
         }
         // `full` mode: no baseline suppression, so every run's bold/italic/etc.
         // survives into tagged_text at node-level fidelity.
-        const tagged = mergeAdjacentTags(emitFormattingTags({ runs: annotated, baseline: FOOTNOTE_TAG_BASELINE, formattingMode: 'full' }));
+        const tagged = mergeAdjacentTags(emitFormattingTags({
+            runs: annotated,
+            baseline: FOOTNOTE_TAG_BASELINE,
+            fontBaseline: { modalColor: null, colorSuppressed: false, modalFontSizePt: 0, fontSizeSuppressed: true, modalFontName: '', fontNameSuppressed: true },
+            formattingMode: 'full',
+        }));
         out.push({ text: textParts.join(''), tagged_text: tagged, style });
     }
     return out;
@@ -311,30 +333,50 @@ function getFootnoteParagraphStyle(p) {
     return getWAttr(pStyle, 'val');
 }
 // ── Insertion ───────────────────────────────────────────────────────────
+/**
+ * Add one footnote definition and its exact point reference in the main story.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.11.14
+ */
 export async function addFootnote(documentXml, zip, params, ctx) {
-    const { paragraphEl, afterText, text } = params;
+    const { paragraphEl, afterText, visibleOffset, text, presentation } = params;
+    if (afterText !== undefined && visibleOffset !== undefined) {
+        throw new Error('afterText and visibleOffset are mutually exclusive footnote anchors');
+    }
     // Load or bootstrap footnotes.xml
     const footnotesXml = await zip.readText('word/footnotes.xml');
     const footnotesDoc = parseXml(footnotesXml);
     // Allocate next ID
     const noteId = allocateNextFootnoteId(footnotesDoc);
     // Insert footnoteReference run in document body
-    insertFootnoteReference(documentXml, paragraphEl, noteId, afterText, ctx);
+    insertFootnoteReference(documentXml, paragraphEl, noteId, afterText, visibleOffset, ctx);
     // Add footnote body to footnotes.xml
-    const footnoteEl = addFootnoteElement(footnotesDoc, noteId, text);
+    const destinations = [
+        ...(presentation?.prefixRuns ?? []),
+        ...(presentation?.separatorRuns ?? []),
+        ...(presentation?.body?.flatMap((paragraph) => paragraph.runs) ?? []),
+    ].flatMap((run) => run.hyperlink ? [run.hyperlink.destination] : []);
+    const hyperlinkRelationshipIds = await ensureExternalHyperlinkRelationships(zip, 'word/footnotes.xml', destinations);
+    const footnoteEl = addFootnoteElement(footnotesDoc, noteId, text, presentation, hyperlinkRelationshipIds);
     if (ctx) {
         wrapFootnoteParagraphTextRuns(getFirstFootnoteParagraph(footnoteEl), 'ins', ctx);
     }
     zip.writeText('word/footnotes.xml', serializeXml(footnotesDoc));
     return { noteId };
 }
-function insertFootnoteReference(documentXml, paragraphEl, noteId, afterText, ctx) {
+function insertFootnoteReference(documentXml, paragraphEl, noteId, afterText, requestedVisibleOffset, ctx) {
     // Create the reference run
     const refRun = documentXml.createElementNS(OOXML.W_NS, 'w:r');
     const rPr = documentXml.createElementNS(OOXML.W_NS, 'w:rPr');
     const rStyle = documentXml.createElementNS(OOXML.W_NS, 'w:rStyle');
     rStyle.setAttributeNS(OOXML.W_NS, 'w:val', 'FootnoteReference');
     rPr.appendChild(rStyle);
+    // Some source documents omit or redefine the FootnoteReference character
+    // style. Keep the semantic style and make the required visual elevation
+    // explicit so the marker remains superscript across those documents.
+    const vertAlign = documentXml.createElementNS(OOXML.W_NS, 'w:vertAlign');
+    vertAlign.setAttributeNS(OOXML.W_NS, 'w:val', 'superscript');
+    rPr.appendChild(vertAlign);
     refRun.appendChild(rPr);
     const fnRef = documentXml.createElementNS(OOXML.W_NS, 'w:footnoteReference');
     fnRef.setAttributeNS(OOXML.W_NS, 'w:id', String(noteId));
@@ -343,44 +385,49 @@ function insertFootnoteReference(documentXml, paragraphEl, noteId, afterText, ct
     if (ctx) {
         refAnchor.appendChild(refRun);
     }
-    if (!afterText) {
+    if (afterText === undefined && requestedVisibleOffset === undefined) {
         // Default: append at end of paragraph
         paragraphEl.appendChild(refAnchor);
         return;
     }
-    // Find the text boundary using unique substring matching
-    const runs = getParagraphRuns(paragraphEl);
-    const fullText = runs.map((r) => r.text).join('');
-    const match = findUniqueSubstringMatch(fullText, afterText);
-    if (match.status === 'not_found') {
-        throw new Error(`after_text '${afterText}' not found in paragraph`);
+    const index = buildParagraphIndex(paragraphEl);
+    const runs = index.runs.filter((run) => run.visibleText.length > 0);
+    let insertOffset;
+    if (requestedVisibleOffset !== undefined) {
+        if (!Number.isInteger(requestedVisibleOffset) || requestedVisibleOffset < 0 || requestedVisibleOffset > index.text.length) {
+            throw new Error(`visibleOffset ${requestedVisibleOffset} is outside paragraph visible text [0, ${index.text.length}]`);
+        }
+        insertOffset = requestedVisibleOffset;
     }
-    if (match.status === 'multiple') {
-        throw new Error(`after_text '${afterText}' found ${match.matchCount} times in paragraph`);
+    else {
+        const match = findUniqueSubstringMatch(index.text, afterText);
+        if (match.status === 'not_found')
+            throw new Error(`after_text '${afterText}' not found in paragraph`);
+        if (match.status === 'multiple')
+            throw new Error(`after_text '${afterText}' found ${match.matchCount} times in paragraph`);
+        insertOffset = match.end;
     }
-    // We need to insert after the end of the matched text
-    const insertOffset = match.end;
     // Map offset to run position
     let pos = 0;
     for (let i = 0; i < runs.length; i++) {
         const run = runs[i];
-        const runEnd = pos + run.text.length;
+        const runEnd = pos + run.visibleText.length;
         if (insertOffset <= pos) {
             // Insert before this run
-            const parent = run.r.parentNode;
-            parent.insertBefore(refAnchor, run.r);
+            const parent = run.element.parentNode;
+            parent.insertBefore(refAnchor, run.element);
             return;
         }
         if (insertOffset > pos && insertOffset < runEnd) {
             // Need to split this run at the offset
             const splitOffset = insertOffset - pos;
-            splitRunAndInsertReference(run.r, splitOffset, refAnchor);
+            splitRunAndInsertReference(run.element, splitOffset, refAnchor);
             return;
         }
         if (insertOffset === runEnd) {
             // Insert after this run
-            const parent = run.r.parentNode;
-            parent.insertBefore(refAnchor, run.r.nextSibling);
+            const parent = run.element.parentNode;
+            parent.insertBefore(refAnchor, run.element.nextSibling);
             return;
         }
         pos = runEnd;
@@ -493,8 +540,11 @@ function setXmlSpacePreserve(t, text) {
         t.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve');
     }
 }
-function addFootnoteElement(footnotesDoc, noteId, text) {
+function addFootnoteElement(footnotesDoc, noteId, text, presentation, hyperlinkRelationshipIds) {
     const root = footnotesDoc.documentElement;
+    if (hyperlinkRelationshipIds?.size && root.lookupNamespaceURI('r') !== OOXML.R_NS) {
+        root.setAttributeNS(XMLNS_NS, 'xmlns:r', OOXML.R_NS);
+    }
     const footnoteEl = footnotesDoc.createElementNS(OOXML.W_NS, 'w:footnote');
     footnoteEl.setAttributeNS(OOXML.W_NS, 'w:id', String(noteId));
     // Word-compatible body skeleton
@@ -511,6 +561,9 @@ function addFootnoteElement(footnotesDoc, noteId, text) {
     const refRStyle = footnotesDoc.createElementNS(OOXML.W_NS, 'w:rStyle');
     refRStyle.setAttributeNS(OOXML.W_NS, 'w:val', 'FootnoteReference');
     refRPr.appendChild(refRStyle);
+    const refVertAlign = footnotesDoc.createElementNS(OOXML.W_NS, 'w:vertAlign');
+    refVertAlign.setAttributeNS(OOXML.W_NS, 'w:val', 'superscript');
+    refRPr.appendChild(refVertAlign);
     refRun.appendChild(refRPr);
     const fnRefEl = footnotesDoc.createElementNS(OOXML.W_NS, 'w:footnoteRef');
     refRun.appendChild(fnRefEl);
@@ -522,19 +575,99 @@ function addFootnoteElement(footnotesDoc, noteId, text) {
     spaceT.appendChild(footnotesDoc.createTextNode(' '));
     spaceRun.appendChild(spaceT);
     p.appendChild(spaceRun);
-    // User text run
-    const textRun = footnotesDoc.createElementNS(OOXML.W_NS, 'w:r');
-    const t = footnotesDoc.createElementNS(OOXML.W_NS, 'w:t');
-    if (text.startsWith(' ') || text.endsWith(' ')) {
-        t.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve');
-    }
-    t.appendChild(footnotesDoc.createTextNode(text));
-    textRun.appendChild(t);
-    p.appendChild(textRun);
+    const prefixRuns = presentation?.prefixRuns
+        ?? (presentation?.prefix ? [{ text: presentation.prefix, style: presentation.prefixStyle }] : []);
+    const separatorRuns = presentation?.separatorRuns
+        ?? (presentation?.prefixSeparator ? [{ text: presentation.prefixSeparator }] : []);
+    appendFootnoteRuns(p, prefixRuns, footnotesDoc, hyperlinkRelationshipIds);
+    appendFootnoteRuns(p, separatorRuns, footnotesDoc, hyperlinkRelationshipIds);
+    const body = presentation?.body ?? [{ runs: [{ text, style: presentation?.bodyStyle }] }];
+    appendFootnoteRuns(p, body[0]?.runs ?? [], footnotesDoc, hyperlinkRelationshipIds);
     footnoteEl.appendChild(p);
+    for (const paragraph of body.slice(1)) {
+        const bodyParagraph = footnotesDoc.createElementNS(OOXML.W_NS, 'w:p');
+        appendFootnoteRuns(bodyParagraph, paragraph.runs, footnotesDoc, hyperlinkRelationshipIds);
+        footnoteEl.appendChild(bodyParagraph);
+    }
     root.appendChild(footnoteEl);
     return footnoteEl;
 }
+/**
+ * Emit footnote runs under destination-grouped external hyperlink wrappers.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.16.22
+ * @see #956
+ */
+function appendFootnoteRuns(paragraph, runs, doc, relationshipIds) {
+    let activeDestination;
+    let activeHyperlink;
+    for (const styledRun of runs) {
+        const destination = styledRun.hyperlink?.destination;
+        if (!destination) {
+            activeDestination = undefined;
+            activeHyperlink = undefined;
+            paragraph.appendChild(buildStyledTextRun(doc, styledRun.text, styledRun.style));
+            continue;
+        }
+        const relationshipId = relationshipIds?.get(destination);
+        if (!relationshipId)
+            throw new Error(`Missing footnote hyperlink relationship for ${destination}`);
+        if (activeDestination !== destination || !activeHyperlink) {
+            activeDestination = destination;
+            activeHyperlink = doc.createElementNS(OOXML.W_NS, 'w:hyperlink');
+            activeHyperlink.setAttributeNS(OOXML.R_NS, 'r:id', relationshipId);
+            paragraph.appendChild(activeHyperlink);
+        }
+        activeHyperlink.appendChild(buildStyledTextRun(doc, styledRun.text, styledRun.style));
+    }
+}
+function buildStyledTextRun(doc, text, style) {
+    const run = doc.createElementNS(OOXML.W_NS, 'w:r');
+    if (style && Object.values(style).some((value) => value !== undefined && value !== false)) {
+        const rPr = doc.createElementNS(OOXML.W_NS, 'w:rPr');
+        const onOff = (name) => {
+            const el = doc.createElementNS(OOXML.W_NS, `w:${name}`);
+            rPr.appendChild(el);
+        };
+        if (style.styleId) {
+            const rStyle = doc.createElementNS(OOXML.W_NS, 'w:rStyle');
+            rStyle.setAttributeNS(OOXML.W_NS, 'w:val', style.styleId);
+            rPr.appendChild(rStyle);
+        }
+        if (style.fontSizeHalfPoints !== undefined) {
+            const size = doc.createElementNS(OOXML.W_NS, 'w:sz');
+            size.setAttributeNS(OOXML.W_NS, 'w:val', String(style.fontSizeHalfPoints));
+            rPr.appendChild(size);
+        }
+        if (style.bold)
+            onOff('b');
+        if (style.italic)
+            onOff('i');
+        if (style.underline) {
+            const u = doc.createElementNS(OOXML.W_NS, 'w:u');
+            u.setAttributeNS(OOXML.W_NS, 'w:val', 'single');
+            rPr.appendChild(u);
+        }
+        if (style.color) {
+            const color = doc.createElementNS(OOXML.W_NS, 'w:color');
+            color.setAttributeNS(OOXML.W_NS, 'w:val', style.color);
+            rPr.appendChild(color);
+        }
+        if (style.highlight && style.highlight !== 'none') {
+            const highlight = doc.createElementNS(OOXML.W_NS, 'w:highlight');
+            highlight.setAttributeNS(OOXML.W_NS, 'w:val', style.highlight);
+            rPr.appendChild(highlight);
+        }
+        run.appendChild(rPr);
+    }
+    const t = doc.createElementNS(OOXML.W_NS, 'w:t');
+    if (text.startsWith(' ') || text.endsWith(' ')) {
+        t.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve');
+    }
+    t.appendChild(doc.createTextNode(text));
+    run.appendChild(t);
+    return run;
+}
 // ── Update ──────────────────────────────────────────────────────────────
 export async function updateFootnoteText(zip, params, ctx) {
     const { noteId, newText } = params;
@@ -661,78 +794,90 @@ function buildFootnoteTextRuns(doc, text) {
     return [spaceRun, textRun];
 }
 function removeFootnoteParagraphTextRuns(paragraph) {
-    const collected = collectFootnoteTextRuns(paragraph);
-    if (!collected)
-        return;
-    for (const run of collected.runs) {
-        run.parentNode?.removeChild(run);
+    for (const group of collectFootnoteTextRunGroups(paragraph)) {
+        for (const run of group.runs)
+            group.parent.removeChild(run);
     }
-    cleanupEmptyRevisionWrappers(paragraph);
+    cleanupEmptyRunContainers(paragraph);
 }
+/**
+ * Wrap every text run of a footnote paragraph in a `w:ins` / `w:del`
+ * revision container. Runs are wrapped per parent container, so text that
+ * already sits inside a revision wrapper or inside a `w:hyperlink` stays
+ * where it is: the new container is created inside that parent, which keeps
+ * document order and link identity intact instead of hoisting linked runs
+ * out of their hyperlink.
+ *
+ * @conformance ECMA-376 edition 5, Part 1 § 17.16.22
+ * @see #956
+ */
 function wrapFootnoteParagraphTextRuns(paragraph, kind, ctx) {
-    const collected = collectFootnoteTextRuns(paragraph);
-    if (!collected)
+    const groups = collectFootnoteTextRunGroups(paragraph);
+    if (groups.length === 0)
         return null;
     const doc = paragraph.ownerDocument;
     if (!doc)
         throw new Error('Paragraph has no ownerDocument');
-    const { parent: anchorParent, before: anchorBefore } = collected.insertionAnchor;
-    const wrapper = createRevisionContainer(doc, kind, ctx);
-    anchorParent.insertBefore(wrapper, anchorBefore);
-    for (const run of collected.runs) {
-        run.parentNode?.removeChild(run);
-        wrapper.appendChild(kind === 'del' ? prepareElementForDeletion(run) : run);
+    let first = null;
+    for (const group of groups) {
+        const wrapper = createRevisionContainer(doc, kind, ctx);
+        group.parent.insertBefore(wrapper, group.runs[0]);
+        for (const run of group.runs) {
+            group.parent.removeChild(run);
+            wrapper.appendChild(kind === 'del' ? prepareElementForDeletion(run) : run);
+        }
+        first ??= wrapper;
     }
-    cleanupEmptyRevisionWrappers(paragraph);
-    return wrapper;
+    cleanupEmptyRunContainers(paragraph);
+    return first;
 }
 /**
  * Collect every `<w:r>` descendant of the paragraph that does NOT contain a
- * `footnoteRef` marker. This intentionally crosses into `<w:ins>` / `<w:del>`
- * wrappers so that footnote text already carrying revision history (e.g.,
- * third-party documents or prior tracked edits in the same session) is still
- * captured by `updateFootnoteText` and `deleteFootnote`. The first-found
- * insertion-anchor (the parent of the first match) is returned so callers
- * can place a new wrapper at the same structural position.
+ * `footnoteRef` marker, grouped by immediate parent in document order. The
+ * traversal intentionally crosses `<w:ins>` / `<w:del>` wrappers so footnote
+ * text already carrying revision history (third-party documents or prior
+ * tracked edits in the same session) is still captured by
+ * `updateFootnoteText` and `deleteFootnote`, and crosses `<w:hyperlink>`
+ * containers so linked text is captured without being detached from its link.
  */
-function collectFootnoteTextRuns(paragraph) {
-    const collected = [];
+function collectFootnoteTextRunGroups(paragraph) {
+    const groups = [];
     function visit(parent) {
         for (const child of childElements(parent)) {
             if (isW(child, W.r)) {
-                if (!runContainsFootnoteRef(child)) {
-                    collected.push({ parent, run: child });
-                }
+                if (runContainsFootnoteRef(child))
+                    continue;
+                const last = groups[groups.length - 1];
+                if (last && last.parent === parent)
+                    last.runs.push(child);
+                else
+                    groups.push({ parent, runs: [child] });
                 continue;
             }
-            if (isW(child, 'ins') || isW(child, 'del')) {
+            if (isW(child, 'ins') || isW(child, 'del') || isW(child, W.hyperlink)) {
                 visit(child);
             }
         }
     }
     visit(paragraph);
-    if (collected.length === 0)
-        return null;
-    const first = collected[0];
-    return {
-        insertionAnchor: { parent: first.parent, before: first.run },
-        runs: collected.map((entry) => entry.run),
-    };
+    return groups;
 }
 function runContainsFootnoteRef(run) {
     return run.getElementsByTagNameNS(OOXML.W_NS, W.footnoteRef).length > 0;
 }
 /**
  * After detaching runs from their parents, sweep up any now-empty
- * `<w:ins>`/`<w:del>` siblings of the paragraph so we do not leave orphan
- * revision wrappers behind. This pairs with `collectFootnoteTextRuns`'s
- * cross-wrapper traversal.
+ * `<w:ins>` / `<w:del>` wrappers and `<w:hyperlink>` containers at any depth
+ * so we do not leave orphan containers behind. This pairs with
+ * `collectFootnoteTextRunGroups`'s cross-container traversal.
  */
-function cleanupEmptyRevisionWrappers(paragraph) {
-    for (const child of Array.from(childElements(paragraph))) {
-        if ((isW(child, 'ins') || isW(child, 'del')) && childElements(child).length === 0) {
-            paragraph.removeChild(child);
-        }
+function cleanupEmptyRunContainers(element) {
+    for (const child of Array.from(childElements(element))) {
+        if (!(isW(child, 'ins') || isW(child, 'del') || isW(child, W.hyperlink)))
+            continue;
+        cleanupEmptyRunContainers(child);
+        if (childElements(child).length === 0)
+            element.removeChild(child);
     }
 }
 function isolateReferenceRun(run, ref) {