fix(reader): PDF search returned nothing — reactive proxy broke pdf.js; add back-to-location

PDF search diagnosis: extraction and matching were proven correct
against the real 609-page library PDF (pdfjs 5.5.207, incl. the exact
range-transport setup makePDF uses — 841 hits for 'SELECT'), and the
served bundle had every piece. The failure was Alpine's reactivity:
this.book is a plain object, so reading .pdf through component state
returns a reactive Proxy around the PDFDocumentProxy — and pdf.js
v5 uses #private fields, so getPage() through the proxy throws
'cannot read private member', which the empty catch rendered as a
silent empty result set. runPdfSearch now unwraps via Alpine.raw
(falls back to the raw read), and search failures surface in the
drawer ('Search failed — see console') plus console.warn instead of
masquerading as 'No matches'.

Back-to-location stack (research/footnote workflow): the current
position is recorded before every programmatic jump — search-result
clicks, TOC entries, bookmark and highlight jumps — and on every
internal link click (footnotes, cross-references) via foliate's
'link' event. A ↩ button appears in the topbar once a return target
exists; Alt+← works everywhere. Ordinary paging never pollutes the
stack (max depth 50, consecutive duplicates collapse).

web/src/reader/reader.ts

@@ -414,9 +414,11 @@ document.addEventListener("alpine:init", () => {
     }[],
     searchProgress: 0,
     searching: false,
+    searchError: "",
     searchGen: 0,
     pdfPagesCache: null as PdfPageText[] | null,
     pdfSearchKeys: [] as string[],
+    backStack: [] as { cfi?: string; page?: number }[],
     selectionPopover: {
       open: false,
       mode: "create" as "create" | "edit",
@@ -748,6 +750,10 @@ document.addEventListener("alpine:init", () => {
         }
       });
       // ----- highlight rendering (foliate overlayer pipeline) -----
+      // Internal link clicks (footnotes, cross-references): record where we
+      // came from so the back-to-location stack can return; foliate then
+      // navigates on its own.
+      this.view.addEventListener("link", () => this.pushBackStack());
       this.view.addEventListener("draw-annotation", (e: any) => {
         const { draw, annotation } = e.detail;
         draw(Overlayer.highlight, { color: annotation.color || "#ffd54f" });
@@ -1261,9 +1267,11 @@ document.addEventListener("alpine:init", () => {
     }) {
       if (hl.pdfPage >= 0) {
         // Fixed-layout: a bare number navigates to the section (page) index.
+        this.pushBackStack();
         this.view?.goTo?.(hl.pdfPage);
         this.closeDrawers();
       } else if (hl.cfi) {
+        this.pushBackStack();
         this.view?.showAnnotation({ value: hl.cfi })?.catch?.(() => {});
         this.closeDrawers();
       }
@@ -1485,14 +1493,17 @@ document.addEventListener("alpine:init", () => {
       this.searching = true;
       this.searchProgress = 0;
       this.searchGroups = [];
+      this.searchError = "";
       try {
         if (this.isFixedLayout && this.isPDF) {
           await this.runPdfSearch(q, gen);
         } else {
           await this.runEpubSearch(q, gen);
         }
-      } catch (_e) {
-        /* search errors leave partial results */
+      } catch (e) {
+        // Swallowing this silently made a wiring bug look like "no matches".
+        console.warn("search failed:", e);
+        this.searchError = "Search failed (see browser console)";
       }
       if (gen === this.searchGen) this.searching = false;
     },
@@ -1521,8 +1532,19 @@ document.addEventListener("alpine:init", () => {
       }
     },
     async runPdfSearch(q: string, gen: number) {
-      const pdf = this.book?.pdf;
-      if (!pdf) return;
+      // CRITICAL: unwrap Alpine's reactive proxy. `this.book` is a plain
+      // object, so reactivity wraps it — and reading `.pdf` through the
+      // proxy wraps the PDFDocumentProxy too. pdf.js uses #private fields,
+      // so calling getPage() on the proxy throws "cannot read private
+      // member", which used to be swallowed as an empty result set.
+      const rawBook = (Alpine as any).raw
+        ? (Alpine as any).raw(this.book)
+        : this.book;
+      const pdf = rawBook?.pdf;
+      if (!pdf) {
+        this.searchError = "PDF text engine unavailable";
+        return;
+      }
       if (!this.pdfPagesCache) {
         // Extraction reports progress; it's cached so re-searches are instant.
         this.pdfPagesCache = await extractPdfPages(pdf, (fraction) => {
@@ -1566,6 +1588,7 @@ document.addEventListener("alpine:init", () => {
     clearSearchResults() {
       this.searchGen++;
       this.searching = false;
+      this.searchError = "";
       this.searchGroups = [];
       this.searchProgress = 0;
       for (const key of this.pdfSearchKeys) {
@@ -1575,11 +1598,41 @@ document.addEventListener("alpine:init", () => {
       this.view?.clearSearch?.();
     },
     goToSearchResult(item: { cfi?: string; page?: number | null }) {
-      if (item.cfi) this.view?.goTo?.(item.cfi);
-      else if (item.page != null) this.view?.goTo?.(item.page);
-      else return;
+      if (item.cfi) {
+        this.pushBackStack();
+        this.view?.goTo?.(item.cfi);
+      } else if (item.page != null) {
+        this.pushBackStack();
+        this.view?.goTo?.(item.page);
+      } else return;
       this.closeDrawers();
     },
+    // ----- back-to-location stack -----
+    // Research pattern: jump somewhere (search hit, footnote link, TOC
+    // entry), read, then return. Recorded before every programmatic jump
+    // and on every internal link click (footnotes). Ordinary paging never
+    // touches the stack.
+    pushBackStack() {
+      let loc: { cfi?: string; page?: number } | null = null;
+      if (this.isFixedLayout) {
+        const page = this.renderer?.index;
+        if (typeof page === "number" && page >= 0) loc = { page };
+      } else {
+        const cfi = this.view?.lastLocation?.cfi;
+        if (cfi) loc = { cfi };
+      }
+      if (!loc) return;
+      const top = this.backStack[this.backStack.length - 1];
+      if (top && top.cfi === loc.cfi && top.page === loc.page) return;
+      this.backStack.push(loc);
+      if (this.backStack.length > 50) this.backStack.shift();
+    },
+    goBackToLocation() {
+      const loc = this.backStack.pop();
+      if (!loc) return;
+      if (loc.cfi) this.view?.goTo?.(loc.cfi);
+      else if (typeof loc.page === "number") this.view?.goTo?.(loc.page);
+    },
     flattenTOC(items: any[], depth = 0): any[] {
       const result: any[] = [];
       for (const item of items) {
@@ -1592,6 +1645,7 @@ document.addEventListener("alpine:init", () => {
     },
     goToTOCItem(item: any) {
       if (this.view && item.href) {
+        this.pushBackStack();
         this.view.goTo(item.href);
         this.tocOpen = false;
       }
@@ -1599,8 +1653,10 @@ document.addEventListener("alpine:init", () => {
     goToBookmark(item: { cfi: string; page: number | null }) {
       if (!this.view) return;
       if (item.cfi) {
+        this.pushBackStack();
         this.view.goTo(item.cfi);
       } else if (item.page != null && item.page > 0) {
+        this.pushBackStack();
         // Fixed-layout/comic: sections are pages; foliate takes an index.
         this.view.goTo(item.page - 1);
       } else {
@@ -2049,8 +2105,12 @@ document.addEventListener("alpine:init", () => {
       const typing =
         tag === "INPUT" || tag === "SELECT" || tag === "TEXTAREA";
       this.pokeChrome();
-      if (k === "ArrowLeft" || k === "h") this.goLeft();
-      else if (k === "ArrowRight" || k === "l") this.goRight();
+      if (k === "ArrowLeft" || k === "h") {
+        if (event.altKey) {
+          event.preventDefault();
+          this.goBackToLocation();
+        } else this.goLeft();
+      } else if (k === "ArrowRight" || k === "l") this.goRight();
       else if (k === "+" || k === "=") this.zoomIn();
       else if (k === "-" || k === "_") this.zoomOut();
       else if (k === "0") this.resetZoom();