dsh-book-reader 0.2.0 → 0.3.0

package/lib/client.js

@@ -3,16 +3,15 @@
  *
  * Decorates DSH's official PDF preview; it never replaces the renderer:
  *   - current-page readout, prev/next page, and a page-jump box;
- *   - a search panel (Cmd/Ctrl+Shift+F) backed by the Host text route;
- *   - "→ AI" insertion of a search hit into the chat composer;
+ *   - a find bar (Cmd/Ctrl+F) backed by the Host text route, with in-page
+ *     highlights and sequential previous/next navigation between occurrences;
  *   - debounced current-page reporting for AI context, with an on/off toggle.
  *
  * The contribution mounts into the preview's own header slot
  * `sidebar.right.tab.document.actions`, which the preview declares as a
  * Session-scoped list and passes `{ absolutePath }` to. Session-scoped slots
- * also receive the standard `sessionId` and `inputActions` props; insertion
- * uses `captureInsertion()` + `insertText(text, span)`, so the user's draft is
- * preserved and the edit is undoable. It never calls `setDraft`.
+ * also receive the standard `sessionId`, used only to tag the current-page
+ * reports; the plugin never writes to the chat composer.
  *
  * The bundle is the module-loader factory shape used by the profile:
  * `window.__ModuleLoader__.load({ id, factory })`, React is the only external.
