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

package/README.md

@@ -1,32 +1,427 @@
-# @reportwright/pdf
+<h1 align="center">@reportwright/pdf</h1>
+
+<p align="center">
+  <b>Create, comply, sign, light edit.</b><br>
+  A streaming PDF library for Node and browsers with <b>zero runtime dependencies</b>.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@reportwright/pdf"><img alt="npm" src="https://img.shields.io/npm/v/@reportwright/pdf?color=1f4e79"></a>
+  <a href="https://github.com/MrArun005/reportwright-pdf/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/MrArun005/reportwright-pdf/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="./LICENSE"><img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="./package.json"><img alt="runtime dependencies: 0" src="https://img.shields.io/badge/runtime%20dependencies-0-brightgreen"></a>
+  <a href="./package.json"><img alt="node >= 20.16" src="https://img.shields.io/badge/node-%3E%3D20.16-339933"></a>
+  <a href="./conformance"><img alt="PDF/A + PDF/UA: veraPDF clean" src="https://img.shields.io/badge/PDF%2FA%201b%E2%80%933a%20%2B%20UA--1-veraPDF%20clean-6f42c1"></a>
+</p>
+
+<p align="center">
+  <a href="https://mrarun005.github.io/reportwright-demo">Live demo</a> ·
+  <a href="https://mrarun005.github.io/reportwright-demo/play.html">Playground</a> ·
+  <a href="#benchmarks">Benchmarks</a> ·
+  <a href="#security-model">Security model</a>
+</p>
+
+Pages are written to your sink as they end, so memory stays flat however many pages you write: 20,000 pages hold
+about the heap that 1,000 do. It is the writer inside ReportWright, extracted, plus a hardened reader for merging,
+splitting, filling and signing existing files.
+
+It does **not** render PDFs (use [pdf.js](https://mozilla.github.io/pdf.js/) or
+[PDFium](https://pdfium.googlesource.com/pdfium/)), and for heavy rewriting, repair or raw speed MuPDF, qpdf and
+pdfcpu are faster (see [Benchmarks](#benchmarks)).
+
+## Contents
+
+[Install](#install) · [Quick start](#quick-start-30-seconds) · [Features](#features) · [Screenshots](#screenshots) ·
+[Guide](#guide) · [Bundle size](#bundle-size) · [Examples](#examples) · [Benchmarks](#benchmarks) · [Options reference](#options-reference) ·
+[Security model](#security-model) · [Known limits](#known-limits) · [Releasing](#releasing) · [Changes](#changes)
+
+## Install
+
+```sh
+npm i @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.
+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 (Indic, Arabic) 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)`.
+
+## Features
+
+| Area | What you get |
+|---|---|
+| **Write** | Text in the 14 standard fonts or embedded TrueType/OpenType (subset, kerned, any Unicode); text boxes with wrapping and alignment; JPEG/PNG images (alpha as a soft mask); Canvas-style vector paths, gradients, patterns, layers |
+| **Complex scripts** | Devanagari, Bengali, Tamil, Telugu, Kannada, Arabic… through a HarfBuzz shaper you plug in (`harfbuzzjs`), text still extractable |
+| **Streaming** | Each page is written and freed when it ends; flat memory for 20,000+ pages; `timeoutMs` and `AbortSignal` |
+| **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 |
+| **Sign** | PAdES B-B / B-T signatures while streaming; incremental countersignatures that keep earlier ones valid |
+| **Comply** | PDF/A-1b, 2b/2u/2a, 3b/3u/3a and PDF/UA-1 (veraPDF clean); Factur-X / ZUGFeRD / XRechnung invoices |
+| **Read and edit** | Load (also damaged or encrypted files), merge, split, reorder, extract text, fill, stamp, `saveIncremental` |
+| **Bulk** | One task over many files in worker threads, each with a heap cap and a per-file timeout; one bad file never stops the batch |
+| **Safe by default** | No JavaScript or launch actions can be written; active content is stripped on read; every input is budgeted |
+| **Small** | Zero runtime dependencies; one ESM file plus a lazily loaded `fflate.js`; TypeScript types included |
+
+## Screenshots
+
+Page 1 of the [examples](#examples), rendered by poppler (`pdftoppm`) on GitHub Actions straight from their output.
+
+<table>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/MrArun005/reportwright-pdf/main/docs/screenshots/write.png" width="240" alt="write.mjs: a report with a logo, a justified paragraph, a table drawn with paths and a link"><br><code>write.mjs</code><br>text, image, table, link</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/MrArun005/reportwright-pdf/main/docs/screenshots/invoice-facturx.png" width="240" alt="invoice-facturx.mjs: a Factur-X PDF/A-3a invoice in Inter"><br><code>invoice-facturx.mjs</code><br>Factur-X, PDF/A-3a</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/MrArun005/reportwright-pdf/main/docs/screenshots/indic.png" width="240" alt="indic.mjs: Devanagari text shaped by HarfBuzz mixed with English"><br><code>indic.mjs</code><br>Devanagari via HarfBuzz</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/MrArun005/reportwright-pdf/main/docs/screenshots/fill-form.png" width="240" alt="fill-form.mjs: a leave request form, filled in"><br><code>fill-form.mjs</code><br>a form, filled</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/MrArun005/reportwright-pdf/main/docs/screenshots/accessible.png" width="240" alt="accessible.mjs: a tagged PDF/UA-1 and PDF/A-2a policy page"><br><code>accessible.mjs</code><br>PDF/UA-1 + PDF/A-2a, tagged</td>
+    <td></td>
+  </tr>
+</table>
+
+## 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();                                                        // ends the stream too
+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] });
 ```
 
-In memory: `const bytes = await toBytes((pdf) => { ... }, options)`.
+`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, …
+```
 
-## Coordinates
+### 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();                                                   // 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
+```
+
+[`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).
+
+### 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 |
+
+## Bundle size
+
+Gzip (`gzip -9`) of the built files in `dist/`. `.` is `dist/index.js` (writer and reader); `./write` is `dist/write.js`
+(writer only: `createPdf`, fonts, images, graphics, forms, standards, encryption, signing). fflate is a separate file
+(`dist/fflate.js`) loaded on first use by either entry.
+
+| entry | before (unminified) | after (minified) |
+| --- | --- | --- |
+| `.` (`dist/index.js`) | 166.8 KiB (170,811 B) | 133.4 KiB (136,583 B) |
+| `./write` (`dist/write.js`) | not exported | 85.0 KiB (87,080 B) |
+| `fflate` (`dist/fflate.js`) | 15.5 KiB (15,842 B) | 12.6 KiB (12,953 B) |
+
+Import `@reportwright/pdf/write` when the code only writes PDFs: it leaves out the reader (`loadPdf`, `mergePdfs`) and
+`bulk`. The two entries are separate bundles, so an app that imports both pays for the writer twice.
+
+## 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).
+
+## Benchmarks
+
+From the deep benchmark of the ReportWright project: every library in its own process, median of 5 runs after a
+warm-up, contestants interleaved on the same GitHub `ubuntu-latest` runner (2 vCPU), every output checked (qpdf,
+MuPDF, pdf.js or the job's own text check) before it is ranked. Times are wall time from process start to exit, so they include each runtime's
+start-up. Full tables, method and raw numbers:
+**[bench/deep/RESULTS.md](https://github.com/MrArun005/reportwright/blob/bench-deep/bench/deep/RESULTS.md)**
+(the `@reportwright/pdf` measured there is the 0.1.0-beta.7 code).
+
+**Where it wins**
+
+| Task | @reportwright/pdf | Next best |
+|---|---|---|
+| PDF/A-2b invoice (veraPDF-checked) | 255 ms · 75 MB | pdfkit 543 ms · 103 MB (the only other writer with PDF/A in the test) |
+| Fill and flatten a form | **100 ms** | PyMuPDF / pypdf 139 ms, pdf-lib 296 ms, pdfbox 669 ms |
+| Sign (PAdES/CMS) | **~100 ms** | pdfbox 705 ms, openpdf 760 ms, iText 1,113 ms |
+| Incremental metadata change | 100-125 ms | PyMuPDF / pypdf 139 ms, pdfbox 463 ms |
+| 1,000 pages of text, against other JS writers | 3.1 s · 135 MB | pdfkit 4.5 s, jsPDF 5.8 s, pdf-lib 215 s |
+| Reading fuzzed PDFs (200 mutations) | 182 read, 18 clean errors, 0 crashes or hangs | pdfbox 176 read; most readers refuse far more |
+
+**Where it loses** (honestly)
+
+| Task | @reportwright/pdf | Fastest |
+|---|---|---|
+| Plain text pages (10 / 100 / 1,000) | 0.30 / 0.65 / 3.1 s | fpdf (PHP) 0.05 / 0.11 / 0.57 s: **5-6× faster** |
+| Grouped report, 100 to 100,000 rows | 2.2-5.2× slower | fpdf |
+| One invoice in a warm process | 11 ms | PDFsharp (.NET) 1.7× faster |
+| Images (6 MP PNG + 24 MP JPEG) | 1.2 s | printpdf (Rust) 3.3× faster |
+| Unicode (Hindi, Arabic, CJK) | 3.1× slower | fpdf |
+| Text of a 1,200-page PDF | 1.0 s | pdftotext 0.65 s (1.5× faster) |
+| Merge 100 files / split 100 pages / AES-256 encrypt | 204 / 217 / 147 ms | pdfcpu (Go) 3-4.3× faster |
+
+In short: it is not the fastest PDF writer or reader. It is a fast JavaScript one with flat memory, and it is the
+quickest of those measured at the jobs it is built for (compliance, forms, signing, incremental edits), where most
+libraries have no support at all.
+
+## 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,14 +449,18 @@ 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
+  `subset`: `true` (default) keeps only the glyphs used, both kinds built in (TrueType: the glyphs used, their
+  components and `.notdef` are renumbered 0…n and only `glyf loca head hhea hmtx maxp` and the hinting tables
+  `cvt fpgm prep` are kept; the content still draws by the original glyph ID, through a `/CIDToGIDMap` stream, so
+  ToUnicode and widths are unchanged. CFF: unused glyphs' charstrings become
   `endchar`, subroutines are kept, glyph IDs stay; a font using the deprecated `seac` accents embeds whole; a
   CID-keyed CFF gets an identity charset so every reader maps its glyphs alike); `false` embeds the whole font; or a
   function `(font, codePoints, { glyphs }) => Promise<Uint8Array>` (e.g. a HarfBuzz subsetter, which also
-  desubroutinises CFF) that must keep glyph IDs. `shaper`: see Shaping.
+  desubroutinises CFF) that must keep glyph IDs (its font is embedded as returned, `/CIDToGIDMap /Identity`, as
+  `core` callers that write their own fonts expect). `shaper`: see Shaping.
   A variable font (an `fvar` table) is drawn at its default instance, which may be its thinnest weight (Noto Sans JP's
   is Thin), with a warning naming the axes' values: for another weight, embed a static instance of it (fonttools
   `varLib.instancer`, or `hb-subset --instance`).
@@ -134,6 +533,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 +663,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 +686,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.
@@ -450,6 +859,11 @@ f.signature('sig', { page, x: 40, y: 360, width: 200, height: 40, tooltip: 'Sign
 - An embedded font in a fillable field is subset to the characters drawn; for fields people will type into, embed it
   with `subset: false` so a viewer has every glyph.
 
+A caller that draws its own appearances (pdf.core users) passes `appearance: { normal }` (a checkbox: `{ on, off }`)
+of content-stream operators, written exactly, and `da` (`'/F1 12 Tf 0 g'`, a font it registered with
+`core.resource('Font', …)`): with both, no `font` is needed. Each field's `widgetRef` is its widget's object number,
+and `structParent` puts a `/StructParent` on it for a structure tree of the caller's own.
+
 ### Encryption
 
 ```js
@@ -511,6 +925,11 @@ await pdf.end();                 // the signer runs here
   AcroForm gets `/SigFlags 3`. **One signature** a document (more need incremental updates).
 - Works with encryption (the signature's `/Contents` is not encrypted, as the spec requires) and with PDF/A-2b.
 
+An invisible signature: `pdf.sign({ name: 'Signature1' }, { signer })` (no page, no size) is a zero-`/Rect` field in
+the AcroForm only, so it works after every page is written (a document built through `pdf.core`); with `page` (still
+open) it goes in that page's `/Annots`. A PKCS#12 (.p12/.pfx) file signs through `cmsSigner`:
+`examples/p12-signer.mjs` (node-forge, which you install; not a dependency) gives `p12Signer(bytes, password)`.
+
 ### Tagged PDF
 
 `page.tag(type, fn, options)` options: `alt` (`/Alt`), `actualText` (`/ActualText`: the text the element stands for),
@@ -614,6 +1033,34 @@ default configuration `/D` (`/Name`, `/Order` listing every layer, `/ON`, `/OFF`
 - `await pdf.end()` — ends open pages, writes fonts, outline, metadata and the cross-reference stream; resolves to
   `{ pages, bytes, warnings }`.
 
+### Extension API (core)
+
+`pdf.core` (typed `PdfCore` in index.d.ts) is the layer every feature module is written on, for a caller that writes
+its own content streams and objects beside the Pdf methods (the ReportWright engine does). Not covered by semver in
+0.x; ARCHITECTURE.md ("Extension points") has the details.
+
+```js
+const pdf = createPdf(sink);
+const { core } = pdf;
+const n = core.reserve(); // an object number, written later
+await core.write(n, '<< /Type /ExtGState /ca 0.5 >>'); // small objects go into object streams
+const gs = core.resource('ExtGState', `${n} 0 R`); // a name in every page's shared Resources
+core.catalog('PageLabels', '<< /Nums [0 << /S /r >>] >>');
+core.onFinish(async () => {
+  /* runs at pdf.end(), after the last page, before the fonts and the catalog */
+});
+```
+
+- `reserve()`, `write(n, dict, stream?)`, `writeStream(n, dict, raw)`, `writeBig(n, head, parts, tail)`,
+  `object(dict, stream?)` — objects; a stream's bytes are already filtered (`/Length` is added).
+- `resource(kind, value, name?)`, `resourcesRef` — the shared Resources dictionary.
+- `imageResource(image)` → `{ name, ref, alpha, orientation }` — an image from `pdf.embedImage` for your own content
+  stream: `q w 0 0 h x y cm <orientation> cm /<name> Do Q` (with `alpha`, give the page a transparency `/Group`).
+- `catalog(key, value)`, `onFinish(fn)`, `info`, `xmp` — the end of the document; `info` set to a dictionary's text
+  replaces the Info made from the options.
+- `pageRef(i)`, `pageHeight(i)`, `pageCount`, `warn(msg)`, `serial(fn)`, `tags` — pages, warnings, ordering, tagging.
+- In an encrypted file, every string an object holds (literal or hex) is encrypted as it is written.
+
 ### Reading and modifying
 
 ```js
@@ -686,9 +1133,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 +1203,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 +1226,59 @@ 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
+
+- **Images**: image masks (stencils); embedded ICC profiles of PNG/JPEG files are ignored.
+- **Text**: no Unicode bidi algorithm, no hyphenation, no kerning of the standard fonts, no WOFF fonts; text
+  extraction is reading order, not layout-perfect. 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.
+- **Annotations**: no popup annotations.
+- **Crypto**: RC4 is refused (read only); public-key (certificate) encryption is neither written nor read; signatures
+  are listed with their coverage, but their cryptography is not verified.
+- **Standards**: no PDF/A-1a or PDF/X; no attachment annotations in PDF/A-3 (use `pdf.attach`); a Factur-X invoice's
+  content is not validated.
+- **Editing**: no page edits in an incremental update (use `save()`).
+- **Browsers**: reading encrypted files needs Node (WebCrypto has no synchronous AES).
 
-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.
+See NOTES.md for the plan, and ARCHITECTURE.md for extending the library.
+
+## Releasing
+
+Releases are published to npm by GitHub Actions from a GitHub Release (tag `v<version>`). The one-time `NPM_TOKEN`
+setup and the steps are in [RELEASING.md](./RELEASING.md).
 
 ## Changes
 
+Unreleased: the built-in TrueType subset renumbers its glyphs and drops the tables a PDF does not read (`name`,
+`OS/2`, `gasp`; OpenType/CFF also drops `name` and `OS/2`): a 19-character DejaVu Sans line is 6.5 KB, was 20.2 KB.
+Renders and extracted text are unchanged. A subsetter function, and `core`, still keep glyph IDs.
+
+0.1.0-beta.11: `pdf.core`, the low-level API under `createPdf`, is documented (`PdfCore` in the types), with
+`core.imageResource`; encryption now covers every literal and hex string in direct objects (it leaked some and threw
+on others); `readFont` and `checkSubset` read a font's metrics and check a subset before embedding; form fields take
+a caller's `appearance`, `da`, `structParent` and `widgetRef`; a document whose pages were written through `core` can
+be signed (an invisible field), with a PKCS#12 example (`examples/p12-signer.mjs`); `svgPathOps` turns SVG path data
+into path operators; the build is minified, and `@reportwright/pdf/write` exports the writer without the reader; the
+`page`, `width` and `height` of `SignatureOptions` are optional.
+It includes everything from beta.9 and beta.10.
+
+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