读 PDF 脚本的维护记录：引擎实测与吸收的两个 DSH 插件

/**
 * Worker-thread entry for PDF conversion. Runs `@firecrawl/pdf-inspector`'s
 * WASM build, whose `processPdf` is synchronous, off the main event loop;
 * the parent terminates the worker to cancel. This module is executed by
 * Node directly (never bundled into the plugin entry), so it stays free of
 * TypeScript-only runtime syntax and imports nothing from the plugin.
 * @module @jiaoqsh/dsh-document/pdf-worker
 */

import { readFileSync } from 'node:fs'
import { createRequire } from 'node:module'
import { parentPort, workerData } from 'node:worker_threads'
import { initSync, processPdf } from '@firecrawl/pdf-inspector-wasm'
import type { MarkdownProfile } from '@firecrawl/pdf-inspector-wasm'

/** What the parent posts as `workerData`. */
export interface PdfWorkerRequest {
  bytes: Uint8Array
  /** 1-based pages to convert; absent means all. */
  pages?: number[]
  profile: MarkdownProfile
}

/** The engine facts the parent needs; everything else stays in the worker. */
export interface PdfWorkerResult {
  markdown: string
  pdfType: 'TextBased' | 'Scanned' | 'ImageBased' | 'Mixed'
  pageCount: number
  /** 1-based. */
  pagesNeedingOcr: number[]
  title?: string
}

/** Worker → parent message. */
export type PdfWorkerReply =
  | { ok: true; result: PdfWorkerResult }
  | { ok: false; message: string }

const require = createRequire(import.meta.url)

function run(request: PdfWorkerRequest): PdfWorkerResult {
  initSync({
    module: readFileSync(require.resolve('@firecrawl/pdf-inspector-wasm/pdf_inspector_wasm_bg.wasm')),
  })
  const result = processPdf(new Uint8Array(request.bytes), {
    profile: request.profile,
    includePageMarkers: true,
    includeImages: false,
    ...(request.pages === undefined ? {} : { pages: request.pages }),
  })
  return {
    markdown: result.markdown ?? '',
    pdfType: result.pdfType,
    pageCount: result.pageCount,
    pagesNeedingOcr: result.pagesNeedingOcr,
    ...(result.title === undefined ? {} : { title: result.title }),
  }
}

if (parentPort !== null) {
  let reply: PdfWorkerReply
  try {
    reply = { ok: true, result: run(workerData as PdfWorkerRequest) }
  } catch (error: unknown) {
    reply = { ok: false, message: error instanceof Error ? error.message : String(error) }
  }
  parentPort.postMessage(reply)
}

/**
 * The pdf-inspector engine: PDF → Markdown with page selection, page markers,
 * and scanned-page facts. Each conversion runs in a fresh worker thread so a
 * large document never blocks the harness event loop, and cancellation
 * terminates the worker.
 * @module @jiaoqsh/dsh-document/pdf-inspector
 */

import { Worker } from 'node:worker_threads'
import type { MarkdownProfile } from '@firecrawl/pdf-inspector-wasm'
import {
  DocumentConversionError,
  type ConvertRequest,
  type ConvertResult,
  type DocumentConverter,
  type PdfKind,
} from './converter.ts'
import type { PdfWorkerReply, PdfWorkerRequest, PdfWorkerResult } from './pdf-worker.ts'

/** Deployment choices for the PDF engine. */
export interface PdfInspectorOptions {
  /** `fidelity` keeps source structure; `compact` spends fewer tokens. */
  profile: MarkdownProfile
}

const KIND: Record<PdfWorkerResult['pdfType'], PdfKind> = {
  TextBased: 'text',
  Scanned: 'scanned',
  ImageBased: 'image',
  Mixed: 'mixed',
}

