@web-ts-toolkit/pdf-reader 0.40.1 → 0.42.0

package/README.md

@@ -8,7 +8,9 @@ Resource-safe browser PDF rendering, text extraction, and best-effort embedded-i
 pnpm add @web-ts-toolkit/pdf-reader pdfjs-dist
 ```
 
-`pdfjs-dist` is a peer dependency. This package is browser-oriented, ESM-only, and requires DOM canvas APIs.
+`pdfjs-dist` is a peer dependency. This package is browser-oriented, ESM-only, and requires DOM canvas APIs. Automated browser compatibility coverage currently runs the real PDF.js worker and browser canvas suite in Headless Chromium only. Firefox and WebKit are not claimed by the automated package test boundary until their Playwright browsers are added to `vitest.browser.config.mts` and pass the same fixture suite in CI.
+
+The supported PDF.js compatibility contract is the `pdfjs-dist` `~6.2.108` peer minor. The package test and real-browser fixture suite run against `6.2.108`; future `6.x` minors are not admitted until rendering and embedded-image compatibility are exercised in a reproducible browser matrix.
 
 Canonical imports use named exports from the package root. There is no default export, no supported deep import, and no supported CommonJS `require()` entry.
 
@@ -16,20 +18,22 @@ Canonical imports use named exports from the package root. There is no default e
 
 This follow-up release keeps the small named-export API but intentionally does not preserve the older application-local `PDFReader` names and defaults.
 
-| Area                           | Previous contract                                                                                                            | New contract and migration                                                                                                                                                                                                                                 |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Imports and worker setup       | The application-local reader was typically imported as a default export and could hide PDF.js worker wiring inside app code. | Import named exports from `@web-ts-toolkit/pdf-reader` and call `configurePdfWorker(...)` in application code. There is no default export, no deep import, and no package-owned worker asset emission.                                                     |
-| Load cancellation and teardown | Concurrent callers could accidentally tear down a shared load, and lifecycle states were mostly implicit.                    | Concurrent `load()` callers share one PDF.js task, but aborting one caller rejects only that caller. Use `reader.state` for `new` / `loading` / `loaded` / `iterating` / `failed` / `destroyed`, and call `destroy()` to tear down shared work explicitly. |
-| Load options                   | `load()` previously accepted only an `AbortSignal`-style cancellation pattern.                                               | `load()` still accepts an `AbortSignal`, and now also accepts `{ signal, deadlineMs }`. `deadlineMs` is caller-local and rejects with `DEADLINE_EXCEEDED` without cancelling unrelated waiters.                                                            |
-| Page image results             | Older code used top-level page result fields such as `dataURL`, `dataUrl`, `mimeType`, and `isPNG`.                          | Read `page.pageImage` instead. `pageImageOutput: 'data-url'` returns `{ kind: 'data-url', mimeType, dataUrl }`; `pageImageOutput: 'blob'` returns `{ kind: 'blob', mimeType, blob }`.                                                                      |
-| Convert option names           | Older application-local option names included `getText`, `getDataURL`, `getImages`, and reader `config`.                     | Use `includeText`, `includePageImage`, `includeEmbeddedImages`, and constructor `options`. Unsupported legacy names are intentionally rejected by the type surface instead of being kept as aliases.                                                       |
+| Area                           | Previous contract                                                                                                            | New contract and migration                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Imports and worker setup       | The application-local reader was typically imported as a default export and could hide PDF.js worker wiring inside app code. | Import named exports from `@web-ts-toolkit/pdf-reader` and call `configurePdfWorker(...)` in application code. There is no default export, no deep import, and no package-owned worker asset emission.                                                                                                                                       |
+| Load cancellation and teardown | Concurrent callers could accidentally tear down a shared load, and lifecycle states were mostly implicit.                    | Concurrent `load()` callers share one PDF.js task, but aborting one caller rejects only that caller. The `PDFDocumentProxy` returned by `load()` is borrowed; inspect it if needed, but call `reader.destroy()` instead of `document.destroy()`. Use `reader.state` for `new` / `loading` / `loaded` / `iterating` / `failed` / `destroyed`. |
+| Load options                   | `load()` previously accepted only an `AbortSignal`-style cancellation pattern.                                               | `load()` still accepts an `AbortSignal`, and now also accepts `{ signal, deadlineMs }`. `deadlineMs` is caller-local and rejects with `DEADLINE_EXCEEDED` without cancelling unrelated waiters.                                                                                                                                              |
+| Page image results             | Older code used top-level page result fields such as `dataURL`, `dataUrl`, `mimeType`, and `isPNG`.                          | Read `page.pageImage` instead. `pageImageOutput: 'data-url'` returns `{ kind: 'data-url', mimeType, dataUrl }`; `pageImageOutput: 'blob'` returns `{ kind: 'blob', mimeType, blob }`.                                                                                                                                                        |
+| Convert option names           | Older application-local option names included `getText`, `getDataURL`, `getImages`, and reader `config`.                     | Use `includeText`, `includePageImage`, `includeEmbeddedImages`, and constructor `options`. Unsupported legacy names are intentionally rejected by the type surface instead of being kept as aliases.                                                                                                                                         |
 
-The repository `CHANGELOG.md` contains the same release-level migration summary.
+Release-note evidence for this follow-up is recorded in this README, the website package docs, and the task completion record. `CHANGELOG.md` was intentionally not edited for PDFR2-05 per maintainer instruction.
 
 ## Worker Setup
 
 Configure the PDF.js worker explicitly in your application. The package does not use bundler-specific `?url` imports and does not mutate PDF.js globals merely by being imported.
 
+`configurePdfWorker(...)` writes PDF.js application-global worker state (`GlobalWorkerOptions.workerSrc` or `workerPort`) for the current JavaScript realm. Use it once at application startup only when every PDF.js consumer can share the same setting. Calling it again replaces the previous global URL-or-port setting and can collide with other direct or transitive PDF.js users.
+
 Vite example:
 
 ```ts
@@ -47,7 +51,23 @@ import { configurePdfWorker } from '@web-ts-toolkit/pdf-reader';
 configurePdfWorker(new Worker(new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url), { type: 'module' }));
 ```
 
-Worker URL emission differs by bundler. Keep this setup in application code where the bundler owns asset handling. Calling `configurePdfWorker(...)` again replaces the previous package-level worker configuration. If you pass an existing `Worker`, you still own terminating it.
+Worker URL emission differs by bundler. Keep this setup in application code where the bundler owns asset handling. If you pass an existing `Worker`, you still own terminating it.
+
+For per-document isolation, skip the global helper and pass a caller-created PDF.js `PDFWorker` through the source object. The public `PdfSource` type accepts PDF.js `DocumentInitParameters`, including its `worker` field:
+
+```ts
+import { PDFWorker } from 'pdfjs-dist';
+import { PDFReader } from '@web-ts-toolkit/pdf-reader';
+
+const worker = new PDFWorker({ name: 'tenant-a' });
+const reader = new PDFReader({ data: bytes, worker });
+
+try {
+  await reader.load();
+} finally {
+  await reader.destroy();
+}
+```
 
 ## Quick Start
 
@@ -88,7 +108,7 @@ const reader = new PDFReader(
 );
 ```
 
-Call `load()` before `pages()` or `convert()`. Concurrent `load()` callers share one PDF.js loading task, but aborting one caller only rejects that caller; call `destroy()` to tear down the shared load. `destroy()` is idempotent, permanently closes the reader, cancels active renders, and causes in-flight lifecycle work to reject with `DESTROYED`.
+Call `load()` before `pages()` or `convert()`. Concurrent `load()` callers share one PDF.js loading task, but aborting one caller only rejects that caller. The fulfilled `load()` value is the reader-owned PDF.js `PDFDocumentProxy` exposed as a borrowed interoperability handle. You may inspect metadata or call supported PDF.js read methods, but do not call `document.destroy()` on it while the reader owns the lifecycle; call `reader.destroy()` instead. External proxy destruction is unsupported because PDF.js does not provide a reliable ownership notification to keep `reader.state` authoritative after that mutation. Page operations are reader-serial: at most one executing `pages()` iterator or `convert()` call may be active per `PDFReader`. A second overlapping page operation fails fast with `OPERATION_IN_PROGRESS` before acquiring a page proxy or allocating a canvas; create a separate reader if you need independent concurrent conversions. Calling `pages()` only creates an iterator object and does not reserve the reader until the iterator starts executing. `destroy()` is idempotent, permanently closes the reader, cancels active renders, and causes in-flight lifecycle work to reject with `DESTROYED`. It waits for PDF.js loading/document destruction, but active `pages()` or `convert()` calls finish their own page and canvas cleanup as those operation promises settle; await those operations if you need to observe that cleanup.
 
 ## Reader State And Ownership
 
