dsh-book-reader 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-10-20
+
+### Added
+
+- View-state memory: the toolbar remembers the last page and zoom ratio per PDF
+  and restores them when the same book is reopened. The state is stored by the
+  Host in the `book_reader_views` storage domain through `ctx.storageDomain`
+  (schema-validated JSON under the DSH data directory), survives DSH restarts,
+  and degrades silently when that service is unavailable.
+- New config key `rememberView` (default `true`).
+- Host routes `GET /dsh-pdf-reader/view?path=…` and
+  `POST /dsh-pdf-reader/view` for the browser half.
+- Docs: the README is split into a concise English `README.md` and a concise
+  Simplified Chinese `README.zh-CN.md`; they no longer share one page.
+
 ## [0.1.1] — 2026-10-18
 
 ### Changed
@@ -56,5 +71,6 @@ First public release.
 - `pdfjs-dist` is pinned to `6.3.289` to match the host process.
 - MIT licensed.
 
+[0.2.0]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.2.0
 [0.1.1]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.1.1
 [0.1.0]: https://github.com/Strepsiades2/dsh-book-reader/releases/tag/v0.1.0

package/README.md

@@ -1,101 +1,55 @@
 # dsh-book-reader
 
-Read books and papers in DSH: a reading toolbar on the official PDF preview, plus three PDF tools for the model.
+A reading toolbar for DSH's official PDF preview, plus three PDF tools the model can use.
 