// The worker file sits beside this module in both the source tree and the
// built lib/. A computed name keeps bundlers from rewriting the URL as an
// asset. Source mode exists only for tests: Node then strips the worker's
// types itself, and the flag makes that hold on every supported Node (it is
// the default from 22.18 and merely redundant there).
const WORKER_IS_SOURCE = import.meta.url.endsWith('.ts')
const WORKER_URL = new URL(WORKER_IS_SOURCE ? 'pdf-worker.ts' : 'pdf-worker.js', import.meta.url)
const WORKER_EXEC_ARGV = WORKER_IS_SOURCE
  ? [...process.execArgv, '--experimental-strip-types', '--no-warnings']
  : undefined

/** Classify an engine failure message; the engine reports plain strings, not codes. */
function engineError(message: string): DocumentConversionError {
  const text = message.replace(/^process PDF: /u, '')
  const lower = text.toLowerCase()
  if (lower.includes('not a pdf') || lower.includes('malformed') || lower.includes('invalid')) {
    return new DocumentConversionError(text, 'malformed')
  }
  if (lower.includes('encrypt') || lower.includes('password')) {
    return new DocumentConversionError(text, 'encrypted')
  }
  return new DocumentConversionError(text, 'unknown')
}

/**
 * Run one conversion in a worker and settle with its reply.
 * @param request - bytes, pages, and profile for the worker.
 * @param signal - terminates the worker when it fires.
 * @returns the worker's facts and Markdown.
 */
export function runPdfWorker(request: PdfWorkerRequest, signal: AbortSignal): Promise<PdfWorkerResult> {
  return new Promise<PdfWorkerResult>((resolve, reject) => {
    const worker = new Worker(WORKER_URL, {
      workerData: request,
      ...(WORKER_EXEC_ARGV === undefined ? {} : { execArgv: WORKER_EXEC_ARGV }),
    })
    let settled = false
    const settle = (outcome: () => void): void => {
      if (settled) return
      settled = true
      signal.removeEventListener('abort', onAbort)
      // Terminate is idempotent; after a normal reply it only reclaims the thread.
      void worker.terminate()
      outcome()
    }
    const onAbort = (): void => settle(() => reject(new DocumentConversionError('the conversion was cancelled', 'aborted')))
    signal.addEventListener('abort', onAbort, { once: true })
    worker.once('message', (reply: PdfWorkerReply) => settle(() => {
      if (reply.ok) resolve(reply.result)
      else reject(engineError(reply.message))
    }))
    worker.once('error', (error: Error) => settle(() => reject(new DocumentConversionError(error.message, 'unknown'))))
    worker.once('exit', (code: number) => settle(() => reject(
      new DocumentConversionError(`the PDF worker exited with code ${code} before replying`, 'unknown'),
    )))
  })
}

function formatPages(pages: readonly number[]): string {
  const sorted = [...pages].sort((a, b) => a - b)
  const parts: string[] = []
  for (let i = 0; i < sorted.length;) {
    let j = i
    while (j + 1 < sorted.length && sorted[j + 1] === sorted[j]! + 1) j += 1
    parts.push(j === i ? `${sorted[i]}` : `${sorted[i]}-${sorted[j]}`)
    i = j + 1
  }
  return parts.join(', ')
}

/**
 * Build the PDF engine.
 * @param options - deployment choices.
 * @returns a converter that handles only `pdf`.
 */
