Emit a note backlink only when its target is in the output

[JSv4]

The bug

WmlToHtmlConverter gave every footnote and endnote definition it rendered a return-arrow hyperlink back to the reference that cites it — including definitions that nothing cites.

TestFiles/NVCA-Model-COI.docx is the in-repo case: word/endnotes.xml carries a blank w:endnote with w:id="1", and no w:endnoteReference for it exists in any story. Word keeps orphans like this and the converter renders them, which is the right call for package fidelity. But the arrow it rendered alongside them pointed at #en-ref-1, an id the conversion never emitted. Standalone export then reported

fragment_target_unavailable: Fragment target #en-ref-1 is unavailable in the final page tree.

for markup the converter had authored itself. Under a strict unsupported-content policy that is not a warning, it is a failed export.

Why it happened

The two halves of a note's navigation come from different code paths reading different sources. The marker (#fn-N) is emitted from a w:footnoteReference in a rendered story; the return arrow (#fn-ref-N) is emitted from a w:footnote definition in footnotes.xml. Neither half checks that the other exists, and the relationship fails in both directions — an orphaned definition has no reference, and a reference can outlive its definition.

The fix

One post-pass, RemoveUnresolvableNoteLinks, alongside the two whole-tree passes the converter already runs after the transform.

It resolves against the finished tree, not against the numbering tracker. That matters. FootnoteNumberingTracker only scans the main document part, so a reference living in a header or footer never reaches it — a tracker-based check would have stripped a backlink whose target genuinely does exist. Asking "is this id in the output?" is the question the acceptance criterion actually states, and it is story-agnostic by construction.

The two directions are repaired differently, because they are not the same kind of thing:

• A return arrow is navigation chrome. An unresolvable one is removed outright, along with the separator space rendered with it, so an orphaned note keeps no trailing gap.
• A marker carries the note's visible number, which is document content. An unresolvable one keeps its text and loses only its dead href, becoming the inert label the issue's second option describes.

Only note links are touched (#fn-…, #en-…). Dangling cross-reference or bookmark links are a different question with a different right answer, and comment backlinks were already made target-aware in #563.

Validation

• On the NVCA fixture, the conversion goes from one dangling fragment target (en-ref-1) to none, while all 94 cited footnotes keep working navigation in both directions.
• Six new tests in WmlToHtmlConverterNoteLinkTests cover: the orphaned endnote still renders but without an arrow; the whole NVCA conversion has zero dangling fragment targets; cited footnotes keep both directions; a fixture carrying both an uncited footnote and an uncited endnote produces no dangling links; and the mirror case — a cited note whose definition was deleted — keeps its marker text but loses its href.
• Non-vacuous: with the post-pass disabled, five of the six fail. The sixth asserts the fixture really does carry an uncited endnote, so the others cannot pass by testing nothing.
• Full .NET suite: 3931 passed, 0 failed, 3 skipped.

Scope note

The issue's last two acceptance bullets concern @docxodus/export. This change removes the cause — the converter no longer authors a link to a target it did not emit — so the export warning cannot be raised for this document. The export path's own handling of a genuinely dangling link (strip the href, mark it aria-disabled, warn or fail per policy) is unchanged and still correct for links it did not author.

Closes #667

🤖 Generated with Claude Code

https://claude.ai/code/session_01VSnwkK1Nx6zZb2RnnoxKdx

[JSv4]

Follow-up: the first version of this fix hung the editor

CI caught it, and it was a real defect in my change, not a flake: npm/tests/editor-reconcile.spec.ts — reconciled edits survive save/reopen losslessly — timed out at insertFootnote, on all three retries, and reproduced locally every time. main runs the same spec in 15s.

The mistake. The sweep asks "is this note link's target id in the output?" That is a fair question of a complete document and the wrong question of a fragment. The editor's incremental renderer builds a shell whose body holds only the blocks it asked for, so a citing paragraph rendered on its own has no notes section to point at — and the sweep stripped the href off its citation marker on every re-render.

How it was localized. Calling RenderBlocksHtmlForReview straight through the bridge with the same anchors returned in 6–33 ms and handed back the marker as <a id="fn-ref-1" class="footnote-ref"><sup>1</sup></a> — no href. So the render was never slow; the missing href was what sent the reconciler into a spin that blocked the browser's main thread outright (a waitForFunction for a plain variable could not run either). The equivalent .NET call had always returned in ~0.6 s, which is what made this look WASM-specific at first.

The fix. A new internal WmlToHtmlConverterSettings.RendersDocumentFragment, set by BuildBlockConverterSettings — the single owner of the block-render profile, and already home to SkipFormattingPartsSimplification, the existing "this is the incremental path, not the full one" knob. Completeness checks over the finished tree are skipped when it is set. Nothing else changes, and the full-document render — the one the reported export bug lives on — is unaffected.

Verification

• editor-reconcile.spec.ts: 7 passed in 15.0s, matching main's timing.
• Full .NET suite: 3932 passed, 0 failed, 3 skipped.
• New regression test renders a citing block through the incremental path and asserts the marker keeps both its class and its href. Flipping RendersDocumentFragment back to false fails it, so it pins this bug specifically rather than the general sweep.