Split plain-text citation hover into its own files

Pull the text-based citation code out of RefHover/RefHoverDetect into
two dedicated translation units, mirroring the existing pure-detect vs.
engine-driven layering:

- RefHoverTextDetect.{cpp,h}: pure pattern matchers
  (DetectCitationInPageText, FindSurnameInPageText, IsNamePrefix). No
  engine/HWND deps, unit-tested via RefHover_ut.
- RefHoverText.{cpp,h}: engine page-walk, per-document lookup cache, and
  the multi-word / fragmented-surname fallback (RefHoverTryPlainText).
  RefHoverDestroy now calls the new public RefHoverFreeLookupCache.

RefHoverDetect keeps only the link/destination detectors; RefHover keeps
the popup UI / render machinery. Canvas.cpp and RefHover.cpp include the
new RefHoverText.h. Build files (premake + vcxproj/filters for the app
and test_util) updated for the new files.

No behavior change; build and unit tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: koppor

premake5.files.lua

@@ -798,6 +798,8 @@ function sumatrapdf_files()
     "ProgressUpdateUI.*",
     "RefHover.*",
     "RefHoverDetect.*",
+    "RefHoverText.*",
+    "RefHoverTextDetect.*",
     "RegistryInstaller.*",
     "RegistryPreview.*",
     "RegistrySearchFilter.*",
@@ -1364,6 +1366,7 @@ function test_util_files()
     "DisplayMode.*",
     "Flags.*",
     "RefHoverDetect.*",
+    "RefHoverTextDetect.*",
     "SettingsStructs.*",
     --"StressTesting.*",
     "SumatraConfig.*",

src/Canvas.cpp

@@ -58,6 +58,7 @@
 #include "Translations.h"
 
 #include "RefHover.h"
+#include "RefHoverText.h"
 
 #include "utils/Log.h"
 
@@ -985,8 +986,8 @@ static void OnMouseMove(MainWindow* win, int x, int y, WPARAM) {
                             pageScreenRect.y = topLeft.y;
                         }
                         int delayMs = gGlobalPrefs->citationHoverDelay;
-                        RefHoverSchedule(win->refHover, win->hwndCanvas, delayMs, screenPt, destPage, destX, destY,
-                                         0.f, srcPageNo, RectF{}, pageScreenRect);
+                        RefHoverSchedule(win->refHover, win->hwndCanvas, delayMs, screenPt, destPage, destX, destY, 0.f,
+                                         srcPageNo, RectF{}, pageScreenRect);
                         scheduled = true;
                     }
                 }

src/RefHover.cpp

@@ -68,64 +68,10 @@
 #include "EngineBase.h"
 #include "RefHover.h"
 #include "RefHoverDetect.h"
+#include "RefHoverText.h"
 
 #define REF_HOVER_CLASS L"SumatraPDFRefHover"
 
-// === Plain-text citation lookup cache ===
-// Keyed by (surname, year, srcPage) so the same citation hovered repeatedly
-// is resolved instantly. Negative results (citation not found) are also
-// cached to avoid re-scanning the document on each hover.
-struct CitationCacheEntry {
-    char* surname; // owned UTF-8
-    int year;
-    int srcPage;  // page where the lookup was issued (so cap at srcPage works per-page)
-    int destPage; // -1 if not found
-    float destX;
-    float destY;
-};
-
-struct RefLookupCache {
-    Vec<CitationCacheEntry> entries;
-};
-
-static const CitationCacheEntry* CacheLookup(RefLookupCache* c, const char* surname, int year, int srcPage) {
-    if (!c) {
-        return nullptr;
-    }
-    for (size_t i = 0; i < c->entries.size(); i++) {
-        const CitationCacheEntry& e = c->entries[i];
-        if (e.year == year && e.srcPage == srcPage && str::Eq(e.surname, surname)) {
-            return &e;
-        }
-    }
-    return nullptr;
-}
-
-static void CacheInsert(RefLookupCache* c, const char* surname, int year, int srcPage, int destPage, float destX,
-                        float destY) {
-    if (!c) {
-        return;
-    }
-    CitationCacheEntry e;
-    e.surname = str::Dup(surname);
-    e.year = year;
-    e.srcPage = srcPage;
-    e.destPage = destPage;
-    e.destX = destX;
-    e.destY = destY;
-    c->entries.Append(e);
-}
-
-static void CacheFree(RefLookupCache* c) {
-    if (!c) {
-        return;
-    }
-    for (size_t i = 0; i < c->entries.size(); i++) {
-        str::Free(c->entries[i].surname);
-    }
-    delete c;
-}
-
 // upper bound for the auto-fit base zoom. We render at min(kRenderZoom,
 // fit-to-popup-max), then multiply by RefHoverState::Displayed::userZoom
 // (the mouse-wheel adjustment).