export function pdfInspectorConverter(options: PdfInspectorOptions): DocumentConverter {
  return {
    name: 'pdf-inspector',
    formats: ['pdf'],
    async convert({ bytes, pages, signal }: ConvertRequest): Promise<ConvertResult> {
      if (signal.aborted) throw new DocumentConversionError('the conversion was cancelled', 'aborted')
      const raw = await runPdfWorker({
        bytes,
        profile: options.profile,
        ...(pages === undefined ? {} : { pages: [...pages] }),
      }, signal)

      if (pages !== undefined) {
        const beyond = pages.filter(page => page > raw.pageCount)
        if (beyond.length > 0) {
          throw new DocumentConversionError(
            `the document has ${raw.pageCount} page${raw.pageCount === 1 ? '' : 's'}; requested page${beyond.length === 1 ? '' : 's'} ${formatPages(beyond)} ${beyond.length === 1 ? 'does' : 'do'} not exist`,
            'pageRange',
          )
        }
      }

      const kind = KIND[raw.pdfType]
      if (raw.markdown.trim().length === 0) {
        const plural = pages === undefined ? raw.pageCount !== 1 : pages.length !== 1
        const scope = pages === undefined
          ? `all ${raw.pageCount} page${plural ? 's' : ''}`
          : `the requested page${plural ? 's' : ''} (${formatPages(pages)})`
        const verb = plural ? 'contain' : 'contains'
        if (kind === 'scanned' || kind === 'image') {
          throw new DocumentConversionError(
            `${scope} ${verb} no extractable text: this is ${kind === 'image' ? 'an image-only' : 'a scanned'} PDF and needs OCR`,
            'scanned',
          )
        }
        if (raw.pagesNeedingOcr.length > 0) {
          throw new DocumentConversionError(
            `${scope} ${verb} no extractable text (pages needing OCR: ${formatPages(raw.pagesNeedingOcr)})`,
            'scanned',
          )
        }
        throw new DocumentConversionError('the document contains no extractable text', 'empty')
      }

      return {
        markdown: raw.markdown,
        pdf: {
          pageCount: raw.pageCount,
          kind,
          pagesNeedingOcr: raw.pagesNeedingOcr,
          ...(pages === undefined ? {} : { pages: [...pages] }),
          ...(raw.title === undefined ? {} : { title: raw.title }),
        },
      }
    },
  }
}

export { formatPages }

/**
 * The model-facing `read_document` tool: resolve a path through `ctx.fs`,
 * read the bytes under the input cap, convert them to Markdown through the
 * routed engine, and return one line-numbered window. PDFs additionally
 * accept a page selection and report page facts.
 * @module @jiaoqsh/dsh-document/tool
 */

import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-fs'
import type {} from '@deepseek-ai/dsh-system-prompt'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { GenericCallView, ToolExecution } from '@deepseek-ai/dsh-tools'
import {
  DOCUMENT_EXTENSIONS,
  DOCUMENT_FORMATS,
  DocumentConversionError,
  formatOf,
  type DocumentConverter,
  type DocumentFormat,
  type PdfFacts,
} from './converter.ts'
import { parsePages } from './pages.ts'
import { formatPages } from './pdf-inspector.ts'
import { windowLines, type WindowLine } from './window.ts'

/** Deployment bounds after defaulting (see `Config` in index.ts). */
export interface ReadDocumentCaps {
  /** Inclusive byte cap on the source file; larger files are refused before conversion. */
  maxInputBytes: number
  /** Default and maximum number of lines returned by one call. */
  readLimit: number
  /** Maximum characters returned for a single line. */
  maxLineLength: number
  /** Maximum bytes of line text returned by one call. */
  maxOutputBytes: number
  /** Maximum distinct PDF pages one `pages` selection may name. */
  pdfMaxPages: number
}

/** Canonical value of one successful call. */
export interface ReadDocumentOutcome {
  path: string
  format: DocumentFormat
  offset: number
  lines: WindowLine[]
  totalLines: number
  truncatedByBytes: boolean
  /** PDF facts; absent for other formats. */
  pdf?: PdfFacts
}

/** Validated arguments after defaulting. */
interface ReadInput {
  filePath: string
  offset: number
  limit: number
  pages?: number[]
}

const EXTENSION_LIST = DOCUMENT_EXTENSIONS.map(ext => `.${ext}`).join(', ')
const PDF_KINDS = ['text', 'scanned', 'image', 'mixed'] as const

function parsePositiveInteger(value: number, name: string): number {
  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) {
    throw new Error(`${name} must be a positive integer`)
  }
  return value
}

/**
 * Validate the constraints the schema DSL does not express.
 * @param args - schema-validated raw arguments.
 * @param caps - the deployment line cap and PDF page cap.
 * @returns validated input with `offset` defaulted to 1 and `limit` to the cap.
 */