@@ -41,6 +40,8 @@ window.__ModuleLoader__.load({
     const ZOOM_VAR = '--document-zoom'
     const PAGE_ATTR = 'data-pdf-page'
     const PDF_SECTION_ATTR = 'data-pdf-preview'
+    /** Text-layer container created by pdf.js TextLayerBuilder for one page. */
+    const TEXT_LAYER_ATTR = 'data-pdf-text'
 
     /** Timing. Reporting is the only debounced write; scrolling uses one rAF. */
     const REPORT_DELAY_MS = 400
@@ -52,6 +53,23 @@ window.__ModuleLoader__.load({
     const SEARCH_LIMIT = 100
     const INFO_CACHE_LIMIT = 16
 
+    /**
+     * Search highlighting.
+     *
+     * The panel owns two document-wide CSS Custom Highlights: one for every
+     * match on the pages the Host reported, and one for the occurrence the
+     * counter is on. Pages render lazily and re-render on zoom, so the text
+     * layer is retried for about three seconds and then observed for replacement.
+     */
+    const SEARCH_HIGHLIGHT_NAME = 'dsh-book-reader-search'
+    const SEARCH_ACTIVE_HIGHLIGHT_NAME = 'dsh-book-reader-search-active'
+    const SEARCH_HIT_CLASS = 'dsh-book-reader-search-hit'
+    const SEARCH_ACTIVE_HIT_CLASS = 'dsh-book-reader-search-active-hit'
+    const SEARCH_HIGHLIGHT_STYLE_ID = 'dsh-book-reader-search-highlight-style'
+    const SEARCH_HIGHLIGHT_RETRY_MS = 150
+    const SEARCH_HIGHLIGHT_RETRY_LIMIT = 20
+    const SEARCH_HIGHLIGHT_REBUILD_MS = 60
+
     /**
      * Reading-position memory timing.
      *
@@ -138,7 +156,7 @@ window.__ModuleLoader__.load({
       return page
     }
 
-    /** Collapse whitespace and bound a Host snippet for the composer. */
+    /** Collapse whitespace and bound a diagnostic detail for the quiet panel. */
     function normalizeSnippet(value, limit = 160) {
       const source = typeof value === 'string' ? value : ''
       const clean = source.replace(/\s+/gu, ' ').trim()
@@ -147,51 +165,6 @@ window.__ModuleLoader__.load({
       return `${clean.slice(0, max - 1).trimEnd()}…`
     }
 
-    /** @returns the `p.N` label for one search hit. */
-    function searchResultPage(hit) {
-      if (positiveInteger(hit?.printed)) return hit.printed
-      if (positiveInteger(hit?.pdf)) return hit.pdf
-      return undefined
-    }
-
-    /** @returns the short list label `p.132`, or `p.?` for a malformed hit. */
-    function searchResultLabel(hit) {
-      const page = searchResultPage(hit)
-      return page === undefined ? 'p.?' : `p.${page}`
-    }
-
-    /** @returns `PDF p.132: <snippet>` (or `[PDF p.132]` when there is no snippet). */
-    function buildSearchReference(hit) {
-      const page = searchResultPage(hit)
-      const label = page === undefined ? '?' : String(page)
-      const snippet = normalizeSnippet(hit?.snippet)
-      return snippet === '' ? `[PDF p.${label}]` : `PDF p.${label}: ${snippet}`
-    }
-
-    /**
-     * Insert into the composer through the Session standard props.
-     *
-     * `captureInsertion()` snapshots the selection and draft revision;
-     * `insertText()` applies one undoable plain-text edit only while that
-     * revision is current. Rejected insertions are reported as `false` so the
-     * caller can copy the reference instead; the draft is never replaced.
-     * @param inputActions - standard slot prop.
-     * @param text - plain text to insert.
-     * @returns whether the edit applied.
-     */
-    function insertComposerText(inputActions, text) {
-      if (inputActions === null || typeof inputActions !== 'object') return false
-      if (typeof inputActions.captureInsertion !== 'function') return false
-      if (typeof inputActions.insertText !== 'function') return false
-      try {
-        const span = inputActions.captureInsertion()
-        if (span === null || typeof span !== 'object') return false
-        return inputActions.insertText(String(text), span) === true
-      } catch (_error) {
-        return false
-      }
-    }
-
     /**
      * Pick the page occupying the reading anchor near the top of the viewport.
      *
@@ -249,6 +222,348 @@ window.__ModuleLoader__.load({
       return out
     }
 
+    /**
+     * Case-fold text one UTF-16 code unit at a time.
+     *
+     * Search offsets have to stay 1:1 with the text layer, so characters whose
+     * lowercase form changes length (such as `İ`) keep their original form. The
+     * query is folded with the same function, which mirrors the Host's
+     * case-insensitive literal search closely enough to number occurrences.
+     * @param value - text to fold.
+     * @returns the folded text, same length as the input.
+     */
+    function foldSearchText(value) {
+      const text = typeof value === 'string' ? value : String(value ?? '')
+      let folded = ''
+      for (let at = 0; at < text.length; at += 1) {
+        const char = text[at]
+        let lower = char
+        try {
+          lower = char.toLowerCase()
+        } catch (_error) {
+          lower = char
+        }
+        folded += typeof lower === 'string' && lower.length === 1 ? lower : char
+      }
+      return folded
+    }
+
+    /**
+     * Every non-empty text node under one element, in document order.
+     * @param root - text-layer container.
+     * @returns text nodes, or an empty array when the DOM cannot be walked.
+     */
+    function collectTextNodes(root) {
+      const nodes = []
+      if (root === null || root === undefined) return nodes
+      const documentRef = root.ownerDocument
+      if (documentRef === null || documentRef === undefined) return nodes
+      if (typeof documentRef.createTreeWalker !== 'function') return nodes
+      try {
+        // 4 is NodeFilter.SHOW_TEXT; pdf.js text layers contain no other nodes
+        // that matter, and this avoids depending on the global NodeFilter.
+        const walker = documentRef.createTreeWalker(root, 4)
+        let node = walker.nextNode()
+        while (node !== null) {
+          const text = node.nodeValue
+          if (typeof text === 'string' && text !== '') nodes.push(node)
+          node = walker.nextNode()
+        }
+      } catch (_error) {
+        return []
+      }
+      return nodes
+    }
+
+    /**
+     * Locate literal case-insensitive occurrences across a run of text nodes.
+     *
+     * The text layer is split into arbitrarily many spans, so concatenate the
+     * node values and keep each node's start offset. A match may therefore span
+     * multiple nodes; `Range` creation maps both ends back to the right node.
+     * @param nodes - text nodes in document order.
+     * @param needle - literal query (already trimmed).
+     * @returns `{ nodes, starts, matches }`, or `undefined` when there is no text.
+     */
+    function matchTextNodes(nodes, needle) {
+      const foldedNeedle = foldSearchText(needle)
+      if (nodes.length === 0 || foldedNeedle === '') return undefined
+      const starts = []
+      let text = ''
+      for (const node of nodes) {
+        starts.push(text.length)
+        text += typeof node.nodeValue === 'string' ? node.nodeValue : ''
+      }
+      const folded = foldSearchText(text)
+      const matches = []
+      let from = 0
+      for (;;) {
+        const at = folded.indexOf(foldedNeedle, from)
+        if (at < 0) break
+        matches.push({ start: at, end: at + foldedNeedle.length })
+        from = at + Math.max(1, foldedNeedle.length)
+      }
+      if (matches.length === 0) return undefined
+      return { nodes, starts, matches }
+    }
+
+    /**
+     * @returns the text node and offset containing one global text offset.
+     */
+    function locateTextOffset(nodes, starts, offset) {
+      let low = 0
+      let high = starts.length - 1
+      let found = 0
+      while (low <= high) {
+        const mid = (low + high) >> 1
+        if (starts[mid] <= offset) {
+          found = mid
+          low = mid + 1
+        } else {
+          high = mid - 1
+        }
+      }
+      const node = nodes[found]
+      const length = typeof node.nodeValue === 'string' ? node.nodeValue.length : 0
+      return { node, offset: Math.max(0, Math.min(offset - starts[found], length)) }
+    }
+
+    /** Build a DOM Range for one match, or `undefined` when it cannot be made. */
+    function createTextRange(documentRef, nodes, starts, match) {
+      if (documentRef === null || documentRef === undefined || typeof documentRef.createRange !== 'function') {
+        return undefined
+      }
+      try {
+        const first = locateTextOffset(nodes, starts, match.start)
+        const last = locateTextOffset(nodes, starts, match.end)
+        const range = documentRef.createRange()
+        range.setStart(first.node, first.offset)
+        range.setEnd(last.node, last.offset)
+        return range
+      } catch (_error) {
+        return undefined
+      }
+    }
+
+    /**
+     * Add the highlight stylesheet once per document.
+     *
+     * Both APIs are styled from the same palette: translucent yellow for every
+     * match, a stronger orange for the current one. `rgba` keeps them readable
+     * over light and dark themes and avoids depending on theme variables a
+     * browser might not resolve inside `::highlight`.
+     */
+    function ensureSearchHighlightStyle(documentRef) {
+      if (documentRef === null || documentRef === undefined) return
+      if (typeof documentRef.createElement !== 'function') return
+      try {
+        if (typeof documentRef.getElementById === 'function'
+          && documentRef.getElementById(SEARCH_HIGHLIGHT_STYLE_ID) !== null) {
+          return
+        }
+        const style = documentRef.createElement('style')
+        style.id = SEARCH_HIGHLIGHT_STYLE_ID
+        style.textContent = [
+          `::highlight(${SEARCH_HIGHLIGHT_NAME}) { background-color: rgba(255, 213, 0, 0.42); color: inherit; }`,
+          `::highlight(${SEARCH_ACTIVE_HIGHLIGHT_NAME}) { background-color: rgba(255, 138, 0, 0.68); color: inherit; }`,
+          `.${SEARCH_HIT_CLASS} { background-color: rgba(255, 213, 0, 0.42); color: inherit; }`,
+          `.${SEARCH_ACTIVE_HIT_CLASS} { background-color: rgba(255, 138, 0, 0.68); color: inherit; }`,
+        ].join('\n')
+        const parent = documentRef.head ?? documentRef.documentElement
+        if (parent !== null && parent !== undefined && typeof parent.appendChild === 'function') {
+          parent.appendChild(style)
+        }
+      } catch (_error) {
+        // Highlight color is decorative: a missing <style> must never break search.
+      }
+    }
+
+    /**
+     * Detect the CSS Custom Highlight API.
+     * @returns `{ registry, Highlight }`, or `undefined` when unavailable.
+     */
+    function searchHighlightSupport() {
+      const candidates = []
+      try {
+        if (typeof window !== 'undefined' && window !== null) candidates.push(window)
+      } catch (_error) {
+        // No window in some headless environments; globalThis is enough.
+      }
+      candidates.push(globalThis)
+      for (const candidate of candidates) {
+        try {
+          const registry = candidate?.CSS?.highlights
+          const HighlightClass = candidate?.Highlight
+          if (registry !== null && registry !== undefined
+            && typeof registry.set === 'function'
+            && typeof registry.delete === 'function'
+            && typeof HighlightClass === 'function') {
+            return { registry, Highlight: HighlightClass }
+          }
+        } catch (_error) {
+          // Try the next global.
+        }
+      }
+      return undefined
+    }
+
+    /**
+     * Remove both highlight layers and any fallback span classes.
+     * @param pane - preview body, when still known.
+     */
+    function clearSearchHighlights(pane) {
+      try {
+        const support = searchHighlightSupport()
+        if (support !== undefined) {
+          support.registry.delete(SEARCH_HIGHLIGHT_NAME)
+          support.registry.delete(SEARCH_ACTIVE_HIGHLIGHT_NAME)
+        }
+      } catch (_error) {
+        // Clearing is best effort.
+      }
+      try {
+        const documentRef = pane?.ownerDocument
+          ?? (typeof document === 'undefined' ? undefined : document)
+        if (documentRef === undefined) return
+        const roots = pane !== null && pane !== undefined ? [pane] : [documentRef]
+        for (const root of roots) {
+          if (typeof root.querySelectorAll !== 'function') continue
+          for (const element of root.querySelectorAll(`.${SEARCH_HIT_CLASS}, .${SEARCH_ACTIVE_HIT_CLASS}`)) {
+            if (typeof element.classList?.remove === 'function') {
+              element.classList.remove(SEARCH_HIT_CLASS, SEARCH_ACTIVE_HIT_CLASS)
+            }
+          }
+        }
+      } catch (_error) {
+        // Clearing is best effort.
+      }
+    }
+
+    /**
+     * Highlight the query on every hit page, with the current occurrence stronger.
+     *
+     * The active occurrence is chosen by its per-page ordinal: count the hits
+     * before `active` that share the page. That ordinal indexes the client-side
+     * match list for that page. When the client has fewer matches than the Host
+     * claimed (extraction and the text layer can disagree), every match is still
+     * highlighted and the first one becomes active.
+     * @param pane - preview body.
+     * @param needle - literal query.
+     * @param hits - ordered Host hits (`{ pdf }` is the only field used here).
+     * @param active - index into `hits`.
+     */
+    function applySearchHighlights(pane, needle, hits, active) {
+      if (pane === null || pane === undefined || !Array.isArray(hits) || hits.length === 0) {
+        clearSearchHighlights(pane)
+        return
+      }
+      const queryText = String(needle ?? '').trim()
+      if (queryText === '') {
+        clearSearchHighlights(pane)
+        return
+      }
+      const documentRef = pane.ownerDocument
+      ensureSearchHighlightStyle(documentRef)
+      clearSearchHighlights(pane)
+
+      const elements = new Map()
+      for (const entry of pageElements(pane)) elements.set(entry.number, entry.element)
+      const pageNumbers = []
+      const seenPages = new Set()
+      for (const hit of hits) {
+        const page = hit?.pdf
+        if (!positiveInteger(page) || seenPages.has(page)) continue
+        seenPages.add(page)
+        pageNumbers.push(page)
+      }
+
+      const safeActive = Number.isInteger(active) && active >= 0 && active < hits.length ? active : 0
+      const activePage = positiveInteger(hits[safeActive]?.pdf) ? hits[safeActive].pdf : undefined
+      let activeOrdinal = 0
+      if (activePage !== undefined) {
+        for (let at = 0; at < safeActive; at += 1) {
+          if (hits[at]?.pdf === activePage) activeOrdinal += 1
+        }
+      }
+
+      const pageMatches = []
+      for (const page of pageNumbers) {
+        const element = elements.get(page)
+        if (element === undefined) continue
+        const nodes = []
+        for (const container of element.querySelectorAll(`[${TEXT_LAYER_ATTR}]`)) {
+          for (const node of collectTextNodes(container)) nodes.push(node)
+        }
+        const matched = matchTextNodes(nodes, queryText)
+        if (matched !== undefined) pageMatches.push({ page, ...matched })
+      }
+
+      const support = searchHighlightSupport()
+      if (support !== undefined) {
+        try {
+          const allRanges = []
+          let activeRange
+          for (const page of pageMatches) {
+            const ranges = []
+            for (const match of page.matches) {
+              const range = createTextRange(documentRef, page.nodes, page.starts, match)
+              if (range !== undefined) {
+                ranges.push(range)
+                allRanges.push(range)
+              }
+            }
+            if (page.page === activePage && ranges.length > 0) {
+              activeRange = activeOrdinal < ranges.length ? ranges[activeOrdinal] : ranges[0]
+            }
+          }
+          if (allRanges.length > 0) {
+            support.registry.set(SEARCH_HIGHLIGHT_NAME, new support.Highlight(...allRanges))
+          } else {
+            support.registry.delete(SEARCH_HIGHLIGHT_NAME)
+          }
+          if (activeRange !== undefined) {
+            support.registry.set(SEARCH_ACTIVE_HIGHLIGHT_NAME, new support.Highlight(activeRange))
+          } else {
+            support.registry.delete(SEARCH_ACTIVE_HIGHLIGHT_NAME)
+          }
+          return
+        } catch (_error) {
+          try {
+            support.registry.delete(SEARCH_HIGHLIGHT_NAME)
+            support.registry.delete(SEARCH_ACTIVE_HIGHLIGHT_NAME)
+          } catch (_ignored) {
+            // The span fallback below is still available.
+          }
+        }
+      }
+
+      // Fallback for older Chromium: tint the parent spans overlapping a match.
+      for (const page of pageMatches) {
+        const activeIndex = page.page === activePage
+          ? (activeOrdinal < page.matches.length ? activeOrdinal : 0)
+          : -1
+        for (let index = 0; index < page.matches.length; index += 1) {
+          const match = page.matches[index]
+          for (let at = 0; at < page.nodes.length; at += 1) {
+            const node = page.nodes[at]
+            const start = page.starts[at]
+            const length = typeof node.nodeValue === 'string' ? node.nodeValue.length : 0
+            if (start + length <= match.start || start >= match.end) continue
+            const parent = node.parentElement
+            if (parent === null || parent === undefined) continue
+            if (typeof parent.classList?.add !== 'function') continue
+            try {
+              parent.classList.add(SEARCH_HIT_CLASS)
+              if (index === activeIndex) parent.classList.add(SEARCH_ACTIVE_HIT_CLASS)
+            } catch (_error) {
+              // The fallback is best effort.
+            }
+          }
+        }
+      }
+    }
+
+
     /**
      * Find the preview body that owns one header contribution.
      *
@@ -640,7 +955,7 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * Which mounted contribution answers the next Cmd/Ctrl+Shift+F.
+     * Which mounted contribution answers the next Cmd/Ctrl+F.
      * Pointing at a preview claims it, exactly like dsh-pdf-search's Ctrl+F.
      */
     let activeOwner
@@ -741,51 +1056,17 @@ window.__ModuleLoader__.load({
       userSelect: 'text',
     }
 
-    const LIST_STYLE = {
-      listStyle: 'none',
-      margin: '0',
-      padding: '0',
-      maxHeight: '46vh',
-      overflowY: 'auto',
-      overscrollBehavior: 'contain',
-    }
-
-    const RESULT_ROW_STYLE = {
-      display: 'flex',
-      alignItems: 'center',
-      gap: '4px',
-      borderTop: '1px solid rgba(128,128,128,.18)',
-      padding: '2px 0',
-    }
-
-    const RESULT_JUMP_STYLE = {
-      flex: '1 1 auto',
-      minWidth: '0',
-      padding: '3px 2px',
-      border: 'none',
-      background: 'transparent',
-      color: 'inherit',
-      font: 'inherit',
-      textAlign: 'left',
-      cursor: 'pointer',
-      overflow: 'hidden',
-      whiteSpace: 'nowrap',
-      textOverflow: 'ellipsis',
-      borderRadius: '4px',
-    }
-
-    const AI_BUTTON_STYLE = {
+    const SEARCH_COUNT_STYLE = {
+      minWidth: '42px',
       flex: '0 0 auto',
-      padding: '2px 5px',
-      border: '1px solid rgba(128,128,128,.45)',
-      borderRadius: '5px',
-      background: 'transparent',
-      color: 'inherit',
-      font: 'inherit',
-      cursor: 'pointer',
-      opacity: 0.9,
+      textAlign: 'center',
+      fontVariantNumeric: 'tabular-nums',
+      opacity: 0.8,
+      fontSize: '11px',
     }
 
+    const SEARCH_HINT_STYLE = { ...MUTED_STYLE, fontSize: '10px' }
+
     /**
      * The Client locale service, attached by `apply`. Absent in headless tests,
      * where the language then falls back to the browser's own preference.
@@ -832,8 +1113,8 @@ window.__ModuleLoader__.load({
         en: ['Page number', 'Type a page and press Enter; printed page by default, prefix p for a PDF page'],
       },
       search: {
-        zh: ['搜索', '搜索这个 PDF 的文字层（Cmd/Ctrl+Shift+F）'],
-        en: ['Search', "Search this PDF's text layer (Cmd/Ctrl+Shift+F)"],
+        zh: ['搜索', '搜索这个 PDF 的文字层（Cmd/Ctrl+F）'],
+        en: ['Search', "Search this PDF's text layer (Cmd/Ctrl+F)"],
       },
       follow: {
         zh: ['AI 上下文', '把当前阅读页报告给模型'],
@@ -843,14 +1124,32 @@ window.__ModuleLoader__.load({
         zh: ['关闭搜索', '收起搜索面板（Esc）'],
         en: ['Close search', 'Close the search panel (Esc)'],
       },
-      resultJump: {
-        zh: ['跳到这一页', '滚动到搜索结果所在的页'],
-        en: ['Jump to page', 'Scroll to the page of this search result'],
+      prevHit: {
+        zh: ['上一个匹配', '跳到上一个命中（Shift+Enter）'],
+        en: ['Previous match', 'Jump to the previous occurrence (Shift+Enter)'],
+      },
+      nextHit: {
+        zh: ['下一个匹配', '跳到下一个命中（Enter）'],
+        en: ['Next match', 'Jump to the next occurrence (Enter)'],
       },
-      resultInsert: {
-        zh: ['引用这条结果', '把这条结果的位置插入输入框'],
-        en: ['Insert reference', "Insert this result's position into the chat"],
+    }
+
+    /** Find-bar copy, in both UI languages. */
+    const SEARCH_COPY = {
+      label: { zh: '搜索这个 PDF', en: 'Search this PDF' },
+      hint: {
+        zh: 'Enter 下一个 · Shift+Enter 上一个 · Esc 关闭',
+        en: 'Enter next · Shift+Enter previous · Esc close',
       },
+      prev: { zh: '上一个匹配', en: 'Previous match' },
+      next: { zh: '下一个匹配', en: 'Next match' },
+    }
+
+    /** @returns one find-bar string in the active UI language. */
+    function searchCopy(key) {
+      const entry = SEARCH_COPY[key]
+      if (entry === undefined) return ''
+      return entry[activeLanguage()] ?? entry.en
     }
 
     /** @returns the localized explanation body for the follow control. */
@@ -923,21 +1222,6 @@ window.__ModuleLoader__.load({
     h('circle', { cx: 7, cy: 7, r: 4.4, stroke: 'currentColor', strokeWidth: 1.6 }),
     h('path', { d: 'M10.4 10.4 14.2 14.2', stroke: 'currentColor', strokeWidth: 1.6, strokeLinecap: 'round' }))
 
-    /**
-     * Copy plain text, used only when the composer insertion is unavailable.
-     * @returns whether the clipboard write succeeded.
-     */
-    async function copyText(text) {
-      try {
-        if (typeof navigator === 'undefined' || navigator.clipboard === undefined) return false
-        if (typeof navigator.clipboard.writeText !== 'function') return false
-        await navigator.clipboard.writeText(text)
-        return true
-      } catch (_error) {
-        return false
-      }
-    }
-
     /**
      * The header contribution for one PDF preview.
      * @param props - Session-scope standard props plus the preview's `absolutePath`.
@@ -945,7 +1229,6 @@ window.__ModuleLoader__.load({
     function PdfReaderAction(props) {
       const absolutePath = typeof props?.absolutePath === 'string' ? props.absolutePath : undefined
       const isPdf = isPdfPath(absolutePath)
-      const inputActions = props?.inputActions
       const sessionId = typeof props?.sessionId === 'string' ? props.sessionId : undefined
 
       const hostRef = useRef(null)
@@ -953,7 +1236,6 @@ window.__ModuleLoader__.load({
       const searchInputRef = useRef(null)
       const ownerRef = useRef(null)
       if (ownerRef.current === null) ownerRef.current = Symbol('dsh-pdf-reader')
-      const focusTimerRef = useRef(null)
       const flashTimerRef = useRef(null)
       const reportAbortRef = useRef(null)
       const reportSeqRef = useRef(0)
@@ -983,6 +1265,7 @@ window.__ModuleLoader__.load({
       const [open, setOpen] = useState(false)
       const [query, setQuery] = useState('')
       const [hits, setHits] = useState(null)
+      const [active, setActive] = useState(0)
       const [searching, setSearching] = useState(false)
       const [searchError, setSearchError] = useState(null)
       const [tip, setTip] = useState(null)
@@ -1052,41 +1335,51 @@ window.__ModuleLoader__.load({
 
       /** Focus the search input; keep the query highlighted for quick replacement. */
       const openSearch = () => {
+        const input = searchInputRef.current
+        if (input === null) {
+          // The panel is not mounted yet, so this is a fresh open: start clean
+          // and let the search effect re-query the kept query.
+          setHits(null)
+          setActive(0)
+          setSearching(false)
+          setSearchError(null)
+        }
         setOpen(true)
-        if (focusTimerRef.current !== null) globalThis.clearTimeout(focusTimerRef.current)
-        focusTimerRef.current = globalThis.setTimeout(() => {
-          focusTimerRef.current = null
-          searchInputRef.current?.focus()
-          searchInputRef.current?.select()
-        }, 0)
+        if (input !== null) {
+          input.focus()
+          input.select()
+        }
       }
 
       /** Close the panel and give focus back to the header button. */
       const closeSearch = () => {
         setOpen(false)
-        if (focusTimerRef.current !== null) {
-          globalThis.clearTimeout(focusTimerRef.current)
-          focusTimerRef.current = null
-        }
         searchButtonRef.current?.focus()
       }
 
       /**
-       * Deliver a composer reference.
-       * Primary path is the undoable insertion at the caret; when the composer
-       * is busy or absent, copy instead of clobbering the draft.
+       * Highlighted navigation helpers.
+       *
+       * Search is deliberately the most basic kind: one query, a list of Host
+       * hits, and previous/next stepping that wraps at both ends. The counter
+       * updates immediately; the in-page highlight effect waits for the page's
+       * lazily rendered text layer.
        */
-      const deliverReference = (text, label) => {
-        if (insertComposerText(inputActions, text)) {
-          flashMessage(label, 'ok')
-          return
-        }
-        void copyText(text).then((copied) => {
-          if (hostRef.current === null) return
-          flashMessage(copied ? `${label} (copied)` : 'Composer busy', copied ? 'ok' : 'warn')
-        })
+      const navigateHits = (list, index) => {
+        if (!Array.isArray(list) || list.length === 0) return false
+        const count = list.length
+        const requested = Number.isFinite(index) ? Math.trunc(index) : 0
+        const next = ((requested % count) + count) % count
+        const hit = list[next]
+        if (hit === undefined) return false
+        jumpTo(hit.pdf)
+        setActive(next)
+        return true
       }
 
+      /** Move to an absolute hit index (the caller adds or subtracts one). */
+      const navigate = (index) => navigateHits(hits, index)
+
       /** Scroll a physical page into view and update the readout immediately. */
       const jumpTo = (target) => {
         if (!positiveInteger(target)) return false
@@ -1145,15 +1438,12 @@ window.__ModuleLoader__.load({
         setOpen(false)
         setQuery('')
         setHits(null)
+        setActive(0)
         setSearching(false)
         setSearchError(null)
         lastReportedKeyRef.current = undefined
         pageRef.current = 1
         reportAbortRef.current?.abort()
-        if (focusTimerRef.current !== null) {
-          globalThis.clearTimeout(focusTimerRef.current)
-          focusTimerRef.current = null
-        }
         if (flashTimerRef.current !== null) {
           globalThis.clearTimeout(flashTimerRef.current)
           flashTimerRef.current = null
@@ -1608,29 +1898,40 @@ window.__ModuleLoader__.load({
         /**
          * Scroll the saved page into view, then re-apply once. The second scroll
          * absorbs pages that were 3:4 placeholders and grew when lazily rendered.
+         *
+         * With `finishGate: false` the page jump happens immediately but the save
+         * gate stays closed — the caller restores zoom afterwards and then
+         * calls `finish()`. That keeps the viewer from showing page 1 while a
+         * fixed zoom is being replayed gesture by gesture.
+         * @param options - `{ finishGate }`, default true.
+         * @returns whether the scroll was applied.
          */
-        const placePage = () => {
-          if (disposed || restoreTarget === undefined) return
+        const placePage = ({ finishGate = true } = {}) => {
+          if (disposed || restoreTarget === undefined) return false
           const target = restoreTarget.pdfPage
           if (!refresh() || !scrollPageIntoView(pane, scrollport, target)) {
             retryRestore()
-            return
+            return false
           }
           // The save debounce reads this ref, and the restore runs from a timer
           // (not a React event), so publish the page before state can render.
           pageRef.current = target
           setPage(target)
           setSampled(true)
-          finish()
+          if (finishGate) finish()
           if (reapplyTimer !== undefined) globalThis.clearTimeout(reapplyTimer)
           reapplyTimer = globalThis.setTimeout(() => {
             reapplyTimer = undefined
             if (disposed || !refresh()) return
             scrollPageIntoView(pane, scrollport, target)
           }, VIEW_REAPPLY_MS)
+          return true
         }
 
-        /** Let the renderer's 120 ms zoom settlement commit before scrolling. */
+        /**
+         * Let the renderer's 120 ms zoom settlement commit, then scroll again so
+         * the saved page is aligned after the zoom reflowed every page.
+         */
         const settleZoom = () => {
           if (zoomTimer !== undefined) globalThis.clearTimeout(zoomTimer)
           zoomTimer = globalThis.setTimeout(() => {
@@ -1649,7 +1950,7 @@ window.__ModuleLoader__.load({
           if (disposed || restoreTarget === undefined) return
           const target = restoreTarget.zoomScale
           if (!refresh() || frame === undefined || scrollport === undefined) {
-            placePage()
+            finish()
             return
           }
           const current = frameZoomScale(frame)
@@ -1658,7 +1959,7 @@ window.__ModuleLoader__.load({
               // Same scale, fit-width mode: a zero-delta gesture only asks the
               // renderer to commit `{kind:'fixed'}` at the current scale.
               if (!dispatchZoomWheel(scrollport, 0)) {
-                placePage()
+                finish()
                 return
               }
             }
@@ -1699,6 +2000,8 @@ window.__ModuleLoader__.load({
             retryRestore()
             return
           }
+          // Jump first so the cover never flashes while a fixed zoom is replayed.
+          if (!placePage({ finishGate: false })) return
           if (target.zoomMode === 'fixed' && frame !== undefined && scrollport !== undefined) {
             if (Math.abs(frameZoomScale(frame) / target.zoomScale - 1) > VIEW_ZOOM_TOLERANCE
               || frameZoomMode(frame) !== 'fixed') {
@@ -1706,7 +2009,7 @@ window.__ModuleLoader__.load({
               return
             }
           }
-          placePage()
+          finish()
         }
 
         const loadSavedView = async () => {
@@ -1841,17 +2144,21 @@ window.__ModuleLoader__.load({
       }, [isPdf, absolutePath, sampled, page, printed, sessionId, follow])
 
       // Search: type, wait 220 ms, query the Host route, cancel the stale query.
+      // A new query starts from a clean slate: no stale highlights or counter.
       useEffect(() => {
         if (!open || !isPdf || absolutePath === undefined) return undefined
         const needle = query.trim()
         if (needle === '') {
           setHits(null)
+          setActive(0)
           setSearchError(null)
           setSearching(false)
           return undefined
         }
         setSearching(true)
         setSearchError(null)
+        setHits(null)
+        setActive(0)
         let disposed = false
         let timedOut = false
         let timer
@@ -1869,6 +2176,7 @@ window.__ModuleLoader__.load({
               if (disposed) return
               if (body === null || typeof body !== 'object' || body.ok !== true) {
                 setHits([])
+                setActive(0)
                 setSearchError(describeSearchFailure(body, status))
                 return
               }
@@ -1877,10 +2185,18 @@ window.__ModuleLoader__.load({
                 : []
               setHits(list)
               setSearchError(null)
+              if (list.length > 0) {
+                // Basic find behavior: the first occurrence becomes current and
+                // the preview immediately jumps to its page.
+                navigateHits(list, 0)
+              } else {
+                setActive(0)
+              }
             })
             .catch((error) => {
               if (disposed || (isAbortError(error) && !timedOut)) return
               setHits([])
+              setActive(0)
               setSearchError(timedOut ? 'Search timed out.' : 'Search unavailable.')
             })
             .finally(() => {
@@ -1897,14 +2213,106 @@ window.__ModuleLoader__.load({
         }
       }, [open, isPdf, absolutePath, query])
 
-      // Cmd/Ctrl+Shift+F opens search. Plain Cmd/Ctrl+F is deliberately left
-      // alone: dsh-pdf-search owns it and the browser find bar remains intact.
+      // In-page highlights: locate each hit page's text layer, map the query to
+      // Ranges, and rebuild when pdf.js renders or re-renders a page (zoom).
+      //
+      // The text layer arrives lazily, so the first attempt retries for about
+      // three seconds. Once the active page has a text layer, the timers stop
+      // and the MutationObserver keeps the highlights in sync. Every path is
+      // guarded: highlighting must never break reading or search itself.
+      useEffect(() => {
+        if (!open || !isPdf || absolutePath === undefined) return undefined
+        const needle = query.trim()
+        if (searching || searchError !== null || hits === null || hits.length === 0 || needle === '') {
+          clearSearchHighlights(resolvePane(hostRef.current))
+          return undefined
+        }
+        const host = hostRef.current
+        if (host === null) return undefined
+        const list = hits
+        const current = Number.isInteger(active) ? active : 0
+        const activePage = list[Math.min(Math.max(current, 0), list.length - 1)]?.pdf
+
+        let disposed = false
+        let observer
+        let observedPane
+        let retryTimer
+        let retryCount = 0
+        let rebuildTimer
+
+        const activeTextReady = () => {
+          if (activePage === undefined) return true
+          const pane = resolvePane(host)
+          if (pane === undefined) return false
+          const page = pane.querySelector(`[${PAGE_ATTR}="${activePage}"]`)
+          if (page === null || page === undefined) return false
+          return page.querySelector(`[${TEXT_LAYER_ATTR}]`) !== null
+        }
+
+        const observe = (pane) => {
+          if (pane === observedPane) return
+          observer?.disconnect()
+          observer = undefined
+          observedPane = pane
+          if (typeof MutationObserver !== 'function') return
+          try {
+            observer = new MutationObserver(() => {
+              scheduleRebuild()
+            })
+            observer.observe(pane, { childList: true, subtree: true, characterData: true })
+          } catch (_error) {
+            observer = undefined
+          }
+        }
+
+        const rebuild = () => {
+          if (disposed) return
+          const pane = resolvePane(host)
+          if (pane === undefined) return
+          observe(pane)
+          applySearchHighlights(pane, needle, list, current)
+        }
+
+        const scheduleRebuild = () => {
+          if (disposed || rebuildTimer !== undefined) return
+          rebuildTimer = globalThis.setTimeout(() => {
+            rebuildTimer = undefined
+            rebuild()
+          }, SEARCH_HIGHLIGHT_REBUILD_MS)
+        }
+
+        const retry = () => {
+          if (disposed || retryTimer !== undefined || retryCount >= SEARCH_HIGHLIGHT_RETRY_LIMIT) return
+          retryCount += 1
+          retryTimer = globalThis.setTimeout(() => {
+            retryTimer = undefined
+            if (disposed) return
+            rebuild()
+            if (!activeTextReady()) retry()
+          }, SEARCH_HIGHLIGHT_RETRY_MS)
+        }
+
+        rebuild()
+        if (!activeTextReady()) retry()
+
+        return () => {
+          disposed = true
+          observer?.disconnect()
+          observer = undefined
+          if (retryTimer !== undefined) globalThis.clearTimeout(retryTimer)
+          if (rebuildTimer !== undefined) globalThis.clearTimeout(rebuildTimer)
+          clearSearchHighlights(resolvePane(host))
+        }
+      }, [open, isPdf, absolutePath, query, hits, active, searching, searchError])
+
+      // Cmd/Ctrl+F (with or without Shift) opens our find bar. The first panel
+      // claims the shortcut; pointing at another preview claims it for that one.
       useEffect(() => {
         if (!isPdf) return undefined
         const owner = ownerRef.current
         const onKeyDown = (event) => {
           if (event.defaultPrevented || event.repeat || event.isComposing) return
-          if (!(event.metaKey || event.ctrlKey) || event.altKey || !event.shiftKey) return
+          if (!(event.metaKey || event.ctrlKey) || event.altKey) return
           if (String(event.key).toLowerCase() !== 'f') return
           if (activeOwner === undefined) activeOwner = owner
           if (activeOwner !== owner) return
@@ -1927,9 +2335,24 @@ window.__ModuleLoader__.load({
         }
       }, [isPdf])
 
+      // Focus and select the find input once the panel has actually mounted.
+      // Doing this in an effect (instead of the click handler's timer) also
+      // covers the very first open, when the input ref does not exist yet.
+      useEffect(() => {
+        if (!open) return undefined
+        const input = searchInputRef.current
+        if (input === null) return undefined
+        try {
+          input.focus()
+          input.select()
+        } catch (_error) {
+          // Focus is best effort (for example while the tab is hidden).
+        }
+        return undefined
+      }, [open])
+
       // Timers that outlive a render and must not outlive the component.
       useEffect(() => () => {
-        if (focusTimerRef.current !== null) globalThis.clearTimeout(focusTimerRef.current)
         if (flashTimerRef.current !== null) globalThis.clearTimeout(flashTimerRef.current)
         if (tipTimerRef.current !== null) globalThis.clearTimeout(tipTimerRef.current)
       }, [])
@@ -2094,51 +2517,16 @@ window.__ModuleLoader__.load({
 
       let panel = null
       if (open) {
-        const needle = query.trim()
-        const statusText = searching
-          ? 'Searching…'
-          : searchError !== null
-            ? searchError
-            : needle === ''
-              ? `${total > 0 ? total : '?'} pages · type to search`
-              : hits === null
-                ? ''
-                : hits.length === 0
-                  ? 'No matches — scanned PDFs have no text layer.'
-                  : `${hits.length}${hits.length >= SEARCH_LIMIT ? '+' : ''} result${hits.length === 1 ? '' : 's'}`
-        const list = hits !== null && hits.length > 0
-          ? h('ul', { style: LIST_STYLE }, hits.map((hit, index) => {
-            const label = searchResultLabel(hit)
-            const snippet = normalizeSnippet(hit.snippet, 140)
-            return h('li', {
-              key: `${hit.pdf}:${index}`,
-              style: RESULT_ROW_STYLE,
-            },
-            h('button', {
-              type: 'button',
-              'data-tip': 'resultJump',
-              'data-dsh-pdf-reader': 'result',
-              onClick: () => {
-                jumpTo(hit.pdf)
-              },
-              style: RESULT_JUMP_STYLE,
-            }, snippet === '' ? label : `${label} — ${snippet}`),
-            h('button', {
-              type: 'button',
-              'data-tip': 'resultInsert',
-              'data-dsh-pdf-reader': 'result-ai',
-              onClick: () => {
-                deliverReference(buildSearchReference(hit), 'Inserted')
-              },
-              style: AI_BUTTON_STYLE,
-            }, '→ AI'))
-          }))
-          : null
+        const hitCount = hits === null ? 0 : hits.length
+        const shownHit = hitCount === 0 ? 0 : Math.min(Math.max(active, 0), hitCount - 1) + 1
+        const noHits = hitCount === 0
+        const searchDisabledStyle = noHits ? { opacity: 0.35 } : null
         panel = h('div', {
           key: 'panel',
           style: PANEL_STYLE,
           role: 'dialog',
-          'aria-label': 'Search this PDF',
+          'aria-label': searchCopy('label'),
+          'aria-busy': searching,
           'data-dsh-pdf-reader': 'panel',
           onKeyDown: (event) => {
             if (event.isComposing) return
@@ -2154,40 +2542,74 @@ window.__ModuleLoader__.load({
             ref: searchInputRef,
             type: 'search',
             value: query,
-            placeholder: 'Search this PDF',
-            'aria-label': 'Search this PDF',
+            placeholder: searchCopy('label'),
+            'aria-label': searchCopy('label'),
+            'data-dsh-pdf-reader': 'search-input',
             spellCheck: false,
             autoComplete: 'off',
             maxLength: 1000,
             style: PANEL_INPUT_STYLE,
             onChange: (event) => {
               setQuery(String(event.target.value))
+              setHits(null)
+              setActive(0)
+              setSearchError(null)
             },
             onKeyDown: (event) => {
               if (event.isComposing) return
-              if (event.key === 'Enter' && hits !== null && hits.length > 0) {
+              if (event.key === 'Enter') {
                 event.preventDefault()
-                jumpTo(hits[0].pdf)
+                event.stopPropagation()
+                navigate(active + (event.shiftKey ? -1 : 1))
               }
             },
           }),
+          h('button', {
+            type: 'button',
+            'aria-label': searchCopy('prev'),
+            'data-tip': 'prevHit',
+            'data-dsh-pdf-reader': 'search-prev',
+            disabled: noHits,
+            onClick: () => {
+              navigate(active - 1)
+            },
+            style: { ...BUTTON_STYLE, ...searchDisabledStyle },
+          }, '‹'),
+          h('span', {
+            'data-dsh-pdf-reader': 'search-count',
+            'aria-live': 'polite',
+            style: SEARCH_COUNT_STYLE,
+          }, `${shownHit} / ${hitCount}`),
+          h('button', {
+            type: 'button',
+            'aria-label': searchCopy('next'),
+            'data-tip': 'nextHit',
+            'data-dsh-pdf-reader': 'search-next',
+            disabled: noHits,
+            onClick: () => {
+              navigate(active + 1)
+            },
+            style: { ...BUTTON_STYLE, ...searchDisabledStyle },
+          }, '›'),
           h('button', {
             type: 'button',
             'aria-label': 'Close search',
             'data-tip': 'closeSearch',
+            'data-dsh-pdf-reader': 'search-close',
             onClick: closeSearch,
             style: BUTTON_STYLE,
           }, '✕')),
         h('div', {
-          'aria-live': 'polite',
-          style: {
-            minHeight: '18px',
-            ...(searchError !== null ? WARN_STYLE : MUTED_STYLE),
-          },
-        }, statusText),
-        list,
-        h('div', { style: { ...MUTED_STYLE, fontSize: '10px' } },
-          'Click a page to jump · → AI inserts a reference at the caret'))
+          'data-dsh-pdf-reader': 'search-hint',
+          style: SEARCH_HINT_STYLE,
+        }, searchCopy('hint')),
+        searchError === null
+          ? null
+          : h('div', {
+            'data-dsh-pdf-reader': 'search-error',
+            role: 'status',
+            style: { ...ERROR_STYLE, fontSize: '11px' },
+          }, searchError))
       }
 
       controls.push(panel)
@@ -2248,20 +2670,19 @@ window.__ModuleLoader__.load({
     exports.PdfReaderAction = PdfReaderAction
     // Pure helpers exposed for the headless tests only; the loader ignores them.
     exports.__test = {
-      AI_BUTTON_STYLE,
       PANEL_STYLE,
-      buildSearchReference,
+      SEARCH_ACTIVE_HIGHLIGHT_NAME,
+      SEARCH_HIGHLIGHT_NAME,
       cachedInfo,
       clampZoomScale,
-      copyText,
       createDebouncer,
       createRafThrottle,
       describeSearchFailure,
       displayPage,
       dispatchZoomWheel,
       fetchJson,
+      foldSearchText,
       infoCache,
-      insertComposerText,
       isPdfPath,
       normalizeInfo,
       normalizeSnippet,
@@ -2277,8 +2698,6 @@ window.__ModuleLoader__.load({
       resolveScrollport,
       resolveZoomFrame,
       scrollPageIntoView,
-      searchResultLabel,
-      searchResultPage,
     }
     return module.exports
   },