@@ -98,20 +118,22 @@ Call `load()` before `pages()` or `convert()`. Concurrent `load()` callers share
 | ----------- | ------------------------------------------------------------------------------------ | ------------------------------- |
 | `new`       | Reader constructed but `load()` has not started.                                     | `loading`, `destroyed`          |
 | `loading`   | One shared PDF.js loading task is in flight.                                         | `loaded`, `failed`, `destroyed` |
-| `loaded`    | The PDF.js document is loaded and no page work is active.                            | `iterating`, `destroyed`        |
-| `iterating` | `pages()` or `convert()` currently owns a page proxy, render task, or encoder step.  | `loaded`, `destroyed`           |
+| `loaded`    | The PDF.js document is loaded and no page operation is active.                       | `iterating`, `destroyed`        |
+| `iterating` | One executing `pages()` iterator or `convert()` call owns the reader page operation. | `loaded`, `destroyed`           |
 | `failed`    | The most recent load attempt rejected. A later `load()` call starts a fresh attempt. | `loading`, `destroyed`          |
 | `destroyed` | `destroy()` completed or irrevocably won a race. The reader cannot be reused.        | none                            |
 
 Ownership and lifetime rules:
 
-- Source bytes: the package passes your `PdfSource` to PDF.js unchanged after `sourcePolicy(...)` approval. PDF.js may transfer typed-array ownership to its worker during `load()`.
-- Pages: `pages()` and `convert()` own the live `PDFPageProxy` only while processing that page. The package calls `page.cleanup()` before yielding the result and on every error path.
+- Source bytes: the package snapshots the top-level PDF.js loading parameters once before `sourcePolicy(...)` runs and passes that same snapshot to PDF.js after approval. PDF.js may transfer typed-array ownership to its worker during `load()`.
+- Loaded document proxy: `load()` returns the borrowed `PDFDocumentProxy` owned by the reader. Callers may use supported PDF.js read APIs on it, but external `document.destroy()` is unsupported and can leave `reader.state` reporting `loaded` until a later PDF.js method fails.
+- Public aliases: `LoadedPdfDocument` and `LoadedPdfPage` intentionally expose PDF.js proxy types for adjacent interoperability code. The reader API returns `LoadedPdfDocument` from `load()` and package `PageResult` objects from `pages()`/`convert()`; it does not return raw page proxies.
+- Pages: one executing `pages()` iterator or `convert()` call owns the reader-level page operation at a time. Within that operation, the package owns one live `PDFPageProxy` only while processing the current page and calls `page.cleanup()` before yielding the result and on every error path.
 - Page canvases: the package owns temporary render/encode canvases and always zeroes their dimensions after each settle path.
 - `Blob` page images: the returned `Blob` belongs to the caller. If you create an object URL, revoke it yourself.
 - Data URLs: returned strings belong to the caller. They are copies; the package does not retain the temporary canvas after encoding.
-- Embedded-image data URLs: these are best-effort PNG copies. Unsupported image operators/layouts are skipped with `logger.warn(...)` diagnostics.
-- Documents and workers: the reader owns the loaded `PDFDocumentProxy` and the shared loading task it created. Call `destroy()` in your own `finally` block to terminate document-side resources. When `configurePdfWorker(...)` receives a worker URL, PDF.js owns any worker instances it creates from that URL. When `configurePdfWorker(...)` receives an existing `Worker`, the caller still owns terminating that worker.
+- Embedded-image data URLs: these are best-effort PNG copies. Repeated image XObject placements on one page share one encoded PNG string while each returned image keeps its own transform and coordinates. Unsupported image operators/layouts are skipped with `logger.warn(...)` diagnostics.
+- Documents and workers: the reader owns the loaded `PDFDocumentProxy` and the shared loading task it created. Call `destroy()` in your own `finally` block to terminate document-side resources. `configurePdfWorker(...)` mutates PDF.js application-global worker state; use a per-source PDF.js `PDFWorker` when separate readers need isolated worker configuration. When `configurePdfWorker(...)` receives a worker URL, PDF.js owns any worker instances it creates from that URL. When `configurePdfWorker(...)` receives an existing `Worker`, the caller still owns terminating that worker.
 
 ## Options
 