export function parseReadArgs(
  args: { file_path: string; offset?: number; limit?: number; pages?: string },
  caps: Pick<ReadDocumentCaps, 'readLimit' | 'pdfMaxPages'>,
): ReadInput {
  if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string')
  const offset = args.offset === undefined ? 1 : parsePositiveInteger(args.offset, 'offset')
  const limit = args.limit === undefined ? caps.readLimit : parsePositiveInteger(args.limit, 'limit')
  if (limit > caps.readLimit) throw new Error(`limit must be less than or equal to ${caps.readLimit}`)
  const pages = args.pages === undefined ? undefined : parsePages(args.pages, caps.pdfMaxPages)
  return { filePath: args.file_path, offset, limit, ...(pages === undefined ? {} : { pages }) }
}

const KIND_LABEL: Record<PdfFacts['kind'], string> = {
  text: 'text-based',
  scanned: 'scanned',
  image: 'image-only',
  mixed: 'mixed text and scanned pages',
}

/**
 * Model-facing text for one outcome: an envelope naming the path and format,
 * PDF facts when present, numbered lines, and a footer that says how to
 * continue.
 * @param outcome - the canonical value.
 * @returns the rendered text.
 */
export function formatReadOutput(outcome: ReadDocumentOutcome): string {
  const endLine = outcome.lines.at(-1)?.number ?? Math.max(0, outcome.offset - 1)
  let footer: string
  if (outcome.truncatedByBytes) {
    footer = `(Output capped. Showing lines ${outcome.offset}-${endLine}. Use offset=${endLine + 1} to continue.)`
  } else if (endLine < outcome.totalLines) {
    footer = `(Showing lines ${outcome.offset}-${endLine} of ${outcome.totalLines}. Use offset=${endLine + 1} to continue.)`
  } else {
    footer = `(End of document - total ${outcome.totalLines} lines)`
  }
  const body = outcome.lines.length > 0
    ? `${outcome.lines.map(line => `${line.number}: ${line.text}`).join('\n')}\n\n${footer}`
    : footer
  const head = [`<path>${outcome.path}</path>`, `<format>${outcome.format}</format>`]
  if (outcome.pdf !== undefined) {
    const { pageCount, kind, pages, pagesNeedingOcr, title } = outcome.pdf
    const shown = pages === undefined ? 'all pages' : `showing page${pages.length === 1 ? '' : 's'} ${formatPages(pages)}`
    head.push(`<pdf>${pageCount} page${pageCount === 1 ? '' : 's'}, ${KIND_LABEL[kind]}; ${shown}${title === undefined ? '' : `; title: ${title}`}</pdf>`)
    if (pagesNeedingOcr.length > 0) {
      head.push(`<warning>Page${pagesNeedingOcr.length === 1 ? '' : 's'} ${formatPages(pagesNeedingOcr)} contain${pagesNeedingOcr.length === 1 ? 's' : ''} no extractable text (scanned or image content); ${pagesNeedingOcr.length === 1 ? 'its' : 'their'} content is missing below and would need OCR.</warning>`)
    }
  }
  return `${head.join('\n')}\n<content>\n${body}\n</content>`
}

/** Model-facing message for one conversion failure. */
function describeFailure(displayPath: string, error: DocumentConversionError): string {
  switch (error.code) {
    case 'encrypted':
      return `cannot read "${displayPath}": the document is encrypted; supply a decrypted copy`
    case 'unsupported':
      return `cannot read "${displayPath}": ${error.message}`
    case 'empty':
      return `cannot read "${displayPath}": ${error.message}`
    case 'scanned':
      return `cannot read "${displayPath}": ${error.message}, which this tool does not perform`
    case 'pageRange':
      return `cannot read "${displayPath}": ${error.message}`
    case 'malformed':
    case 'missingPart':
      return `cannot read "${displayPath}": the file is damaged or incomplete (${error.message})`
    case 'resourceLimit':
      return `cannot read "${displayPath}": the document exceeds the converter's internal safety limits (${error.message})`
    case 'aborted':
      return `cannot read "${displayPath}": ${error.message}`
    case 'io':
    case 'unknown':
      return `cannot read "${displayPath}": ${error.message}`
  }
}

