dsh-book-reader 0.1.1 → 0.3.0

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, '-')
@@ -596,8 +828,8 @@ export function printedPageFor(info, pdfPage, reported = null) {
  * @param options - selection, explicit mode, `getInfo` result, and page cap.
  * @returns physical pages, the resolved mode, and the offset used.
  */
-export function resolveRequestedPages({ selection, pageNumbers, info, maxPages = DEFAULT_CONFIG.maxPagesPerCall }) {
-  const requested = parsePageSelection(selection, { maxPages })
+export function resolveRequestedPages({ selection, pageNumbers, info, maxPages = DEFAULT_CONFIG.maxPagesPerCall, hardLimit = PAGE_SELECTION_HARD_LIMIT }) {
+  const requested = parsePageSelection(selection, { maxPages, hardLimit })
   const detected = detectPageMode(info)
   const mode = pageNumbers ?? (detected.detectable ? 'printed' : 'pdf')
   if (mode !== 'printed' && mode !== 'pdf') {
@@ -967,6 +1199,19 @@ const PRINTED_PAGE_SCHEMA = {
   oneOf: [{ type: 'integer' }, { type: 'string' }, { type: 'null' }],
 }
 
+/**
+ * DSH's JsonSchema dialect marks a property required with `required: true`; a
+ * property that may be absent simply omits `required`. `required: false` is
+ * rejected by defineTool at registration time.
+ *
+ * `IMAGE_VALUE_SCHEMA` is required where it is used for a present image, so an
+ * optional use must drop that marker instead of overriding it to false.
+ */
+function optionalPropertySchema(schema) {
+  const { required: _required, ...rest } = schema
+  return rest
+}
+
 const SECTION_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -1075,8 +1320,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)
@@ -1175,13 +1445,12 @@ export function createRouteHandler({ config, pdfCore, infoCache, positions, stat
         sendJson(response, target.status, { ok: false, error: target.error })
         return
       }
-      const query = (url.searchParams.get('q') ?? '').trim()
-      if (query === '') {
-        sendJson(response, 400, { ok: false, error: 'missing-query' })
-        return
-      }
-      if (query.length > 1000) {
-        sendJson(response, 400, { ok: false, error: 'query-too-long' })
+      let query
+      try {
+        query = cleanPdfSearchQuery(url.searchParams.get('q') ?? '')
+      } catch (error) {
+        const tooLong = error instanceof RangeError
+        sendJson(response, 400, { ok: false, error: tooLong ? 'query-too-long' : 'missing-query' })
         return
       }
       const rawLimit = url.searchParams.get('limit')
@@ -1203,8 +1472,17 @@ export function createRouteHandler({ config, pdfCore, infoCache, positions, stat
           printed: hit.printed ?? null,
           snippet: String(hit.snippet ?? ''),
         }))
-        sendJson(response, 200, { ok: true, hits })
+        const mode = ['phrase', 'compact', 'terms'].includes(result?.mode) ? result.mode : 'phrase'
+        sendJson(response, 200, { ok: true, mode, hits })
       } catch (error) {
+        if (
+          error?.code === 'PDF_SEARCH_QUERY_TOO_LONG' ||
+          (error instanceof TypeError && /query must be a non-empty string/u.test(error.message))
+        ) {
+          const tooLong = error?.code === 'PDF_SEARCH_QUERY_TOO_LONG'
+          sendJson(response, 400, { ok: false, error: tooLong ? 'query-too-long' : 'missing-query' })
+          return
+        }
         sendJson(response, 500, {
           ok: false,
           error: 'search-failed',
@@ -1286,6 +1564,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' })
   }
 
@@ -1331,6 +1700,52 @@ export function trimPageText(raw, maxChars) {
   return { text: normalized.slice(0, maxChars), truncated: true, unavailable: false }
 }
 
+/** Longest search query accepted after wrapper/whitespace cleanup. */
+const MAX_SEARCH_QUERY_LENGTH = 1000
+
+/** Whole-query wrappers the model may add around a search query. */
+const SEARCH_QUERY_WRAPPERS = [
+  ['"', '"'],
+  ["'", "'"],
+  ['“', '”'],
+  ['‘', '’'],
+  ['`', '`'],
+  ['$', '$'],
+]
+
+/**
+ * Tool/route-side search-query cleanup: trim, strip a pair of wrapping
+ * quotes/backticks/`$…$`, collapse whitespace, and reject empty/over-long
+ * input.  Mirrors `cleanSearchQuery()` in core/pdf.js; kept local because the
+ * PDF core is imported lazily, only when a PDF operation actually runs.
+ *
+ * @param {unknown} raw
+ * @returns {string}
+ */
+function cleanPdfSearchQuery(raw) {
+  if (typeof raw !== 'string') throw new TypeError('query must be a non-empty string')
+
+  let query = raw.trim()
+  let stripped = true
+  while (stripped && query.length >= 2) {
+    stripped = false
+    for (const [open, close] of SEARCH_QUERY_WRAPPERS) {
+      if (query.startsWith(open) && query.endsWith(close)) {
+        query = query.slice(open.length, query.length - close.length).trim()
+        stripped = true
+        break
+      }
+    }
+  }
+
+  query = query.replace(/\s+/gu, ' ').trim()
+  if (query === '') throw new TypeError('query must be a non-empty string')
+  if (query.length > MAX_SEARCH_QUERY_LENGTH) {
+    throw new RangeError(`query is longer than ${MAX_SEARCH_QUERY_LENGTH} characters`)
+  }
+  return query
+}
+
 /** Register `pdf_info` and `pdf_search`. */
 export function createCheapTools({ defineTool: makeTool, config, core, infoCache, statFile = stat }) {
   return [
@@ -1440,16 +1855,36 @@ export function createCheapTools({ defineTool: makeTool, config, core, infoCache
     makeTool({
       name: 'pdf_search',
       description:
-        'Search a PDF\'s text layer; returns page numbers and snippets. Text only, cheap.',
+        'Search a PDF\'s text layer; returns page numbers, snippets, and the matching mode. Literal-ish search over normalized text: case-insensitive by default, tolerant of wrapping quotes/backticks and `$…$` LaTeX markup, hyphen/space-insensitive fallback, then term-AND fallback when no literal match. Body pages rank before front matter. Pass `pages` to restrict the scan to a page range (printed pages by default), e.g. when reading a later chapter. Text only, cheap.',
       parameters: {
         path: {
           type: 'string',
           required: true,
           description: 'Absolute .pdf path (relative resolves against the session directory).',
         },
-        query: { type: 'string', required: true, description: 'Literal text to search for.' },
+        query: {
+          type: 'string',
+          required: true,
+          description:
+            'Text or formula to find. Wrapping quotes/backticks/$…$ are stripped; use a distinctive phrase.',
+        },
+        pages: {
+          description:
+            'Optional 1-based pages to search within: "132-140", "132,135", 132, or [132,133]. Interpreted as printed numbers when the PDF has an offset, unless page_numbers is "pdf". Use it to scope a search to the chapter the user is reading.',
+          oneOf: [
+            { type: 'integer' },
+            { type: 'string' },
+            { type: 'array', items: { oneOf: [{ type: 'integer' }, { type: 'string' }] } },
+          ],
+        },
+        page_numbers: {
+          type: 'string',
+          enum: ['printed', 'pdf'],
+          description:
+            'How to interpret `pages`. Defaults to "printed" when the PDF exposes numeric printed-page labels, otherwise "pdf".',
+        },
         ignore_case: { type: 'boolean', description: 'Case-insensitive search. Defaults to true.' },
-        limit: { type: 'integer', description: 'Maximum hits to return. Defaults to 20; capped by plugin config.' },
+        limit: { type: 'integer', description: 'Maximum hits to return. Defaults to 30; capped by plugin config.' },
       },
       output: {
         schema: {
@@ -1463,6 +1898,13 @@ export function createCheapTools({ defineTool: makeTool, config, core, infoCache
               required: true,
               description: 'Number of pages with at least one hit; may exceed the returned hit count when limit truncates.',
             },
+            mode: {
+              type: 'string',
+              enum: ['phrase', 'compact', 'terms'],
+              required: true,
+              description:
+                'Which pass produced the hits: literal phrase, space-insensitive, or all-terms.',
+            },
             hits: {
               type: 'array',
               required: true,
@@ -1486,13 +1928,51 @@ export function createCheapTools({ defineTool: makeTool, config, core, infoCache
       async execute(args, exec) {
         const path = resolveToolPath(args.path, exec)
         assertInsideWorkspace(path, exec, config)
-        const query = typeof args.query === 'string' ? args.query.trim() : ''
-        if (query === '') throw codedError('query must be a non-empty string', 'PDF_READER_INVALID_QUERY')
-        if (query.length > 1000) throw codedError('query is longer than 1000 characters', 'PDF_READER_INVALID_QUERY')
+        let query
+        try {
+          query = cleanPdfSearchQuery(args.query)
+        } catch (error) {
+          throw codedError(
+            error instanceof Error ? error.message : String(error),
+            'PDF_READER_INVALID_QUERY',
+          )
+        }
         await assertPdfFile(path, { statFile, maxFileBytes: config.maxFileBytes })
-        const limit = Math.max(1, Math.min(Number.isInteger(args.limit) ? args.limit : 20, config.maxSearchResults))
+        const limit = Math.max(1, Math.min(Number.isInteger(args.limit) ? args.limit : 30, config.maxSearchResults))
         const ignoreCase = args.ignore_case !== false
-        const result = await core.searchPdf(path, query, { ignoreCase, limit })
+        let pdfPages
+        if (args.pages !== undefined) {
+          const info = (await infoCache.load(path)).info
+          const pageCount = Number.isInteger(info?.pageCount) && info.pageCount > 0
+            ? info.pageCount
+            : PAGE_SELECTION_HARD_LIMIT
+          const resolved = resolveRequestedPages({
+            selection: args.pages,
+            pageNumbers: args.page_numbers,
+            info,
+            maxPages: pageCount,
+            hardLimit: Math.max(PAGE_SELECTION_HARD_LIMIT, pageCount),
+          })
+          pdfPages = resolved.pdfPages
+        }
+        let result
+        try {
+          result = await core.searchPdf(path, query, {
+            ignoreCase,
+            limit,
+            ...(pdfPages === undefined ? {} : { pdfPages }),
+          })
+        } catch (error) {
+          // Cleanup above already rejects ordinary empties; core also rejects a
+          // query that normalization erases entirely (e.g. "---").
+          if (
+            error?.code === 'PDF_SEARCH_QUERY_TOO_LONG' ||
+            (error instanceof TypeError && /query must be a non-empty string/u.test(error.message))
+          ) {
+            throw codedError(error.message, 'PDF_READER_INVALID_QUERY')
+          }
+          throw error
+        }
         const rawHits = Array.isArray(result?.hits) ? result.hits : []
         const hits = rawHits.slice(0, limit).map((hit) => ({
           pdf: Number(hit.pdf),
@@ -1504,6 +1984,7 @@ export function createCheapTools({ defineTool: makeTool, config, core, infoCache
           path,
           query,
           pages: Number.isInteger(result?.pages) ? result.pages : new Set(hits.map((hit) => hit.pdf)).size,
+          mode: ['phrase', 'compact', 'terms'].includes(result?.mode) ? result.mode : 'phrase',
           hits,
         }
       },
@@ -1604,7 +2085,7 @@ export function createReadPagesTool({ defineTool: makeTool, ctx, config, core, i
                 pdf: { type: 'integer', required: true },
                 printed: { oneOf: [{ type: 'integer' }, { type: 'string' }], required: true },
                 tokens: { type: 'integer' },
-                image: { ...IMAGE_VALUE_SCHEMA, required: false },
+                image: optionalPropertySchema(IMAGE_VALUE_SCHEMA),
                 text: { type: 'string' },
                 textTruncated: { type: 'boolean' },
                 textUnavailable: { type: 'boolean' },
@@ -1807,6 +2288,7 @@ export function apply(ctx, rawConfig) {
     limit: config.infoCacheSize,
   })
   const positions = createPositionStore()
+  const views = createViewStateAdapter()
 
   const routeHandler = createRouteHandler({
     config,
@@ -1814,6 +2296,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 +2326,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 })