@@ -137,6 +159,8 @@ const pages = await reader.convert({
 - `includeEmbeddedImages`: inspect the operator stream for raster images; defaults to `false`.
 - `signal`: cancels active rendering and stops before subsequent expensive operations.
 
+Constructor `canvasFactory`, when supplied, must create a fresh DOM `HTMLCanvasElement` for each package-owned render or embedded-image copy. Non-DOM canvas objects are not part of the documented runtime contract unless they satisfy the browser `HTMLCanvasElement` behavior used by PDF.js and this package.
+
 `pageImage` is a discriminated union so the output mode and payload cannot contradict each other:
 
 ```ts
@@ -158,7 +182,7 @@ This package returns `Blob` objects directly rather than object URLs so callers
 
 ## Performance And Concurrency
 
-Page work remains serial in the runtime API. PDFR-07 adds a real-browser benchmark under `packages/pdf-reader/benchmark/` that compares the current `pages()` behavior against an external page-level scheduler with a hard concurrency bound of `2`, deterministic output ordering, and abort handling.
+Page work is serial per reader in the runtime API. A loaded `PDFReader` permits one executing `pages()` iterator or `convert()` call at a time and rejects overlap with `OPERATION_IN_PROGRESS`; it does not queue page operations. PDFR-07 adds a real-browser benchmark under `packages/pdf-reader/benchmark/` that compares the current `pages()` behavior against an external page-level scheduler with a hard concurrency bound of `2`, deterministic output ordering, and abort handling.
 
 Run it with:
 
@@ -170,9 +194,11 @@ The recorded local run on Headless Chromium `151.0.7922.34` showed bounded overl
 
 The package still does not expose a concurrency option because that evidence is not yet enough to set a safe browser memory/backpressure contract. See the benchmark README and the PDFR-07 completion evidence for the recorded browser/hardware context and full results.
 
+Overlapping `pages()` or `convert()` calls on the same reader are newly rejected rather than being allowed to multiply active page/canvas ownership. Sequential reuse after the prior operation finishes is still supported.
+
 ## Resource Limits
 
-Defaults reject documents above 1,000 pages, rendered pages above 40 megapixels, and copied embedded images above 25 megapixels.
+Defaults reject documents above 1,000 pages, one page's retained text above 50,000 items or 5,000,000 string code units, embedded-image extraction above 100,000 PDF.js operators, rendered pages above 40 megapixels, one copied embedded image above 25 megapixels, one page above 1,000 extracted embedded images, and one page above 100 megapixels of aggregate decoded embedded-image pixels.
 
 ```ts
 import { PDFReader, PdfReaderError } from '@web-ts-toolkit/pdf-reader';
@@ -181,8 +207,13 @@ const reader = new PDFReader(bytes, {
   limits: {
     maxSourceBytes: 25_000_000,
     maxDocumentPages: 250,
+    maxTextItems: 10_000,
+    maxTextCodeUnits: 1_000_000,
+    maxOperatorCount: 20_000,
     maxCanvasPixels: 20_000_000,
     maxEmbeddedImagePixels: 10_000_000,
+    maxEmbeddedImages: 250,
+    maxEmbeddedImagePixelsTotal: 40_000_000,
   },
   sourcePolicy(source) {
     if (source.url && !source.url.startsWith('https://static.example.com/')) {
@@ -207,24 +238,28 @@ Limits reduce accidental or malicious memory pressure but are not a complete san
 
 `maxSourceBytes` is enforced only when the package can know the byte length synchronously, including direct typed arrays, array buffers, number arrays, and `DocumentInitParameters.data`. It does not apply to remote downloads.
 
-`sourcePolicy(source)` runs before `getDocument()` and can reject remote URLs, protocols, origins, credentials, headers, or any other caller-supplied loading parameters. The original source object still passes through unchanged when the policy allows it, so PDF.js passwords, CMap/font/WASM URLs, and caller-created workers remain available.
+Text and operator limits are enforced after PDF.js returns a complete page text content or operator list, but before the package retains the text result or traverses the operator list. These checks bound package-owned processing and returned results; they cannot prevent PDF.js from initially constructing those PDF.js structures.
+
+Embedded-image limits are enforced before allocating or encoding the next extracted embedded-image canvas. `maxEmbeddedImagePixels` applies to one copied image, `maxEmbeddedImages` applies to extracted images returned for one page, and `maxEmbeddedImagePixelsTotal` applies to aggregate decoded pixels copied for one page, including repeated references to the same underlying PDF image object. Repeated image XObject references reuse one encoded data URL per page only after these aggregate placement limits pass; inline images are not cached by synthetic keys. Unsafe non-finite or overflowing image dimensions fail closed with a resource-limit error. Exact aggregate encoded PNG data-url bytes are not knowable until after browser canvas encoding, so the package does not claim a separate pre-encoding output-byte cap; use the decoded-pixel limits to bound package allocation and encoding work.
+
+`sourcePolicy(source)` runs before `getDocument()` and can reject remote URLs, protocols, origins, credentials, headers, or any other caller-supplied loading parameters. The `source.rawSource` value is an immutable shallow snapshot of the PDF.js parameters that will be used for loading after approval. Top-level getters and later source-object mutation cannot change the approved URL, credential flag, headers reference, password, CMap/font/WASM URLs, or caller-created worker. Opaque objects such as caller-created workers and in-memory data references are preserved rather than recursively cloned.
 
 ## Security Notes
 
 - Prefer trusted `Uint8Array` input. PDF.js may transfer ownership of typed-array data to its worker.
 - Use `sourcePolicy` to reject remote URLs, protocols, origins, credentialed requests, or header-bearing sources before PDF.js starts network work.
-- `configurePdfWorker(...)` mutates PDF.js global worker options only when you call it, not at module evaluation. Reconfiguring it clears the previous URL-or-port setting so stale worker globals do not win unexpectedly.
+- `configurePdfWorker(...)` mutates PDF.js application-global worker options only when you call it, not at module evaluation. Reconfiguring it clears the previous URL-or-port setting so stale worker globals do not win unexpectedly, but the replacement can affect other PDF.js consumers in the same realm. Use a per-source PDF.js `PDFWorker` for isolation.
 - Keep `withCredentials` disabled unless cross-origin credentials are explicitly required.
 - Use `maxSourceBytes` for synchronously knowable in-memory sources. Remote response-byte limits still belong to application-controlled fetch/range transport because this package does not intercept PDF.js network I/O.
 - Use `load({ deadlineMs })` or your own `AbortSignal` to bound load wait time. The package clears deadline timers and abort listeners on success, failure, caller abort, and destroy.
-- Keep `pdfjs-dist` current because malformed-document defenses belong primarily to PDF.js.
+- Keep `pdfjs-dist` current within the supported `~6.2.108` peer minor because malformed-document defenses belong primarily to PDF.js. Wider PDF.js minors require new package compatibility evidence before use.
 - Treat extracted text and images as untrusted content. Do not inject text as HTML without escaping or sanitization.
 
 ## Embedded Images
 
 Embedded-image extraction stays on the package root as an opt-in convenience (`includeEmbeddedImages: true`), but the operator traversal now lives behind one private extractor boundary instead of mixing PDF.js internals into reader lifecycle code.
 
-The real-browser fixture suite for the supported `pdfjs-dist` peer minor (`~5.7.284`) characterizes inline images, image XObjects, repeated references, nested save/restore transforms, mirrored transforms, grayscale, RGB, RGBA soft-mask images, browser `ImageBitmap`-backed image objects, and nested form XObjects with their own matrices.
+The real-browser fixture suite for the supported `pdfjs-dist` peer minor (`~6.2.108`) characterizes inline images, image XObjects, repeated references, nested save/restore transforms, mirrored transforms, grayscale, RGB, RGBA soft-mask images, browser `ImageBitmap`-backed image objects, and nested form XObjects with their own matrices.
 
 Standalone image-mask operators, vector graphics, patterns, and unknown PDF.js image-object layouts remain unsupported. They are skipped with `logger.warn(...)` diagnostics rather than failing the entire page. The extractor never calls `ImageBitmap.close()` because PDF.js owns bitmap lifetime through `page.cleanup()` and document destruction.
 
@@ -242,10 +277,15 @@ Validation and resource failures use `PdfReaderError` with stable codes:
 - `DESTROYED`
 - `DOCUMENT_NOT_LOADED`
 - `IMAGE_LIMIT_EXCEEDED`
+- `IMAGE_COUNT_LIMIT_EXCEEDED`
+- `IMAGE_TOTAL_PIXELS_LIMIT_EXCEEDED`
 - `INVALID_OPTION`
+- `OPERATOR_LIMIT_EXCEEDED`
+- `OPERATION_IN_PROGRESS`
 - `PAGE_LIMIT_EXCEEDED`
 - `SOURCE_LIMIT_EXCEEDED`
 - `SOURCE_POLICY_VIOLATION`
+- `TEXT_LIMIT_EXCEEDED`
 - `UNSUPPORTED_ENVIRONMENT`
 
 Package-owned errors cover invalid options, lifecycle cancellation/destroy/deadline states, resource limits, source-policy/known-byte rejections, and unsupported canvas/runtime features such as missing 2D contexts or missing `toBlob()` support.

package/index.d.mts

@@ -1,7 +1,7 @@
 import * as pdfjs_dist from 'pdfjs-dist';
 import { PDFDocumentProxy, PDFPageProxy, PageViewport } from 'pdfjs-dist';
 
-type PdfReaderErrorCode = 'ABORTED' | 'CANVAS_LIMIT_EXCEEDED' | 'DEADLINE_EXCEEDED' | 'DESTROYED' | 'DOCUMENT_NOT_LOADED' | 'IMAGE_LIMIT_EXCEEDED' | 'INVALID_OPTION' | 'PAGE_LIMIT_EXCEEDED' | 'SOURCE_LIMIT_EXCEEDED' | 'SOURCE_POLICY_VIOLATION' | 'UNSUPPORTED_ENVIRONMENT';
+type PdfReaderErrorCode = 'ABORTED' | 'CANVAS_LIMIT_EXCEEDED' | 'DEADLINE_EXCEEDED' | 'DESTROYED' | 'DOCUMENT_NOT_LOADED' | 'IMAGE_LIMIT_EXCEEDED' | 'IMAGE_COUNT_LIMIT_EXCEEDED' | 'IMAGE_TOTAL_PIXELS_LIMIT_EXCEEDED' | 'INVALID_OPTION' | 'OPERATOR_LIMIT_EXCEEDED' | 'OPERATION_IN_PROGRESS' | 'PAGE_LIMIT_EXCEEDED' | 'SOURCE_LIMIT_EXCEEDED' | 'SOURCE_POLICY_VIOLATION' | 'TEXT_LIMIT_EXCEEDED' | 'UNSUPPORTED_ENVIRONMENT';
 /** An actionable package error with a stable machine-readable code. */
 declare class PdfReaderError extends Error {
     readonly code: PdfReaderErrorCode;
@@ -36,17 +36,27 @@ interface PdfReaderLimits {
     maxSourceBytes?: number;
     /** Maximum number of document pages accepted after loading. Defaults to 1,000. */
     maxDocumentPages?: number;
+    /** Maximum PDF.js text items retained for one page. Defaults to 50,000. */
+    maxTextItems?: number;
+    /** Maximum string code units retained across one page's text items. Defaults to 5,000,000. */
+    maxTextCodeUnits?: number;
+    /** Maximum PDF.js operators traversed for embedded-image extraction on one page. Defaults to 100,000. */
+    maxOperatorCount?: number;
     /** Maximum pixels allocated for one rendered page. Defaults to 40 megapixels. */
     maxCanvasPixels?: number;
     /** Maximum pixels allocated while copying one embedded image. Defaults to 25 megapixels. */
     maxEmbeddedImagePixels?: number;
+    /** Maximum extracted embedded images returned for one page. Defaults to 1,000. */
+    maxEmbeddedImages?: number;
+    /** Maximum decoded embedded-image pixels copied across one page. Defaults to 100 megapixels. */
+    maxEmbeddedImagePixelsTotal?: number;
 }
 interface PdfReaderLogger {
     warn(message: string, error?: unknown): void;
 }
 interface PdfReaderSourceInfo {
-    /** The original source value that will be passed to PDF.js if policy allows it. */
-    rawSource: PdfSource;
+    /** Immutable shallow snapshot that will be passed to PDF.js if policy allows it. */
+    rawSource: Readonly<PdfDocumentInitParameters>;
     /** Broad source shape so callers can distinguish direct bytes from URL-based inputs. */
     kind: 'bytes' | 'url' | 'document-init-parameters';
     /** Normalized URL string when one is present on the source. */
@@ -60,9 +70,9 @@ interface PdfReaderSourceInfo {
     /** Whether PDF.js would send credentials for URL-based loading. */
     withCredentials: boolean;
 }
-type PdfReaderSourcePolicy = (source: PdfReaderSourceInfo) => void | Promise<void>;
+type PdfReaderSourcePolicy = (source: PdfReaderSourceInfo) => void | PromiseLike<void>;
 interface PdfReaderOptions {
-    /** Canvas boundary injectable for tests or non-DOM canvas implementations. */
+    /** Creates a fresh DOM `HTMLCanvasElement` for each package-owned page or embedded-image render. */
     canvasFactory?: () => HTMLCanvasElement;
     /** Optional warning sink. The package never writes directly to the console. */
     logger?: PdfReaderLogger;
@@ -127,7 +137,21 @@ interface PageResult {
     /** Best-effort embedded raster images extracted from the current page. */
     images: ExtractedImage[];
 }
+/**
+ * Borrowed PDF.js document proxy returned by `PDFReader.load()`.
+ *
+ * The reader owns lifecycle teardown. Callers may inspect metadata and call
+ * supported PDF.js read methods, but must not call `destroy()` on this proxy
+ * while the `PDFReader` owns it. Use `PDFReader.destroy()` instead.
+ */
 type LoadedPdfDocument = PDFDocumentProxy;
+/**
+ * PDF.js page proxy alias for consumers interoperating with PDF.js APIs.
+ *
+ * `PDFReader.pages()` returns package `PageResult` objects, not raw page
+ * proxies. This alias is exported so applications can type adjacent PDF.js
+ * integration code without relying on unsupported package deep imports.
+ */
 type LoadedPdfPage = PDFPageProxy;
 
 /** Browser PDF reader with bounded canvas allocation and deterministic cleanup. */
@@ -137,7 +161,14 @@ declare class PDFReader {
     get numPages(): number | undefined;
     /** Current lifecycle state for load, iteration/rendering, retry, and teardown boundaries. */
     get state(): PdfReaderState;
-    /** Loads once and returns the underlying PDF.js document proxy. */
+    /**
+     * Loads once and returns the borrowed PDF.js document proxy.
+     *
+     * The returned proxy remains owned by this reader. Callers may inspect it and
+     * use supported PDF.js read methods, but must not call `destroy()` on the
+     * proxy while the reader owns lifecycle teardown. Call `reader.destroy()` to
+     * release document and worker resources.
+     */
     load(signal?: AbortSignal): Promise<PDFDocumentProxy>;
     load(options?: LoadOptions): Promise<PDFDocumentProxy>;
     /** Streams page results so callers do not need to retain the entire document conversion in memory. */
@@ -183,11 +214,16 @@ type PdfUrlSource = PdfUrlSourceOptions & {
 declare function pdfUrlSource(url: string | URL, options?: PdfUrlSourceOptions): PdfUrlSource;
 
 /**
- * Configures PDF.js without bundler-specific imports or package-load side effects.
- * Pass either a worker URL emitted by your bundler or an existing module Worker.
+ * Configures PDF.js application-global worker state.
+ *
+ * Use this once at application startup when every PDF.js consumer can share the
+ * same worker configuration. Calling it again replaces the previous global
+ * worker URL or port and can collide with other PDF.js consumers in the same
+ * JavaScript realm. For isolation, pass a caller-created PDF.js `PDFWorker` on
+ * an individual `DocumentInitParameters` source instead of using this helper.
  *
- * Calling this again replaces the previous configuration. When passing an
- * existing `Worker`, the caller retains ownership of terminating it.
+ * When passing an existing DOM `Worker`, the caller retains ownership of
+ * terminating it.
  */
 declare function configurePdfWorker(worker: string | Worker): void;
 

package/index.mjs

@@ -42,94 +42,128 @@ function getTransformedUnitBounds(transform) {
 
 // src/embeddedImages.ts
 var identityTransform = [1, 0, 0, 1, 0, 0];
-var propagatedErrorCodes = /* @__PURE__ */ new Set(["ABORTED", "DESTROYED", "IMAGE_LIMIT_EXCEEDED"]);
+var propagatedErrorCodes = /* @__PURE__ */ new Set([
+  "ABORTED",
+  "DESTROYED",
+  "IMAGE_LIMIT_EXCEEDED",
+  "IMAGE_COUNT_LIMIT_EXCEEDED",
+  "IMAGE_TOTAL_PIXELS_LIMIT_EXCEEDED",
+  "OPERATOR_LIMIT_EXCEEDED"
+]);
 async function extractEmbeddedImages(page, viewport, options) {
   const operators = await page.getOperatorList();
+  enforceOperatorLimit(operators.fnArray.length, options.maxOperators);
   const images = [];
   const stack = [];
   let transform = identityTransform;
-  for (let index = 0; index < operators.fnArray.length; index += 1) {
-    options.throwIfDestroyed();
-    options.throwIfAborted(options.signal);
-    const operation = operators.fnArray[index];
-    if (operation === OPS.save) {
-      stack.push([...transform]);
-      continue;
-    }
-    if (operation === OPS.restore || operation === OPS.paintFormXObjectEnd) {
-      transform = stack.pop() ?? identityTransform;
-      continue;
-    }
-    if (operation === OPS.transform) {
-      const next = readTransformArgs(operators.argsArray[index]);
-      if (next) transform = Util.transform(transform, next);
-      continue;
-    }
-    if (operation === OPS.paintFormXObjectBegin) {
-      stack.push([...transform]);
-      const next = readTransformMatrix(operators.argsArray[index]?.[0]);
-      if (next) transform = Util.transform(transform, next);
-      continue;
-    }
-    if (operation === OPS.paintImageMaskXObject) {
-      warn(options.logger, "Skipped embedded image operator paintImageMaskXObject: image masks are not supported.");
-      continue;
-    }
-    if (operation !== OPS.paintXObject && operation !== OPS.paintImageXObject && operation !== OPS.paintInlineImageXObject) {
-      continue;
-    }
-    try {
-      const paintedImage = await resolvePaintedImage(page, operation, operators.argsArray[index], index);
-      if (!paintedImage) continue;
-      const dataUrl = imageToDataUrl(paintedImage.image, options);
-      if (!dataUrl) {
-        warn(
-          options.logger,
-          `Skipped embedded image ${paintedImage.label}: unsupported PDF.js image shape or data layout.`
-        );
-        continue;
-      }
-      const bounds = getTransformedUnitBounds(transform);
-      images.push({
-        dataUrl,
-        x: bounds.left,
-        y: bounds.top,
-        width: bounds.width,
-        height: bounds.height,
-        size: imageByteLength(paintedImage.image),
-        mimeType: "image/png",
-        pageWidth: viewport.width / viewport.scale,
-        pageHeight: viewport.height / viewport.scale,
-        transform: [...transform]
-      });
-    } catch (error) {
+  let totalPixels = 0;
+  const encodedXObjects = /* @__PURE__ */ new Map();
+  try {
+    for (let index = 0; index < operators.fnArray.length; index += 1) {
       options.throwIfDestroyed();
       options.throwIfAborted(options.signal);
-      if (shouldPropagateEmbeddedImageError(error)) throw error;
-      const label = readOperationLabel(operation, operators.argsArray[index], index);
-      warn(options.logger, `Failed to extract embedded image ${label}.`, error);
+      const operation = operators.fnArray[index];
+      if (operation === OPS.save) {
+        stack.push([...transform]);
+        continue;
+      }
+      if (operation === OPS.restore || operation === OPS.paintFormXObjectEnd) {
+        transform = stack.pop() ?? identityTransform;
+        continue;
+      }
+      if (operation === OPS.transform) {
+        const next = readTransformArgs(operators.argsArray[index]);
+        if (next) transform = Util.transform(transform, next);
+        continue;
+      }
+      if (operation === OPS.paintFormXObjectBegin) {
+        stack.push([...transform]);
+        const next = readTransformMatrix(operators.argsArray[index]?.[0]);
+        if (next) transform = Util.transform(transform, next);
+        continue;
+      }
+      if (operation === OPS.paintImageMaskXObject) {
+        warn(options.logger, "Skipped embedded image operator paintImageMaskXObject: image masks are not supported.");
+        continue;
+      }
+      if (operation !== OPS.paintXObject && operation !== OPS.paintImageXObject && operation !== OPS.paintInlineImageXObject) {
+        continue;
+      }
+      try {
+        const args = operators.argsArray[index];
+        const reference = operation === OPS.paintInlineImageXObject ? void 0 : readImageReference(args);
+        let encoded = reference ? encodedXObjects.get(reference) : void 0;
+        if (encoded) {
+          enforceNextImageLimits(images.length, totalPixels, encoded.dimensions.pixels, options);
+        } else {
+          const paintedImage = await resolvePaintedImage(page, operation, args, index);
+          options.throwIfDestroyed();
+          options.throwIfAborted(options.signal);
+          if (!paintedImage) continue;
+          const dimensions = readImageDimensions(paintedImage.image, options.maxPixels);
+          if (!dimensions || !isSupportedImageSource(paintedImage.image)) {
+            warn(
+              options.logger,
+              `Skipped embedded image ${paintedImage.label}: unsupported PDF.js image shape or data layout.`
+            );
+            continue;
+          }
+          enforceNextImageLimits(images.length, totalPixels, dimensions.pixels, options);
+          const dataUrl = imageToDataUrl(paintedImage.image, dimensions, options);
+          if (!dataUrl) {
+            warn(
+              options.logger,
+              `Skipped embedded image ${paintedImage.label}: unsupported PDF.js image shape or data layout.`
+            );
+            continue;
+          }
+          encoded = { dataUrl, dimensions, size: imageByteLength(paintedImage.image) };
+          if (paintedImage.reference) encodedXObjects.set(paintedImage.reference, encoded);
+        }
+        totalPixels += encoded.dimensions.pixels;
+        const bounds = getTransformedUnitBounds(transform);
+        images.push({
+          dataUrl: encoded.dataUrl,
+          x: bounds.left,
+          y: bounds.top,
+          width: bounds.width,
+          height: bounds.height,
+          size: encoded.size,
+          mimeType: "image/png",
+          pageWidth: viewport.width / viewport.scale,
+          pageHeight: viewport.height / viewport.scale,
+          transform: [...transform]
+        });
+      } catch (error) {
+        options.throwIfDestroyed();
+        options.throwIfAborted(options.signal);
+        if (shouldPropagateEmbeddedImageError(error)) throw error;
+        const label = readOperationLabel(operation, operators.argsArray[index], index);
+        warn(options.logger, `Failed to extract embedded image ${label}.`, error);
+      }
     }
+  } finally {
+    encodedXObjects.clear();
   }
   return images;
 }
+function readImageReference(args) {
+  const reference = Array.isArray(args) ? args[0] : void 0;
+  return typeof reference === "string" ? reference : void 0;
+}
 async function resolvePaintedImage(page, operation, args, index) {
   if (operation === OPS.paintInlineImageXObject) {
     const inlineImage = Array.isArray(args) ? args[0] : void 0;
     if (!inlineImage || typeof inlineImage !== "object") return void 0;
     return { image: inlineImage, label: `inline@${index}` };
   }
-  const reference = Array.isArray(args) ? args[0] : void 0;
-  if (typeof reference !== "string") return void 0;
+  const reference = readImageReference(args);
+  if (!reference) return void 0;
   const image = await page.objs.get(reference);
-  return { image, label: reference };
+  return { image, label: reference, reference };
 }
-function imageToDataUrl(image, options) {
-  const width = image.width;
-  const height = image.height;
-  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
-    return void 0;
-  }
-  const canvas = allocateCanvas(width, height, options.maxPixels, options.createCanvas);
+function imageToDataUrl(image, dimensions, options) {
+  const canvas = allocateCanvas(dimensions.width, dimensions.height, options.maxPixels, options.createCanvas);
   try {
     const context = canvas.getContext("2d");
     if (!context) return void 0;
@@ -139,9 +173,9 @@ function imageToDataUrl(image, options) {
     }
     if (!ArrayBuffer.isView(image.data)) return void 0;
     const source = new Uint8ClampedArray(image.data.buffer, image.data.byteOffset, image.data.byteLength);
-    const rgba = toRgba(source, width, height);
+    const rgba = toRgba(source, dimensions);
     if (!rgba) return void 0;
-    const pixels = context.createImageData(width, height);
+    const pixels = context.createImageData(dimensions.width, dimensions.height);
     pixels.data.set(rgba);
     context.putImageData(pixels, 0, 0);
     return canvas.toDataURL("image/png");
@@ -149,13 +183,17 @@ function imageToDataUrl(image, options) {
     releaseCanvas(canvas);
   }
 }
-function toRgba(data, width, height) {
-  const pixels = width * height;
-  if (data.length === pixels * 4) return data;
-  if (data.length !== pixels && data.length !== pixels * 3) return void 0;
-  const channels = data.length / pixels;
-  const rgba = new Uint8ClampedArray(pixels * 4);
-  for (let pixel = 0; pixel < pixels; pixel += 1) {
+function toRgba(data, dimensions) {
+  const rgbaLength = multiplySafe(dimensions.pixels, 4);
+  const rgbLength = multiplySafe(dimensions.pixels, 3);
+  if (rgbaLength === void 0 || rgbLength === void 0) {
+    throw new PdfReaderError("IMAGE_LIMIT_EXCEEDED", "embedded image has unsafe decoded pixel dimensions.");
+  }
+  if (data.length === rgbaLength) return data;
+  if (data.length !== dimensions.pixels && data.length !== rgbLength) return void 0;
+  const channels = data.length / dimensions.pixels;
+  const rgba = new Uint8ClampedArray(rgbaLength);
+  for (let pixel = 0; pixel < dimensions.pixels; pixel += 1) {
     const input = pixel * channels;
     const output = pixel * 4;
     rgba[output] = data[input];
@@ -165,11 +203,52 @@ function toRgba(data, width, height) {
   }
   return rgba;
 }
+function enforceOperatorLimit(count, limit) {
+  if (!Number.isSafeInteger(count) || count > limit) {
+    throw new PdfReaderError("OPERATOR_LIMIT_EXCEEDED", `PDF page has ${count} operators; limit is ${limit}.`);
+  }
+}
+function enforceNextImageLimits(currentImageCount, currentTotalPixels, nextPixels, options) {
+  const nextImageCount = currentImageCount + 1;
+  if (!Number.isSafeInteger(nextImageCount) || nextImageCount > options.maxImages) {
+    throw new PdfReaderError(
+      "IMAGE_COUNT_LIMIT_EXCEEDED",
+      `PDF page has more than ${options.maxImages} extractable embedded images.`
+    );
+  }
+  const nextTotalPixels = currentTotalPixels + nextPixels;
+  if (!Number.isSafeInteger(nextTotalPixels) || nextTotalPixels > options.maxTotalPixels) {
+    throw new PdfReaderError(
+      "IMAGE_TOTAL_PIXELS_LIMIT_EXCEEDED",
+      `PDF page embedded images require more than ${options.maxTotalPixels} decoded pixels.`
+    );
+  }
+}
+function readImageDimensions(image, limit) {
+  const { width, height } = image;
+  if (width === void 0 || height === void 0) return void 0;
+  if (typeof width !== "number" || typeof height !== "number") return void 0;
+  const pixelWidth = Math.ceil(width);
+  const pixelHeight = Math.ceil(height);
+  const pixels = multiplySafe(pixelWidth, pixelHeight);
+  if (pixelWidth <= 0 || pixelHeight <= 0 || pixels === void 0 || pixels > limit) {
+    throw new PdfReaderError("IMAGE_LIMIT_EXCEEDED", `embedded image requires ${pixels} pixels; limit is ${limit}.`);
+  }
+  return { width: pixelWidth, height: pixelHeight, pixels };
+}
+function isSupportedImageSource(image) {
+  return typeof ImageBitmap !== "undefined" && image.bitmap instanceof ImageBitmap || ArrayBuffer.isView(image.data);
+}
+function multiplySafe(left, right) {
+  if (!Number.isSafeInteger(left) || !Number.isSafeInteger(right)) return void 0;
+  const product = left * right;
+  return Number.isSafeInteger(product) ? product : void 0;
+}
 function allocateCanvas(width, height, limit, createCanvas) {
   const pixelWidth = Math.ceil(width);
   const pixelHeight = Math.ceil(height);
-  const pixels = pixelWidth * pixelHeight;
-  if (!Number.isSafeInteger(pixels) || pixels > limit) {
+  const pixels = multiplySafe(pixelWidth, pixelHeight);
+  if (pixels === void 0 || pixels > limit) {
     throw new PdfReaderError("IMAGE_LIMIT_EXCEEDED", `embedded image requires ${pixels} pixels; limit is ${limit}.`);
   }
   const canvas = createCanvas();
@@ -266,10 +345,15 @@ function validatePageRange(pageRange) {
 // src/PDFReader.ts
 var defaultLimits = {
   maxDocumentPages: 1e3,
+  maxTextItems: 5e4,
+  maxTextCodeUnits: 5e6,
+  maxOperatorCount: 1e5,
   maxCanvasPixels: 4e7,
-  maxEmbeddedImagePixels: 25e6
+  maxEmbeddedImagePixels: 25e6,
+  maxEmbeddedImages: 1e3,
+  maxEmbeddedImagePixelsTotal: 1e8
 };
-var _source, _createCanvas, _logger, _limits, _sourcePolicy, _loadingState, _loadingTask, _document, _destroyPromise, _activeRenderTasks, _activePageWorkCount, _destroyed, _lastLoadFailed, _PDFReader_instances, load_fn, processPage_fn, encodePageImage_fn, resolveViewport_fn, encodeCanvasToBlob_fn, allocateCanvas_fn, waitForRender_fn, releaseCanvas_fn, getOrCreateLoadState_fn, awaitWithSignal_fn, createAbortedError_fn, createDestroyedError_fn, createDeadlineExceededError_fn, createUnsupportedEnvironmentError_fn, rethrowLifecycleError_fn, throwIfDestroyed_fn, throwIfAborted_fn, resolveLoadOptions_fn, isAbortSignal_fn, enforceSourcePolicy_fn, isPromiseLike_fn, inspectSource_fn, toPdfJsSource_fn, isPdfTypedArray_fn, knownByteLength_fn, readUrl_fn, readHttpHeaders_fn, validateLimits_fn;
+var _source, _createCanvas, _logger, _limits, _sourcePolicy, _loadingState, _loadingTask, _document, _destroyPromise, _destroyController, _activeRenderTasks, _activePageOperation, _activePageWorkCount, _destroyed, _lastLoadFailed, _PDFReader_instances, load_fn, processPage_fn, enforceTextLimits_fn, encodePageImage_fn, resolveViewport_fn, encodeCanvasToBlob_fn, allocateCanvas_fn, waitForRender_fn, releaseCanvas_fn, acquirePageOperation_fn, releasePageOperation_fn, getOrCreateLoadState_fn, destroyLoadStateTask_fn, awaitWithSignal_fn, awaitWithDestroy_fn, createAbortedError_fn, createDestroyedError_fn, createDeadlineExceededError_fn, createUnsupportedEnvironmentError_fn, rethrowLifecycleError_fn, throwIfDestroyed_fn, throwIfAborted_fn, resolveLoadOptions_fn, isAbortSignal_fn, enforceSourcePolicy_fn, createSourceSnapshot_fn, inspectSource_fn, sourceKind_fn, toPdfJsSource_fn, freezeSource_fn, isPdfTypedArray_fn, knownByteLength_fn, readUrl_fn, readHttpHeaders_fn, validateLimits_fn;
 var PDFReader = class {
   constructor(source, options = {}) {
     __privateAdd(this, _PDFReader_instances);
@@ -282,7 +366,9 @@ var PDFReader = class {
     __privateAdd(this, _loadingTask);
     __privateAdd(this, _document);
     __privateAdd(this, _destroyPromise);
+    __privateAdd(this, _destroyController, new AbortController());
     __privateAdd(this, _activeRenderTasks, /* @__PURE__ */ new Set());
+    __privateAdd(this, _activePageOperation, false);
     __privateAdd(this, _activePageWorkCount, 0);
     __privateAdd(this, _destroyed, false);
     __privateAdd(this, _lastLoadFailed, false);
@@ -299,7 +385,7 @@ var PDFReader = class {
   /** Current lifecycle state for load, iteration/rendering, retry, and teardown boundaries. */
   get state() {
     if (__privateGet(this, _destroyed)) return "destroyed";
-    if (__privateGet(this, _activePageWorkCount) > 0) return "iterating";
+    if (__privateGet(this, _activePageOperation) || __privateGet(this, _activePageWorkCount) > 0) return "iterating";
     if (__privateGet(this, _document)) return "loaded";
     if (__privateGet(this, _loadingState)) return "loading";
     if (__privateGet(this, _lastLoadFailed)) return "failed";
@@ -314,37 +400,43 @@ var PDFReader = class {
   }
   /** Streams page results so callers do not need to retain the entire document conversion in memory. */
   async *pages(options = {}) {
-    __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
-    const documentProxy = __privateGet(this, _document);
-    if (!documentProxy) {
-      throw new PdfReaderError("DOCUMENT_NOT_LOADED", "Document not loaded. Call load() first.");
-    }
-    const resolved = resolveConvertOptions(options);
-    const [start, end] = resolvePageNumbers(resolved.pageRange, documentProxy.numPages);
-    if (start > documentProxy.numPages) {
-      throw new PdfReaderError("INVALID_OPTION", `pageRange starts after the last page (${documentProxy.numPages}).`);
-    }
-    for (let pageNumber = start; pageNumber <= Math.min(end, documentProxy.numPages); pageNumber += 1) {
-      __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
-      __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, resolved.signal);
-      let page;
-      let ownsActivePageWork = false;
-      try {
-        __privateSet(this, _activePageWorkCount, __privateGet(this, _activePageWorkCount) + 1);
-        ownsActivePageWork = true;
-        page = await documentProxy.getPage(pageNumber);
-        const result = await __privateMethod(this, _PDFReader_instances, processPage_fn).call(this, page, pageNumber, documentProxy.numPages, resolved);
-        page.cleanup();
-        page = void 0;
-        __privateSet(this, _activePageWorkCount, __privateGet(this, _activePageWorkCount) - 1);
-        ownsActivePageWork = false;
-        yield result;
-      } catch (error) {
-        __privateMethod(this, _PDFReader_instances, rethrowLifecycleError_fn).call(this, error, resolved.signal);
-      } finally {
-        if (ownsActivePageWork) __privateSet(this, _activePageWorkCount, __privateGet(this, _activePageWorkCount) - 1);
-        page?.cleanup();
+    let ownsPageOperation = false;
+    try {
+      __privateMethod(this, _PDFReader_instances, acquirePageOperation_fn).call(this);
+      ownsPageOperation = true;
+      const documentProxy = __privateGet(this, _document);
+      if (!documentProxy) {
+        throw new PdfReaderError("DOCUMENT_NOT_LOADED", "Document not loaded. Call load() first.");
+      }
+      const resolved = resolveConvertOptions(options);
+      const [start, end] = resolvePageNumbers(resolved.pageRange, documentProxy.numPages);
+      if (start > documentProxy.numPages) {
+        throw new PdfReaderError("INVALID_OPTION", `pageRange starts after the last page (${documentProxy.numPages}).`);
+      }
+      for (let pageNumber = start; pageNumber <= Math.min(end, documentProxy.numPages); pageNumber += 1) {
+        __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
+        __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, resolved.signal);
+        let page;
+        let ownsActivePageWork = false;
+        try {
+          __privateSet(this, _activePageWorkCount, __privateGet(this, _activePageWorkCount) + 1);
+          ownsActivePageWork = true;
+          page = await documentProxy.getPage(pageNumber);
+          const result = await __privateMethod(this, _PDFReader_instances, processPage_fn).call(this, page, pageNumber, documentProxy.numPages, resolved);
+          page.cleanup();
+          page = void 0;
+          __privateSet(this, _activePageWorkCount, __privateGet(this, _activePageWorkCount) - 1);
+          ownsActivePageWork = false;
+          yield result;
+        } catch (error) {
+          __privateMethod(this, _PDFReader_instances, rethrowLifecycleError_fn).call(this, error, resolved.signal);
+        } finally {
+          if (ownsActivePageWork) __privateSet(this, _activePageWorkCount, __privateGet(this, _activePageWorkCount) - 1);
+          page?.cleanup();
+        }
       }
+    } finally {
+      if (ownsPageOperation) __privateMethod(this, _PDFReader_instances, releasePageOperation_fn).call(this);
     }
   }
   /** Collects `pages()` into an array. Prefer `pages()` for large documents. */
@@ -357,6 +449,7 @@ var PDFReader = class {
   async destroy() {
     if (__privateGet(this, _destroyPromise)) return __privateGet(this, _destroyPromise);
     __privateSet(this, _destroyed, true);
+    __privateGet(this, _destroyController).abort();
     const loadingTask = __privateGet(this, _loadingTask);
     const loadingState = __privateGet(this, _loadingState);
     __privateSet(this, _loadingTask, void 0);
@@ -370,8 +463,7 @@ var PDFReader = class {
       }
       if (!loadingState) return;
       loadingState.destroyed = true;
-      loadingState.destroyPromise ?? (loadingState.destroyPromise = loadingState.task ? loadingState.task.destroy() : Promise.resolve());
-      await loadingState.destroyPromise;
+      await __privateMethod(this, _PDFReader_instances, destroyLoadStateTask_fn).call(this, loadingState);
     })());
     await __privateGet(this, _destroyPromise);
   }
@@ -385,7 +477,9 @@ _loadingState = new WeakMap();
 _loadingTask = new WeakMap();
 _document = new WeakMap();
 _destroyPromise = new WeakMap();
+_destroyController = new WeakMap();
 _activeRenderTasks = new WeakMap();
+_activePageOperation = new WeakMap();
 _activePageWorkCount = new WeakMap();
 _destroyed = new WeakMap();
 _lastLoadFailed = new WeakMap();
@@ -416,7 +510,9 @@ processPage_fn = async function(page, pageNumber, numPages, options) {
   __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
   if (options.includeText) {
     try {
-      result.text = await page.getTextContent();
+      const text = await page.getTextContent();
+      __privateMethod(this, _PDFReader_instances, enforceTextLimits_fn).call(this, text);
+      result.text = text;
     } catch (error) {
       __privateMethod(this, _PDFReader_instances, rethrowLifecycleError_fn).call(this, error, options.signal);
     }
@@ -429,6 +525,9 @@ processPage_fn = async function(page, pageNumber, numPages, options) {
         signal: options.signal,
         createCanvas: __privateGet(this, _createCanvas),
         maxPixels: __privateGet(this, _limits).maxEmbeddedImagePixels,
+        maxImages: __privateGet(this, _limits).maxEmbeddedImages,
+        maxTotalPixels: __privateGet(this, _limits).maxEmbeddedImagePixelsTotal,
+        maxOperators: __privateGet(this, _limits).maxOperatorCount,
         logger: __privateGet(this, _logger),
         throwIfAborted: (signal) => __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, signal),
         throwIfDestroyed: () => __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this)
@@ -455,6 +554,30 @@ processPage_fn = async function(page, pageNumber, numPages, options) {
   }
   return result;
 };
+enforceTextLimits_fn = function(text) {
+  const items = text.items;
+  if (!Array.isArray(items) || !Number.isSafeInteger(items.length)) {
+    throw new PdfReaderError("TEXT_LIMIT_EXCEEDED", "PDF text content has an unsafe item count.");
+  }
+  if (items.length > __privateGet(this, _limits).maxTextItems) {
+    throw new PdfReaderError(
+      "TEXT_LIMIT_EXCEEDED",
+      `PDF page has ${items.length} text items; limit is ${__privateGet(this, _limits).maxTextItems}.`
+    );
+  }
+  let codeUnits = 0;
+  for (const item of items) {
+    const value = item && typeof item === "object" ? item.str : void 0;
+    if (typeof value !== "string") continue;
+    codeUnits += value.length;
+    if (!Number.isSafeInteger(codeUnits) || codeUnits > __privateGet(this, _limits).maxTextCodeUnits) {
+      throw new PdfReaderError(
+        "TEXT_LIMIT_EXCEEDED",
+        `PDF page text has more than ${__privateGet(this, _limits).maxTextCodeUnits} string code units.`
+      );
+    }
+  }
+};
 encodePageImage_fn = async function(canvas, mimeType, output, jpegQuality, signal) {
   __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
   __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, signal);
@@ -481,11 +604,16 @@ encodeCanvasToBlob_fn = async function(canvas, mimeType, quality, signal) {
   if (typeof canvas.toBlob !== "function") {
     throw __privateMethod(this, _PDFReader_instances, createUnsupportedEnvironmentError_fn).call(this, "Canvas Blob encoding is not supported by this canvas implementation.");
   }
+  __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
   __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, signal);
   return await new Promise((resolve, reject) => {
     let settled = false;
     const onAbort = () => settle(() => reject(__privateMethod(this, _PDFReader_instances, createAbortedError_fn).call(this)));
-    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    const onDestroy = () => settle(() => reject(__privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this)));
+    const cleanup = () => {
+      signal?.removeEventListener("abort", onAbort);
+      __privateGet(this, _destroyController).signal.removeEventListener("abort", onDestroy);
+    };
     const settle = (callback) => {
       if (settled) return;
       settled = true;
@@ -493,6 +621,7 @@ encodeCanvasToBlob_fn = async function(canvas, mimeType, quality, signal) {
       callback();
     };
     signal?.addEventListener("abort", onAbort, { once: true });
+    __privateGet(this, _destroyController).signal.addEventListener("abort", onDestroy, { once: true });
     try {
       const resolveBlob = (blob) => {
         if (!blob) {
@@ -531,7 +660,7 @@ waitForRender_fn = async function(renderTask, signal) {
   __privateGet(this, _activeRenderTasks).add(renderTask);
   signal?.addEventListener("abort", abort, { once: true });
   try {
-    await renderTask.promise;
+    await __privateMethod(this, _PDFReader_instances, awaitWithSignal_fn).call(this, renderTask.promise, signal);
     __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
     __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, signal);
   } catch (error) {
@@ -545,6 +674,19 @@ releaseCanvas_fn = function(canvas) {
   canvas.width = 0;
   canvas.height = 0;
 };
+acquirePageOperation_fn = function() {
+  __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
+  if (__privateGet(this, _activePageOperation)) {
+    throw new PdfReaderError(
+      "OPERATION_IN_PROGRESS",
+      "Another pages() or convert() operation is already active for this PDFReader."
+    );
+  }
+  __privateSet(this, _activePageOperation, true);
+};
+releasePageOperation_fn = function() {
+  __privateSet(this, _activePageOperation, false);
+};
 getOrCreateLoadState_fn = function() {
   const existing = __privateGet(this, _loadingState);
   if (existing) return existing;
@@ -552,32 +694,45 @@ getOrCreateLoadState_fn = function() {
   const state = { destroyed: false };
   state.promise = (async () => {
     try {
-      const policyResult = __privateMethod(this, _PDFReader_instances, enforceSourcePolicy_fn).call(this);
-      if (__privateMethod(this, _PDFReader_instances, isPromiseLike_fn).call(this, policyResult)) await policyResult;
+      const source = __privateMethod(this, _PDFReader_instances, createSourceSnapshot_fn).call(this);
+      const policyResult = __privateMethod(this, _PDFReader_instances, enforceSourcePolicy_fn).call(this, source.info);
+      if (policyResult) await __privateMethod(this, _PDFReader_instances, awaitWithDestroy_fn).call(this, policyResult);
       if (state.destroyed || __privateGet(this, _destroyed)) {
         throw __privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this);
       }
-      const task = getDocument(__privateMethod(this, _PDFReader_instances, toPdfJsSource_fn).call(this, __privateGet(this, _source)));
+      const task = getDocument(source.pdfJsSource);
       state.task = task;
-      const documentProxy = await task.promise;
-      if (state.destroyed || state.destroyPromise) {
-        await state.destroyPromise?.catch(() => void 0);
+      let documentProxy;
+      try {
+        documentProxy = await __privateMethod(this, _PDFReader_instances, awaitWithDestroy_fn).call(this, task.promise);
+      } catch (error) {
+        if (state.destroyed || __privateGet(this, _destroyed)) {
+          await state.destroyPromise?.catch(() => void 0);
+          throw __privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this);
+        }
+        await __privateMethod(this, _PDFReader_instances, destroyLoadStateTask_fn).call(this, state).catch(() => void 0);
+        throw error;
+      }
+      if (state.destroyed) {
+        await __privateMethod(this, _PDFReader_instances, destroyLoadStateTask_fn).call(this, state).catch(() => void 0);
         throw __privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this);
       }
       if (documentProxy.numPages > __privateGet(this, _limits).maxDocumentPages) {
-        await task.destroy();
-        throw new PdfReaderError(
+        const error = new PdfReaderError(
           "PAGE_LIMIT_EXCEEDED",
           `PDF has ${documentProxy.numPages} pages; limit is ${__privateGet(this, _limits).maxDocumentPages}.`
         );
+        await __privateMethod(this, _PDFReader_instances, destroyLoadStateTask_fn).call(this, state).catch(() => void 0);
+        throw error;
       }
       __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
+      state.task = void 0;
       __privateSet(this, _loadingTask, task);
       __privateSet(this, _document, documentProxy);
       __privateSet(this, _lastLoadFailed, false);
       return documentProxy;
     } catch (error) {
-      if (state.destroyed || state.destroyPromise || __privateGet(this, _destroyed)) {
+      if (state.destroyed || __privateGet(this, _destroyed)) {
         await state.destroyPromise?.catch(() => void 0);
         throw __privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this);
       }
@@ -591,14 +746,23 @@ getOrCreateLoadState_fn = function() {
   __privateSet(this, _loadingState, state);
   return state;
 };
+destroyLoadStateTask_fn = function(state) {
+  if (state.destroyPromise) return state.destroyPromise;
+  const task = state.task;
+  state.task = void 0;
+  state.destroyPromise = task ? Promise.resolve(task.destroy()) : Promise.resolve();
+  return state.destroyPromise;
+};
 awaitWithSignal_fn = async function(promise, signal, deadlineMs) {
   __privateMethod(this, _PDFReader_instances, throwIfAborted_fn).call(this, signal);
-  if (!signal && deadlineMs === void 0) return promise;
+  __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
   return await new Promise((resolve, reject) => {
     let settled = false;
     const onAbort = () => settle(() => reject(__privateMethod(this, _PDFReader_instances, createAbortedError_fn).call(this)));
+    const onDestroy = () => settle(() => reject(__privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this)));
     const cleanup = () => {
       signal?.removeEventListener("abort", onAbort);
+      __privateGet(this, _destroyController).signal.removeEventListener("abort", onDestroy);
       if (timer !== void 0) clearTimeout(timer);
     };
     const settle = (callback) => {
@@ -609,12 +773,32 @@ awaitWithSignal_fn = async function(promise, signal, deadlineMs) {
     };
     const timer = deadlineMs === void 0 ? void 0 : setTimeout(() => settle(() => reject(__privateMethod(this, _PDFReader_instances, createDeadlineExceededError_fn).call(this))), deadlineMs);
     signal?.addEventListener("abort", onAbort, { once: true });
+    __privateGet(this, _destroyController).signal.addEventListener("abort", onDestroy, { once: true });
     promise.then(
       (value) => settle(() => resolve(value)),
       (error) => settle(() => reject(error))
     ).catch(() => void 0);
   });
 };
+awaitWithDestroy_fn = async function(promise) {
+  __privateMethod(this, _PDFReader_instances, throwIfDestroyed_fn).call(this);
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const onDestroy = () => settle(() => reject(__privateMethod(this, _PDFReader_instances, createDestroyedError_fn).call(this)));
+    const cleanup = () => __privateGet(this, _destroyController).signal.removeEventListener("abort", onDestroy);
+    const settle = (callback) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    __privateGet(this, _destroyController).signal.addEventListener("abort", onDestroy, { once: true });
+    Promise.resolve(promise).then(
+      (value) => settle(() => resolve(value)),
+      (error) => settle(() => reject(error))
+    );
+  });
+};
 createAbortedError_fn = function() {
   return new PdfReaderError("ABORTED", "PDF operation was aborted.");
 };
@@ -649,8 +833,7 @@ resolveLoadOptions_fn = function(options) {
 isAbortSignal_fn = function(value) {
   return "aborted" in value && "addEventListener" in value && "removeEventListener" in value;
 };
-enforceSourcePolicy_fn = function() {
-  const source = __privateMethod(this, _PDFReader_instances, inspectSource_fn).call(this, __privateGet(this, _source));
+enforceSourcePolicy_fn = function(source) {
   if (source.byteLength !== void 0 && __privateGet(this, _limits).maxSourceBytes !== void 0 && source.byteLength > __privateGet(this, _limits).maxSourceBytes) {
     throw new PdfReaderError(
       "SOURCE_LIMIT_EXCEEDED",
@@ -660,8 +843,8 @@ enforceSourcePolicy_fn = function() {
   if (!__privateGet(this, _sourcePolicy)) return;
   try {
     const result = __privateGet(this, _sourcePolicy).call(this, source);
-    if (!__privateMethod(this, _PDFReader_instances, isPromiseLike_fn).call(this, result)) return;
-    return result.catch((error) => {
+    if (result === void 0) return;
+    return Promise.resolve(result).catch((error) => {
       if (error instanceof PdfReaderError) throw error;
       throw new PdfReaderError("SOURCE_POLICY_VIOLATION", "PDF source rejected by sourcePolicy.");
     });
@@ -670,56 +853,52 @@ enforceSourcePolicy_fn = function() {
     throw new PdfReaderError("SOURCE_POLICY_VIOLATION", "PDF source rejected by sourcePolicy.");
   }
 };
-isPromiseLike_fn = function(value) {
-  return value instanceof Promise;
+createSourceSnapshot_fn = function() {
+  const kind = __privateMethod(this, _PDFReader_instances, sourceKind_fn).call(this, __privateGet(this, _source));
+  const pdfJsSource = __privateMethod(this, _PDFReader_instances, toPdfJsSource_fn).call(this, __privateGet(this, _source));
+  const info = __privateMethod(this, _PDFReader_instances, inspectSource_fn).call(this, pdfJsSource, kind);
+  return { pdfJsSource, info };
+};
+inspectSource_fn = function(source, kind) {
+  const headers = __privateMethod(this, _PDFReader_instances, readHttpHeaders_fn).call(this, source.httpHeaders);
+  const info = {
+    rawSource: source,
+    kind,
+    url: __privateMethod(this, _PDFReader_instances, readUrl_fn).call(this, source.url),
+    byteLength: __privateMethod(this, _PDFReader_instances, knownByteLength_fn).call(this, source.data),
+    hasHttpHeaders: headers.hasHttpHeaders,
+    httpHeaders: headers.httpHeaders,
+    withCredentials: source.withCredentials === true
+  };
+  return Object.freeze(info);
 };
-inspectSource_fn = function(source) {
+sourceKind_fn = function(source) {
+  if (typeof source === "string") return "url";
+  if (typeof URL !== "undefined" && source instanceof URL) return "url";
+  if (source instanceof ArrayBuffer || __privateMethod(this, _PDFReader_instances, isPdfTypedArray_fn).call(this, source) || Array.isArray(source)) return "bytes";
+  return "document-init-parameters";
+};
+toPdfJsSource_fn = function(source) {
   if (typeof source === "string") {
-    return {
-      rawSource: source,
-      kind: "url",
-      url: source,
-      hasHttpHeaders: false,
-      withCredentials: false
-    };
+    return __privateMethod(this, _PDFReader_instances, freezeSource_fn).call(this, { url: source });
   }
   if (typeof URL !== "undefined" && source instanceof URL) {
-    return {
-      rawSource: source,
-      kind: "url",
-      url: source.toString(),
-      hasHttpHeaders: false,
-      withCredentials: false
-    };
+    return __privateMethod(this, _PDFReader_instances, freezeSource_fn).call(this, { url: source.toString() });
   }
-  const byteLength = __privateMethod(this, _PDFReader_instances, knownByteLength_fn).call(this, source);
-  if (byteLength !== void 0) {
-    return {
-      rawSource: source,
-      kind: "bytes",
-      byteLength,
-      hasHttpHeaders: false,
-      withCredentials: false
-    };
+  if (source instanceof ArrayBuffer || __privateMethod(this, _PDFReader_instances, isPdfTypedArray_fn).call(this, source) || Array.isArray(source)) {
+    return __privateMethod(this, _PDFReader_instances, freezeSource_fn).call(this, { data: source });
   }
-  const candidate = source;
-  const headers = __privateMethod(this, _PDFReader_instances, readHttpHeaders_fn).call(this, candidate.httpHeaders);
-  return {
-    rawSource: source,
-    kind: "document-init-parameters",
-    url: __privateMethod(this, _PDFReader_instances, readUrl_fn).call(this, candidate.url),
-    byteLength: __privateMethod(this, _PDFReader_instances, knownByteLength_fn).call(this, candidate.data),
-    hasHttpHeaders: headers !== void 0,
-    httpHeaders: headers,
-    withCredentials: candidate.withCredentials === true
-  };
+  const snapshot = {};
+  for (const key of Reflect.ownKeys(source)) {
+    const descriptor = Object.getOwnPropertyDescriptor(source, key);
+    if (!descriptor?.enumerable) continue;
+    snapshot[key] = source[key];
+  }
+  if (typeof URL !== "undefined" && snapshot.url instanceof URL) snapshot.url = snapshot.url.toString();
+  return __privateMethod(this, _PDFReader_instances, freezeSource_fn).call(this, snapshot);
 };
-toPdfJsSource_fn = function(source) {
-  if (typeof source === "string") return { url: source };
-  if (source instanceof URL) return { url: source };
-  if (source instanceof ArrayBuffer || __privateMethod(this, _PDFReader_instances, isPdfTypedArray_fn).call(this, source) || Array.isArray(source))
-    return { data: source };
-  return source;
+freezeSource_fn = function(source) {
+  return Object.freeze(source);
 };
 isPdfTypedArray_fn = function(source) {
   return ArrayBuffer.isView(source) && !(source instanceof DataView);
@@ -736,10 +915,24 @@ readUrl_fn = function(value) {
   return void 0;
 };
 readHttpHeaders_fn = function(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
-  const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
-  if (entries.length === 0) return void 0;
-  return Object.freeze(Object.fromEntries(entries));
+  if (!value || typeof value !== "object") return { hasHttpHeaders: false };
+  const entries = [];
+  try {
+    for (const [name, headerValue] of Object.entries(value)) {
+      if (typeof headerValue === "string") entries.push([name, headerValue]);
+    }
+    if ("forEach" in value && typeof value.forEach === "function") {
+      value.forEach((headerValue, name) => {
+        if (typeof name === "string" && typeof headerValue === "string") entries.push([name, headerValue]);
+      });
+    }
+  } catch {
+    return { hasHttpHeaders: true };
+  }
+  return {
+    hasHttpHeaders: true,
+    httpHeaders: entries.length > 0 ? Object.freeze(Object.fromEntries(entries)) : void 0
+  };
 };
 validateLimits_fn = function() {
   for (const [name, value] of Object.entries(__privateGet(this, _limits))) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/pdf-reader",
   "description": "Resource-safe browser PDF rendering, text extraction, and embedded-image extraction built on PDF.js",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/pdf-reader",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "sideEffects": false,
   "keywords": [
     "pdf",
@@ -26,7 +26,7 @@
     "node": ">=22.13.0"
   },
   "peerDependencies": {
-    "pdfjs-dist": "^6.2.108"
+    "pdfjs-dist": "~6.2.108"
   },
   "files": [
     "**/*",