/**
 * Register the `read_document` tool and its system-prompt guidance.
 * @param ctx - the plugin context; registrations are effects scoped to it.
 * @param converterFor - the format router over the mounted engines.
 * @param caps - resolved deployment bounds.
 */
export function applyReadDocumentTool(
  ctx: Context,
  converterFor: (format: DocumentFormat) => DocumentConverter,
  caps: ReadDocumentCaps,
): void {
  ctx.systemPrompt.section({
    name: 'tool:read_document',
    order: 100,
    text: `Use the read_document tool — not read or shell commands — to inspect PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, and CSV files. It returns the document converted to line-numbered Markdown; use offset and limit to continue reading long documents. For a PDF, pass pages (for example "1-3,7") to read only those pages; page markers like <!-- Page 4 --> show where each page starts.`,
  })

  ctx.tools.register(defineTool({
    name: 'read_document',
    description: `Read a document file as Markdown: PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, and CSV files are converted to line-numbered Markdown text. Supported: ${EXTENSION_LIST}. Returns text only and writes no files. PDFs report page count, whether pages are scanned, and accept a pages selection; scanned or image-only pages are not OCRed. For plain text or source files use read; for images use read_image.`,
    parameters: {
      file_path: { type: 'string', required: true, description: 'Path to the document, resolved by the filesystem backend; relative paths resolve against the session workspace.' },
      offset: { type: 'number', description: '1-based first line of the converted Markdown to return. Defaults to 1.' },
      limit: { type: 'number', description: `Maximum number of lines to return. Defaults to ${caps.readLimit}.` },
      pages: { type: 'string', description: `PDF only: 1-based pages to convert, as numbers and ranges like "1-3,7" (at most ${caps.pdfMaxPages} pages). Defaults to every page.` },
    },
    output: {
      schema: {
        type: 'object',
        additionalProperties: false,
        properties: {
          path: { type: 'string', required: true },
          format: { type: 'string', enum: [...DOCUMENT_FORMATS], required: true },
          offset: { type: 'integer', required: true },
          lines: {
            type: 'array',
            required: true,
            items: {
              type: 'object',
              additionalProperties: false,
              properties: {
                number: { type: 'integer', required: true },
                text: { type: 'string', required: true },
              },
            },
          },
          totalLines: { type: 'integer', required: true },
          truncatedByBytes: { type: 'boolean', required: true },
          pdf: {
            type: 'object',
            additionalProperties: false,
            properties: {
              pageCount: { type: 'integer', required: true },
              kind: { type: 'string', enum: [...PDF_KINDS], required: true },
              pagesNeedingOcr: { type: 'array', required: true, items: { type: 'integer' } },
              pages: { type: 'array', items: { type: 'integer' } },
              title: { type: 'string' },
            },
          },
        },
      },
      render: (_args, value) => [{ type: 'text', text: formatReadOutput(value as ReadDocumentOutcome) }],
    },
    // Read-only: safe beside other tool calls in the same step.
    isConcurrencySafe: () => true,
    async execute(args, exec: ToolExecution): Promise<ReadDocumentOutcome> {
      const input = parseReadArgs(args, caps)
      const format = formatOf(input.filePath)
      if (format === undefined) {
        throw new Error(
          `cannot read "${input.filePath}": unsupported extension. Supported: ${EXTENSION_LIST}. For plain text or source files use the read tool.`,
        )
      }
      if (input.pages !== undefined && format !== 'pdf') {
        throw new Error(`pages applies to PDF files only; "${input.filePath}" is ${format}`)
      }

      // Per-session workspace, like the shipped filesystem tools; a non-agent
      // caller falls back to the provider default.
      const cwd = exec.agent?.session.header.cwd
      const target = await ctx.fs.resolve(input.filePath, {
        ...cwd === undefined ? {} : { cwd },
        signal: exec.signal,
      })
      const info = await ctx.fs.stat(target, exec.signal)
      if (info === undefined) throw new Error(`cannot read "${target.displayPath}": not found`)
      if (info.type !== 'file') throw new Error(`cannot read "${target.displayPath}": not a regular file`)

      // The provider enforces the input cap, so an oversized file never buffers.
      const bytes = await ctx.fs.readBytes(target, exec.signal, caps.maxInputBytes)

      let converted
      try {
        converted = await converterFor(format).convert({
          bytes,
          format,
          signal: exec.signal,
          ...(input.pages === undefined ? {} : { pages: input.pages }),
        })
      } catch (error: unknown) {
        if (error instanceof DocumentConversionError) throw new Error(describeFailure(target.displayPath, error))
        throw error
      }

      const window = windowLines(converted.markdown, {
        offset: input.offset,
        limit: input.limit,
        maxLineLength: caps.maxLineLength,
        maxBytes: caps.maxOutputBytes,
      })
      return {
        path: target.displayPath,
        format,
        offset: input.offset,
        lines: window.lines,
        totalLines: window.totalLines,
        truncatedByBytes: window.truncatedByBytes,
        ...(converted.pdf === undefined ? {} : { pdf: converted.pdf }),
      }
    },
    // Pure display: a generic read-kind card titled by the file, with the
    // requested pages or line window when the raw args carry one, and a
    // follow-along location.
    presentCall(args): GenericCallView {
      const { offset, limit, pages } = args
      const window = pages !== undefined && pages.length > 0
        ? ` (pages ${pages})`
        : limit !== undefined && limit > 0
          ? ` (lines ${offset ?? 1} - ${(offset ?? 1) + limit - 1})`
          : offset !== undefined ? ` (from line ${offset})` : ''
      return {
        card: 'generic',
        title: `Read ${args.file_path} as Markdown${window}`,
        kind: 'read',
        locations: [{ path: args.file_path }],
      }
    },
  }))
}

