pdfnova 1.0.0

package/README.md

@@ -0,0 +1,336 @@
+# pdfnova
+
+**PDFium-powered PDF library for JavaScript.** Chrome-grade rendering via WebAssembly with full TypeScript types. Supports text extraction, search, bookmarks, annotations, forms, and digital signatures.
+
+Built on [`@embedpdf/pdfium`](https://www.npmjs.com/package/@embedpdf/pdfium) — the real PDFium engine (used in Chrome) compiled to WebAssembly.
+
+## Installation
+
+```bash
+npm install pdfnova
+```
+
+## Two Tiers
+
+|                          | pdfnova/lite | pdfnova (full) |
+| ------------------------ | ------------ | -------------- |
+| **JS Bundle (minified)** | ~3KB         | ~5KB           |
+| **WASM Binary**          | 4.4MB on disk / ~1.5MB over the wire (Brotli) | |
+| Rendering                | Yes          | Yes            |
+| Text extraction          | Yes          | Yes            |
+| Text layer (DOM)         | Yes          | Yes            |
+| Search                   | Yes          | Yes            |
+| Bookmarks/TOC            | Yes          | Yes            |
+| Virtualization           | Yes          | Yes            |
+| Worker/OffscreenCanvas   | Yes          | Yes            |
+| Annotations (read/write) | —            | Yes            |
+| Form filling/flattening  | —            | Yes            |
+| Digital signatures       | —            | Yes            |
+| doc.save()               | —            | Yes            |
+
+> The WASM binary is fetched once and cached in IndexedDB — subsequent page loads are instant with zero network cost. Both tiers share the same binary — the lite/full distinction controls which TypeScript API features are available.
+
+```typescript
+// Lightweight — render, text, search, bookmarks
+import { PDFDocument } from "pdfnova/lite";
+
+// Full — everything above + annotations, forms, signatures
+import { PDFDocument } from "pdfnova";
+```
+
+## Quick Start
+
+```typescript
+import { PDFDocument } from "pdfnova/lite";
+
+// Open from URL, ArrayBuffer, File, Blob, or base64 data URI
+const doc = await PDFDocument.open("/report.pdf");
+
+// Document info
+console.log(doc.pageCount); // 42
+console.log(doc.metadata); // { title, author, subject, ... }
+console.log(doc.outline); // OutlineItem[] (bookmarks tree)
+
+// Render a page
+const page = doc.getPage(0);
+const canvas = document.createElement("canvas");
+await page.render(canvas, { scale: 2 });
+
+// Text extraction with character-level precision
+const text = page.getText();
+const spans = page.getTextSpans(); // TextSpan[] with x, y, width, height
+
+// Build a selectable text layer over the canvas
+page.createTextLayer(container);
+
+// Full-text search
+const results = doc.search("quarterly revenue");
+
+// Cleanup
+doc.close();
+```
+
+## Rendering
+
+```typescript
+const page = doc.getPage(0);
+
+// Render to canvas
+await page.render(canvas, {
+  scale: 2, // 2x resolution
+  rotation: 90, // 0, 90, 180, 270
+  background: "#ffffff",
+});
+
+// Render to ImageData (no DOM required)
+const imageData = await page.renderToImageData({ scale: 1.5 });
+
+// Thumbnails
+import { PageRenderer } from "pdfnova/lite";
+await PageRenderer.renderThumbnail(page, thumbCanvas, 200);
+
+// Fit-to-width scale calculation
+const scale = PageRenderer.fitWidthScale(page, containerWidth);
+```
+
+## Virtual Renderer
+
+For large documents, only render visible pages:
+
+```typescript
+import { VirtualRenderer } from "pdfnova/lite";
+
+const renderer = new VirtualRenderer({
+  container: document.getElementById("viewer")!,
+  scale: 1.5,
+  overscan: 2, // render 2 pages above/below viewport
+  cacheSize: 10, // LRU cache for rendered pages
+});
+
+await renderer.setDocument(doc);
+renderer.scrollToPage(5);
+console.log(renderer.getCurrentPage());
+```
+
+## Text Layer
+
+pdfnova uses PDFium's character-level bounding boxes for pixel-perfect text selection:
+
+```typescript
+// Span-level positioning (fast, good enough for most use cases)
+const layer = page.createTextLayer(container);
+
+// Character-level positioning (slower but pixel-perfect)
+import { TextLayerBuilder } from "pdfnova/lite";
+const builder = new TextLayerBuilder(wasm, bridge);
+builder.buildCharLevel(textPagePtr, container, page.width, page.height, scale);
+```
+
+## Search
+
+```typescript
+// Search a single page
+const pageResults = page.search("revenue", { caseSensitive: true });
+
+// Search entire document
+const allResults = doc.search("quarterly revenue", { wholeWord: true });
+
+// Each result has:
+// - pageIndex, charIndex, charCount
+// - rects (TextRect[] for highlighting)
+// - text (matched text)
+```
+
+## Bookmarks / Table of Contents
+
+```typescript
+const outline = doc.outline;
+// OutlineItem { title, pageIndex, children: OutlineItem[] }
+
+for (const item of outline) {
+  console.log(`${item.title} → page ${item.pageIndex + 1}`);
+  for (const child of item.children) {
+    console.log(`  ${child.title} → page ${child.pageIndex + 1}`);
+  }
+}
+```
+
+## Annotations (full tier)
+
+```typescript
+import { PDFDocument, AnnotationType } from "pdfnova";
+
+const doc = await PDFDocument.open(data);
+const page = doc.getPage(0);
+
+// Read existing annotations
+const annotations = await page.getAnnotations();
+
+// Add a highlight annotation
+await page.addAnnotation({
+  type: AnnotationType.Highlight,
+  rect: { left: 72, top: 720, right: 300, bottom: 700 },
+  color: { r: 255, g: 235, b: 59, a: 128 },
+  contents: "Important section",
+});
+
+// Remove an annotation
+await page.removeAnnotation(0);
+
+// Save modified PDF
+const bytes = await doc.save();
+```
+
+## Form Filling (full tier)
+
+```typescript
+import { PDFDocument } from "pdfnova";
+
+const doc = await PDFDocument.open(formPdf);
+
+// Read all form fields
+const fields = await doc.getFormFields();
+// FormFieldData { name, type, value, isChecked, pageIndex }
+
+// Fill fields
+await doc.setFormField("name", "John Doe");
+await doc.setFormField("email", "john@example.com");
+
+// Flatten forms (make non-interactive)
+await doc.flattenForms();
+
+// Save
+const filled = await doc.save();
+```
+
+## Digital Signatures (full tier)
+
+```typescript
+import { PDFDocument } from "pdfnova";
+
+const doc = await PDFDocument.open(signedPdf);
+
+const signatures = await doc.getSignatures();
+// SignatureData { index, contents, byteRange, subFilter, reason, signingTime }
+
+// Format signature info
+import { SignatureInfo } from "pdfnova";
+for (const sig of signatures) {
+  console.log(SignatureInfo.formatSummary(sig));
+  console.log(SignatureInfo.getSignatureFormat(sig.subFilter));
+}
+```
+
+## Worker Pool
+
+Render pages concurrently across multiple Web Workers:
+
+```typescript
+import { WorkerPool } from "pdfnova/lite";
+
+const pool = new WorkerPool(4); // 4 workers
+await pool.init({ tier: "lite" });
+
+// Render multiple pages in parallel
+const images = await pool.renderPages([0, 1, 2, 3], { scale: 2 });
+
+pool.destroy();
+```
+
+## Authenticated URLs
+
+```typescript
+const doc = await PDFDocument.open(
+  "https://api.example.com/documents/123/download",
+  {
+    headers: { Authorization: "Bearer eyJ..." },
+    credentials: "include",
+  },
+);
+```
+
+## Password-Protected PDFs
+
+```typescript
+const doc = await PDFDocument.open(encryptedPdf, {
+  password: "secret123",
+});
+```
+
+## Custom WASM URL
+
+By default, pdfnova loads the PDFium WASM binary from jsDelivr CDN. To self-host:
+
+```typescript
+const doc = await PDFDocument.open(data, {
+  wasmUrl: "https://cdn.example.com/pdfium.wasm",
+});
+```
+
+You can get the WASM binary from `node_modules/@embedpdf/pdfium/dist/pdfium.wasm` and serve it from your own infrastructure.
+
+## API Reference
+
+### PDFDocument
+
+| Method/Property                      | Description                                                                      |
+| ------------------------------------ | -------------------------------------------------------------------------------- |
+| `PDFDocument.open(source, options?)` | Open a PDF from URL, ArrayBuffer, File, Blob, or data URI                        |
+| `.pageCount`                         | Number of pages                                                                  |
+| `.metadata`                          | `{ title, author, subject, keywords, creator, producer, creationDate, modDate }` |
+| `.outline`                           | Bookmark tree (`OutlineItem[]`)                                                  |
+| `.permissions`                       | `{ print, copy, modify, annotate, fillForms, ... }`                              |
+| `.getPage(index)`                    | Get a page (0-indexed)                                                           |
+| `.search(query, options?)`           | Search entire document                                                           |
+| `.getFormFields()`                   | Read form fields (full tier)                                                     |
+| `.setFormField(name, value)`         | Fill a form field (full tier)                                                    |
+| `.flattenForms()`                    | Flatten forms (full tier)                                                        |
+| `.getSignatures()`                   | Read digital signatures (full tier)                                              |
+| `.save()`                            | Save modified PDF as Uint8Array (full tier)                                      |
+| `.close()`                           | Free all WASM memory                                                             |
+
+### PDFPage
+
+| Method/Property                | Description                    |
+| ------------------------------ | ------------------------------ |
+| `.pageIndex`                   | 0-based page index             |
+| `.width` / `.height`           | Page dimensions in PDF points  |
+| `.render(canvas, options?)`    | Render to canvas               |
+| `.renderToImageData(options?)` | Render to ImageData            |
+| `.getText()`                   | Extract plain text             |
+| `.getTextSpans()`              | Extract text with positions    |
+| `.getCharBoxes()`              | Character-level bounding boxes |
+| `.createTextLayer(container)`  | Build selectable text layer    |
+| `.search(query, options?)`     | Search this page               |
+| `.getLinks()`                  | Extract hyperlinks             |
+| `.getAnnotations()`            | Read annotations (full tier)   |
+| `.addAnnotation(options)`      | Add annotation (full tier)     |
+| `.removeAnnotation(index)`     | Remove annotation (full tier)  |
+| `.close()`                     | Free page resources            |
+
+## How WASM Loading Works
+
+pdfnova uses [`@embedpdf/pdfium`](https://www.npmjs.com/package/@embedpdf/pdfium) for the pre-built PDFium WebAssembly binary. No manual compilation is needed.
+
+1. On first use, `WasmLoader` fetches `pdfium.wasm` (4.4MB) from CDN — ~1.5MB with Brotli compression (standard on CDNs)
+2. The binary is cached in **IndexedDB** — subsequent visits load instantly with zero network cost
+3. The module is initialized via `PDFiumExt_Init()` and adapted to pdfnova's typed interface
+4. All downstream API calls go through the real PDFium C engine via the WASM bridge
+
+To override the WASM URL (e.g., for air-gapped environments), pass `wasmUrl` in `PDFDocument.open()` options.
+
+To clear the cached binary: `WasmLoader.clearCache()`
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run build        # TypeScript check + tsup build
+npm test             # Run all 71 tests
+npm run test:watch   # Watch mode
+npm run test:coverage # With V8 coverage report
+```
+
+## License
+
+MIT

package/dist/AnnotationReader-ADHPZ3V5.mjs

@@ -0,0 +1,3 @@
+export { AnnotationReader } from './chunk-VRJQZOCH.mjs';
+//# sourceMappingURL=AnnotationReader-ADHPZ3V5.mjs.map
+//# sourceMappingURL=AnnotationReader-ADHPZ3V5.mjs.map

package/dist/AnnotationReader-ADHPZ3V5.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"AnnotationReader-ADHPZ3V5.mjs"}

package/dist/AnnotationReader-C5XLXGWS.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkDVMAQ62T_cjs = require('./chunk-DVMAQ62T.cjs');
+
+
+
+Object.defineProperty(exports, "AnnotationReader", {
+  enumerable: true,
+  get: function () { return chunkDVMAQ62T_cjs.AnnotationReader; }
+});
+//# sourceMappingURL=AnnotationReader-C5XLXGWS.cjs.map
+//# sourceMappingURL=AnnotationReader-C5XLXGWS.cjs.map

package/dist/AnnotationReader-C5XLXGWS.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"AnnotationReader-C5XLXGWS.cjs"}

package/dist/AnnotationWriter-N3Y4KTPI.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkRZFKZ2CA_cjs = require('./chunk-RZFKZ2CA.cjs');
+
+
+
+Object.defineProperty(exports, "AnnotationWriter", {
+  enumerable: true,
+  get: function () { return chunkRZFKZ2CA_cjs.AnnotationWriter; }
+});
+//# sourceMappingURL=AnnotationWriter-N3Y4KTPI.cjs.map
+//# sourceMappingURL=AnnotationWriter-N3Y4KTPI.cjs.map

package/dist/AnnotationWriter-N3Y4KTPI.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"AnnotationWriter-N3Y4KTPI.cjs"}

package/dist/AnnotationWriter-XWY5N6AZ.mjs

@@ -0,0 +1,3 @@
+export { AnnotationWriter } from './chunk-I7OBHZLB.mjs';
+//# sourceMappingURL=AnnotationWriter-XWY5N6AZ.mjs.map
+//# sourceMappingURL=AnnotationWriter-XWY5N6AZ.mjs.map

package/dist/AnnotationWriter-XWY5N6AZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"AnnotationWriter-XWY5N6AZ.mjs"}

package/dist/FormFiller-2O4MOQYV.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunk7FGOUG4Z_cjs = require('./chunk-7FGOUG4Z.cjs');
+
+
+
+Object.defineProperty(exports, "FormFiller", {
+  enumerable: true,
+  get: function () { return chunk7FGOUG4Z_cjs.FormFiller; }
+});
+//# sourceMappingURL=FormFiller-2O4MOQYV.cjs.map
+//# sourceMappingURL=FormFiller-2O4MOQYV.cjs.map

package/dist/FormFiller-2O4MOQYV.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"FormFiller-2O4MOQYV.cjs"}

package/dist/FormFiller-6DLWMRN5.mjs

@@ -0,0 +1,3 @@
+export { FormFiller } from './chunk-XEHKVFPJ.mjs';
+//# sourceMappingURL=FormFiller-6DLWMRN5.mjs.map
+//# sourceMappingURL=FormFiller-6DLWMRN5.mjs.map

package/dist/FormFiller-6DLWMRN5.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"FormFiller-6DLWMRN5.mjs"}

package/dist/FormFlattener-5MWLLH7W.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkCPMUWWNS_cjs = require('./chunk-CPMUWWNS.cjs');
+
+
+
+Object.defineProperty(exports, "FormFlattener", {
+  enumerable: true,
+  get: function () { return chunkCPMUWWNS_cjs.FormFlattener; }
+});
+//# sourceMappingURL=FormFlattener-5MWLLH7W.cjs.map
+//# sourceMappingURL=FormFlattener-5MWLLH7W.cjs.map

package/dist/FormFlattener-5MWLLH7W.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"FormFlattener-5MWLLH7W.cjs"}

package/dist/FormFlattener-YQRQ3QOY.mjs

@@ -0,0 +1,3 @@
+export { FormFlattener } from './chunk-FO3DQLVB.mjs';
+//# sourceMappingURL=FormFlattener-YQRQ3QOY.mjs.map
+//# sourceMappingURL=FormFlattener-YQRQ3QOY.mjs.map

package/dist/FormFlattener-YQRQ3QOY.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"FormFlattener-YQRQ3QOY.mjs"}

package/dist/FormReader-QAEDFD77.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+var chunkG2FA6VKV_cjs = require('./chunk-G2FA6VKV.cjs');
+require('./chunk-2YFCKMVK.cjs');
+
+
+
+Object.defineProperty(exports, "FormReader", {
+  enumerable: true,
+  get: function () { return chunkG2FA6VKV_cjs.FormReader; }
+});
+//# sourceMappingURL=FormReader-QAEDFD77.cjs.map
+//# sourceMappingURL=FormReader-QAEDFD77.cjs.map

package/dist/FormReader-QAEDFD77.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"FormReader-QAEDFD77.cjs"}

package/dist/FormReader-XEF3T5LD.mjs

@@ -0,0 +1,4 @@
+export { FormReader } from './chunk-FD5RTJ5W.mjs';
+import './chunk-G7575D5X.mjs';
+//# sourceMappingURL=FormReader-XEF3T5LD.mjs.map
+//# sourceMappingURL=FormReader-XEF3T5LD.mjs.map

package/dist/FormReader-XEF3T5LD.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"FormReader-XEF3T5LD.mjs"}

package/dist/SignatureVerifier-2IR7UQGU.mjs

@@ -0,0 +1,3 @@
+export { SignatureVerifier } from './chunk-X53667JS.mjs';
+//# sourceMappingURL=SignatureVerifier-2IR7UQGU.mjs.map
+//# sourceMappingURL=SignatureVerifier-2IR7UQGU.mjs.map

package/dist/SignatureVerifier-2IR7UQGU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"SignatureVerifier-2IR7UQGU.mjs"}

package/dist/SignatureVerifier-4KWQA7X6.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkETSUOY4U_cjs = require('./chunk-ETSUOY4U.cjs');
+
+
+
+Object.defineProperty(exports, "SignatureVerifier", {
+  enumerable: true,
+  get: function () { return chunkETSUOY4U_cjs.SignatureVerifier; }
+});
+//# sourceMappingURL=SignatureVerifier-4KWQA7X6.cjs.map
+//# sourceMappingURL=SignatureVerifier-4KWQA7X6.cjs.map

package/dist/SignatureVerifier-4KWQA7X6.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"SignatureVerifier-4KWQA7X6.cjs"}