@web-ts-toolkit/pdf-reader 0.37.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright Junmin Ahn
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,253 @@
+# `@web-ts-toolkit/pdf-reader`
+
+Resource-safe browser PDF rendering, text extraction, and best-effort embedded-image extraction built on PDF.js.
+
+## Installation
+
+```sh
+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.
+
+Canonical imports use named exports from the package root. There is no default export, no supported deep import, and no supported CommonJS `require()` entry.
+
+## Unreleased Migration
+
+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.                                                       |
+
+The repository `CHANGELOG.md` contains the same release-level migration summary.
+
+## 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.
+
+Vite example:
+
+```ts
+import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?url';
+import { configurePdfWorker } from '@web-ts-toolkit/pdf-reader';
+
+configurePdfWorker(workerUrl);
+```
+
+Alternatively, pass an existing module `Worker`:
+
+```ts
+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.
+
+## Quick Start
+
+```ts
+import { PDFReader } from '@web-ts-toolkit/pdf-reader';
+
+const bytes = new Uint8Array(await file.arrayBuffer());
+const reader = new PDFReader(bytes);
+
+try {
+  await reader.load({ deadlineMs: 15_000 });
+
+  for await (const page of reader.pages({
+    includeText: true,
+    includePageImage: true,
+    pageImageOutput: 'blob',
+    imageFormat: 'image/jpeg',
+    jpegQuality: 0.85,
+  })) {
+    console.log(page.pageNumber, page.text, page.pageImage);
+  }
+} finally {
+  await reader.destroy();
+}
+```
+
+Use `pages()` for large PDFs because it lets the caller consume and release each result incrementally. `convert(options)` provides the same results as an array for small documents.
+
+For a remote PDF, use `pdfUrlSource(...)` to create constructor-ready PDF.js loading data:
+
+```ts
+import { PDFReader, pdfUrlSource } from '@web-ts-toolkit/pdf-reader';
+
+const reader = new PDFReader(
+  pdfUrlSource('https://static.example.com/document.pdf', {
+    withCredentials: false,
+  }),
+);
+```
+
+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`.
+
+## Reader State And Ownership
+
+`reader.state` exposes the public lifecycle:
+
+| State       | Meaning                                                                              | Legal next states               |
+| ----------- | ------------------------------------------------------------------------------------ | ------------------------------- |
+| `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`           |
+| `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.
+- 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.
+
+## Options
+
+```ts
+const pages = await reader.convert({
+  pageRange: [2, 5],
+  viewportScale: (width, height) => (width > height ? 1 : 1.5),
+  imageFormat: 'image/png',
+  includePageImage: true,
+  includeText: true,
+  includeEmbeddedImages: false,
+  signal: abortController.signal,
+});
+```
+
+- `pageRange`: one 1-based page number or an inclusive tuple. Reversed tuples are accepted and normalized.
+- `viewportScale`: positive number or page-size callback; defaults to `1.5`.
+- `imageFormat`: `image/png` or `image/jpeg`; defaults to PNG.
+- `jpegQuality`: finite number from `0` through `1`; defaults to `0.92`. It is applied only when `imageFormat` is `image/jpeg`; PNG output ignores it.
+- `includePageImage`: render the complete page and include it under `page.pageImage`; defaults to `true`.
+- `pageImageOutput`: `data-url` or `blob`; defaults to `data-url`.
+- `includeText`: include PDF.js `TextContent`; defaults to `true`.
+- `includeEmbeddedImages`: inspect the operator stream for raster images; defaults to `false`.
+- `signal`: cancels active rendering and stops before subsequent expensive operations.
+
+`pageImage` is a discriminated union so the output mode and payload cannot contradict each other:
+
+```ts
+if (page.pageImage?.kind === 'blob') {
+  const objectUrl = URL.createObjectURL(page.pageImage.blob);
+  try {
+    preview.src = objectUrl;
+  } finally {
+    URL.revokeObjectURL(objectUrl);
+  }
+}
+
+if (page.pageImage?.kind === 'data-url') {
+  preview.src = page.pageImage.dataUrl;
+}
+```
+
+This package returns `Blob` objects directly rather than object URLs so callers keep explicit ownership of any `URL.createObjectURL(...)` lifecycle.
+
+## 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.
+
+Run it with:
+
+```sh
+pnpm --filter @web-ts-toolkit/pdf-reader benchmark
+```
+
+The recorded local run on Headless Chromium `151.0.7922.34` showed bounded overlap materially improving the synthetic `long.pdf` (`207.1 ms` to `107.3 ms`) and `image-heavy.pdf` (`62.3 ms` to `39.3 ms`) fixtures, while `text-heavy.pdf` stayed effectively flat (`69.7 ms` to `72.5 ms`) and peak active pages/canvases deterministically doubled from `1/1` to `2/2`.
+
+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.
+
+## Resource Limits
+
+Defaults reject documents above 1,000 pages, rendered pages above 40 megapixels, and copied embedded images above 25 megapixels.
+
+```ts
+import { PDFReader, PdfReaderError } from '@web-ts-toolkit/pdf-reader';
+
+const reader = new PDFReader(bytes, {
+  limits: {
+    maxSourceBytes: 25_000_000,
+    maxDocumentPages: 250,
+    maxCanvasPixels: 20_000_000,
+    maxEmbeddedImagePixels: 10_000_000,
+  },
+  sourcePolicy(source) {
+    if (source.url && !source.url.startsWith('https://static.example.com/')) {
+      throw new PdfReaderError('SOURCE_POLICY_VIOLATION', 'Remote PDF source rejected by sourcePolicy.');
+    }
+    if (source.withCredentials || source.hasHttpHeaders) {
+      throw new PdfReaderError(
+        'SOURCE_POLICY_VIOLATION',
+        'Credentialed or header-bearing PDF sources are not allowed.',
+      );
+    }
+  },
+  logger: {
+    warn(message, error) {
+      reportWarning(message, error);
+    },
+  },
+});
+```
+
+Limits reduce accidental or malicious memory pressure but are not a complete sandbox. PDF parsing still occurs in PDF.js and its worker.
+
+`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.
+
+## 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.
+- 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.
+- 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.
+
+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.
+
+Individual unsupported images are skipped. Supply `logger.warn` if those diagnostics matter to the application. Resource-limit and cancellation errors are never swallowed.
+
+Image `x`, `y`, `width`, and `height` values are PDF user-space coordinates before viewport scaling. The full six-value graphics transform is included when consumers need custom coordinate conversion.
+
+## Errors And Cleanup
+
+Validation and resource failures use `PdfReaderError` with stable codes:
+
+- `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`
+
+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.
+
+PDF.js loading, password, malformed-document, response, and rendering errors pass through unchanged so callers can use PDF.js error classes. Abort and destroy races are normalized to package `PdfReaderError` codes rather than leaking PDF.js cancellation exceptions. Best-effort embedded-image skips do not throw; they call `logger.warn(...)` when a logger is supplied. Always call `destroy()` from your own `finally` block to terminate reader-owned document resources.

package/index.d.mts

@@ -0,0 +1,192 @@
+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';
+/** An actionable package error with a stable machine-readable code. */
+declare class PdfReaderError extends Error {
+    readonly code: PdfReaderErrorCode;
+    constructor(code: PdfReaderErrorCode, message: string);
+}
+
+/**
+ * PDF.js `getDocument(...)` source accepted by the package root.
+ *
+ * Prefer trusted in-memory bytes when possible. PDF.js may transfer typed-array
+ * ownership to its worker during load.
+ */
+type PdfSource = NonNullable<Parameters<typeof pdfjs_dist.getDocument>[0]>;
+type TransformMatrix = readonly [number, number, number, number, number, number];
+type PageRange = number | readonly [start: number, end: number];
+type ViewportScale = number | ((pageWidth: number, pageHeight: number) => number);
+type PageImageMimeType = 'image/png' | 'image/jpeg';
+type PageImageOutputMode = 'data-url' | 'blob';
+/**
+ * Public lifecycle states reported by `PDFReader.state`.
+ *
+ * `failed` means the most recent package- or PDF.js-owned load attempt
+ * rejected and a later `load()` call will start a fresh attempt.
+ */
+type PdfReaderState = 'new' | 'loading' | 'loaded' | 'iterating' | 'failed' | 'destroyed';
+/** PDF.js text output without requiring consumers to import PDF.js internals. */
+type PdfTextContent = Awaited<ReturnType<PDFPageProxy['getTextContent']>>;
+interface PdfReaderLimits {
+    /** Maximum known in-memory source bytes accepted before PDF.js starts loading. Unset by default. */
+    maxSourceBytes?: number;
+    /** Maximum number of document pages accepted after loading. Defaults to 1,000. */
+    maxDocumentPages?: 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;
+}
+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;
+    /** 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. */
+    url?: string;
+    /** Known byte length for direct byte sources and `DocumentInitParameters.data` when synchronously measurable. */
+    byteLength?: number;
+    /** True when the source carries any custom HTTP headers. */
+    hasHttpHeaders: boolean;
+    /** Shallow copy of recognized HTTP headers when the source uses a plain object. */
+    httpHeaders?: Readonly<Record<string, string>>;
+    /** Whether PDF.js would send credentials for URL-based loading. */
+    withCredentials: boolean;
+}
+type PdfReaderSourcePolicy = (source: PdfReaderSourceInfo) => void | Promise<void>;
+interface PdfReaderOptions {
+    /** Canvas boundary injectable for tests or non-DOM canvas implementations. */
+    canvasFactory?: () => HTMLCanvasElement;
+    /** Optional warning sink. The package never writes directly to the console. */
+    logger?: PdfReaderLogger;
+    limits?: PdfReaderLimits;
+    /** Optional pre-load policy hook for rejecting sources before PDF.js starts work. */
+    sourcePolicy?: PdfReaderSourcePolicy;
+}
+interface LoadOptions {
+    /** Cancels only the current load caller, not other callers sharing the same underlying PDF.js task. */
+    signal?: AbortSignal;
+    /** Caller-local deadline in milliseconds for waiting on `load()`. */
+    deadlineMs?: number;
+}
+interface ConvertOptions {
+    pageRange?: PageRange;
+    viewportScale?: ViewportScale;
+    imageFormat?: PageImageMimeType;
+    jpegQuality?: number;
+    includePageImage?: boolean;
+    pageImageOutput?: PageImageOutputMode;
+    includeText?: boolean;
+    includeEmbeddedImages?: boolean;
+    /** Stops between expensive steps and cancels an active page render. */
+    signal?: AbortSignal;
+}
+interface DataUrlPageImage {
+    /** Inline base64 page image. The package owns the temporary canvas, not the returned string. */
+    kind: 'data-url';
+    mimeType: PageImageMimeType;
+    dataUrl: string;
+}
+interface BlobPageImage {
+    /** Binary page image. Callers own any object URL created from this blob. */
+    kind: 'blob';
+    mimeType: PageImageMimeType;
+    blob: Blob;
+}
+type PageImageResult = DataUrlPageImage | BlobPageImage;
+interface ExtractedImage {
+    /** Best-effort PNG data URL copied from a PDF.js image object. */
+    dataUrl: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    size: number;
+    mimeType: 'image/png';
+    pageWidth: number;
+    pageHeight: number;
+    transform: TransformMatrix;
+}
+interface PageResult {
+    /** Total document pages from the loaded PDF.js document proxy. */
+    numPages: number;
+    pageNumber: number;
+    pageIndex: number;
+    /** Optional full-page render owned by the caller after the page canvas is released. */
+    pageImage?: PageImageResult;
+    viewport: PageViewport;
+    /** Optional PDF.js text content. Treat extracted strings as untrusted input. */
+    text?: PdfTextContent;
+    /** Best-effort embedded raster images extracted from the current page. */
+    images: ExtractedImage[];
+}
+type LoadedPdfDocument = PDFDocumentProxy;
+type LoadedPdfPage = PDFPageProxy;
+
+/** Browser PDF reader with bounded canvas allocation and deterministic cleanup. */
+declare class PDFReader {
+    #private;
+    constructor(source: PdfSource, options?: PdfReaderOptions);
+    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. */
+    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. */
+    pages(options?: ConvertOptions): AsyncGenerator<PageResult>;
+    /** Collects `pages()` into an array. Prefer `pages()` for large documents. */
+    convert(options?: ConvertOptions): Promise<PageResult[]>;
+    /** Terminates the loading task and document resources. The reader cannot be reused afterwards. */
+    destroy(): Promise<void>;
+}
+
+interface PdfUrlSourceOptions {
+    /** Basic authentication headers forwarded to PDF.js URL loading. */
+    httpHeaders?: Readonly<Record<string, string>>;
+    /** Whether PDF.js should send cross-origin credentials while loading the URL. */
+    withCredentials?: boolean;
+    /** Password for encrypted PDFs. */
+    password?: string;
+    /** Maximum bytes fetched per PDF.js range request. */
+    rangeChunkSize?: number;
+    /** Base URL used by PDF.js when resolving relative links in the document. */
+    docBaseUrl?: string;
+    /** URL where predefined Adobe CMaps are located. Include the trailing slash. */
+    cMapUrl?: string;
+    /** Whether CMaps are binary packed. */
+    cMapPacked?: boolean;
+    /** URL where PDF.js standard font data is located. Include the trailing slash. */
+    standardFontDataUrl?: string;
+    /** URL where PDF.js WASM assets are located. Include the trailing slash. */
+    wasmUrl?: string;
+    /** Disable HTTP range requests. */
+    disableRange?: boolean;
+    /** Disable streaming PDF data. */
+    disableStream?: boolean;
+    /** Disable automatic prefetching after the first range request. */
+    disableAutoFetch?: boolean;
+    /** PDF.js verbosity level. */
+    verbosity?: number;
+}
+type PdfUrlSource = PdfUrlSourceOptions & {
+    url: string | URL;
+};
+/** Creates a PDF.js URL source object that can be passed directly to `new PDFReader(...)`. */
+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.
+ *
+ * Calling this again replaces the previous configuration. When passing an
+ * existing `Worker`, the caller retains ownership of terminating it.
+ */
+declare function configurePdfWorker(worker: string | Worker): void;
+
+export { type BlobPageImage, type ConvertOptions, type DataUrlPageImage, type ExtractedImage, type LoadOptions, type LoadedPdfDocument, type LoadedPdfPage, PDFReader, type PageImageMimeType, type PageImageOutputMode, type PageImageResult, type PageRange, type PageResult, PdfReaderError, type PdfReaderErrorCode, type PdfReaderLimits, type PdfReaderLogger, type PdfReaderOptions, type PdfReaderSourceInfo, type PdfReaderSourcePolicy, type PdfReaderState, type PdfSource, type PdfTextContent, type PdfUrlSource, type PdfUrlSourceOptions, type TransformMatrix, type ViewportScale, configurePdfWorker, pdfUrlSource };