/**
 * The `pages` argument grammar: comma-separated 1-based page numbers and
 * inclusive ranges, e.g. `"1-3,7,10-12"`.
 * @module @jiaoqsh/dsh-document/pages
 */

const TOKEN = /^(\d+)(?:-(\d+))?$/

/**
 * Parse a page selection into a sorted, de-duplicated list.
 * @param spec - the model-supplied text.
 * @param maxPages - the largest number of distinct pages one call may select.
 * @returns ascending 1-based page numbers.
 * @throws Error naming the offending token, or the count when it exceeds `maxPages`.
 */
export function parsePages(spec: string, maxPages: number): number[] {
  const pages = new Set<number>()
  for (const rawToken of spec.split(',')) {
    const token = rawToken.trim()
    const match = TOKEN.exec(token)
    if (match === null) {
      throw new Error(`pages must be comma-separated page numbers or ranges like "1-3,7", got "${token}"`)
    }
    const first = Number(match[1])
    const last = match[2] === undefined ? first : Number(match[2])
    if (first < 1 || last < first) throw new Error(`pages contains an invalid range "${token}"`)
    if (last - first + 1 > maxPages || pages.size + (last - first + 1) > maxPages) {
      throw new Error(`pages selects more than ${maxPages} pages`)
    }
    for (let page = first; page <= last; page += 1) pages.add(page)
  }
  if (pages.size === 0) throw new Error('pages must select at least one page')
  return [...pages].sort((a, b) => a - b)
}