-**English** | [中文](#中文说明)
+[中文说明](README.zh-CN.md)
 
 ## Features
 
-**Reading toolbar** — appears only on `.pdf` previews in the right sidebar; the stock previewer (zoom, selection, reload) is untouched.
+**Reading toolbar** — only on `.pdf` previews in the right sidebar; the stock previewer is untouched.
 
-- Previous/next page, a page readout that follows scrolling, and a jump box that accepts printed page numbers (or `p152` for PDF page 152).
-- Full-text search panel (`Cmd/Ctrl+Shift+F`): click a result to jump there, or insert its page reference into the chat.
-- **AI position hint** (on by default): before a turn starts, the model may receive one short line with the page you are reading — at most once per turn, and only when the page changed since the last hint. Turn it off if you do not want the model to know your page automatically.
-- Every control has a hover/focus explanation in English or Chinese, following the DSH UI language.
+- Previous/next page, a current-page readout, and a jump box (printed page numbers, or `p152` for PDF page 152).
+- Full-text search with `Cmd/Ctrl+Shift+F`; click a result to jump, or insert its page reference into the chat.
+- AI position hint: before each turn the model may receive one short “you are reading page N” line (the `AI●` toggle, on by default).
+- **Remembers your place**: reopening a book restores the last page and zoom. State is stored by DSH per book and survives restarts.
+- Hover/focus explanations on every control, in English or Chinese.
 
-**Model tools** — the model can look up the page map, search the text, or read chosen pages (as text or as page images) when you ask about a PDF.
+**Model tools** — the model calls them when you ask about a PDF.
 
 | Tool | What it does |
 | --- | --- |
-| `pdf_info` | Page count, printed↔physical page offset, outline/TOC. Text only. |
-| `pdf_search` | Literal full-text search; returns page numbers and snippets. |
-| `pdf_read_pages` | Text of chosen pages, optionally as images (`include_image: false` for text only; images cost ~350–1024 tokens/page). |
-
-Typical loop: `pdf_info` → `pdf_search` → `pdf_read_pages` (text) → images only for formulas, diagrams, or tables.
+| `pdf_info` | Page count, printed↔physical page offset, outline/TOC |
+| `pdf_search` | Literal full-text search; page numbers and snippets |
+| `pdf_read_pages` | Reads chosen pages as text, optionally with page images |
 
 ## Install
 
-- **From npm**: DSH **Plugins → Add plugin** → `dsh-book-reader` (or pin `dsh-book-reader@0.1.1`), or `dsh plugin add dsh-book-reader`.
-- A fresh install applies live (this profile has HMR); **upgrading a plugin that is already loaded needs a DSH restart** to load the new code.
-- **Optional skill** (gives the model the built-in PDF reading guide): symlink the package into the workspace:
-  ```sh
-  ln -sfn "<installed package dir>" "<workspace>/.dsh/skills/pdf-reader"
-  ```
-- **Local checkout**: `dsh plugin add "/abs/path/to/dsh-book-reader"`; keep the checkout and its `node_modules/` in place.
+1. **Plugins → Add plugin** in DSH and enter `dsh-book-reader` (or run `dsh plugin add dsh-book-reader`).
+2. Restart DSH after installing or upgrading.
+3. Optional: give the model the reading guide by linking the skill into your workspace:
+
+   ```sh
+   ln -sfn "<installed package dir>" "<workspace>/.dsh/skills/pdf-reader"
+   ```
 
 ## Configuration
 
-Every option is optional and the defaults are safe. Common ones: `maxPagesPerCall` (default 4), `defaultScale` (2.5), `autoShare` (automatic position hint), `allowOutsideWorkspace` (tools stay inside the session workspace by default), `routeAllowedRoots` (restrict the local HTTP routes). The full list with defaults is commented in [`cordis.patch.yml`](cordis.patch.yml).
+All keys are optional and the defaults are safe. Common ones:
+
+- `rememberView` (default `true`) — remember page/zoom per book.
+- `maxPagesPerCall` (default `4`) — page cap for `pdf_read_pages`.
+- `defaultScale` (default `2.5`) — image render scale.
+- `autoShare` (default `true`) — the AI position hint.
+
+The full list with defaults is in [`cordis.patch.yml`](cordis.patch.yml).
 
 ## Notes
 
-- HTTP routes are loopback-only and unauthenticated; the tools are workspace-scoped by default. Other local preview plugins make the same tradeoff.
-- Works only with the official PDF preview: it relies on that preview's DOM markers, which a DSH upgrade may change.
-- Scanned PDFs have no text layer — there is no OCR, so only page images help.
+- Only the official PDF preview is supported; the toolbar relies on that preview's private DOM markers, so a DSH upgrade may change behavior.
+- Tools read only inside the session workspace unless `allowOutsideWorkspace` is set; the local HTTP routes are loopback-only and unauthenticated.
+- Scanned PDFs have no text layer — page images are the only option (no OCR).
 - `pdfjs-dist` is pinned to `6.3.289` to match the host process.
 
 ## More
 
-- [`SKILL.md`](SKILL.md) — model-facing guide: costs, page numbering, pitfalls.
-- [`CHANGELOG.md`](CHANGELOG.md) · [`LICENSE`](LICENSE) (MIT)
-
----
-
-## 中文说明
-
-在 DSH 里读 PDF 书和论文：官方 PDF 预览上加一条读书工具栏，外加三个 PDF 工具给模型。
-
-### 功能
-
-**阅读工具栏** —— 只在右侧栏的 `.pdf` 预览上出现；不替换官方预览器（缩放、选中、刷新都保持原样）。
-
-- 上一页/下一页、随滚动更新的页码读数、跳页框（输入印刷页码，或 `p152` 表示 PDF 第 152 页）。
-- 全文搜索面板（`Cmd/Ctrl+Shift+F`）：点结果跳页，或把该页引用插入对话框。
-- **AI 位置提示**（默认开）：每轮对话开始时，模型可能收到一行“你正在看第 N 页”的短提示 —— 每轮最多一次，且页码变了才发。关掉后，模型不会自动知道你在哪页。
-- 每个控件都有 hover / 键盘聚焦提示，跟随 DSH 界面语言（中文或英文）。
-
-**模型工具** —— 默认只花文本 token，图片是按需付的钱。
-
-| 工具 | 作用 |
-| --- | --- |
-| `pdf_info` | 页数、印刷页↔物理页偏移、目录/TOC；纯文本。 |
-| `pdf_search` | 字面全文搜索；返回页码和摘要。 |
-| `pdf_read_pages` | 选中页的文本，也可返回页面图片（`include_image: false` 只取文本；图片约 350–1024 token/页）。 |
-
-典型流程：`pdf_info` → `pdf_search` → `pdf_read_pages`（文本）→ 只有公式、图表、表格才看图。
-
-### 安装
-
-- **从 npm 安装**：DSH **Plugins → Add plugin** → 输入 `dsh-book-reader`（或锁定版本 `dsh-book-reader@0.1.1`），或命令行 `dsh plugin add dsh-book-reader`。
-- 全新安装即时生效（本 profile 已启用 HMR）；**升级已加载的插件需要完整重启 DSH** 才能加载新代码。
-- **可选 skill**（给模型一份内置的 PDF 阅读指南）：把包目录软链到工作区：
-  ```sh
-  ln -sfn "<已安装的包目录>" "<workspace>/.dsh/skills/pdf-reader"
-  ```
-- **本地开发**：`dsh plugin add "/abs/path/to/dsh-book-reader"`；源码目录和 `node_modules/` 必须留在原处。
-
-### 配置
-
-全部可选，默认值即安全值。常用：`maxPagesPerCall`（默认 4）、`defaultScale`（2.5）、`autoShare`（自动位置提示）、`allowOutsideWorkspace`（工具默认只读会话工作区）、`routeAllowedRoots`（限制本地 HTTP 路由）。完整键和默认值见 [`cordis.patch.yml`](cordis.patch.yml) 注释。
-
-### 说明
-
-- HTTP 路由只认回环地址且无鉴权；工具默认只在工作区内。其他本地预览插件也是同样的权衡。
-- 只支持官方 PDF 预览（依赖它的私有 DOM 标记，DSH 升级可能失效）。
-- 扫描件没有文本层，**没有 OCR**，只能看图。
-- `pdfjs-dist` 锁定 `6.3.289`，以和宿主进程保持一致。
-
-### 更多
-
-- [`SKILL.md`](SKILL.md) —— 模型使用手册：成本、页码、常见陷阱。
-- [`CHANGELOG.md`](CHANGELOG.md) · [`LICENSE`](LICENSE)（MIT）
+[`SKILL.md`](SKILL.md) — the model's reading guide · [`CHANGELOG.md`](CHANGELOG.md) · [`LICENSE`](LICENSE) (MIT)

package/README.zh-CN.md

@@ -0,0 +1,55 @@
+# dsh-book-reader
+
+给 DSH 官方 PDF 预览加一条读书工具栏，并给模型三个 PDF 工具。
+
+[English](README.md)
+
+## 功能
+
+**阅读工具栏** —— 只在右侧栏的 `.pdf` 预览上出现，不替换官方预览器。
+
+- 上一页/下一页、跟随滚动的页码读数、跳页框（印刷页码，或 `p152` 表示 PDF 第 152 页）。
+- 全文搜索（`Cmd/Ctrl+Shift+F`）：点结果跳页，或把该页引用插入对话框。
+- AI 位置提示：每轮对话开始前，模型可能收到一行“你正在看第 N 页”的短提示（`AI●` 开关，默认开）。
+- **记住阅读位置**：再次打开同一本书时恢复上次的页码和缩放；状态按书保存在 DSH 侧，重启后仍有效。
+- 每个控件都有悬停/聚焦说明，跟随 DSH 界面语言（中文或英文）。
+
+**模型工具** —— 你问 PDF 内容时由模型调用。
+
+| 工具 | 作用 |
+| --- | --- |
+| `pdf_info` | 页数、印刷页↔物理页偏移、目录/TOC |
+| `pdf_search` | 字面全文搜索；返回页码和摘要 |
+| `pdf_read_pages` | 读取指定页的文本，也可返回页面图片 |
+
+## 安装
+
+1. DSH 的 **Plugins → Add plugin** 输入 `dsh-book-reader`（或命令行 `dsh plugin add dsh-book-reader`）。
+2. 安装或升级后重启 DSH。
+3. 可选：把 skill 软链到工作区，让模型拿到阅读流程说明：
+
+   ```sh
+   ln -sfn "<已安装的包目录>" "<workspace>/.dsh/skills/pdf-reader"
+   ```
+
+## 配置
+
+全部可选，默认值即安全值。常用：
+
+- `rememberView`（默认 `true`）—— 按书记住页码/缩放。
+- `maxPagesPerCall`（默认 `4`）—— 单次读页上限。
+- `defaultScale`（默认 `2.5`）—— 图片渲染倍率。
+- `autoShare`（默认 `true`）—— AI 位置提示。
+
+完整键和默认值见 [`cordis.patch.yml`](cordis.patch.yml) 注释。
+
+## 说明
+
+- 只支持官方 PDF 预览；工具栏依赖该预览的私有 DOM 标记，DSH 升级可能影响行为。
+- 工具默认只在会话工作区内读取（可设 `allowOutsideWorkspace`）；本地 HTTP 路由只认回环地址、无鉴权。
+- 扫描件没有文本层，只能看图（没有 OCR）。
+- `pdfjs-dist` 锁定 `6.3.289`，以和宿主进程一致。
+
+## 更多
+
+[`SKILL.md`](SKILL.md) —— 模型使用手册 · [`CHANGELOG.md`](CHANGELOG.md) · [`LICENSE`](LICENSE)（MIT）

package/cordis.patch.yml

@@ -1,8 +1,9 @@
 # dsh-book-reader bundle patch: mount the plugin into the active profile.
 # Host half: pdf_info / pdf_search / pdf_read_pages tools,
-#            /dsh-book-reader/* routes, and a minimal per-turn reading-position
-#            line injected through agent/pre-step.
-# Browser half: page readout, jump, search panel, and share-to-chat on top of
+#            /dsh-pdf-reader/* routes (PDF info/search, reading position, saved
+#            page/zoom), and a minimal per-turn reading-position line injected
+#            through agent/pre-step.
+# Browser half: page readout, jump, search panel, remembered page/zoom on top of
 #               the official PDF preview's document-header slot.
 #
 # All config keys are optional. The defaults shown are the shipped behavior.
@@ -11,6 +12,7 @@
       name: 'dsh-book-reader'
       # config:
       #   enabled: true
+      #   rememberView: true              # remember last page + zoom per book
       #   autoShare: true                 # false stops position hints
       #   autoShareSection: true          # include the outline section in the line
       #   autoShareMinIntervalMs: 0       # optional: min ms between hints (0 = no time throttle)

package/lib/client.js

@@ -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)
@@ -267,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.
      *
