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://files.jabref.org/sumatra/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://files.jabref.org/sumatra/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://files.jabref.org/sumatra/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://files.jabref.org/sumatra/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://files.jabref.org/sumatra/SumatraPDF-dll-4.exe

[koppor]

@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

I personally would like to see where the hover comes from - so that my eyes can jump from the source to the target and back. I will try that soon.

[GitHubRulesOK]

@koppor It is not for me to be a director (I script/program bits but am not a programmer) simply an OLD observer on behalf of others (collaborator)

But my brief observation based on suggested Sioyek is they seem to use roughly 80% of current viewer width (10% to 90%) and perhaps 40 - 45 % height where you could still see the source if the box be flipped above or below that point.

[koppor]

Pushed 93ab2c6 (this PR). Test build: https://files.jabref.org/sumatra/SumatraPDF-dll-5.exe

Iterated on popup geometry and figure-caption detection so the popup is unobtrusive (preserves context around the hovered link) and tightly cropped to the relevant region for figures/tables/listings.

Popup positioning & sizing

• Popup is now horizontally centered on the source page (dm->GetPageInfo(srcPage)->pageOnScreen plumbed through RefHoverSchedule). When the popup is wider than the page text column, it expands symmetrically into the gray margins rather than drifting toward one edge.
• Width capped at ~95% of monitor work area. Height capped at 45% of the source page on screen (default), or up to 75% / cursor-relative spaceAbove for the figure-with-caption case so the body + caption both fit without scaling text down.
• 30px gap above/below the cursor (was 16) so 1-2 lines of context around the hovered word stay visible.
• Popup never overlaps the cursor: prefer below, flip above on overflow; if neither side has room for the full popup, the popup height shrinks to the larger side rather than clamping into the cursor's text line.
• Vertical bounds clamp the popup to the source page's screen rect (doesn't escape into the next page area); horizontal bounds use the monitor work area so the popup can span past the page text column.

LandscapeBox region & caption detection (figures, tables, listings, sections — anywhere DetectEntryBox falls back to a landscape view)

• Base region capped at 200pt tall (was destY → bottom-of-page) so the popup is wide and short rather than narrow and tall.
• Caption-extension: when a Figure N.M / Table N.M / Listing N.M / Algorithm N.M line-start is detected, the region extends downward to include the full caption block. Search range goes to the bottom of the page so tall figures with captions far below the initial cap still match. Logic moved out of DetectEntryBox into LandscapeBox itself, so it applies both when DetectEntryBox produces a fitted box AND when it falls through (image-only figures with no extractable text at destY).
• Caption end is detected by line-by-line Y-range scan (text-stream order is unreliable for figure-float text) with a justification check: walk up to 3 lines from caption start; stop at any line whose right edge reaches within 30pt of the page text margin (= justified body paragraph). Avoids sweeping body text in when the caption is followed by a no-parskip body paragraph (Figure 2.1 case) while still extending through the full 3-line caption when caption lines are raggedright (typical LaTeX).

[koppor]

New test build with two more fixes: https://files.jabref.org/sumatra/SumatraPDF-6.exe

Commit 929de36 (this PR):

Hyphenated multi-line captions (e.g. German "Abbildung 2.1: ...Verdecchia und Bo-/gner [VB25]..."). The previous "stop on any line reaching the right margin" rule truncated captions whose lines all hit the column edge due to hyphenation. Replaced with a dual signal:

• gap > 70% line height = paragraph break (ends caption),
• a short caption line followed by a justified line also ends the caption.

Covers both parskip-spaced captions and short-caption-then-body layouts.

Bracket-entry label on different baseline ([VB25]-style bibs). After the same-y walk-leftmost step, if the chosen start glyph still isn't "[", search for "[" within ~one line height of the start glyph at any smaller x. Catches description-list bibs where the label sits on a slightly different baseline than body line 1 — previously the popup rendered only a narrow vertical strip from mid-body-text rather than the full entry.

[GitHubRulesOK]

@kjk I think this is also the close out answer to #1085 as OP complaint was having to see-saw to check a target goto.
@koppor I still have problems with the way the goto is boxed as there are so many ways those can be defined and the test case is now a good width but still not a minimal height in proportion so I see this for the poor test file
Bluey.pdf it is a BAD example but the point is it has a height that in your earlier example was better. but the fig 2 case is very good
BPG-Math-in-PDF - Copy.pdf

[koppor]

I still have problems with the way the goto is boxed as there are so many ways those can be defined and the test case is now a good width but still not a minimal height in proportion

Oh, yes 🙈

My aim is to distinguish scientific references and other things. If other things: Show half of page. If scientific: Show only the relevant target. Seems the current algorithm classifies your first example wrong.

[koppor]

Fixed in c76ea35 — three issues for malformed /XYZ destinations and image-heavy dest pages (e.g. Bluey.pdf "JUMP TO ALL (A-Z)" button, /Dest /allcharacters → /XYZ 0 -2.580017 0):

1. destY past page bottom now treated as page-level so source-text resolver runs.
2. ResolveDestYFromSourceText tries every alphanumeric candidate run (parens-flanked first, then length desc) — "Jump to all (a-z)" now falls back to "all" when "Jump" is absent on the dest page.
3. Sparse-text dest pages (< 50 chars) return the full page region instead of fitting to a thin heading sliver.

Test build: https://files.jabref.org/sumatra/SumatraPDF-7.exe

[GitHubRulesOK]

OH yes much much better for that odd ball and I am writing others :-) with my goto script so I wonder what happens there ah command was below as MuPDF uses that format and that type of Adobe XYZ is simply goto topleft with a 2x magnification.

"C:\Program Files\SumatraPDF\SumatraPDF.exe" run AddLink.js -x=10 -y=10 -w=150 -h=14 -t="Double Zoom to page 2" -d="2,XYZ[14,85,200]" -p=1 -i="test.1.pdf"

Result is
output.pdf

what most viewers do is

[koppor]

Thanks for the AddLink.js repro — useful test vehicle (although I just used your output.pdf)

Two follow-ups landed on this branch since:

1. Hover preview now honours the /XYZ zoom hint. Hovering "Double Zoom to page 2" renders page 2 anchored at the destination's top at the link's requested zoom (clamped to at least the current display zoom so the preview never feels like a zoom-out). Strict /XYZ would crop at the destination's left value, which lopped off the first glyph of the target lines, so the preview spans the full page width.
2. When a Link annotation sits underneath a FreeText annotation (the typical AddLink.js layout — visible label + clickable goto), the "Free Text annotation. Ctrl+click to edit." notification is suppressed so the hover preview wins.

New build: https://files.jabref.org/sumatra/SumatraPDF-8.exe

---

Is it OK that the preview exceeds the bound of the SumatraPDF window?

[GitHubRulesOK]

@koppor Most impressed by your tenacity, I am, to get it WRITE as you found with your first opening comment 11 years ago "Unfortunately it's too complicated. I don't see us implementing that." so not a "simple ask". But your attempts seem good enough to let loose in the wild. Often KJK may take a while to be able to review such a large change

@kjk can this PR be included now and tweaked if needs be ?

[koppor]

@koppor Most impressed by your tenacity, I am, to get it WRITE

😅💪

Regarding your math issue, I tried "blindly" to fix it: https://files.jabref.org/sumatra/SumatraPDF-9.exe