import { Service, type Context } from '@deepseek-ai/cordis'
import type { FileSystem } from '@deepseek-ai/dsh-fs'
import { getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs'
import type { PdfDocument, PdfDocumentId, PdfPageText } from './types.js'
import { PdfDocumentId as makePdfDocumentId } from './types.js'

declare module '@deepseek-ai/cordis' {
  interface Context {
    /** Mounted PDF reader capability. */
    pdfReader: PdfReader
  }
}

/** The replaceable PDF parsing service consumed by the tool plugin. */
export abstract class PdfReader extends Service {
  constructor(ctx: Context) {
    super(ctx, 'pdfReader')
  }

  /** Open a PDF and return stable metadata. */
  abstract open(path: string, signal?: AbortSignal): Promise<PdfDocument>
  /** Extract one inclusive page range. */
  abstract extract(document: PdfDocumentId, fromPage: number, toPage: number, signal?: AbortSignal): Promise<readonly PdfPageText[]>
  /** Resolve a document id to metadata. */
  abstract get(document: PdfDocumentId): PdfDocument | undefined
}

interface LoadedDocument {
  readonly metadata: PdfDocument
  readonly pages: readonly string[]
}

/** Local provider using the harness filesystem seam and pdfjs-dist. */
export class PdfReaderLocal extends PdfReader {
  static inject = ['fs']

  private readonly fs: FileSystem
  private readonly maxPdfBytes: number
  private readonly documents = new Map<PdfDocumentId, LoadedDocument>()

  constructor(ctx: Context, config: { maxPdfBytes?: number } = {}) {
    super(ctx)
    this.fs = ctx.fs
    this.maxPdfBytes = config.maxPdfBytes ?? 128 * 1024 * 1024
    if (!Number.isSafeInteger(this.maxPdfBytes) || this.maxPdfBytes < 1) {
      throw new Error('pdf-reader: maxPdfBytes must be a positive safe integer')
    }
  }

  async open(path: string, signal?: AbortSignal): Promise<PdfDocument> {
    const target = await this.fs.resolve(path, { signal })
    const info = await this.fs.stat(target, signal)
    if (info?.type !== 'file') throw new Error(`PDF file is not a regular file: ${path}`)
    const bytes = await this.fs.readBytes(target, signal, this.maxPdfBytes)
    signal?.throwIfAborted()
    const loadingTask = getDocument({ data: bytes, useSystemFonts: true })
    const pdf = await loadingTask.promise
    const pages: string[] = []
    for (let pageNumber = 1; pageNumber <= pdf.numPages; pageNumber++) {
      signal?.throwIfAborted()
      const page = await pdf.getPage(pageNumber)
      const content = await page.getTextContent()
      pages.push(content.items.map(item => 'str' in item ? item.str : '').join(' ').replace(/\s+/g, ' ').trim())
      page.cleanup()
    }
    const pageCount = pdf.numPages
    pdf.cleanup()
    const id = makePdfDocumentId(`pdf-${stableId(target.displayPath)}`)
    const metadata: PdfDocument = {
      id,
      path: target.displayPath,
      title: basename(target.displayPath),
      pageCount,
      sizeBytes: bytes.byteLength,
    }
    this.documents.set(id, { metadata, pages })
    return metadata
  }

  async extract(document: PdfDocumentId, fromPage: number, toPage: number, signal?: AbortSignal): Promise<readonly PdfPageText[]> {
    const loaded = this.documents.get(document)
    if (loaded === undefined) throw new Error(`PDF document is not open: ${document}`)
    if (!Number.isSafeInteger(fromPage) || !Number.isSafeInteger(toPage) || fromPage < 1 || toPage < fromPage || toPage > loaded.pages.length) {
      throw new Error(`PDF page range must be within 1-${loaded.pages.length}`)
    }
    const result: PdfPageText[] = []
    for (let page = fromPage; page <= toPage; page++) {
      signal?.throwIfAborted()
      result.push({ page, text: loaded.pages[page - 1] ?? '' })
    }
    return result
  }

  get(document: PdfDocumentId): PdfDocument | undefined {
    return this.documents.get(document)?.metadata
  }
}

function basename(path: string): string {
  const name = path.split(/[\\/]/).pop() ?? path
  return name.toLowerCase().endsWith('.pdf') ? name.slice(0, -4) : name
}

function stableId(path: string): string {
  let hash = 2166136261
  for (const char of path) {
    hash ^= char.charCodeAt(0)
    hash = Math.imul(hash, 16777619)
  }
  return Math.abs(hash >>> 0).toString(36)
}

export default PdfReader