dsh-book-reader 0.1.1 → 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.
@@ -31,12 +30,18 @@ window.__ModuleLoader__.load({
     const INFO_ROUTE = '/dsh-pdf-reader/info'
     const SEARCH_ROUTE = '/dsh-pdf-reader/search'
     const CURRENT_ROUTE = '/dsh-pdf-reader/current'
+    const VIEW_ROUTE = '/dsh-pdf-reader/view'
 
     /** DOM markers owned by the official preview (same ones dsh-pdf-search uses). */
     const PANE_ATTR = 'data-textpreview-body'
     const SCROLL_ATTR = 'data-document-zoom-scrollport'
+    const ZOOM_FRAME_ATTR = 'data-document-zoom-frame'
+    const ZOOM_MODE_ATTR = 'data-document-zoom-mode'
+    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
@@ -48,6 +53,45 @@ 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.
+     *
+     * Restoring is best effort and must not block the preview: the saved view is
+     * fetched in parallel, then the structure/page markers are retried for about
+     * eight seconds. Saving starts only after restore finished (success or
+     * failure) so opening a book cannot overwrite its saved page with page 1.
+     * The save debounce is deliberately longer than the report debounce so a
+     * scroll settles before either write happens.
+     */
+    const VIEW_TIMEOUT_MS = 6_000
+    const VIEW_SAVE_DELAY_MS = 500
+    const VIEW_RETRY_MS = 200
+    const VIEW_RETRY_LIMIT = 40
+    const VIEW_REAPPLY_MS = 300
+    const VIEW_ZOOM_STEP_MS = 50
+    const VIEW_ZOOM_SETTLE_MS = 160
+    const VIEW_ZOOM_EVENT_LIMIT = 20
+    const VIEW_ZOOM_TOLERANCE = 0.02
+    const VIEW_ZOOM_MIN = 0.25
+    const VIEW_ZOOM_MAX = 4
+
     /** Non-PDF files are left entirely alone (Office previews have .docx paths). */
     function isPdfPath(value) {
       return typeof value === 'string' && /\.pdf$/iu.test(value)
@@ -112,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()
@@ -121,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.
      *
@@ -223,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.
      *
@@ -267,6 +608,29 @@ window.__ModuleLoader__.load({
       return undefined
     }
 
+    /**
+     * Find the zoom wrapper that owns the preview scrollport.
+     *
+     * The PDF renderer nests the frame inside the preview body, so the frame is
+     * usually the scrollport's closest ancestor. A pane descendant is also
+     * checked so a renderer reshuffle degrades to "no zoom restore" instead of
+     * failing the page restore.
+     * @param pane - preview body.
+     * @param scrollport - inner scrolling element, when one exists.
+     * @returns the zoom frame, or `undefined` for a renderer without zoom.
+     */
+    function resolveZoomFrame(pane, scrollport) {
+      if (scrollport !== null && scrollport !== undefined && typeof scrollport.closest === 'function') {
+        const nearest = scrollport.closest(`[${ZOOM_FRAME_ATTR}]`)
+        if (isElement(nearest)) return nearest
+      }
+      if (pane !== null && pane !== undefined && typeof pane.querySelector === 'function') {
+        const nested = pane.querySelector(`[${ZOOM_FRAME_ATTR}]`)
+        if (isElement(nested)) return nested
+      }
+      return undefined
+    }
+
     /**
      * Scroll one page near the top of the preview.
      *
@@ -300,6 +664,118 @@ window.__ModuleLoader__.load({
       return false
     }
 
+    /**
+     * Ask the official preview to change zoom through its own gesture path.
+     *
+     * The preview implements zoom as a native `wheel` listener on the scrollport:
+     * it only reacts to `ctrlKey`, multiplies the current scale by
+     * `exp(-deltaY * 0.01)`, clamps `deltaY` to ±40, and commits the fixed
+     * preference 120 ms after the last event. Dispatching that synthetic event
+     * is therefore the only supported way for a plugin to set an arbitrary
+     * scale (0.25..4) without writing React state it does not own.
+     * @param scrollport - the preview's inner scrolling element.
+     * @param deltaY - wheel delta; negative zooms in.
+     * @returns whether an event was dispatched.
+     */
+    function dispatchZoomWheel(scrollport, deltaY) {
+      if (scrollport === null || scrollport === undefined || typeof scrollport.dispatchEvent !== 'function') {
+        return false
+      }
+      const view = scrollport.ownerDocument?.defaultView
+      const Wheel = view?.WheelEvent ?? (typeof WheelEvent === 'function' ? WheelEvent : undefined)
+      if (typeof Wheel !== 'function') return false
+      let event
+      try {
+        event = new Wheel('wheel', {
+          ctrlKey: true,
+          deltaY,
+          deltaMode: 0,
+          clientX: 0,
+          clientY: 0,
+          bubbles: true,
+          cancelable: true,
+        })
+      } catch (_error) {
+        return false
+      }
+      try {
+        scrollport.dispatchEvent(event)
+      } catch (_error) {
+        return false
+      }
+      return true
+    }
+
+    /**
+     * Clamp one zoom ratio into the range the preview and the Host agree on.
+     * @param value - number or CSS custom-property string.
+     * @returns a 3-decimal scale in 0.25..4, or `undefined` when unreadable.
+     */
+    function clampZoomScale(value) {
+      const numeric = typeof value === 'number' ? value : Number.parseFloat(String(value ?? ''))
+      if (!Number.isFinite(numeric)) return undefined
+      return Math.round(Math.min(VIEW_ZOOM_MAX, Math.max(VIEW_ZOOM_MIN, numeric)) * 1000) / 1000
+    }
+
+    /**
+     * Normalize one `GET /dsh-pdf-reader/view` payload.
+     *
+     * A missing row, a 404, and a malformed row all mean "nothing to restore";
+     * the Host owns validation, so the client only keeps values it can act on.
+     * @param body - parsed response body.
+     * @returns `{ pdfPage, zoomMode, zoomScale }`, or `undefined`.
+     */
+    function normalizeView(body) {
+      if (body === null || typeof body !== 'object' || body.ok !== true) return undefined
+      const view = body.view
+      if (view === null || typeof view !== 'object') return undefined
+      if (!positiveInteger(view.pdfPage)) return undefined
+      return {
+        pdfPage: view.pdfPage,
+        zoomMode: view.zoomMode === 'fixed' ? 'fixed' : 'fit-width',
+        zoomScale: clampZoomScale(view.zoomScale) ?? 1,
+      }
+    }
+
+    /** @returns the zoom mode the preview frame currently reports. */
+    function frameZoomMode(frame) {
+      if (frame === null || frame === undefined || typeof frame.getAttribute !== 'function') return 'fit-width'
+      return frame.getAttribute(ZOOM_MODE_ATTR) === 'fixed' ? 'fixed' : 'fit-width'
+    }
+
+    /**
+     * Read the effective zoom the preview frame currently shows.
+     *
+     * The renderer writes the resolved scale to the frame's inline
+     * `--document-zoom` (fit-width included), so the inline value is read first
+     * and the computed value only serves a frame whose style was not inlined.
+     * @param frame - zoom frame, when one exists.
+     * @returns a clamped, 3-decimal scale.
+     */
+    function frameZoomScale(frame) {
+      if (frame === null || frame === undefined || typeof frame.getAttribute !== 'function') return 1
+      let raw
+      try {
+        raw = typeof frame.style?.getPropertyValue === 'function'
+          ? frame.style.getPropertyValue(ZOOM_VAR)
+          : undefined
+        if (raw === undefined || raw === null || String(raw).trim() === '') {
+          const view = frame.ownerDocument?.defaultView
+          if (view !== null && view !== undefined && typeof view.getComputedStyle === 'function') {
+            raw = view.getComputedStyle(frame).getPropertyValue(ZOOM_VAR)
+          }
+        }
+      } catch (_error) {
+        raw = undefined
+      }
+      return clampZoomScale(raw) ?? 1
+    }
+
+    /** @returns `{ zoomMode, zoomScale }` as the frame currently shows them. */
+    function readFrameZoom(frame) {
+      return { zoomMode: frameZoomMode(frame), zoomScale: frameZoomScale(frame) }
+    }
+
     /**
      * A cancellable trailing-edge debouncer.
      * @param delay - milliseconds.
@@ -479,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
@@ -580,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.
@@ -671,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 上下文', '把当前阅读页报告给模型'],
@@ -682,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. */
@@ -762,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`.
@@ -784,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)
@@ -792,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)
@@ -805,6 +1248,10 @@ window.__ModuleLoader__.load({
           (id) => globalThis.clearTimeout(id),
         )
       }
+      /** Latest sampled page, readable from the debounced view save. */
+      const pageRef = useRef(1)
+      /** Installed by the view effect; `null` when this preview keeps no view. */
+      const requestViewSaveRef = useRef(null)
 
       const [page, setPage] = useState(1)
       const [sampled, setSampled] = useState(false)
@@ -818,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)
@@ -887,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
@@ -980,14 +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
@@ -1254,6 +1710,360 @@ window.__ModuleLoader__.load({
         }
       }, [isPdf, absolutePath])
 
+      // Restore the last page/zoom for this book, then persist both best-effort.
+      //
+      // The official preview keeps neither across tabs, so this owns one restore
+      // per absolutePath: fetch the saved view in parallel with rendering, wait
+      // (up to ~8 s) for the preview structure and the target page, drive the
+      // renderer's own Ctrl+wheel path for a fixed zoom, and only then allow
+      // saving. The gate matters: saving before the restore lands would replace
+      // the saved page with page 1 every time a book is opened.
+      useEffect(() => {
+        if (!isPdf || absolutePath === undefined) return undefined
+        const host = hostRef.current
+        if (host === null) return undefined
+        const pdfPath = absolutePath
+
+        let disposed = false
+        let finished = false
+        let pane
+        let scrollport
+        let frame
+        let attributeObserver
+        let structureObserver
+        let retryTimer
+        let retryCount = 0
+        let reapplyTimer
+        let zoomTimer
+        let zoomEvents = 0
+        let restoreTarget
+        let lastAttemptKey = ''
+        const restoreController = new AbortController()
+        const saveController = new AbortController()
+
+        const saveDebouncer = createDebouncer(
+          VIEW_SAVE_DELAY_MS,
+          (fn, ms) => globalThis.setTimeout(fn, ms),
+          (id) => globalThis.clearTimeout(id),
+        )
+        const structureDebouncer = createDebouncer(
+          250,
+          (fn, ms) => globalThis.setTimeout(fn, ms),
+          (id) => globalThis.clearTimeout(id),
+        )
+
+        /**
+         * Persist the current page and zoom. The four client fields are the whole
+         * contract; the Host stamps `updatedAt`. Identical consecutive payloads
+         * are suppressed, and a failed write is retried by the next trigger.
+         */
+        const saveNow = () => {
+          if (disposed || !finished) return
+          if (typeof fetch !== 'function') return
+          // A debounced save is also a cheap reconnect point: if the preview
+          // replaced its structure, resolve it again before reading the frame.
+          refresh()
+          const zoom = readFrameZoom(frame)
+          const payload = {
+            path: pdfPath,
+            pdfPage: positiveInteger(pageRef.current) ? pageRef.current : 1,
+            zoomMode: zoom.zoomMode,
+            zoomScale: zoom.zoomScale,
+          }
+          const key = JSON.stringify(payload)
+          if (key === lastAttemptKey) return
+          lastAttemptKey = key
+          let request
+          try {
+            request = fetch(VIEW_ROUTE, {
+              method: 'POST',
+              headers: { 'content-type': 'application/json', accept: 'application/json' },
+              body: JSON.stringify(payload),
+              signal: saveController.signal,
+              keepalive: true,
+            })
+          } catch (_error) {
+            lastAttemptKey = ''
+            return
+          }
+          Promise.resolve(request)
+            .then((response) => {
+              if (disposed) return
+              if (response !== null && response !== undefined && response.ok === true) return
+              if (lastAttemptKey === key) lastAttemptKey = ''
+            })
+            .catch(() => {
+              if (disposed) return
+              if (lastAttemptKey === key) lastAttemptKey = ''
+            })
+        }
+
+        const requestSave = () => {
+          if (disposed) return
+          saveDebouncer.schedule(saveNow)
+        }
+        requestViewSaveRef.current = requestSave
+
+        /** Allow saving once, including when the restore failed or timed out. */
+        const finish = () => {
+          if (disposed || finished) return
+          finished = true
+          requestSave()
+        }
+
+        const detach = () => {
+          attributeObserver?.disconnect()
+          attributeObserver = undefined
+          structureObserver?.disconnect()
+          structureObserver = undefined
+        }
+
+        const observeStructure = () => {
+          structureObserver?.disconnect()
+          structureObserver = undefined
+          if (typeof MutationObserver !== 'function') return
+          const root = pane?.parentElement ?? host.parentElement ?? pane ?? host
+          if (root === null || root === undefined) return
+          structureObserver = new MutationObserver(() => {
+            if (disposed) return
+            structureDebouncer.schedule(syncStructure)
+          })
+          structureObserver.observe(root, { childList: true, subtree: true })
+        }
+
+        const observeFrame = (target) => {
+          attributeObserver?.disconnect()
+          attributeObserver = undefined
+          if (target === null || target === undefined) return
+          if (typeof MutationObserver !== 'function') return
+          attributeObserver = new MutationObserver(() => {
+            if (disposed) return
+            requestSave()
+          })
+          attributeObserver.observe(target, {
+            attributes: true,
+            attributeFilter: [ZOOM_MODE_ATTR, 'style'],
+            subtree: false,
+          })
+        }
+
+        const bind = (nextPane, nextScrollport, nextFrame) => {
+          attributeObserver?.disconnect()
+          attributeObserver = undefined
+          structureObserver?.disconnect()
+          structureObserver = undefined
+          pane = nextPane
+          scrollport = nextScrollport
+          frame = nextFrame
+          observeFrame(frame)
+          observeStructure()
+        }
+
+        const syncStructure = () => {
+          if (disposed) return
+          const nextPane = resolvePane(host)
+          if (nextPane === undefined) return
+          const nextScrollport = resolveScrollport(nextPane)
+          const nextFrame = resolveZoomFrame(nextPane, nextScrollport)
+          if (nextPane !== pane || nextScrollport !== scrollport || nextFrame !== frame) {
+            bind(nextPane, nextScrollport, nextFrame)
+          }
+        }
+
+        /** Re-resolve the preview structure; true when a body exists. */
+        const refresh = () => {
+          const nextPane = resolvePane(host)
+          if (nextPane === undefined) return false
+          const nextScrollport = resolveScrollport(nextPane)
+          const nextFrame = resolveZoomFrame(nextPane, nextScrollport)
+          if (nextPane !== pane || nextScrollport !== scrollport || nextFrame !== frame) {
+            bind(nextPane, nextScrollport, nextFrame)
+          }
+          return true
+        }
+
+        const retryRestore = () => {
+          if (disposed || finished || retryTimer !== undefined) return
+          if (retryCount >= VIEW_RETRY_LIMIT) {
+            finish()
+            return
+          }
+          retryCount += 1
+          retryTimer = globalThis.setTimeout(() => {
+            retryTimer = undefined
+            if (!disposed) stepRestore()
+          }, VIEW_RETRY_MS)
+        }
+
+        /**
+         * 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 = ({ finishGate = true } = {}) => {
+          if (disposed || restoreTarget === undefined) return false
+          const target = restoreTarget.pdfPage
+          if (!refresh() || !scrollPageIntoView(pane, scrollport, target)) {
+            retryRestore()
+            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)
+          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, 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(() => {
+            zoomTimer = undefined
+            if (!disposed) placePage()
+          }, VIEW_ZOOM_SETTLE_MS)
+        }
+
+        /**
+         * Drive Ctrl+wheel events until the frame scale is within 2% of the saved
+         * fixed scale. Each event can change the ratio by at most ~1.49x, so a
+         * large jump needs a few events; the event budget bounds a missing or
+         * non-responsive handler.
+         */
+        const stepZoom = () => {
+          if (disposed || restoreTarget === undefined) return
+          const target = restoreTarget.zoomScale
+          if (!refresh() || frame === undefined || scrollport === undefined) {
+            finish()
+            return
+          }
+          const current = frameZoomScale(frame)
+          if (Math.abs(current / target - 1) <= VIEW_ZOOM_TOLERANCE) {
+            if (frameZoomMode(frame) !== 'fixed') {
+              // 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)) {
+                finish()
+                return
+              }
+            }
+            // The renderer commits its fixed preference 120 ms after the last
+            // gesture and only then re-renders pages at the new scale.
+            settleZoom()
+            return
+          }
+          if (zoomEvents >= VIEW_ZOOM_EVENT_LIMIT) {
+            settleZoom()
+            return
+          }
+          const deltaY = Math.max(-40, Math.min(40, -100 * Math.log(target / current)))
+          if (!Number.isFinite(deltaY) || Math.abs(deltaY) < 0.05) {
+            settleZoom()
+            return
+          }
+          zoomEvents += 1
+          if (!dispatchZoomWheel(scrollport, deltaY)) {
+            settleZoom()
+            return
+          }
+          zoomTimer = globalThis.setTimeout(() => {
+            zoomTimer = undefined
+            if (!disposed) stepZoom()
+          }, VIEW_ZOOM_STEP_MS)
+        }
+
+        const stepRestore = () => {
+          if (disposed || finished || restoreTarget === undefined) return
+          const target = restoreTarget
+          if (!refresh()) {
+            retryRestore()
+            return
+          }
+          const page = pane.querySelector(`[${PAGE_ATTR}="${target.pdfPage}"]`)
+          if (!isElement(page)) {
+            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') {
+              stepZoom()
+              return
+            }
+          }
+          finish()
+        }
+
+        const loadSavedView = async () => {
+          const timer = globalThis.setTimeout(() => {
+            restoreController.abort()
+          }, VIEW_TIMEOUT_MS)
+          try {
+            const { body } = await fetchJson(
+              `${VIEW_ROUTE}?path=${encodeURIComponent(pdfPath)}`,
+              { headers: { accept: 'application/json' }, signal: restoreController.signal },
+            )
+            if (disposed) return
+            const saved = normalizeView(body)
+            if (saved === undefined) {
+              finish()
+              return
+            }
+            restoreTarget = saved
+            stepRestore()
+          } catch (_error) {
+            if (disposed) return
+            // A missing route, a network failure, or a timeout must not block
+            // saving forever: the restore is best effort.
+            finish()
+          } finally {
+            globalThis.clearTimeout(timer)
+          }
+        }
+
+        // Observe the current structure while the GET is in flight, so a zoom the
+        // reader performs before the response still gets saved once the gate opens.
+        refresh()
+        void loadSavedView()
+
+        return () => {
+          disposed = true
+          restoreController.abort()
+          saveController.abort()
+          saveDebouncer.cancel()
+          structureDebouncer.cancel()
+          if (retryTimer !== undefined) globalThis.clearTimeout(retryTimer)
+          if (reapplyTimer !== undefined) globalThis.clearTimeout(reapplyTimer)
+          if (zoomTimer !== undefined) globalThis.clearTimeout(zoomTimer)
+          detach()
+          if (requestViewSaveRef.current === requestSave) requestViewSaveRef.current = null
+        }
+      }, [isPdf, absolutePath])
+
+      // Save the sampled page through the same 500 ms gate as zoom changes.
+      useEffect(() => {
+        pageRef.current = page
+        if (sampled) requestViewSaveRef.current?.()
+      }, [page, sampled])
+
       // Debounced AI-context reporting. One timer, one in-flight POST, abort on
       // page change, toggle-off, path change, or unmount.
       useEffect(() => {
@@ -1334,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
@@ -1362,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
               }
@@ -1370,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(() => {
@@ -1390,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
@@ -1420,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)
       }, [])
@@ -1587,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
@@ -1647,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)
@@ -1741,32 +2670,34 @@ 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,
-      copyText,
+      clampZoomScale,
       createDebouncer,
       createRafThrottle,
       describeSearchFailure,
       displayPage,
+      dispatchZoomWheel,
       fetchJson,
+      foldSearchText,
       infoCache,
-      insertComposerText,
       isPdfPath,
       normalizeInfo,
       normalizeSnippet,
+      normalizeView,
       pageElements,
       parsePageInput,
       pickPage,
       positiveInteger,
       printedPageOf,
+      readFrameZoom,
       rememberInfo,
       resolvePane,
       resolveScrollport,
+      resolveZoomFrame,
       scrollPageIntoView,
-      searchResultLabel,
-      searchResultPage,
     }
     return module.exports
   },