fix(search): position match highlights from item geometry (correct at zoom + across text-layer builders) (#299)

* fix(search): position highlights from the matched items, not a visual re-scan

Highlights were positioned by re-scanning the DOM for the match text
and pairing the Nth stream-order result with the Nth visual-order
occurrence; whenever content-stream order differs from reading order
(multi-column pages, tables, headers drawn last) the box lands on the
wrong occurrence, and matches spanning multiple text items were
missed entirely. Build the highlight from the result's own items via
span[data-item-index] and a character Range, which is exact in both
orders and across item boundaries. Also fix the continuous-mode
page selectors (data-page, not data-page-num), which returned null
and silently skipped highlight/scroll there.

* fix(search): scale highlight rects into the text layer's coordinate space

Search highlights are positioned inside .textLayer, which is laid out in
unscaled PDF points and zoomed via a CSS matrix transform. The highlight
rects were measured with getBoundingClientRect() (visual, post-transform
pixels) and applied as-is, so the layer's transform scaled them a second
time — at any zoom other than 100% every highlight drifted away from its
match, proportionally to its distance from the page origin.

Divide the measured offsets and sizes by the layer's effective scale
(bounding-rect width over layout width) before positioning. Works in both
single-page and continuous mode and is a no-op at scale 1.

Also remove findAllMatchPositions(), dead since the switch to
item-based positioning.

* fix(search): position highlights from item geometry, not DOM spans

Highlighting depended on span[data-item-index], which only the custom
single-page PDF.js text layer sets. The Rust-extracted vector-mode layer
and the stock PDF.js TextLayer (continuous mode) carry no such attribute,
so every match on those pages silently produced zero highlights. DOM
measurement also broke on zoom: rects captured at one zoom level went
stale the moment the layer was rebuilt or re-scaled.

Position highlights directly from the matched items' PDF-space geometry
(transform/width/height captured at text extraction), converted to
layer-local coordinates via --total-scale-factor, which every layer
builder sets. Layer-local rects ride the viewport zoom transform, so
zooming no longer displaces them.

Also sort results by visual position (top-to-bottom, left-to-right)
instead of content-stream order, so "1 of N" starts at the top of the
page, and remove the now-unused findDomSpanForItem().

* fix(search): start at the visually-first match on the current page

The initial current match is chosen during the progressive search, from
a page's raw results — which were in content-stream order, so "1 of N"
could land mid-page (e.g. starting at 3/14). Sort each page's results
visually at discovery time so the starting match is the topmost one on
the current page (or the next page with matches).

---------

Co-authored-by: Maarten Vroegindeweij <30430941+DutchSailor@users.noreply.github.com>

Author: art804

open-pdf-studio/js/search/find-bar.js

@@ -303,7 +303,7 @@ async function navigateToResult(result) {
 
     if (getActiveDocument()?.viewMode === 'continuous') {
       // Scroll to page in continuous mode
-      const pageWrapper = document.querySelector(`[data-page-num="${result.pageNum}"]`);
+      const pageWrapper = document.querySelector(`.page-wrapper[data-page="${result.pageNum}"]`);
       if (pageWrapper) {
         pageWrapper.scrollIntoView({ behavior: 'smooth', block: 'center' });
       }
@@ -395,147 +395,71 @@ export function highlightResults() {
 }
 
 /**
- * Find all occurrences of search text in the text layer and return their positions
- */
-function findAllMatchPositions(textLayer, searchText, matchCase, wholeWord) {
-  const positions = [];
-  const textSpans = textLayer.querySelectorAll('span');
-  const compareSearchText = matchCase ? searchText : searchText.toLowerCase();
-
-  for (const span of textSpans) {
-    const spanText = span.textContent;
-    if (!spanText) continue;
-
-    const compareSpanText = matchCase ? spanText : spanText.toLowerCase();
-    let startIndex = 0;
-
-    while (true) {
-      const matchIndex = compareSpanText.indexOf(compareSearchText, startIndex);
-      if (matchIndex === -1) break;
-
-      // Whole word check: verify word boundaries in the span text
-      if (wholeWord) {
-        const before = matchIndex > 0 ? compareSpanText[matchIndex - 1] : ' ';
-        const after = matchIndex + compareSearchText.length < compareSpanText.length
-          ? compareSpanText[matchIndex + compareSearchText.length] : ' ';
-        const isWordChar = (c) => /\w/.test(c);
-        if (isWordChar(before) || isWordChar(after)) {
-          startIndex = matchIndex + 1;
-          continue;
-        }
-      }
-
-      const textNode = span.firstChild;
-      if (textNode && textNode.nodeType === Node.TEXT_NODE) {
-        try {
-          // Get span's position within the text layer (from its style)
-          const spanLeft = parseFloat(span.style.left) || 0;
-          const spanTop = parseFloat(span.style.top) || 0;
-
-          // Get the scaleX factor from transform if present
-          let scaleX = 1;
-          const transform = span.style.transform;
-          if (transform) {
-            const scaleMatch = transform.match(/scaleX\(([^)]+)\)/);
-            if (scaleMatch) {
-              scaleX = parseFloat(scaleMatch[1]) || 1;
-            }
-          }
-
-          // Measure the width of text before the match (in original coordinates)
-          let preWidth = 0;
-          if (matchIndex > 0) {
-            const preRange = document.createRange();
-            preRange.setStart(textNode, 0);
-            preRange.setEnd(textNode, matchIndex);
-            preWidth = preRange.getBoundingClientRect().width;
-          }
-
-          // Measure the width of the match itself
-          const matchRange = document.createRange();
-          matchRange.setStart(textNode, matchIndex);
-          matchRange.setEnd(textNode, matchIndex + searchText.length);
-          const matchRect = matchRange.getBoundingClientRect();
-
-          // Get span's visual bounding rect
-          const spanRect = span.getBoundingClientRect();
-          const textLayerRect = span.parentElement.getBoundingClientRect();
-
-          // Calculate position relative to text layer using visual coordinates
-          const highlightLeft = matchRect.left - textLayerRect.left;
-          const highlightTop = matchRect.top - textLayerRect.top;
-
-          // Store position data
-          positions.push({
-            span,
-            highlightLeft,
-            highlightTop,
-            matchWidth: matchRect.width,
-            matchHeight: matchRect.height,
-            matchIndex,
-            spanText,
-            // Also store viewport rect for sorting
-            viewportTop: matchRect.top,
-            viewportLeft: matchRect.left
-          });
-        } catch (e) {
-          console.warn('Range error:', e);
-        }
-      }
-
-      startIndex = matchIndex + 1;
-    }
-  }
-
-  // Sort by position (top to bottom, left to right)
-  positions.sort((a, b) => {
-    if (Math.abs(a.viewportTop - b.viewportTop) > 5) {
-      return a.viewportTop - b.viewportTop;
-    }
-    return a.viewportLeft - b.viewportLeft;
-  });
-
-  return positions;
-}
-
-/**
- * Highlight search results on a page
+ * Highlight search results on a page.
+ *
+ * Highlights are positioned from the matched items' own PDF-space geometry
+ * (transform/width/height captured at text extraction), NOT from measuring
+ * DOM spans. The three text-layer builders (custom single-page PDF.js,
+ * stock PDF.js TextLayer in continuous mode, Rust-extracted spans in vector
+ * mode) produce different span structures — only one of them carries
+ * data-item-index — so any DOM-based lookup breaks on the other two.
+ * Item geometry is layer-type independent, and because the rects live in
+ * layer-local coordinates they ride along with the viewport's zoom
+ * transform instead of needing re-measurement.
  */
 function highlightMatch(result, isCurrent) {
-  if (!result || !result.matchText) return;
+  if (!result || !result.items || result.items.length === 0) return;
 
   const pageNum = result.pageNum;
+  const doc = getActiveDocument();
 
   // Get the text layer for this page
   let textLayer;
-  if (getActiveDocument()?.viewMode === 'continuous') {
-    textLayer = document.querySelector(`[data-page-num="${pageNum}"] .textLayer`);
+  if (doc?.viewMode === 'continuous') {
+    const wrapper = document.querySelector(`.page-wrapper[data-page="${pageNum}"]`);
+    textLayer = wrapper?.querySelector('.textLayer');
   } else {
+    if (doc && doc.currentPage !== pageNum) return;
     textLayer = document.querySelector('.textLayer');
   }
-
   if (!textLayer) return;
 
-  // Find all match positions in the text layer
-  const positions = findAllMatchPositions(textLayer, result.matchText, state.search.matchCase, state.search.wholeWord);
-
-  // Count which occurrence this result is on this page
-  const pageResults = state.search.results.filter(r => r.pageNum === pageNum);
-  const occurrenceIndex = pageResults.findIndex(r => r.index === result.index);
-
-  if (occurrenceIndex >= 0 && occurrenceIndex < positions.length) {
-    const pos = positions[occurrenceIndex];
+  // Layer-local px per PDF point. Every layer builder sets
+  // --total-scale-factor on the layer or an ancestor: 1 in vector mode
+  // (layout px = PDF pt, zoom applied via CSS transform), viewport.scale
+  // for the PDF.js-built layers (laid out at scaled size).
+  const scale = parseFloat(
+    getComputedStyle(textLayer).getPropertyValue('--total-scale-factor')
+  ) || 1;
+  const pageHeightPt = textLayer.offsetHeight / scale;
+
+  for (const item of result.items) {
+    const t = item.transform;
+    if (!t) continue; // synthetic (Add Text) items carry no geometry
+
+    const startInItem = Math.max(0, result.startPos - item.startPos);
+    const endInItem = Math.min(item.str.length, result.endPos - item.startPos);
+    if (endInItem <= startInItem) continue;
+
+    // Partial matches inside an item: slice the run width proportionally
+    // by character count. Approximate for proportional fonts, but close
+    // enough for a highlight and independent of DOM/font availability.
+    const len = item.str.length || 1;
+    const itemH = item.height || Math.abs(t[3]) || 10;
+    const itemW = item.width || 0;
+    const x0 = t[4] + itemW * (startInItem / len);
+    const x1 = t[4] + itemW * (endInItem / len);
+    // t[5] is the baseline; ascent ≈ 0.8em above it (same convention the
+    // vector-mode span builder uses), Y flipped into top-left space.
+    const topPt = pageHeightPt - t[5] - itemH * 0.8;
 
     const highlight = document.createElement('div');
     highlight.className = 'search-highlight' + (isCurrent ? ' current' : '');
     highlight.dataset.resultIndex = result.index;
-
-    // Position using calculated visual coordinates
-    highlight.style.left = pos.highlightLeft + 'px';
-    highlight.style.top = pos.highlightTop + 'px';
-    highlight.style.width = pos.matchWidth + 'px';
-    highlight.style.height = pos.matchHeight + 'px';
-
+    highlight.style.left = (x0 * scale) + 'px';
+    highlight.style.top = (topPt * scale) + 'px';
+    highlight.style.width = (Math.max(x1 - x0, 2) * scale) + 'px';
+    highlight.style.height = (itemH * scale) + 'px';
     textLayer.appendChild(highlight);
   }
 }

open-pdf-studio/js/search/find-controller.js

@@ -128,20 +128,48 @@ function searchPage(pageData, pattern, query) {
     );
 
     if (matchItems.length > 0) {
+      // Visual anchor (PDF space, Y-up) of the first geometric item, used
+      // to order results top-to-bottom on the page rather than in
+      // content-stream order.
+      const anchor = matchItems.find(item => item.transform);
       results.push({
         pageNum,
         startPos,
         endPos,
         matchText: text.substring(startPos, endPos),
         items: matchItems,
+        anchorX: anchor ? anchor.transform[4] : null,
+        anchorY: anchor ? anchor.transform[5] : null,
         index: 0 // will be re-indexed later
       });
     }
   }
 
+  // Sort visually at discovery time, not just in the final pass: the
+  // progressive search picks the initial current match from a page's raw
+  // results, and stream order would make "1 of N" land mid-page.
+  results.sort(compareResultsVisually);
+
   return results;
 }
 
+/**
+ * Order results the way a reader scans the page: by page, then top to
+ * bottom (PDF Y is up, so larger anchorY first), then left to right.
+ * Content-stream order (startPos) is only the tiebreaker — streams often
+ * draw headers/footers/cards out of visual order.
+ */
+function compareResultsVisually(a, b) {
+  if (a.pageNum !== b.pageNum) return a.pageNum - b.pageNum;
+  if (a.anchorY != null && b.anchorY != null) {
+    if (Math.abs(a.anchorY - b.anchorY) > 2) return b.anchorY - a.anchorY;
+    if (a.anchorX != null && b.anchorX != null && a.anchorX !== b.anchorX) {
+      return a.anchorX - b.anchorX;
+    }
+  }
+  return a.startPos - b.startPos;
+}
+
 /**
  * Build the search regex from query and options
  */
@@ -167,13 +195,12 @@ export async function performSearch(query, options = {}) {
     const results = [];
 
     for (const pageData of pagesText) {
-      const pageResults = searchPage(pageData, pattern, query);
-      for (const r of pageResults) {
-        r.index = results.length;
-        results.push(r);
-      }
+      results.push(...searchPage(pageData, pattern, query));
     }
 
+    results.sort(compareResultsVisually);
+    results.forEach((r, i) => r.index = i);
+
     return results;
   } finally {
     state.search.isSearching = false;
@@ -251,7 +278,7 @@ export function executeProgressiveSearch(onProgress) {
       textCache.set(docId, pagesText);
     }
 
-    allResults.sort((a, b) => a.pageNum - b.pageNum || a.startPos - b.startPos);
+    allResults.sort(compareResultsVisually);
     allResults.forEach((r, i) => r.index = i);
 
     onProgress(allResults, totalPages, totalPages, true);
@@ -386,29 +413,6 @@ function replaceInTextEdit(doc, result, replaceText) {
   return { type: 'textEdit', id: edit.id, oldText, newText: edit.newText };
 }
 
-/**
- * Find the DOM span for a search result item by matching dataset.itemIndex.
- * This is the ONLY reliable way to map search results to DOM spans.
- */
-function findDomSpanForItem(item, pageNum, doc) {
-  if (item.itemIndex < 0) return null; // synthetic item (text edit)
-
-  let textLayer;
-  if (doc.viewMode === 'continuous') {
-    const wrapper = document.querySelector(`.page-wrapper[data-page="${pageNum}"]`);
-    textLayer = wrapper?.querySelector('.textLayer');
-  } else {
-    // In single-page mode, verify we're on the correct page
-    if (doc.currentPage !== pageNum) return null;
-    textLayer = document.querySelector('.textLayer');
-  }
-  if (!textLayer) return null;
-
-  // Direct lookup by data-item-index attribute
-  const span = textLayer.querySelector(`span[data-item-index="${item.itemIndex}"]`);
-  return span || null;
-}
-
 /**
  * Replace a match in base PDF content.
  *