dsh-book-reader 0.1.0 → 0.2.0

package/lib/client.js

@@ -4,7 +4,7 @@
  * 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" and "share this page" insertions into the chat composer;
+ *   - "→ AI" insertion of a search hit into the chat composer;
  *   - debounced current-page reporting for AI context, with an on/off toggle.
  *
  * The contribution mounts into the preview's own header slot
@@ -31,10 +31,14 @@ 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'
 
@@ -48,6 +52,28 @@ window.__ModuleLoader__.load({
     const SEARCH_LIMIT = 100
     const INFO_CACHE_LIMIT = 16
 
+    /**
+     * 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)
@@ -134,11 +160,6 @@ window.__ModuleLoader__.load({
       return page === undefined ? 'p.?' : `p.${page}`
     }
 
-    /** @returns `[PDF p.132]` for the share button. */
-    function buildShareReference(pdfPage, printedOffset) {
-      return `[PDF p.${displayPage(pdfPage, printedOffset)}]`
-    }
-
     /** @returns `PDF p.132: <snippet>` (or `[PDF p.132]` when there is no snippet). */
     function buildSearchReference(hit) {
       const page = searchResultPage(hit)
@@ -272,6 +293,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.
      *
@@ -305,6 +349,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.
@@ -679,10 +835,6 @@ window.__ModuleLoader__.load({
         zh: ['搜索', '搜索这个 PDF 的文字层（Cmd/Ctrl+Shift+F）'],
         en: ['Search', "Search this PDF's text layer (Cmd/Ctrl+Shift+F)"],
       },
-      share: {
-        zh: ['引用当前页', '把当前位置引用插入输入框'],
-        en: ['Insert reference', 'Insert this page reference into the chat'],
-      },
       follow: {
         zh: ['AI 上下文', '把当前阅读页报告给模型'],
         en: ['AI context', 'Report the page you are reading to the model'],
@@ -814,6 +966,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)
@@ -992,6 +1148,7 @@ window.__ModuleLoader__.load({
         setSearching(false)
         setSearchError(null)
         lastReportedKeyRef.current = undefined
+        pageRef.current = 1
         reportAbortRef.current?.abort()
         if (focusTimerRef.current !== null) {
           globalThis.clearTimeout(focusTimerRef.current)
@@ -1263,6 +1420,347 @@ 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.
+         */
+        const placePage = () => {
+          if (disposed || restoreTarget === undefined) return
+          const target = restoreTarget.pdfPage
+          if (!refresh() || !scrollPageIntoView(pane, scrollport, target)) {
+            retryRestore()
+            return
+          }
+          // 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 (reapplyTimer !== undefined) globalThis.clearTimeout(reapplyTimer)
+          reapplyTimer = globalThis.setTimeout(() => {
+            reapplyTimer = undefined
+            if (disposed || !refresh()) return
+            scrollPageIntoView(pane, scrollport, target)
+          }, VIEW_REAPPLY_MS)
+        }
+
+        /** Let the renderer's 120 ms zoom settlement commit before scrolling. */
+        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) {
+            placePage()
+            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)) {
+                placePage()
+                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
+          }
+          if (target.zoomMode === 'fixed' && frame !== undefined && scrollport !== undefined) {
+            if (Math.abs(frameZoomScale(frame) / target.zoomScale - 1) > VIEW_ZOOM_TOLERANCE
+              || frameZoomMode(frame) !== 'fixed') {
+              stepZoom()
+              return
+            }
+          }
+          placePage()
+        }
+
+        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(() => {
@@ -1536,17 +2034,6 @@ window.__ModuleLoader__.load({
           },
           style: BUTTON_STYLE,
         }, SEARCH_ICON),
-        h('button', {
-          key: 'share',
-          type: 'button',
-          'aria-label': 'Insert this page reference into the chat',
-          'data-tip': 'share',
-          'data-dsh-pdf-reader': 'share',
-          onClick: () => {
-            deliverReference(buildShareReference(page, printedOffset), 'Inserted')
-          },
-          style: BUTTON_STYLE,
-        }, h('span', { 'aria-hidden': 'true', style: { fontSize: '14px' } }, '↗')),
         h('button', {
           key: 'follow',
           type: 'button',
@@ -1764,27 +2251,31 @@ window.__ModuleLoader__.load({
       AI_BUTTON_STYLE,
       PANEL_STYLE,
       buildSearchReference,
-      buildShareReference,
       cachedInfo,
+      clampZoomScale,
       copyText,
       createDebouncer,
       createRafThrottle,
       describeSearchFailure,
       displayPage,
+      dispatchZoomWheel,
       fetchJson,
       infoCache,
       insertComposerText,
       isPdfPath,
       normalizeInfo,
       normalizeSnippet,
+      normalizeView,
       pageElements,
       parsePageInput,
       pickPage,
       positiveInteger,
       printedPageOf,
+      readFrameZoom,
       rememberInfo,
       resolvePane,
       resolveScrollport,
+      resolveZoomFrame,
       scrollPageIntoView,
       searchResultLabel,
       searchResultPage,