@@ -267,8 +213,7 @@ void RefHoverDestroy(RefHoverState* s) {
     }
     delete s->bmp;
     s->bmp = nullptr;
-    CacheFree(s->lookupCache);
-    s->lookupCache = nullptr;
+    RefHoverFreeLookupCache(s);
     delete s;
 }
 
@@ -1031,169 +976,3 @@ void RefHoverOnTimer(RefHoverState* s, HWND hwndCanvas, EngineBase* engine, floa
     req.destYRaw = s->pending.destY;
     RefHoverRequestRender(s, engine, req);
 }
-
-// === Plain-text citation lookup ===
-
-// Result of detecting a citation under the cursor.
-struct DetectedCitation {
-    char* surname; // owned UTF-8 (caller frees), or nullptr
-    int year;
-};
-
-static void FreeDetectedCitation(DetectedCitation* c) {
-    str::Free(c->surname);
-    c->surname = nullptr;
-}
-
-// Detect a citation pattern under the cursor on srcPage. On success, returns
-// true and fills *out with a freshly-allocated surname and year. The actual
-// pattern matching is the pure DetectCitationInPageText (RefHoverDetect.cpp).
-static bool DetectCitationAtCursor(EngineBase* engine, int srcPage, Point pagePos, DetectedCitation* out) {
-    out->surname = nullptr;
-    out->year = 0;
-    int textLen = 0;
-    Rect* coords = nullptr;
-    const WCHAR* text = engine->GetTextForPage(srcPage, &textLen, &coords);
-    return DetectCitationInPageText(text, coords, textLen, pagePos, &out->surname, &out->year);
-}
-
-// Walk pages from pageCount → srcPage looking for a bibliography entry that
-// matches the surname + year. Returns true on hit.
-static bool FindReferenceLocation(EngineBase* engine, int srcPage, const char* surname, int year, int* destPageOut,
-                                  float* destXOut, float* destYOut) {
-    if (!engine || !surname || !*surname) {
-        return false;
-    }
-    int pageCount = engine->PageCount();
-    if (pageCount <= 0 || srcPage < 1 || srcPage > pageCount) {
-        return false;
-    }
-
-    // Convert surname to wide string for engine text matching.
-    WCHAR* surnameW = ToWStr(surname);
-    if (!surnameW) {
-        return false;
-    }
-    int surnameLen = (int)str::Len(surnameW);
-    if (surnameLen < 2) {
-        free(surnameW);
-        return false;
-    }
-
-    bool found = false;
-    for (int p = pageCount; p >= srcPage; p--) {
-        int textLen = 0;
-        Rect* coords = nullptr;
-        const WCHAR* text = engine->GetTextForPage(p, &textLen, &coords);
-        float x = 0, y = 0;
-        if (FindSurnameInPageText(text, coords, textLen, surnameW, surnameLen, year, &x, &y)) {
-            *destPageOut = p;
-            *destXOut = x;
-            *destYOut = y;
-            found = true;
-            break;
-        }
-    }
-    free(surnameW);
-    return found;
-}
-
-// Look up `surname` in the cache; on miss, do a fresh document scan and
-// insert the result (positive or negative). Returns true on positive hit.
-static bool LookupOrSearch(RefHoverState* s, EngineBase* engine, int srcPage, const char* surname, int year,
-                           int& destPageOut, float& destXOut, float& destYOut) {
-    const CitationCacheEntry* hit = CacheLookup(s->lookupCache, surname, year, srcPage);
-    if (hit) {
-        if (hit->destPage > 0) {
-            destPageOut = hit->destPage;
-            destXOut = hit->destX;
-            destYOut = hit->destY;
-            return true;
-        }
-        return false;
-    }
-    int destPage = -1;
-    float destX = -1.f, destY = -1.f;
-    if (FindReferenceLocation(engine, srcPage, surname, year, &destPage, &destX, &destY)) {
-        CacheInsert(s->lookupCache, surname, year, srcPage, destPage, destX, destY);
-        destPageOut = destPage;
-        destXOut = destX;
-        destYOut = destY;
-        return true;
-    }
-    CacheInsert(s->lookupCache, surname, year, srcPage, -1, 0.f, 0.f);
-    return false;
-}
-
-bool RefHoverTryPlainText(RefHoverState* s, EngineBase* engine, int srcPage, Point pagePos, int& destPageOut,
-                          float& destXOut, float& destYOut) {
-    if (!s || !engine || srcPage <= 0) {
-        return false;
-    }
-    DetectedCitation cite{};
-    if (!DetectCitationAtCursor(engine, srcPage, pagePos, &cite)) {
-        return false;
-    }
-
-    if (!s->lookupCache) {
-        s->lookupCache = new RefLookupCache();
-    }
-
-    bool result = LookupOrSearch(s, engine, srcPage, cite.surname, cite.year, destPageOut, destXOut, destYOut);
-
-    // Fallback: if surname has multiple space-separated parts and the full
-    // form didn't match, try each part as a prefix in descending-length
-    // order. Two patterns this covers:
-    //   1. Bibliography lists the entry under just the last name
-    //      ("Vrielink, Oude R. A." vs. detected "Oude Vrielink").
-    //   2. PDF text extraction split a single-word surname by dropping a
-    //      glyph ("Bash b" for "Bashab") — the longest fragment ("Bash")
-    //      prefix-matches the real surname in the bibliography.
-    if (!result && cite.surname && str::FindChar(cite.surname, ' ')) {
-        struct Part {
-            const char* s;
-            int len;
-        };
-        Part parts[8];
-        int nParts = 0;
-        const char* p = cite.surname;
-        while (*p && nParts < 8) {
-            while (*p == ' ') {
-                p++;
-            }
-            if (!*p) {
-                break;
-            }
-            const char* start = p;
-            while (*p && *p != ' ') {
-                p++;
-            }
-            int len = (int)(p - start);
-            if (len >= 2) {
-                parts[nParts].s = start;
-                parts[nParts].len = len;
-                nParts++;
-            }
-        }
-        // Sort parts by length descending (simple selection sort, n<=8).
-        for (int i = 0; i < nParts - 1; i++) {
-            for (int j = i + 1; j < nParts; j++) {
-                if (parts[j].len > parts[i].len) {
-                    Part t = parts[i];
-                    parts[i] = parts[j];
-                    parts[j] = t;
-                }
-            }
-        }
-        for (int i = 0; i < nParts && !result; i++) {
-            char buf[64];
-            int n = parts[i].len < 63 ? parts[i].len : 63;
-            memcpy(buf, parts[i].s, n);
-            buf[n] = 0;
-            result = LookupOrSearch(s, engine, srcPage, buf, cite.year, destPageOut, destXOut, destYOut);
-        }
-    }
-
-    FreeDetectedCitation(&cite);
-    return result;
-}

src/RefHover.h

@@ -108,11 +108,3 @@ bool RefHoverWheelZoom(RefHoverState* s, EngineBase* engine, int wheelDelta);
 // (continuous scrolling). Popup window keeps its initial size; only the
 // rendered region's Y (and possibly page number) changes.
 bool RefHoverWheelScroll(RefHoverState* s, EngineBase* engine, int wheelDelta);
-
-// Plain-text citation hover: when no link element is under the cursor, try
-// to detect a "(Surname et al., 2020)" / "Surname (2020)" pattern at pagePos
-// on srcPage, find the bibliography entry that matches, and return its
-// location. Returns true on success and fills destPage/destX/destY.
-// Lookups are cached on s.
-bool RefHoverTryPlainText(RefHoverState* s, EngineBase* engine, int srcPage, Point pagePos, int& destPageOut,
-                          float& destXOut, float& destYOut);