dsh-book-reader 0.2.0 → 0.3.1

package/lib/index.js

@@ -828,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') {
@@ -1199,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,
@@ -1233,7 +1246,11 @@ export function renderPageReadContent(value) {
       type: 'text',
       text: `<page pdf="${page.pdf}" printed="${page.printed}">\n${body}${truncation}\n</page>`,
     })
-    blocks.push({ type: 'image', attachment: imageRefFromValue(page.image) })
+    // Text-only reads (include_image:false) never carry an image; emitting an
+    // image block for them crashed output.render on page.image.attachmentId.
+    if (page.image !== undefined) {
+      blocks.push({ type: 'image', attachment: imageRefFromValue(page.image) })
+    }
   }
   return blocks
 }
@@ -1432,13 +1449,12 @@ export function createRouteHandler({
         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')
@@ -1460,8 +1476,17 @@ export function createRouteHandler({
           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',
@@ -1679,6 +1704,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 [
@@ -1788,16 +1859,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: {
@@ -1811,6 +1902,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,
@@ -1834,13 +1932,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),
@@ -1852,6 +1988,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,
         }
       },
@@ -1952,7 +2089,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' },
@@ -1970,11 +2107,17 @@ export function createReadPagesTool({ defineTool: makeTool, ctx, config, core, i
       const path = resolveToolPath(args.path, exec)
         assertInsideWorkspace(path, exec, config)
       const targetStat = await assertPdfFile(path, { statFile, maxFileBytes: config.maxFileBytes })
-      const attachments = ctx.get('attachments')
-      if (attachments === undefined) {
-        throw codedError('cannot read PDF pages as images: no attachment service is mounted', 'PDF_READER_NO_ATTACHMENTS')
+      // Images need the attachment store and an image-capable route; a
+      // text-only read needs neither and must keep working without them.
+      const includeImage = args.include_image !== false
+      let attachments
+      if (includeImage) {
+        attachments = ctx.get('attachments')
+        if (attachments === undefined) {
+          throw codedError('cannot read PDF pages as images: no attachment service is mounted', 'PDF_READER_NO_ATTACHMENTS')
+        }
+        await assertImageCapableRoute(ctx, exec, path)
       }
-      await assertImageCapableRoute(ctx, exec, path)
       const info = (await infoCache.load(path, targetStat)).info
       const resolved = resolveRequestedPages({
         selection: args.pages,
@@ -1982,7 +2125,6 @@ export function createReadPagesTool({ defineTool: makeTool, ctx, config, core, i
         info,
         maxPages: config.maxPagesPerCall,
       })
-      const includeImage = args.include_image !== false
       if (!includeImage) {
         const book = titleFromPath(path)
         const includeText = args.include_text !== false && config.maxTextCharsPerPage > 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-book-reader",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",