feat: editable footnotes (re-land #995)

[jacobjove]

Re-lands the editable-footnotes feature. It merged as #995 but dropped out of main during the chore: release (#983) rebase (the useDocxEditor.ts max-lines cap from #996 stayed, but the feature commits did not). This branch is the same work rebased onto current main.

Footnotes become editable in the live editor: click into a footnote to place a caret, type, select, and delete like body text; in suggesting mode footnote edits are tracked changes, and edits round-trip back into the document. React and Vue at parity.

Includes the post-merge follow-up fixes that were never merged separately: exit-edit-mode when the footnote is gone, black caret + glyph-accurate click placement, click-drag selection, context-menu dismissal, and toolbar-flicker on body→footnote clicks.

useDocxEditor.ts lands at 1003 lines, under the 1060 cap already on main, so lint stays green. API snapshots regenerated against current main.

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docx-editor	Ready	Preview, Comment	Jun 24, 2026 3:32pm

[jacobjove]

@jedrazb heads-up: this re-lands #995, which you merged on 2026-06-23 but which then dropped out of main during the chore: release (#983) rebase. The useDocxEditor.ts max-lines bump you added in #996 to keep it survived, but the feature commits themselves did not — there's no revert or follow-up commit, so it looks like an accidental rebase/force-push casualty rather than an intentional removal. This branch is the identical work rebased cleanly onto current main (no conflicts, snapshots regenerated). Flagging in case your release reflog shows what happened.

[eigenpal-release-pal]

All contributors have signed the CLA ✍️ ✅

_{Posted by the CLA bot.}

[greptile-apps]

Greptile Summary

Re-lands editable footnotes: clicking into a painted footnote now places a real ProseMirror caret, supports typing/selection/delete like body text, tracks changes in suggesting mode, and round-trips edits back into the saved DOCX. The feature follows the established hidden-PM model already used for header/footer editing — a lazy single off-screen EditorView per active footnote, with the painter reading the live PM doc via a getFootnotePmDoc seam on computeLayout.

• Core changes: footnoteOverlay.ts (caret + selection rect helpers scoped per-container to avoid footnote PM position collisions), noteSerializer.ts (re-inserts the auto-number ref mark that the body parser doesn't model), footnoteLayout.ts + computeLayout.ts (getFootnotePmDoc live-doc seam).
• React: HiddenFootnotePM, useFootnoteEditState, updated usePagesPointer (footnote surface routing alongside HF), DocxEditorPagedArea overlay wiring, PagedEditor integration.
• Vue parity: useFootnotePM, useFootnoteOverlay, FootnoteOverlay.vue, usePagesPointer routing; the Vue caret placement intentionally stays at coarse span-snap (a precise mid-span variant exposed a multi-char typing scatter and is deferred).

Confidence Score: 3/5

Safe to merge after fixing the Vue stopPropagation call — the React path is solid, but the Vue footnote-click handler breaks context-menu dismissal in a way that's directly contradicted by the PR's own stated goals.

The Vue usePagesPointer footnote handler calls event.stopPropagation() on every footnote click, which stops the mousedown from reaching document. Any open context menu's outside-click listener therefore never fires, so the menu stays visible. The React implementation deliberately omits this call and even carries a comment explaining why — context-menu dismissal depends on the native mousedown bubbling to document. This means a behavior the PR description lists as fixed (context-menu dismissal) is broken in the Vue adapter. Everything else — the hidden PM model, the serializer auto-number patch, the overlay helpers, the React path — looks well-structured and correct.

packages/vue/src/composables/usePagesPointer.ts — the footnote mousedown handler (around the fnHit block) needs event.stopPropagation() removed.

Important Files Changed

Filename	Overview
packages/vue/src/composables/usePagesPointer.ts	Adds footnote-edit routing to Vue's pointer handler; calls event.stopPropagation() on footnote clicks (React explicitly omits this to preserve context-menu dismissal).
packages/react/src/components/DocxEditor/hooks/usePagesPointer.ts	Adds footnote surface routing alongside HF; refactors HF snap-to-span into shared snapToScopedSpan; has one stale orphaned JSDoc block.
packages/react/src/components/DocxEditor/HiddenFootnotePM.tsx	New lazy single hidden PM for the active footnote, mirrors the HF model; teardown, writeback, and suggestion-mode sync look correct.
packages/react/src/components/DocxEditor/hooks/useFootnoteEditState.ts	Owns footnote-edit state and HF PM-doc resolver; exit-to-body deferred focus pattern correctly relies on React effect ordering after child teardown.
packages/vue/src/composables/useFootnotePM.ts	Vue parity for the lazy single hidden footnote PM; appends host to window.document.body (consistent with the Vue adapter's HF off-screen pattern).
packages/core/src/layout-bridge/footnoteOverlay.ts	Framework-free caret and selection rect helpers for painted footnotes; multi-tier fallback strategy looks solid; scoping constraint (per-container) is correctly documented and enforced.
packages/core/src/docx/serializer/noteSerializer.ts	Adds withNoteRefMark to re-insert the auto-number marker on serialization; shallow-clones content arrays to keep inputs pure; guarded by skip-if-present check.
packages/react/src/components/DocxEditor/DocxEditorPagedArea.tsx	Adds footnote caret/selection overlay and transaction forwarding; uses window.document.querySelector('.paged-editor__pages') which is consistent with the existing HF pattern but fragile for multi-editor setups.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User
    participant usePagesPointer
    participant HiddenFootnotePM
    participant computeLayout
    participant footnoteOverlay
    participant DocxEditorPagedArea

    User->>usePagesPointer: mousedown on painted footnote
    usePagesPointer->>usePagesPointer: resolveFootnoteHit(target)
    usePagesPointer->>usePagesPointer: setFootnoteEditId(id)
    usePagesPointer->>usePagesPointer: rAF poll: placeCaret → footnotePosAtPoint
    HiddenFootnotePM-->>usePagesPointer: view mounts (lazy)
    usePagesPointer->>HiddenFootnotePM: surf.setSelection(pos) + focus()

    User->>HiddenFootnotePM: keystroke (off-screen PM receives input)
    HiddenFootnotePM->>HiddenFootnotePM: dispatchTransaction → syncBlocksToDocument
    HiddenFootnotePM->>computeLayout: runLayoutPipeline (body state)
    computeLayout->>computeLayout: getFootnotePmDoc(id) → live PM doc
    computeLayout->>footnoteOverlay: painter repaints with live doc
    footnoteOverlay-->>DocxEditorPagedArea: onFootnoteTransaction → applyFootnoteOverlay
    DocxEditorPagedArea->>DocxEditorPagedArea: render caret/selection rects (position:fixed)

    User->>usePagesPointer: mousedown outside footnote
    usePagesPointer->>usePagesPointer: exitFootnoteToBody(bodyPos)
    usePagesPointer->>HiddenFootnotePM: setFootnoteEditId(null) → teardown
    HiddenFootnotePM-->>usePagesPointer: view destroyed
    usePagesPointer->>usePagesPointer: deferred rAF → body.setSelection + focus

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User
    participant usePagesPointer
    participant HiddenFootnotePM
    participant computeLayout
    participant footnoteOverlay
    participant DocxEditorPagedArea

    User->>usePagesPointer: mousedown on painted footnote
    usePagesPointer->>usePagesPointer: resolveFootnoteHit(target)
    usePagesPointer->>usePagesPointer: setFootnoteEditId(id)
    usePagesPointer->>usePagesPointer: rAF poll: placeCaret → footnotePosAtPoint
    HiddenFootnotePM-->>usePagesPointer: view mounts (lazy)
    usePagesPointer->>HiddenFootnotePM: surf.setSelection(pos) + focus()

    User->>HiddenFootnotePM: keystroke (off-screen PM receives input)
    HiddenFootnotePM->>HiddenFootnotePM: dispatchTransaction → syncBlocksToDocument
    HiddenFootnotePM->>computeLayout: runLayoutPipeline (body state)
    computeLayout->>computeLayout: getFootnotePmDoc(id) → live PM doc
    computeLayout->>footnoteOverlay: painter repaints with live doc
    footnoteOverlay-->>DocxEditorPagedArea: onFootnoteTransaction → applyFootnoteOverlay
    DocxEditorPagedArea->>DocxEditorPagedArea: render caret/selection rects (position:fixed)

    User->>usePagesPointer: mousedown outside footnote
    usePagesPointer->>usePagesPointer: exitFootnoteToBody(bodyPos)
    usePagesPointer->>HiddenFootnotePM: setFootnoteEditId(null) → teardown
    HiddenFootnotePM-->>usePagesPointer: view destroyed
    usePagesPointer->>usePagesPointer: deferred rAF → body.setSelection + focus

Loading

_{Reviews (1): Last reviewed commit: "fix(footnotes): stop toolbar flicker whe..." | Re-trigger Greptile}