@@ -300,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.
@@ -805,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)
@@ -983,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)
@@ -1254,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(() => {
@@ -1745,25 +2252,30 @@ window.__ModuleLoader__.load({
       PANEL_STYLE,
       buildSearchReference,
       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,

package/lib/index.js

@@ -19,6 +19,7 @@
  */
 
 import { basename, isAbsolute, relative, resolve as resolvePath, sep } from 'node:path'
+import { createHash } from 'node:crypto'
 import { appendFileSync } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import z from '@deepseek-ai/schemastery'
@@ -51,6 +52,8 @@ const PAGE_SELECTION_HARD_LIMIT = 256
 export const Config = z.object({
   /** Master switch: false mounts no tool, route, or listener. */
   enabled: z.boolean().default(true),
+  /** Remember page/zoom per PDF and restore on reopen. */
+  rememberView: z.boolean().default(true),
   /** Inject the current reading page into `agent/pre-step`, at most once per turn. */
   autoShare: z.boolean().default(true),
   /** Resolve the outline section for the injected message (one cached getInfo). */
@@ -94,6 +97,7 @@ export const Config = z.object({
 /** Defaults applied independently of the loader, so direct callers work too. */
 export const DEFAULT_CONFIG = Object.freeze({
   enabled: true,
+  rememberView: true,
   autoShare: true,
   autoShareSection: true,
   autoShareMinIntervalMs: 0,
@@ -166,6 +170,7 @@ export function normalizeConfig(raw) {
   if (typeof source !== 'object' || Array.isArray(source)) throw new TypeError('pdf-reader: config must be an object')
   return {
     enabled: configBoolean(source.enabled, DEFAULT_CONFIG.enabled, 'enabled'),
+    rememberView: configBoolean(source.rememberView, DEFAULT_CONFIG.rememberView, 'rememberView'),
     autoShare: configBoolean(source.autoShare, DEFAULT_CONFIG.autoShare, 'autoShare'),
     autoShareSection: configBoolean(source.autoShareSection, DEFAULT_CONFIG.autoShareSection, 'autoShareSection'),
     autoShareMinIntervalMs: configInteger(
@@ -416,6 +421,233 @@ export function createPositionStore({ now = Date.now, maxSessions = 200, maxPath
   }
 }
 
+// ---------------------------------------------------------------------------
+// Remembered page/zoom view state
+// ---------------------------------------------------------------------------
+
+/** Durable storage-domain name for remembered book views. */
+export const VIEW_DOMAIN_NAME = 'book_reader_views'
+
+/** Format version of {@link VIEW_DOMAIN_NAME}; bump only with a migration. */
+export const VIEW_DOMAIN_VERSION = 1
+
+/** Table holding one remembered view per book inside {@link VIEW_DOMAIN_NAME}. */
+export const VIEW_TABLE_NAME = 'views'
+
+/** Hard cap on remembered books; the oldest records are pruned past this. */
+export const MAX_VIEW_RECORDS = 500
+
+/** Longest accepted book path in a `/view` request. */
+export const MAX_VIEW_PATH_LENGTH = 4096
+
+/** Hard ceiling for a remembered PDF page number. */
+export const MAX_VIEW_PAGE = 100_000
+
+/** The only accepted zoom modes (mirrors the client's toolbar). */
+export const VIEW_ZOOM_MODES = Object.freeze(['fit-width', 'fixed'])
+
+/** Smallest accepted zoom ratio. */
+export const VIEW_ZOOM_SCALE_MIN = 0.25
+
+/** Largest accepted zoom ratio. */
+export const VIEW_ZOOM_SCALE_MAX = 4
+
+/**
+ * Stable storage key for one book: sha256 hex of the absolute path.
+ * @param path - normalized absolute `.pdf` path.
+ * @returns 64 lowercase hex characters.
+ */
+export function viewKeyForPath(path) {
+  return createHash('sha256').update(path, 'utf8').digest('hex')
+}
+
+/**
+ * Declarative zod schema for one remembered view.
+ *
+ * The schema is the durable-boundary validator of the storage domain. The
+ * HTTP route validates requests itself, so this stays purely declarative and
+ * needs no zod call at request time.
+ * @param zod - the dynamically imported zod module namespace.
+ * @returns a zod object schema matching the `/view` record contract.
+ */
+export function viewRecordSchema(zod) {
+  return zod.object({
+    path: zod.string().min(1).max(MAX_VIEW_PATH_LENGTH),
+    pdfPage: zod.number().int().min(1).max(MAX_VIEW_PAGE),
+    zoomMode: zod.enum([...VIEW_ZOOM_MODES]),
+    zoomScale: zod.number().min(VIEW_ZOOM_SCALE_MIN).max(VIEW_ZOOM_SCALE_MAX),
+    updatedAt: zod.number().int().nonnegative(),
+  })
+}
+
+/**
+ * Build the `book_reader_views` domain declaration.
+ *
+ * `zod` and the domain helpers are imported dynamically so this module still
+ * loads where the storage packages are absent; callers must handle rejection.
+ * @returns the domain spec understood by `ctx.storageDomain.open`.
+ */
+export async function createViewDomainSpec() {
+  const [{ defineDomain, domainTable }, { z: zod }] = await Promise.all([
+    import('@deepseek-ai/dsh-storage-domain'),
+    import('zod'),
+  ])
+  return defineDomain({
+    name: VIEW_DOMAIN_NAME,
+    version: VIEW_DOMAIN_VERSION,
+    layout: 'single',
+    tables: {
+      [VIEW_TABLE_NAME]: domainTable(viewRecordSchema(zod)),
+    },
+  })
+}
+
+/**
+ * Open the remembered-view domain through the injected `storageDomain` service.
+ * @param storageDomain - the `ctx.storageDomain` facility (DomainFacility).
+ * @returns the opened domain handle; the caller owns `close()`.
+ * @throws when the service, the modules, or `open` itself are unavailable.
+ */
+export async function openViewStateDomain(storageDomain) {
+  if (storageDomain === null || typeof storageDomain !== 'object' || typeof storageDomain.open !== 'function') {
+    throw new TypeError('pdf-reader: storageDomain service is unavailable')
+  }
+  const spec = await createViewDomainSpec()
+  const domain = await storageDomain.open(spec)
+  if (domain === null || typeof domain !== 'object' || typeof domain.table !== 'function') {
+    throw new TypeError('pdf-reader: storageDomain.open returned no domain')
+  }
+  return domain
+}
+
+/** Whether one stored value is a usable view record for the requested path. */
+function isViewRecordFor(record, path) {
+  if (typeof path !== 'string' || path.length === 0 || path.length > MAX_VIEW_PATH_LENGTH) return false
+  if (record === null || typeof record !== 'object') return false
+  if (record.path !== path) return false
+  if (!Number.isInteger(record.pdfPage) || record.pdfPage < 1 || record.pdfPage > MAX_VIEW_PAGE) return false
+  if (record.zoomMode !== 'fit-width' && record.zoomMode !== 'fixed') return false
+  if (typeof record.zoomScale !== 'number' || !Number.isFinite(record.zoomScale)) return false
+  if (record.zoomScale < VIEW_ZOOM_SCALE_MIN || record.zoomScale > VIEW_ZOOM_SCALE_MAX) return false
+  if (!Number.isInteger(record.updatedAt) || record.updatedAt < 0) return false
+  return true
+}
+
+/** Project one stored record to the exact client-facing shape. */
+function publicViewRecord(record) {
+  return {
+    path: record.path,
+    pdfPage: record.pdfPage,
+    zoomMode: record.zoomMode,
+    zoomScale: record.zoomScale,
+    updatedAt: record.updatedAt,
+  }
+}
+
+/**
+ * Delete the least recently updated records once the table exceeds the cap.
+ * Best-effort: pruning never rejects an already-durable write.
+ * @param table - an open domain table handle.
+ */
+async function pruneViewTable(table) {
+  try {
+    if (table.size <= MAX_VIEW_RECORDS) return
+    const excess = table.size - MAX_VIEW_RECORDS
+    const oldest = [...table.entries()]
+      .sort((left, right) => {
+        const leftAt = Number.isFinite(left[1]?.updatedAt) ? left[1].updatedAt : 0
+        const rightAt = Number.isFinite(right[1]?.updatedAt) ? right[1].updatedAt : 0
+        return leftAt - rightAt
+      })
+      .slice(0, excess)
+    for (const [key] of oldest) await table.delete(key)
+  } catch {
+    // The record is already durable; a failed prune is not a failed write.
+  }
+}
+
+/**
+ * Route-facing adapter over the opened `book_reader_views` domain.
+ *
+ * `apply()` attaches the table once storage is open and detaches it on
+ * unload. Until then (or forever, when storage is unavailable) `read()`
+ * answers `null` and `write()` answers `false`, so routes degrade without
+ * throwing. Every failure is contained here and reported to `warn` once.
+ * @param options - warning sink; defaults to `console.warn`.
+ * @returns a mutable adapter read by the route handler.
+ */
+export function createViewStateAdapter({ warn = console.warn } = {}) {
+  let table = null
+  let warned = false
+
+  function warnOnce(message, error) {
+    if (warned) return
+    warned = true
+    try {
+      const detail = error instanceof Error ? `: ${error.message}` : ''
+      warn(`dsh-pdf-reader: ${message}${detail}`)
+    } catch {
+      // A broken logger must not break plugin loading or routing.
+    }
+  }
+
+  return {
+    /** Whether an open domain table is currently attached. */
+    get available() {
+      return table !== null
+    },
+    /** Attach the table of a successfully opened domain. */
+    attach(nextTable) {
+      table = nextTable ?? null
+    },
+    /** Detach on unload so in-flight routes degrade instead of throwing. */
+    detach() {
+      table = null
+    },
+    /** Emit at most one warning for this adapter. */
+    warnOnce,
+    /**
+     * Read the remembered view for one normalized absolute path.
+     * @returns the public record, or `null` when absent/unavailable/invalid.
+     */
+    async read(path) {
+      const current = table
+      if (current === null) return null
+      try {
+        const record = current.get(viewKeyForPath(path))
+        if (!isViewRecordFor(record, path)) return null
+        return publicViewRecord(record)
+      } catch (error) {
+        warnOnce('could not read the remembered page/zoom', error)
+        return null
+      }
+    },
+    /**
+     * Persist one complete view record (key hashed from `record.path`).
+     * @returns true when durable, false when storage is unavailable/failed.
+     */
+    async write(record) {
+      const current = table
+      if (current === null) return false
+      try {
+        const value = {
+          path: record.path,
+          pdfPage: record.pdfPage,
+          zoomMode: record.zoomMode,
+          zoomScale: record.zoomScale,
+          updatedAt: Number.isInteger(record.updatedAt) ? record.updatedAt : Date.now(),
+        }
+        await current.put(viewKeyForPath(value.path), value)
+        await pruneViewTable(current)
+        return true
+      } catch (error) {
+        warnOnce('could not remember the page/zoom', error)
+        return false
+      }
+    },
+  }
+}
+
 /** Normalize unicode dashes so a pasted page range parses. */
 function normalizeDashes(value) {
   return value.replace(/[\u2010-\u2015\u2212]/gu, '-')
@@ -1075,8 +1307,33 @@ function createLazyCore() {
   }
 }
 
+/**
+ * Validate a `/view` book path without touching the filesystem.
+ *
+ * The remembered-view route deliberately does not stat the PDF: the client
+ * may report a state for a book whose preview is still opening, and restoring
+ * a missing book's state is harmless. The shape and size checks still mirror
+ * the rest of the route surface.
+ * @param rawPath - the raw query/body `path` value.
+ * @returns the normalized absolute path, or `null` when invalid.
+ */
+function validateViewPath(rawPath) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0 || rawPath.length > MAX_VIEW_PATH_LENGTH) return null
+  if (!isAbsolute(rawPath)) return null
+  const path = resolvePath(rawPath)
+  if (!/\.pdf$/iu.test(path)) return null
+  return path
+}
+
 /** Build the route handler. Exported so tests can use fake core and stat. */
-export function createRouteHandler({ config, pdfCore, infoCache, positions, statFile = stat }) {
+export function createRouteHandler({
+  config,
+  pdfCore,
+  infoCache,
+  positions,
+  statFile = stat,
+  views = createViewStateAdapter(),
+}) {
   async function loadPositionFor(sessionId, path) {
     if (typeof sessionId === 'string' && sessionId !== '') {
       return positions.forSession(sessionId)
@@ -1286,6 +1543,97 @@ export function createRouteHandler({ config, pdfCore, infoCache, positions, stat
       return
     }
 
+    if (url.pathname === `${ROUTE_PATH}/view`) {
+      const rememberView = config.rememberView !== false
+      if (method === 'GET') {
+        const path = validateViewPath(url.searchParams.get('path') ?? '')
+        if (path === null) {
+          sendJson(response, 400, { ok: false, error: 'invalid-path' })
+          return
+        }
+        // Disabled remembering and unavailable storage both answer the same
+        // non-blocking shape, so restoring a book never fails the preview.
+        if (!rememberView) {
+          sendJson(response, 200, { ok: true, view: null })
+          return
+        }
+        let view = null
+        try {
+          view = await views.read(path)
+        } catch {
+          view = null
+        }
+        sendJson(response, 200, { ok: true, view: view ?? null })
+        return
+      }
+
+      if (method === 'POST') {
+        const contentType = String(request.headers['content-type'] ?? '').toLowerCase()
+        if (!contentType.startsWith('application/json')) {
+          sendJson(response, 415, { ok: false, error: 'unsupported-media-type' })
+          return
+        }
+        let body
+        try {
+          body = await readJsonBody(request, config.maxRouteBodyBytes)
+        } catch (error) {
+          const status = Number.isInteger(error?.status) ? error.status : 400
+          sendJson(response, status, { ok: false, error: error?.error ?? 'invalid-body' })
+          return
+        }
+        const path = validateViewPath(body.path)
+        if (path === null) {
+          sendJson(response, 400, { ok: false, error: 'invalid-path' })
+          return
+        }
+        if (!Number.isInteger(body.pdfPage) || body.pdfPage < 1 || body.pdfPage > MAX_VIEW_PAGE) {
+          sendJson(response, 400, { ok: false, error: 'invalid-page' })
+          return
+        }
+        if (body.zoomMode !== 'fit-width' && body.zoomMode !== 'fixed') {
+          sendJson(response, 400, { ok: false, error: 'invalid-zoom-mode' })
+          return
+        }
+        if (
+          typeof body.zoomScale !== 'number' ||
+          !Number.isFinite(body.zoomScale) ||
+          body.zoomScale < VIEW_ZOOM_SCALE_MIN ||
+          body.zoomScale > VIEW_ZOOM_SCALE_MAX
+        ) {
+          sendJson(response, 400, { ok: false, error: 'invalid-zoom-scale' })
+          return
+        }
+        // Remembering may be disabled while previews still talk to the route:
+        // validation stays complete, the write becomes a deliberate no-op.
+        if (!rememberView) {
+          sendJson(response, 200, { ok: true })
+          return
+        }
+        let stored = false
+        try {
+          stored =
+            (await views.write({
+              path,
+              pdfPage: body.pdfPage,
+              zoomMode: body.zoomMode,
+              zoomScale: body.zoomScale,
+              updatedAt: Date.now(),
+            })) === true
+        } catch {
+          stored = false
+        }
+        if (!stored) {
+          sendJson(response, 503, { ok: false, error: 'storage-unavailable' })
+          return
+        }
+        sendJson(response, 200, { ok: true })
+        return
+      }
+
+      sendJson(response, 405, { ok: false, error: 'method-not-allowed' })
+      return
+    }
+
     sendJson(response, 404, { ok: false, error: 'not-found' })
   }
 
@@ -1807,6 +2155,7 @@ export function apply(ctx, rawConfig) {
     limit: config.infoCacheSize,
   })
   const positions = createPositionStore()
+  const views = createViewStateAdapter()
 
   const routeHandler = createRouteHandler({
     config,
@@ -1814,6 +2163,7 @@ export function apply(ctx, rawConfig) {
     infoCache,
     positions,
     statFile: stat,
+    views,
   })
   ctx.effect(
     () => ctx.webServer.register({ kind: 'prefix', path: ROUTE_PATH, handler: routeHandler }),
@@ -1843,6 +2193,53 @@ export function apply(ctx, rawConfig) {
     )
   })
 
+  if (config.rememberView) {
+    ctx.inject(['storageDomain'], (storageCtx) => {
+      let disposed = false
+      let domain = null
+
+      async function closeDomain() {
+        const handle = domain
+        domain = null
+        if (handle === null) return
+        try {
+          await handle.close()
+        } catch (error) {
+          views.warnOnce('remembered page/zoom storage did not close cleanly', error)
+        }
+      }
+
+      // Opening is asynchronous while the route is already answering: the
+      // adapter stays unavailable until attach(), and reverts to unavailable
+      // on unload. Every failure leaves the feature disabled, never thrown.
+      const opening = (async () => {
+        try {
+          domain = await openViewStateDomain(storageCtx.storageDomain)
+        } catch (error) {
+          views.warnOnce('remembered page/zoom storage is unavailable', error)
+          return
+        }
+        if (disposed) {
+          await closeDomain()
+          return
+        }
+        try {
+          views.attach(domain.table(VIEW_TABLE_NAME))
+        } catch (error) {
+          views.warnOnce('remembered page/zoom storage is unavailable', error)
+          await closeDomain()
+        }
+      })()
+
+      return async () => {
+        disposed = true
+        views.detach()
+        await opening
+        await closeDomain()
+      }
+    })
+  }
+
   if (config.autoShare) {
     const listener = createAutoShareListener({ config, positions, infoCache })
     ctx.on('agent/pre-step', listener, { prepend: true })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-book-reader",
-  "version": "0.1.1",
-  "description": "Read books and papers in DSH: a reading toolbar on the official PDF preview, plus PDF tools for the model (page map, full-text search, page text and images).",
+  "version": "0.2.0",
+  "description": "Read books and papers in DSH: a reading toolbar on the official PDF preview that remembers your page and zoom, plus PDF tools for the model (page map, full-text search, page text and images).",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -32,18 +32,26 @@
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-tools": "^0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.4"
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "zod": "^4.4.3"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-llm": {
       "optional": true
     },
+    "@deepseek-ai/dsh-storage-domain": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-tools": {
       "optional": true
     },
     "@deepseek-ai/schemastery": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "main": "lib/index.js",
@@ -66,6 +74,7 @@
     "SKILL.md",
     "cordis.patch.yml",
     "README.md",
+    "README.zh-CN.md",
     "LICENSE",
     "icon.svg",
     "locale/*.json",