@reportwright/pdf 0.1.0-beta.1 → 0.1.0-beta.10

package/README.md

@@ -1,32 +1,369 @@
 # @reportwright/pdf
 
-A streaming PDF writer for Node and browsers, with no runtime dependencies. Pages are written to your sink as
-they end, so memory stays flat however many pages you write. It is the writer inside ReportWright, extracted.
+**Create, comply, sign, light edit: a streaming PDF library for Node and browsers with zero runtime dependencies.**
+
+[![npm](https://img.shields.io/npm/v/@reportwright/pdf?color=1f4e79)](https://www.npmjs.com/package/@reportwright/pdf)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![dependencies: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen)](./package.json)
+[![node >= 20.16](https://img.shields.io/badge/node-%3E%3D20.16-339933)](./package.json)
+[![PDF/A + PDF/UA: veraPDF](https://img.shields.io/badge/PDF%2FA%201b%E2%80%933a%20%2B%20UA--1-veraPDF%20clean-6f42c1)](./conformance)
+
+**Live demo:** [mrarun005.github.io/reportwright-demo](https://mrarun005.github.io/reportwright-demo) ·
+[PDF benchmarks](https://mrarun005.github.io/reportwright-demo/bench.html) ·
+[playground](https://mrarun005.github.io/reportwright-demo/play.html)
+
+Pages are written to your sink as they end, so memory stays flat however many pages you write. It is the writer inside
+ReportWright, extracted, plus a hardened reader for merging, splitting, filling and signing existing files.
+
+What it is for: **create, comply, sign, light edit**. It does not render PDFs: for rendering use
+[pdf.js](https://mozilla.github.io/pdf.js/) or [PDFium](https://pdfium.googlesource.com/pdfium/). For heavy
+rewriting, repair or raw speed, MuPDF and qpdf are the established tools; this library does not claim to be faster
+than them.
+
+- **Write**: text in the 14 standard fonts or embedded TrueType/OpenType (subset, kerned, any Unicode), complex
+  scripts through a HarfBuzz shaper, JPEG/PNG images, Canvas-style vector paths, gradients, patterns, layers.
+- **Navigate**: links, named destinations, bookmarks, page labels, annotations.
+- **Forms**: every AcroForm field type with appearance streams; fill and flatten existing forms.
+- **Protect**: AES-256 / AES-128 encryption with permissions; PAdES B-B / B-T signatures while streaming.
+- **Comply**: PDF/A-1b, 2b/2u/2a, 3b/3u/3a and PDF/UA-1 (veraPDF clean), Factur-X / ZUGFeRD / XRechnung.
+- **Read and edit**: load (also damaged or encrypted files), merge, split, reorder, extract text, fill, stamp,
+  `saveIncremental` that keeps existing signatures valid.
+- **Safe by default**: no JavaScript or launch actions can be written; active content is stripped on read; every
+  input is budgeted.
+
+## Contents
+
+[Install](#install) · [Quick start](#quick-start-30-seconds) · [Guide](#guide) · [Examples](#examples) ·
+[Comparison](#comparison) · [Options reference](#options-reference) · [Security model](#security-model) ·
+[Known limits](#known-limits) · [Changes](#changes)
+
+## Install
+
+```sh
+npm i @reportwright/pdf
+```
+
+ESM only, Node 20.16 or later, and modern browsers (the same `dist/index.js`; crypto comes from WebCrypto). Types are
+included (`index.d.ts`). Optional, for complex scripts only: `npm i harfbuzzjs`.
 
-## Quickstart
+## Quick start (30 seconds)
 
 ```js
+// hello.mjs  →  node hello.mjs
 import fs from 'node:fs';
 import { createPdf } from '@reportwright/pdf';
 
-const pdf = createPdf(fs.createWriteStream('hello.pdf'), { title: 'Hello', creationDate: new Date('2026-01-01') });
-const bold = pdf.standardFont('Helvetica-Bold');
-const page = pdf.addPage({ width: 595.28, height: 841.89 });          // A4, in points
-page.text('Hello, world', { x: 72, y: 72, font: bold, size: 24, color: '#1f4e79' });
+const pdf = createPdf(fs.createWriteStream('hello.pdf'), { title: 'Hello' });
+const page = pdf.addPage();                                       // A4, points, origin top-left
+page.text('Hello, world', { x: 72, y: 72, font: pdf.standardFont('Helvetica-Bold'), size: 24, color: '#1f4e79' });
 page.line(72, 104, 523, 104, { color: 0.6, width: 0.5 });
+await page.end();                                                 // the page is written and freed
+console.log(await pdf.end());                                     // { pages: 1, bytes: …, warnings: [] }
+```
+
+In memory instead of a stream: `const bytes = await toBytes(async (pdf) => { … }, options)`.
+
+## Guide
+
+Every snippet below is cut from a file in [`examples/`](./examples), each of which was run and produces a PDF. The
+examples import `../dist/index.js`; in your code import `@reportwright/pdf`. They also ship in the package
+(`node_modules/@reportwright/pdf/examples/`).
+
+### Write: text, fonts, images, tables
+
+```js
+const pdf = createPdf(fs.createWriteStream('report.pdf'), { title: 'Quarterly report', author: 'Example Ltd' });
+const regular = pdf.standardFont('Helvetica'), bold = pdf.standardFont('Helvetica-Bold');
+const inter = await pdf.embedFont(fs.readFileSync('Inter-Regular.ttf'));          // subset, any Unicode
+const logo = await pdf.embedImage(fs.readFileSync('logo.png'));                   // alpha becomes a soft mask
+
+const page = pdf.addPage();
+page.image(logo, { x: 40, y: 40, width: 32 });
+page.text('Quarterly report', { x: 84, y: 44, font: bold, size: 22, color: '#1f4e79' });
+const box = page.textBox(longText, { x: 40, y: 90, width: 515, font: inter, size: 11, align: 'justify' });
+// box = { height, lines, overflow }: continue `overflow` in the next box or page
+```
+
+**Tables are paths and text**: there is no table primitive, so you control every rule and alignment.
+
+```js
+const rows = [['Region', 'Q1', 'Q2'], ['North', '1,204', '1,390'], ['South', '980', '1,122']];
+const cols = [40, 300, 430], right = 555, rowH = 22, top = 100 + box.height;
+page.fill(page.path().rect(40, top, right - 40, rowH), { fill: '#1f4e79' });       // header band
+rows.forEach((r, i) => {
+  const y = top + i * rowH;
+  r.forEach((cell, c) => {
+    const font = i === 0 ? bold : regular;
+    const x = c === 0 ? cols[c] + 6 : (cols[c + 1] ?? right) - 6 - font.widthOfText(cell, 11);   // right-align numbers
+    page.text(cell, { x, y: y + 5, font, size: 11, color: i === 0 ? '#ffffff' : 0 });
+  });
+  if (i > 0) page.stroke(page.path().moveTo(40, y + rowH).lineTo(right, y + rowH), { stroke: 0.75, width: 0.5 });
+});
+await page.end();
+await pdf.end();
+```
+
+Full file: [`examples/write.mjs`](./examples/write.mjs) (it also generates its PNG, so it needs no input files).
+
+### Indic and other complex scripts (HarfBuzz)
+
+Pass a shaper to `embedFont` and conjuncts, reordered matras, Arabic joining and marks are drawn correctly; copied
+and extracted text stays the source text, in logical order. The adapter for harfbuzzjs ships as
+[`examples/harfbuzz-shaper.mjs`](./examples/harfbuzz-shaper.mjs).
+
+```js
+import { harfbuzzShaper } from '@reportwright/pdf/examples/harfbuzz-shaper.mjs';   // needs: npm i harfbuzzjs
+
+const bytes = fs.readFileSync('NotoSansDevanagari-Regular.ttf');
+const hindi = await pdf.embedFont(bytes, { shaper: harfbuzzShaper(bytes) });
+page.text('किताब हिन्दी क्षत्रिय', { x: 40, y: 40, font: hindi, size: 24 });
+page.textBox('इस किताब में हिन्दी और English दोनों हैं।', { x: 40, y: 90, width: 400, font: hindi, fallback: [latin] });
+```
+
+`node examples/indic.mjs NotoSansDevanagari-Regular.ttf`. Right-to-left: `{ direction: 'rtl' }` (there is no bidi
+algorithm: split mixed-direction lines into runs yourself).
+
+### Links and bookmarks
+
+```js
+page.link(40, 300, 160, 14, { url: 'https://example.com/report' });              // http, https, mailto by default
+pdf.destination('appendix', 2, { top: 40 });                                      // a named destination
+page.link(40, 320, 160, 14, { dest: 'appendix' }, { alt: 'Go to the appendix' });
+page.link(40, 340, 160, 14, { page: 2, fit: 'FitH', top: 0 });
+pdf.outline([
+  { title: 'Quarterly report', page: 1 },
+  { title: 'Appendix', page: 2, level: 1 },                                       // level nests under the previous entry
+]);
+pdf.pageLabels([{ start: 0, style: 'r' }, { start: 2, style: 'D' }]);             // i, ii, 1, 2, …
+```
+
+### Forms: create, fill, flatten
+
+```js
+import { toBytes, loadPdf } from '@reportwright/pdf';
+
+const form = await toBytes(async (pdf) => {
+  const font = pdf.standardFont('Helvetica'), page = pdf.addPage();
+  pdf.form.textField('name', { page, x: 40, y: 80, width: 240, height: 22, font, tooltip: 'Full name', required: true });
+  pdf.form.comboBox('type', { page, x: 40, y: 115, width: 160, height: 22, font, options: ['Annual', 'Sick', 'Unpaid'], value: 'Annual', tooltip: 'Leave type' });
+  pdf.form.checkbox('approved', { page, x: 40, y: 150, width: 14, height: 14, tooltip: 'Approved by manager' });
+  await page.end();
+});
+
+const doc = await loadPdf(form);
+doc.fields;                                                        // [{ name: 'name', type: 'text', … }, …]
+doc.fill({ name: 'Aanya Sharma', type: 'Sick', approved: true });  // appearances redrawn by the writer
+const filled = (await doc.save()).bytes;
+
+const flattened = (await (await loadPdf(form)).fill({ name: 'Aanya Sharma' }).flatten().save()).bytes;  // no AcroForm left
+```
+
+[`examples/fill-form.mjs`](./examples/fill-form.mjs) writes `form.pdf`, `filled.pdf` and `flattened.pdf`. To
+flatten while writing: `createPdf(sink, { form: { flatten: true } })`.
+
+### Encryption
+
+```js
+const bytes = await toBytes(build, {
+  encrypt: {
+    userPassword: 'open me', ownerPassword: 'full access',
+    algorithm: 'aes-256',                                          // default; 'aes-128' for very old readers
+    permissions: { print: true, copy: false, modify: false },      // each defaults to true
+  },
+});
+const doc = await loadPdf(bytes, { password: 'open me' });         // doc.encryption.algorithm === 'aes-256'
+```
+
+[`examples/encrypt.mjs`](./examples/encrypt.mjs). RC4 is read, never written.
+
+### Signing (PAdES)
+
+```js
+import { createPdf, loadPdf, nodeSigner } from '@reportwright/pdf';
+
+const signer = nodeSigner({ key: fs.readFileSync('key.pem', 'utf8'), certs: fs.readFileSync('cert.pem', 'utf8') });
+const pdf = createPdf(sink, { title: 'Offer letter', sign: true });
+const page = pdf.addPage();
+const hr = pdf.form.signature('hr', { page, x: 40, y: 700, width: 200, height: 40, tooltip: 'HR signature' });
+pdf.form.signature('candidate', { page, x: 300, y: 700, width: 200, height: 40, tooltip: 'Candidate signature' });
+await pdf.sign(hr, { signer, reason: 'Issued', location: 'Bengaluru', certify: 2 });
 await page.end();
-await pdf.end();                                                        // ends the stream too
+await pdf.end();                                                   // the signer runs here
+
+// Countersign later: an incremental update, so the first signature stays valid.
+const { bytes } = await (await loadPdf(signedBytes)).saveIncremental({ sign: { field: 'candidate', signer } });
+```
+
+[`examples/sign.mjs`](./examples/sign.mjs) (make a test key with the `openssl` line at its top). Its output checks with
+`pdfsig`: both signatures "Signature is Valid", the second "Total document signed". `signer` can be any async function
+returning CMS bytes (an HSM, a cloud KMS: see `cmsSigner`); add `timestamp` for PAdES B-T.
+
+### PDF/A, PDF/UA and Factur-X
+
+```js
+const pdf = createPdf(sink, {
+  title: 'Leave policy',
+  tagged: { lang: 'en-GB' },                // PDF/UA-1: structure tree, title, embedded fonts
+  pdfa: { part: 2, conformance: 'a' },      // or true (2b), { part: 1, conformance: 'b' }, { part: 3, … }
+});
+const font = await pdf.embedFont(fs.readFileSync('Inter-Regular.ttf'));
+const page = pdf.addPage();
+page.artifact({ type: 'Pagination', subtype: 'Header' }, () => page.text('HR policies', { x: 40, y: 20, font, size: 8 }));
+page.tag('H1', () => page.text('Leave policy', { x: 40, y: 50, font, size: 22 }));
+page.figure({ alt: 'Bar chart: annual leave 18 days' }, () => page.fill(page.path().rect(40, 180, 180, 16), { fill: '#1f4e79' }));
+```
+
+A Factur-X / ZUGFeRD invoice is PDF/A-3 with the CII XML attached:
+
+```js
+const pdf = createPdf(sink, { title: 'Invoice INV-2026-001', pdfa: { part: 3, conformance: 'a' }, tagged: { lang: 'en' } });
+// … draw the invoice from the same data as the XML …
+await pdf.facturX(xmlBytes, { profile: 'EN 16931' });   // MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG
+```
+
+[`examples/accessible.mjs`](./examples/accessible.mjs) (PDF/A-2a + PDF/UA-1) and
+[`examples/invoice-facturx.mjs`](./examples/invoice-facturx.mjs) (self-contained PDF/A-3a invoice; `factur-x.mjs`
+does the same from your own XML) both pass veraPDF with 0 failed rules (`2a` + `ua1`, `3a` + `ua1`).
+
+### Read: merge, split, extractText, saveIncremental
+
+```js
+import { loadPdf, mergePdfs } from '@reportwright/pdf';
+
+const a = await loadPdf(fs.readFileSync('contract.pdf')), b = await loadPdf(fs.readFileSync('annexure.pdf'));
+const merged = await mergePdfs([a, b]);                            // { bytes, pages, stripped, warnings }
+
+const all = await loadPdf(merged.bytes);
+all.extractText();                                                 // every page, joined by \f
+all.page(0).extractText();                                         // one page, in lines
+
+for (let i = 0; i < all.pageCount; i++) {                          // split: one file per page
+  fs.writeFileSync(`page-${i + 1}.pdf`, (await all.fork().reorder([i]).save()).bytes);
+}
+
+const doc = await loadPdf(merged.bytes);
+doc.setInfo({ title: 'Contract (reviewed)' });
+const { bytes } = await doc.saveIncremental();                     // the original bytes + an appended update
 ```
 
-In memory: `const bytes = await toBytes((pdf) => { ... }, options)`.
+[`examples/merge-split.mjs`](./examples/merge-split.mjs). `save()` rewrites the file (and strips active content);
+`saveIncremental()` appends (and refuses files with active content): see [Security model](#security-model).
 
-## Coordinates
+### Bulk: many files in worker threads
+
+```js
+import { bulk } from '@reportwright/pdf';
+
+const files = fs.readdirSync('in').map((f) => fs.readFileSync(`in/${f}`));
+const texts = await bulk(files, 'extractText', { workers: 4 });           // [{ ok: true, value } | { ok: false, error }]
+const locked = await bulk(files, 'encrypt', { encrypt: { userPassword: 'u', ownerPassword: 'o' } });
+const pages = await bulk(files, 'split');                                 // value: one Uint8Array per page
+const joined = await bulk([[a, b], [c, d]], 'merge');                     // each input: the files to merge
+```
+
+Tasks are names (`extractText`, `merge`, `split`, `encrypt`; `BULK_TASKS`), never functions, so only bytes and plain
+options cross to a worker. Results come back in input order; a file that fails (malformed, wrong password, over the
+budget) gives `{ ok: false, error: { name, code, message } }` and the batch goes on. Each worker's heap is capped
+(`memoryMb`, default 512): a file that exhausts it kills only that worker, its item fails with `E_WORKER`, and a new
+worker takes the next. `workers` defaults to `os.availableParallelism() - 1`. Node only: in browsers (no
+`node:worker_threads`), and with `workers: 1`, the same tasks run one at a time in the calling thread, without the
+heap cap. [`examples/bulk.mjs`](./examples/bulk.mjs).
+
+Workers stay warm (unref'd, so they never keep the process alive) for 2 s after a call, so the next call skips their
+start-up; small files are sent several at a time (up to 8, or 256 KB, a worker). Each item has `itemTimeoutMs` (default 120000) in a worker: past it the worker is ended and the item fails with `E_TIMEOUT`; a failed item is never retried, so a batch of stuck or worker-killing files ends with each failing alone (`workers` is 1–64, `memoryMb` 16–16384; with `workers: 1` there is no item timeout or heap cap). Pass `signal` to stop a call (or
+`AbortSignal.timeout(ms)` for a time limit): its workers are ended and `bulk` rejects with the signal's reason. When
+to use it: CPU-heavy items (encrypt, the text of long files) gain from the first call; cheap items on small files
+(extractText or merge of 1–2 page files) gain only once the workers are warm: the first call pays ~25 ms a worker to
+start them, so a one-off batch of under ~100 ms of work is quicker with `workers: 1`.
+
+Measured on an Apple M2 (4 performance + 4 efficiency cores, 8 GB, busy laptop), Node 22, files made with
+`toBytes` (small: 200 files of 2 pages, 0.4 MB in all; large: 20 files of 200 pages of text, 2.3 MB in all). Items/s
+from the best of 3 calls in one process (warm), and the first call's ms (cold); results equal to `workers: 1`'s
+(encrypt: the same text once opened). Before: one worker started per call, one item a round trip.
+
+| files | task | workers | items/s before | items/s now | first call ms before | now | peak RSS MB |
+|---|---|---|---|---|---|---|---|
+| small | extractText | 1 | 4762 | 4762 | 80 | 78 | 135 |
+| small | extractText | 2 | 1923 | 5882 | 106 | 99 | 246 |
+| small | extractText | 4 | 1754 | 6452 | 123 | 100 | 351 |
+| small | merge | 1 | 2174 | 2128 | 137 | 136 | 148 |
+| small | merge | 4 | 1299 | 3175 | 171 | 142 | 429 |
+| small | encrypt | 1 | 284 | 288 | 733 | 738 | 171 |
+| small | encrypt | 4 | 563 | 813 | 370 | 373 | 465 |
+| large | extractText | 1 | 11 | 11 | 1906 | 1891 | 218 |
+| large | extractText | 4 | 29 | 37 | 684 | 653 | 422 |
+| large | merge | 1 | 143 | 135 | 224 | 220 | 176 |
+| large | merge | 4 | 77 | 196 | 276 | 249 | 429 |
+| large | encrypt | 1 | 149 | 155 | 213 | 212 | 181 |
+| large | encrypt | 4 | 93 | 217 | 218 | 210 | 416 |
+
+## Examples
+
+| file | what it shows | run |
+|---|---|---|
+| [`write.mjs`](./examples/write.mjs) | text, a PNG, a table from paths, a link, bookmarks | `node examples/write.mjs out.pdf` |
+| [`indic.mjs`](./examples/indic.mjs) | Devanagari shaped by HarfBuzz, Latin fallback | `node examples/indic.mjs NotoSansDevanagari-Regular.ttf out.pdf` |
+| [`harfbuzz-shaper.mjs`](./examples/harfbuzz-shaper.mjs) | the harfbuzzjs shaper adapter (a module) | imported by `indic.mjs` |
+| [`fill-form.mjs`](./examples/fill-form.mjs) | create, fill and flatten a form | `node examples/fill-form.mjs outDir` |
+| [`encrypt.mjs`](./examples/encrypt.mjs) | AES-256 with permissions, read back | `node examples/encrypt.mjs out.pdf` |
+| [`sign.mjs`](./examples/sign.mjs) | PAdES signature while streaming + countersignature | `node examples/sign.mjs key.pem cert.pem out.pdf` |
+| [`accessible.mjs`](./examples/accessible.mjs) | PDF/UA-1 + PDF/A-2a | `node examples/accessible.mjs font.ttf out.pdf` |
+| [`invoice-facturx.mjs`](./examples/invoice-facturx.mjs) | self-contained Factur-X PDF/A-3a invoice | `node examples/invoice-facturx.mjs font.ttf out.pdf` |
+| [`factur-x.mjs`](./examples/factur-x.mjs) | Factur-X from your own CII XML | `node examples/factur-x.mjs invoice.xml font.ttf out.pdf` |
+| [`merge-split.mjs`](./examples/merge-split.mjs) | merge, split, extractText, saveIncremental | `node examples/merge-split.mjs outDir` |
+| [`bulk.mjs`](./examples/bulk.mjs) | extractText and encrypt over many files in worker threads | `node examples/bulk.mjs outDir` |
+
+Run from `node_modules/@reportwright/pdf` (or the package folder of the repository).
+
+## Comparison
+
+Positioning: **create, comply, sign, light edit**. Only measured facts: `bench/compare.mjs` (Node 20, Apple Silicon laptop, median of 10;
+reading cases median of 3) and the beta.0 measurements. Where something was not measured the cell says so. MuPDF and qpdf are faster at rewriting and repair: this table does not compare against them.
+
+| | @reportwright/pdf | pdf-lib 1.17.1 | PDFKit | jsPDF |
+|---|---|---|---|---|
+| Runtime dependencies | 0 | 4 (pako, tslib, @pdf-lib/standard-fonts, @pdf-lib/upng) | not measured | not measured |
+| Package size | 161 KB gzipped (dist/index.js, unminified, beta.2) | not measured | not measured | not measured |
+| 10,000 pages | 3.2 s, 123 MB (beta.0); heap 5.0 MB at 20,000 pages (streaming) | not measured | not measured | not measured |
+| Cold start, new process | 91 ms (beta.0); 43 ms for a 1-page invoice now | 96 ms (1-page invoice) | not measured | not measured |
+| 1,000-page text: bytes / warm ms | 461,320 / 134 | 1,421,783 / 918 | not measured | not measured |
+| 1,000 vector shapes: bytes / warm ms | 8,353 / 5.3 | 22,273 / 20.5 | not measured | not measured |
+| 200-field form, filled: bytes / warm ms | 63,095 / 15.4 | 165,910 / 97.0 | not measured | not measured |
+| Merge 10 ten-page PDFs: warm ms | 11.6 | 14.5 | not measured | not measured |
+| Split 100 pages into 100 files: warm ms | 33.7 | 30.3 (faster) | not measured | not measured |
+| Real-world PDFs read | 196 of 206 (beta.0 corpus) | not measured | not measured | not measured |
+| AES encryption | AES-256, AES-128 | cannot encrypt | not measured | not measured |
+| Digital signatures | PAdES B-B / B-T, incremental countersign | cannot sign | not measured | not measured |
+| PDF/A, PDF/UA | 1b, 2b/2u/2a, 3b/3u/3a, UA-1: veraPDF 0 failures | not measured | not measured | not measured |
+| Factur-X / ZUGFeRD | yes | not measured | not measured | not measured |
+
+The split files are larger than pdf-lib's (each carries ~1 KB of XMP and Info). PDFKit and jsPDF were not installed
+where the benchmark ran, so they have no numbers here; run `bench/compare.mjs` where they are. Full tables and method: `NOTES.md` ("Measurements") and the [benchmarks page](https://mrarun005.github.io/reportwright-demo/bench.html).
+
+## Options reference
+
+The sections below are the full API: every option of `createPdf`, the drawing methods, forms, encryption, signatures,
+PDF/A levels and the reader. The most used:
+
+| function | key options |
+|---|---|
+| `createPdf(sink, o)` / `toBytes(build, o)` | `title`, `author`, `creationDate`, `compress`, `metadata`, `pdfa`, `tagged`, `encrypt`, `sign`, `form.flatten`, `signal`, `timeoutMs`, `id` ([table](#createpdfsink-options)) |
+| `pdf.embedFont(bytes, o)` | `subset`, `shaper`, `textMapping` ([Fonts](#fonts), [Shaping](#shaping)) |
+| `page.text` / `page.textBox` | `x`, `y`, `font`, `size`, `color`, `width`, `align`, `maxLines`, `fallback`, `direction`, `kerning` ([Text options](#pages)) |
+| `pdf.embedImage` / `page.image` | `colorSpace`, `maxDecodedBytes`, `compression` / `width`, `height`, `fit`, `opacity`, `alt` ([Images](#images)) |
+| `page.fill` / `stroke` | `fill`, `stroke`, `width`, `dash`, `cap`, `join`, `opacity`, `blendMode`, `rule` ([Vector graphics](#vector-graphics)) |
+| `encrypt` | `userPassword`, `ownerPassword`, `algorithm`, `permissions`, `encryptMetadata` ([Encryption](#encryption-1)) |
+| `pdf.sign(field, o)` | `signer`, `reason`, `location`, `name`, `certify`, `timestamp`, `subFilter`, `reserve` ([Signatures](#signatures)) |
+| `loadPdf(bytes, o)` | `password`, `budget`, `timeoutMs`, `signal` ([Reading](#reading-and-modifying)) |
+| `doc.save(o)` / `mergePdfs(docs, o)` | `compress`, `keepActiveContent`, `encrypt`, `pdfa`, `keepStructure`, `creationDate` |
+| `doc.saveIncremental(o)` | `sign`, `keepActiveContent`, `allowFillAfterSigning`, `allowChangesAfterSigning` |
+
+### Coordinates
 
 PDF points (1/72 inch), **origin at the top-left corner of the page, y growing downwards** (as in CSS and canvas;
 PDF itself counts from the bottom-left — the library converts). For `page.text`, `y` is the **top of the line box**:
 the baseline sits at `y + font.ascent * size`.
 
-## API
 
 ### `createPdf(sink, options?)`
 
@@ -54,7 +391,7 @@ writer to be ready. `pdf.end()` ends a Node stream and closes a `WritableStream`
   `Helvetica-BoldOblique`, `Times-Roman`, `Times-Bold`, `Times-Italic`, `Times-BoldItalic`, `Courier`,
   `Courier-Bold`, `Courier-Oblique`, `Courier-BoldOblique`, `Symbol`, `ZapfDingbats`). Not embedded; text is WinAnsi
   (Latin-1 plus €, curly quotes, dashes…). Not allowed with `pdfa` or `tagged`.
-- `await pdf.embedFont(bytes, { subset, shaper })` — a TrueType (`glyf`) or OpenType/CFF (`.otf`) font. Any Unicode
+- `await pdf.embedFont(bytes, { subset, shaper, textMapping })` — a TrueType (`glyf`) or OpenType/CFF (`.otf`) font. Any Unicode
   text (Identity-H with a ToUnicode map, so text can be copied and searched). TrueType embeds as `FontFile2`
   (CIDFontType2); OpenType/CFF as `FontFile3 /Subtype /OpenType` (CIDFontType0; `pdffonts` says "CID Type 0C (OT)").
   `subset`: `true` (default) keeps only the glyphs used, both kinds built in (CFF: unused glyphs' charstrings become
@@ -134,6 +471,10 @@ dots) has its text on one glyph and WJ (U+2060) on the others, which are drawn a
 `CIDToGIDMap`; a CFF font cannot, so there it gets an ActualText span). The shaper's output is checked (glyph IDs in
 the font, finite numbers, clusters inside the text, at most 4 glyphs a character).
 
+`textMapping` (left-to-right clusters in an ActualText span): `'carrier'` (default) also maps the cluster's text on its
+carrier glyph, which suits Firefox, pdf.js and search (MuPDF reads such a cluster twice); `'actualText'` maps the
+carrier to WJ so the text is only in the ActualText, which suits MuPDF/PyMuPDF and AI pipelines (pdf.js loses those clusters).
+
 An adapter for harfbuzzjs v1 (`npm i harfbuzzjs`; not a dependency of this package). The same file ships in the package
 as `examples/harfbuzz-shaper.mjs`:
 
@@ -260,10 +601,12 @@ const logo = await pdf.embedImage(fs.readFileSync('logo.png'));         // alpha
 for (const y of [400, 500, 600]) page.image(logo, { x: 40, y, height: 24, opacity: 0.6 });   // written once
 ```
 
-- `await pdf.embedImage(bytes, { colorSpace, maxDecodedBytes })` — a JPEG or PNG, written to the file at once as an image XObject;
+- `await pdf.embedImage(bytes, { colorSpace, maxDecodedBytes, compression })` — a JPEG or PNG, written to the file at once as an image XObject;
   returns a handle with `width` and `height` (pixels, after the EXIF orientation). `colorSpace`: an ICC colour space
   (`pdf.iccColorSpace`) with the image's number of components, instead of the device space. `maxDecodedBytes`: the
-  decoded size allowed for a PNG that needs decoding (default 64 MB, 67,108,864 bytes).
+  decoded size allowed for a PNG that needs decoding (default 64 MB, 67,108,864 bytes). `compression`: the zlib level
+  for a PNG that is re-compressed (alpha or interlacing): `'default'` is 6, or 3 above 2 megapixels (about half the
+  time for 2–3% more bytes on photos); `'fast'` is 1; or a level 1–9. JPEGs and passed-through PNGs are not affected.
   - **JPEG**: baseline and progressive, gray, RGB and CMYK, embedded unchanged (DCTDecode, no re-encoding). Adobe's
     inverted CMYK (an APP14 "Adobe" segment) is drawn with `/Decode [1 0 1 0 1 0 1 0]`. The EXIF orientation (1–8)
     is honoured. 12-bit, lossless, hierarchical and arithmetic-coded JPEGs are refused.
@@ -281,6 +624,10 @@ for (const y of [400, 500, 600]) page.image(logo, { x: 40, y, height: 24, opacit
   `height`: the other keeps the aspect ratio; neither: one point per pixel. `fit`: `'fill'` (default: stretch to the
   box), `'contain'` (all of the image, centred), `'cover'` (fills the box, centred, cut to it). `opacity` 0–1. Tagged
   PDFs: `alt` makes the image a `Figure` with that alternate text; without `alt` it is an artifact (decoration).
+- Images are deduplicated automatically: `embedImage` called again with the same bytes (and the same options) in the
+  same document returns the same handle and writes nothing new (keyed by a SHA-256 of the bytes; Node's `node:crypto`,
+  else WebCrypto, else a fast hash confirmed byte for byte). A different option (`colorSpace`, `maxDecodedBytes`, `compression`)
+  embeds it again.
 - An image drawn any number of times, on any pages, is one XObject in the file. Images are always XObjects, never
   inline images: an inline image would be repeated in every content stream and cannot have a soft mask.
 - Image handles, like fonts and gradients, only work in the PDF that made them.
@@ -686,9 +1033,23 @@ const signed = await doc.saveIncremental({ sign: { field: { name: 'approval', pa
 - Errors from the input are `PdfReadError` with a `code`: `E_MALFORMED`, `E_BUDGET`, `E_DEPTH`, `E_CYCLE`,
   `E_TIMEOUT`, `E_ABORTED`, `E_PASSWORD`, `E_UNSUPPORTED`, `E_ACTIVE`.
 
-## Security
+## Security model
+
+In short:
 
-What the library refuses, and why:
+- **No active content can be written.** There is no API for JavaScript, Launch, SubmitForm, ImportData, GoToR or any
+  other action, no `/AA`, no form scripts; URLs are limited to http, https and mailto (widen per link with
+  `allowSchemes`, never to `javascript:`, `data:`, `file:` or `vbscript:`). Every caller string is written escaped.
+- **Active content is stripped on read.** `save()` and `mergePdfs()` drop JavaScript, launch and submit actions, `/AA`,
+  XFA, RichMedia and every annotation or action outside an allowlist, and report it in `stripped`
+  (`keepActiveContent: true` opts out). `saveIncremental()` cannot strip (the old bytes stay), so it scans the whole
+  file and refuses (`E_ACTIVE`) instead.
+- **Every input is budgeted.** Decoded bytes, parse steps, objects, nesting, reference chains, text items and time
+  have caps (`budget`, `timeoutMs`, `signal`); exceeding one is a `PdfReadError` (`E_BUDGET`, `E_TIMEOUT`…), never
+  a hang or an out-of-memory crash. Images, attachments and Factur-X XML have their own size caps.
+- **Platform crypto only**, no RC4 written, signed documents' DocMDP/FieldMDP permissions enforced on update.
+
+The details, and what the library refuses and why:
 
 | Refused | Why |
 |---|---|
@@ -742,6 +1103,12 @@ any active content, or if anything cannot be read (fail closed), unless `keepAct
 strangers, `save()` is the safe path** (it rewrites the file without the active content; this invalidates existing
 signatures).
 
+**This is why `saveIncremental` is slower by design.** Appending a few objects could be done without reading the
+original, but then active content hidden in it (a shadow attack: an earlier revision, an unreferenced object, a
+duplicate, an object stream the latest cross-reference does not point at) would ride along under your new signature.
+So it reads and scans the whole file first, every time: a large file costs a full parse before a byte is appended.
+Safer, slower, on purpose.
+
 **Signed documents (signature policy).** `saveIncremental` reads every signature's permissions and takes the
 strictest: DocMDP from the catalog `/Perms` and from each signature's `/Reference` in every revision (no `/P` means
 P=2), FieldMDP from each `/Reference` and each signed field's `/Lock`, and ReadOnly from any ancestor field. Anything it
@@ -759,13 +1126,28 @@ after signing", and refilling widgets that existed before signing is how "shadow
 Security 2021) make a signed document look different while its signature still verifies. As a second guard the filled
 widgets may cover at most 40% of a page in all, and a widget with an opaque background may not lie over the page's text.
 
-## Not supported yet
+## Known limits
 
 Image masks (stencils) and colour-managed images (embedded ICC profiles of PNG/JPEG files are ignored); the Unicode
-bidi algorithm, hyphenation, kerning of the standard fonts, WOFF fonts; popup annotations; RC4 encryption (refused; read only), public-key (certificate) encryption (neither written nor read), verifying signatures' cryptography (they are listed with their coverage); PDF/A-1a, PDF/X, attachment annotations in PDF/A-3 (use `pdf.attach`), validating a Factur-X invoice's content; layout-perfect text extraction; page edits in an incremental update (use `save()`); reading encrypted files in browsers (WebCrypto has no synchronous AES; Node only). See NOTES.md for the plan. Extending the library: ARCHITECTURE.md.
+bidi algorithm, hyphenation, kerning of the standard fonts, WOFF fonts; popup annotations; RC4 encryption (refused; read only), public-key (certificate) encryption (neither written nor read), verifying signatures' cryptography (they are listed with their coverage); PDF/A-1a, PDF/X, attachment annotations in PDF/A-3 (use `pdf.attach`), validating a Factur-X invoice's content; layout-perfect text extraction; page edits in an incremental update (use `save()`); reading encrypted files in browsers (WebCrypto has no synchronous AES; Node only); with `textMapping: 'actualText'`, readers that ignore ActualText or close it early (pdf.js; a tester saw an older MuPDF drop a line's last Bengali cluster) lose the spanned clusters: the writer closes every span after its cluster's last glyph, and MuPDF 1.28.2 (PyMuPDF) reads Bengali, Devanagari and the other test scripts whole. See NOTES.md for the plan. Extending the library: ARCHITECTURE.md.
 
 ## Changes
 
+0.1.0-beta.10: a WritableStream's writer lock is released when the export ends, fails or is stopped (`timeoutMs`,
+`signal`), so the caller can reuse or cancel the stream; the abort reason is still the original error.
+
+0.1.0-beta.9: stamping every page (`page.draw` then `save()`) is about 35% faster on a 1,000-page file: a page's open
+graphics states are counted with a byte scan instead of a full parse, and FlateDecode inflates whole, valid zlib
+streams with Node's zlib (damaged, truncated, raw or over-budget streams still go through fflate as before); the output
+is byte-identical. `bulk` starts an item's `itemTimeoutMs` clock when its worker is ready, so a respawned worker's
+start-up no longer fails good files; a stopped export (`timeoutMs` or `signal`) aborts its WritableStream even when
+the stop lands between two calls.
+
+0.1.0-beta.2: a left-to-right shaped cluster in an ActualText span has its text only in the ActualText, so MuPDF
+no longer reads it twice (pdf.js, which ignores ActualText, now misses those clusters; poppler, PDFium and
+`extractText` read them); `extractText` drops WJ (U+2060) and reads a code a ToUnicode skips as nothing (U+FFFD
+only when the font has no mapping at all); `@reportwright/pdf/examples/*` can be imported.
+
 0.1.0-beta.1: shaped text (Indic, Arabic) extracts once and in order in pdf.js, poppler and `extractText`;
 `extractText` honours ActualText, reads unmapped glyphs as U+FFFD, falls back to an embedded TrueType cmap, spaces
 separate text objects (spreadsheet cells), orders a line along its baseline (rotated text too), and stops a

package/THIRD-PARTY-NOTICES.md

@@ -4,7 +4,7 @@
 
 | Component | Version | License | Used for |
 |---|---|---|---|
-| [fflate](https://github.com/101arrowz/fflate) by Arjun Barrett | 0.8.3 | MIT | Flate (zlib) compression and decompression, bundled into `dist/index.js` |
+| [fflate](https://github.com/101arrowz/fflate) by Arjun Barrett | 0.8.3 | MIT | Flate (zlib) compression and decompression, bundled into `dist/fflate.js` |
 | Adobe Font Metrics (AFM) for the 14 standard PDF fonts, via [@pdf-lib/standard-fonts](https://github.com/Hopding/standard-fonts) | 1.0.0 | MIT (the package); the AFM files are © Adobe, distributed with permission to use, copy and distribute | widths and metrics of Helvetica, Times, Courier, Symbol and ZapfDingbats (`src/fonts/standard-metrics.js`, generated) |
 | `sRGB-v2-magic.icc` from [Compact-ICC-Profiles](https://github.com/saucecontrol/Compact-ICC-Profiles) by Clinton Ingram | — | CC0 1.0 (public domain) | the sRGB output intent of PDF/A files |