Add citation/reference hover preview

[koppor]

Unfortunately it's too complicated. I don't see us implementing that.

#128 (comment)

11 years later, Claude can help.

This update is entirely written by claude - "only" driven by me in a code-and-fix mannger

Screenshot:

• Closes Preview of Internal Links #3326
• Fixes Popup preview of PDF links #128
• Fixes Can we have a snapshot feature like Skim in MacOS #4221

Summary

Hovering an internal-document link (citation, figure reference, footnote marker, etc.) shows a small popup rendering the destination region of the target page — so a [1] citation, a "Figure 2.3" reference, or a footnote can be inspected without leaving the current page. Inspired by PDFRefPreview.

Fixes #128
Fixes #4221

Demo

Hover any in-text reference for ~300 ms. The popup shows just the relevant entry / figure / footnote, cropped to its actual text box. Works for both 1-column and 2-column layouts, hanging-indent and numeric [N] bibliographies, and figure references (where the strip falls back to a generous region around the anchor).

Implementation

Detection (src/Canvas.cpp + src/RefHover.cpp):

• IsCitationLink accepts any internal kindPageElementDest link.
• DetectEntryBox does a per-glyph text+coords scan starting at destY, with several boundary signals: [N at the entry's first-line X, indent change back to that X, an X that matches neither first-line nor continuation X, vertical paragraph break, single-line-entry pattern, and column wrap.
• Falls back to a fixed strip when text scan finds nothing near destY, and to a taller strip when the detected box is suspiciously small (figure / diagram fragment).
• The detected region is rendered via engine->RenderPage and blitted into a popup, letterboxed to fit max bounds.

Engine API change (would appreciate a quick eyeball on this part):

• New virtual IPageDestination::GetDestPoint2() in src/EngineBase.h, default returns GetRect2() (so existing implementations are unaffected).
• New helper PageDestGetDestPoint().
• PageDestinationMupdf (in src/EngineMupdf.cpp) now stores destX/destY resolved via fz_resolve_link at construction; previously the resolved (x, y) from ResolveLink was discarded after the page number was extracted.

Plumbing:

• New files src/RefHover.cpp / src/RefHover.h.
• MainWindow gets a refHover member, destroyed in dtor.
• Canvas::OnMouseMove schedules / hides the popup; OnTimer renders.
• Both vs2022/*.vcxproj and *.vcxproj.filters updated.

Setting: EnableCitationHover advanced setting (default true, version 3.7), defined in cmd/gen-settings.ts. Generated files updated.

Test plan

• bun ./cmd/build.ts clean — 0 warnings, 0 errors.
• 2-column academic paper, numeric [N] citations: tight popup of the right column entry only.
• 1-column paper, author-year hanging-indent bibliography (Bischoff and Küchlin, 2017 → bib entry Daniel Bischoff and Wolfgang Küchlin. Adapting…): single entry, correctly cropped.
• Last bibliography entry (no [N] follows): stops before author bios / footers thanks to the indent-change signal.
• Footnote markers (single-line stacked footnotes ¹url \n ²url \n …): just the hovered footnote.
• Figure / table reference (Figure 2.2): falls back to a generous strip around the anchor so the diagram is visible.
• Toggle EnableCitationHover to false: existing popup is hidden, no further popups scheduled.

Notes

• Test PDF used during development: tests-manual/extract-references/paper1/main.pdf from the JabRef repo. Not included in this PR.
• The RefHover.cpp text-scan boundary heuristics are defensive (multiple signals), but they're heuristics — happy to iterate based on PDFs that don't crop cleanly.

🤖 Generated with Claude Code

[GitHubRulesOK]

Looks very usefull do you have a compiled exe for me to play with while testing some other files

[koppor]

Looks very usefull

Thank you! I was searching for that feature for a long time - but none of the existing apps convinced me. Sioyek kind of looked nice, but it has other issues (e.g., ahrm/sioyek#1350)

do you have a compiled exe for me to play with while testing some other files

Sure! I put it at https://builds.jabref.org/main/SumatraPDF-dll.exe .

[GitHubRulesOK]

Thanks so not your fault the first file I opened is another new oddity where fonts are big and thus window content is limited which begs the question what do other apps have such as is there a zoomin out function

[koppor]

Good question — I just added mouse-wheel zoom for the popup. Hover a citation link to bring up the popup, then scroll the wheel while still hovering the link to zoom the preview in/out:

• Wheel down (zoom out): the popup re-renders a larger region of the page, so previously-empty space fills with new content from below/right of the detected entry. Useful when the destination has large fonts or when the auto-detected region was too small.
• Wheel up (zoom in): re-renders a smaller region at higher detail, cropping the trailing whitespace.

The popup window keeps its initial size; only the rendered content changes. The initial zoom now matches the document's current page zoom, so popup text height is comparable to the visible page text.

New build: https://builds.jabref.org/main/SumatraPDF-dll-2.exe

[GitHubRulesOK]

@koppor Fantastic improvement though took me a while to grasp the concept of zoom the source box but once tried out it makes sense as an alternative to try to zoom the quick viewbox (I have had issues with that when attempting a magnifier box as mouse focus is then relocated). The last core issue I see is the "window" is highly varied depending on sources own desired target. Take this silly example, where the target is a wide set of goto with a topbar target. It would be better if the quickview is a fixed ratio.

[koppor]

@GitHubRulesOK Good catch — pushed 77b017f to address that.

Now the popup shape depends on what the link actually points to:

• Reference (bibliography entry): detection finds a [N]/author-year-shaped block — popup is sized to that block (as before).
• Non-reference (TOC, topbar, generic goto): detection's text scan doesn't find a bibliography-shaped entry — popup falls back to a fixed-ratio box (≈ 360×260 pt) anchored on the destination, regardless of what's nearby.

So your wide-thin "topbar goto" example now gets the same compact box as any other non-reference target, rather than stretching to the right page margin.

Build with this fix: https://builds.jabref.org/main/SumatraPDF-dll-3.exe

[GitHubRulesOK]

@koppor I am not trying to be a killjoy this IS a good improvement

but it may just be that the examples I have to hand are wildly variable so in the case shown below the target is top of table but user would expect a box much higher than the target zone more like a landscape view of page width or half page width for 2 column content. I understand it cannot always be known what users desire but the qwickview overlay could be as wide as the current viewport page width and half the current source page height as it is temporary.

[koppor]

@koppor I am not trying to be a killjoy

The thing is that with the AI helper, it is much easier to adress user comments and wishes.

I only hope that the code style is good enough. 😅

[GitHubRulesOK]

@kjk can the PR be adjusted to your expectation of common user desires my test with others suggest they use a fixed window size so click figure1 will show a large area around that goto

[koppor]

Pushed 5915fb57f. Test build: https://builds.jabref.org/main/SumatraPDF-dll-4.exe

Iterated through several non-bibliography hover targets and edge cases in description-list bibliographies. The detector now handles:

Figures / tables / code listings / headings

• Figure / Table / Listing / Algorithm N.M caption anywhere below the detected entry box → landscape view, popup includes the caption. Catches code listings whose lines start with [TAG] (e.g. linter output) that would otherwise look like a description-list bib.
• High brace/semicolon/paren density inside the entry box → code-listing destination → landscape view (caption follows below).
• Numbered (6.2 Foo) or label-prefixed (Figure 2.2, Section 7) entries → landscape view so the heading + content below land in the popup.

Description-list bibliographies and abbreviation lists

• descListSibling flag set on rule (a) [-at-firstLineLeftX, rule (b) indent-change-back, rule (c) vertical paragraph break with the next glyph at firstLineLeftX, and rule (d) single-line case. Fixes single-line abbreviation entries (JVM, AKM, ADR, OMT, ...) where blank lines separate sibling entries — rule (c) used to fire first and route to landscape view.
• Walk startIdx to the line's leftmost glyph after the y-band scan. PDF link destX is unreliable (often carries the source-page X), which would land startIdx mid-line on hanging-indent layouts and drop the leading [KOS06] / "Philippe Kruchten" portion from the popup.

Page-level link destinations

• PageDestGetDestPoint returns {0,0,0,0} when the link has no specific anchor — common for body-text abbreviation links. Plumb the source page + source rect through RefHoverSchedule; on destY <= 0 extract the longest alphanumeric run from the source rect (preferring (XYZ)-flanked tokens over [citationKey]-style tokens) and search the destination page for it. The matched glyph's Y becomes destY. Hovering (AKM) body text now crops to just the AKM entry instead of showing the whole abbreviations page.

Popup positioning / re-render

• Cap popup height by monitor work-area (~90%, max 1400px); clamp position to work-area edges so the popup isn't clipped at the top/left when the cursor is near a screen corner.
• Re-render guard now also compares destX/destY: two adjacent links sharing a destination page but landing at different positions each render their own content (no stale popup).
• LandscapeBox trims trailing blank page margin so the popup ends just below the last text glyph instead of including the page footer.

Top-of-file checklist comment in src/RefHover.cpp documents the case classes covered and remaining known limits (link destinations whose source rect doesn't isolate a unique key still fall back to the full-page landscape view).

[koppor]

The new build is available at https://builds.jabref.org/main/SumatraPDF-dll-4.exe