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

package/examples/accessible.mjs

@@ -0,0 +1,28 @@
+// PDF/UA-1 and PDF/A-2a in one file: a structure tree (headings, a list, a figure), artifacts for decoration.
+//
+//   node examples/accessible.mjs font.ttf [out.pdf]
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+
+const [fontFile, out = 'accessible.pdf'] = process.argv.slice(2);
+if (!fontFile) { console.error('node examples/accessible.mjs font.ttf [out.pdf]'); process.exit(2); }
+const pdf = createPdf(fs.createWriteStream(out), {
+  title: 'Leave policy', tagged: { lang: 'en-GB' },               // PDF/UA-1: a title and tags are required
+  pdfa: { part: 2, conformance: 'a' },                            // PDF/A-2a: archival and tagged
+});
+const font = await pdf.embedFont(fs.readFileSync(fontFile));
+const page = pdf.addPage();
+page.artifact({ type: 'Pagination', subtype: 'Header' }, () => page.text('Example Ltd · HR policies', { x: 40, y: 20, font, size: 8 }));
+page.tag('H1', () => page.text('Leave policy', { x: 40, y: 50, font, size: 22 }));
+page.tag('P', () => page.textBox('Every employee gets the following leave each calendar year.', { x: 40, y: 90, width: 500, font }));
+page.tag('L', () => ['18 days of annual leave', '12 days of sick leave'].forEach((s, i) => page.tag('LI', () => {
+  page.tag('Lbl', () => page.text('•', { x: 40, y: 120 + i * 18, font }));
+  page.tag('LBody', () => page.text(s, { x: 56, y: 120 + i * 18, font }));
+})), { listNumbering: 'Disc' });
+page.figure({ alt: 'Bar chart: annual leave 18 days, sick leave 12 days' }, () => {
+  page.fill(page.path().rect(40, 180, 180, 16), { fill: '#1f4e79' });
+  page.fill(page.path().rect(40, 200, 120, 16), { fill: '#5b9bd5' });
+});
+await page.end();
+const { warnings } = await pdf.end();
+console.log(`wrote ${out}: PDF/UA-1 + PDF/A-2a`, warnings.length ? warnings : '');

package/examples/bulk.mjs

@@ -0,0 +1,19 @@
+// Many files at once: extract text and encrypt in worker threads; a broken file fails alone.
+//
+//   node examples/bulk.mjs [outDir]   writes locked-1.pdf … locked-N.pdf
+import fs from 'node:fs';
+import path from 'node:path';
+import { toBytes, bulk } from '../dist/index.js';
+
+const dir = process.argv[2] ?? '.';
+const make = (label) => toBytes(async (pdf) => {
+  const p = pdf.addPage(); p.text(`${label}: total due 1,250.00`, { x: 40, y: 40, font: pdf.standardFont('Helvetica'), size: 14 }); await p.end();
+});
+const files = [await make('Invoice 1'), new Uint8Array([0x25, 0x50]), await make('Invoice 3')]; // the second is not a PDF
+
+const texts = await bulk(files, 'extractText', { workers: 2 });
+texts.forEach((r, i) => console.log(i + 1, r.ok ? r.value : `failed: ${r.error.code} ${r.error.message}`));
+
+const locked = await bulk(files, 'encrypt', { workers: 2, encrypt: { userPassword: 'open me', ownerPassword: 'full access' } });
+locked.forEach((r, i) => { if (r.ok) fs.writeFileSync(path.join(dir, `locked-${i + 1}.pdf`), r.value); });
+console.log(`encrypted ${locked.filter((r) => r.ok).length} of ${files.length}`);

package/examples/encrypt.mjs

@@ -0,0 +1,23 @@
+// AES-256 password protection with permissions, then reading it back with the password.
+//
+//   node examples/encrypt.mjs [out.pdf]
+import fs from 'node:fs';
+import { toBytes, loadPdf } from '../dist/index.js';
+
+const out = process.argv[2] ?? 'encrypted.pdf';
+const bytes = await toBytes(async (pdf) => {
+  const page = pdf.addPage();
+  page.text('Salary statement: confidential', { x: 40, y: 40, font: pdf.standardFont('Helvetica'), size: 14 });
+  await page.end();
+}, {
+  title: 'Salary statement',
+  encrypt: {
+    userPassword: 'open me',                 // asked when the file opens ('' opens without a prompt)
+    ownerPassword: 'full access',            // lifts the permissions; left out: random
+    algorithm: 'aes-256',                    // or 'aes-128' for very old readers
+    permissions: { print: true, copy: false, modify: false },   // each defaults to true
+  },
+});
+fs.writeFileSync(out, bytes);
+const doc = await loadPdf(bytes, { password: 'open me' });
+console.log(`wrote ${out}: ${doc.encryption.algorithm}, copy allowed: ${doc.encryption.permissions.copy}; text: ${doc.extractText().trim()}`);

package/examples/fill-form.mjs

@@ -0,0 +1,33 @@
+// Forms: create a fillable PDF, fill it after loading, and flatten it into a plain PDF.
+//
+//   node examples/fill-form.mjs [outDir]   writes form.pdf, filled.pdf, flattened.pdf
+import fs from 'node:fs';
+import path from 'node:path';
+import { toBytes, loadPdf } from '../dist/index.js';
+
+const dir = process.argv[2] ?? '.';
+// 1. Create: every field gets its appearance streams, so every viewer shows the same thing.
+const form = await toBytes(async (pdf) => {
+  const font = pdf.standardFont('Helvetica');
+  const page = pdf.addPage();
+  page.text('Leave request', { x: 40, y: 40, font: pdf.standardFont('Helvetica-Bold'), size: 18 });
+  const f = pdf.form;
+  f.textField('name', { page, x: 40, y: 80, width: 240, height: 22, font, tooltip: 'Full name', required: true });
+  f.comboBox('type', { page, x: 40, y: 115, width: 160, height: 22, font, options: ['Annual', 'Sick', 'Unpaid'], value: 'Annual', tooltip: 'Leave type' });
+  f.checkbox('approved', { page, x: 40, y: 150, width: 14, height: 14, tooltip: 'Approved by manager' });
+  page.text('Approved', { x: 60, y: 151, font, size: 11 });
+  await page.end();
+});
+fs.writeFileSync(path.join(dir, 'form.pdf'), form);
+
+// 2. Fill: values by full field name; the appearances are drawn again by the writer.
+const doc = await loadPdf(form);
+console.log('fields:', doc.fields.map((x) => `${x.name} (${x.type})`).join(', '));
+doc.fill({ name: 'Aanya Sharma', type: 'Sick', approved: true });
+fs.writeFileSync(path.join(dir, 'filled.pdf'), (await doc.save()).bytes);
+
+// 3. Flatten: the fields become page content; no AcroForm is left.
+const flat = (await loadPdf(form)).fill({ name: 'Aanya Sharma', type: 'Sick', approved: true }).flatten();
+const flattened = (await flat.save()).bytes;
+fs.writeFileSync(path.join(dir, 'flattened.pdf'), flattened);
+console.log('flattened text:', (await loadPdf(flattened)).page(0).extractText().replace(/\s+/g, ' '));

package/examples/indic.mjs

@@ -0,0 +1,20 @@
+// Hindi (Devanagari) text shaped by HarfBuzz: conjuncts and reordered matras drawn right, copied text in logical order.
+//
+//   npm i harfbuzzjs
+//   node examples/indic.mjs NotoSansDevanagari-Regular.ttf [out.pdf]
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+import { harfbuzzShaper } from './harfbuzz-shaper.mjs';
+
+const [fontFile, out = 'indic.pdf'] = process.argv.slice(2);
+if (!fontFile) { console.error('node examples/indic.mjs NotoSansDevanagari-Regular.ttf [out.pdf]'); process.exit(2); }
+const pdf = createPdf(fs.createWriteStream(out), { title: 'हिन्दी' });
+const bytes = fs.readFileSync(fontFile);
+const hindi = await pdf.embedFont(bytes, { shaper: harfbuzzShaper(bytes) });
+const latin = pdf.standardFont('Helvetica');
+const page = pdf.addPage();
+page.text('किताब हिन्दी क्षत्रिय', { x: 40, y: 40, font: hindi, size: 24 });
+page.textBox('Mixed text: इस किताब में हिन्दी और English दोनों हैं।', { x: 40, y: 90, width: 400, font: hindi, fallback: [latin], size: 14 });
+await page.end();
+const { warnings } = await pdf.end();
+console.log(`wrote ${out}`, warnings.length ? warnings : '');

package/examples/invoice-facturx.mjs

@@ -0,0 +1,40 @@
+// A self-contained Factur-X invoice: a tagged PDF/A-3a page drawn from the same data as the CII XML embedded in it.
+// (examples/factur-x.mjs does the same from an XML file you already have.)
+//
+//   node examples/invoice-facturx.mjs font.ttf [out.pdf]     any TrueType font, e.g. Inter-Regular.ttf
+//
+// The XML below is a short EN 16931 skeleton for the example. pdf.facturX checks its root, profile ID and that it has
+// no DOCTYPE or entities; it does not validate the invoice: run the Factur-X XSD and Schematron on real invoices.
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+
+const [fontFile, out = 'invoice-facturx.pdf'] = process.argv.slice(2);
+if (!fontFile) { console.error('node examples/invoice-facturx.mjs font.ttf [out.pdf]'); process.exit(2); }
+const inv = { number: 'INV-2026-001', date: '20261009', seller: 'Example Ltd', buyer: 'Acme GmbH', currency: 'EUR',
+  lines: [['Consulting, 10 h', '1000.00'], ['Licence', '250.00']], net: '1250.00', vat: '237.50', total: '1487.50' };
+const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<rsm:CrossIndustryInvoice xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100" xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">
+<rsm:ExchangedDocumentContext><ram:GuidelineSpecifiedDocumentContextParameter><ram:ID>urn:cen.eu:en16931:2017</ram:ID></ram:GuidelineSpecifiedDocumentContextParameter></rsm:ExchangedDocumentContext>
+<rsm:ExchangedDocument><ram:ID>${inv.number}</ram:ID><ram:TypeCode>380</ram:TypeCode><ram:IssueDateTime><udt:DateTimeString format="102">${inv.date}</udt:DateTimeString></ram:IssueDateTime></rsm:ExchangedDocument>
+<rsm:SupplyChainTradeTransaction><ram:ApplicableHeaderTradeAgreement><ram:SellerTradeParty><ram:Name>${inv.seller}</ram:Name></ram:SellerTradeParty><ram:BuyerTradeParty><ram:Name>${inv.buyer}</ram:Name></ram:BuyerTradeParty></ram:ApplicableHeaderTradeAgreement>
+<ram:ApplicableHeaderTradeSettlement><ram:InvoiceCurrencyCode>${inv.currency}</ram:InvoiceCurrencyCode><ram:SpecifiedTradeSettlementHeaderMonetarySummation><ram:TaxBasisTotalAmount>${inv.net}</ram:TaxBasisTotalAmount><ram:TaxTotalAmount currencyID="${inv.currency}">${inv.vat}</ram:TaxTotalAmount><ram:GrandTotalAmount>${inv.total}</ram:GrandTotalAmount><ram:DuePayableAmount>${inv.total}</ram:DuePayableAmount></ram:SpecifiedTradeSettlementHeaderMonetarySummation></ram:ApplicableHeaderTradeSettlement></rsm:SupplyChainTradeTransaction>
+</rsm:CrossIndustryInvoice>`;
+
+const pdf = createPdf(fs.createWriteStream(out), {
+  title: `Invoice ${inv.number}`, author: inv.seller, pdfa: { part: 3, conformance: 'a' }, tagged: { lang: 'en' },
+});
+const font = await pdf.embedFont(fs.readFileSync(fontFile));   // PDF/A: every font embedded
+const page = pdf.addPage();
+const t = (s, x, y, size = 11) => page.text(s, { x, y, font, size });
+page.tag('H1', () => t(`Invoice ${inv.number}`, 56, 56, 22));
+page.tag('P', () => t(`From ${inv.seller} to ${inv.buyer}`, 56, 96));
+page.tag('Table', () => {
+  page.tag('TR', () => ['Item', `Amount (${inv.currency})`].forEach((h, i) => page.tag('TH', () => t(h, 56 + i * 300, 140), { scope: 'Column', id: `h${i}` })));
+  [...inv.lines, ['Net', inv.net], ['VAT 19%', inv.vat], ['Total', inv.total]].forEach(([item, amount], r) =>
+    page.tag('TR', () => [item, amount].forEach((v, i) => page.tag('TD', () => t(v, 56 + i * 300, 162 + r * 20), { headers: [`h${i}`] }))));
+});
+page.stroke(page.path().moveTo(56, 156).lineTo(540, 156), { width: 0.5 });   // outside any tag: an artifact
+await pdf.facturX(new TextEncoder().encode(xml), { profile: 'EN 16931' });
+await page.end();
+const { warnings } = await pdf.end();
+console.log(`wrote ${out}: PDF/A-3a + factur-x.xml (EN 16931)`, warnings.length ? warnings : '');

package/examples/merge-split.mjs

@@ -0,0 +1,29 @@
+// Read and modify: merge, split, extract text, and an incremental update that keeps the original bytes.
+//
+//   node examples/merge-split.mjs [outDir]   writes merged.pdf, page-1.pdf … page-N.pdf, updated.pdf
+import fs from 'node:fs';
+import path from 'node:path';
+import { toBytes, loadPdf, mergePdfs } from '../dist/index.js';
+
+const dir = process.argv[2] ?? '.';
+const make = (label, n) => toBytes(async (pdf) => {
+  const font = pdf.standardFont('Helvetica');
+  for (let i = 1; i <= n; i++) { const p = pdf.addPage(); p.text(`${label}, page ${i}`, { x: 40, y: 40, font, size: 16 }); await p.end(); }
+}, { title: label });
+const a = await loadPdf(await make('Contract', 2)), b = await loadPdf(await make('Annexure', 1));
+
+const merged = await mergePdfs([a, b]);                         // a new file, every page of each
+fs.writeFileSync(path.join(dir, 'merged.pdf'), merged.bytes);
+const all = await loadPdf(merged.bytes);
+console.log(`merged: ${all.pageCount} pages; text:`, all.extractText().split('\f').map((t) => t.trim()));
+
+for (let i = 0; i < all.pageCount; i++) {                       // split: a fork per page
+  const { bytes } = await all.fork().reorder([i]).save();
+  fs.writeFileSync(path.join(dir, `page-${i + 1}.pdf`), bytes);
+}
+
+const doc = await loadPdf(merged.bytes);
+doc.setInfo({ title: 'Contract (reviewed)' });
+const update = await doc.saveIncremental();                     // original bytes + an appended update
+fs.writeFileSync(path.join(dir, 'updated.pdf'), update.bytes);
+console.log(`split into ${all.pageCount} files; update appended ${update.size - merged.bytes.length} bytes`);

package/examples/p12-signer.mjs

@@ -0,0 +1,30 @@
+// A signer for pdf.sign from a PKCS#12 file (.p12 / .pfx: a key and its certificates under a password), through
+// cmsSigner and node-forge (npm i node-forge; it is not a dependency of @reportwright/pdf). RSA keys, PKCS#1 v1.5.
+//
+//   import { p12Signer } from '@reportwright/pdf/examples/p12-signer.mjs';
+//   await pdf.sign({ name: 'Signature1' }, { signer: p12Signer(fs.readFileSync('id.p12'), 'password') });
+import forge from 'node-forge';
+import { cmsSigner } from '@reportwright/pdf';
+
+/** @param {Uint8Array} p12 the file's bytes @param {string} password */
+export function p12Signer(p12, password) {
+  const asn1 = forge.asn1.fromDer(forge.util.createBuffer(Buffer.from(p12).toString('binary')));
+  const box = forge.pkcs12.pkcs12FromAsn1(asn1, password); // a wrong password throws here
+  const bags = (type) => box.getBags({ bagType: type })[type] ?? [];
+  const key = [...bags(forge.pki.oids.pkcs8ShroudedKeyBag), ...bags(forge.pki.oids.keyBag)][0]?.key;
+  if (!key) throw new TypeError('p12Signer: no private key in the file');
+  const certs = bags(forge.pki.oids.certBag).map((b) => b.cert);
+  // the signer's certificate first: the one whose public key is the key's
+  const mine = certs.findIndex((c) => c.publicKey.n?.equals(key.n));
+  if (mine < 0) throw new TypeError("p12Signer: no certificate for the file's key");
+  certs.unshift(...certs.splice(mine, 1));
+  return cmsSigner({
+    certs: certs.map((c) => forge.pki.certificateToPem(c)).join('\n'),
+    keyAlgorithm: 'rsa',
+    sign(bytes, hash) {
+      const md = { 'SHA-256': forge.md.sha256, 'SHA-384': forge.md.sha384, 'SHA-512': forge.md.sha512 }[hash].create();
+      md.update(Buffer.from(bytes).toString('binary'));
+      return Uint8Array.from(Buffer.from(key.sign(md), 'binary'));
+    },
+  });
+}

package/examples/sign.mjs

@@ -0,0 +1,29 @@
+// PAdES B-B signature while the PDF streams out, then a second signature appended with saveIncremental.
+//
+//   openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365 -subj "/CN=Example Signer"
+//   node examples/sign.mjs key.pem cert.pem [out.pdf]
+// For a real signature use a certificate from a CA your readers trust, and a timestamp (RFC 3161) for PAdES B-T.
+import fs from 'node:fs';
+import { createPdf, loadPdf, nodeSigner } from '../dist/index.js';
+
+const [keyFile, certFile, out = 'signed.pdf'] = process.argv.slice(2);
+if (!certFile) { console.error('node examples/sign.mjs key.pem cert.pem [out.pdf]'); process.exit(2); }
+const signer = nodeSigner({ key: fs.readFileSync(keyFile, 'utf8'), certs: fs.readFileSync(certFile, 'utf8') });
+
+const chunks = [];
+const pdf = createPdf({ write: (b) => { chunks.push(Buffer.from(b)); } }, { title: 'Offer letter', sign: true });
+const font = pdf.standardFont('Helvetica');
+const page = pdf.addPage();
+page.text('Offer letter', { x: 40, y: 40, font, size: 18 });
+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', name: 'HR', certify: 2 });   // DocMDP P=2: signing allowed later
+await page.end();
+await pdf.end();                                                 // the signer runs here, on the streamed bytes' digest
+
+// Countersign: appends an update, so the first signature stays valid.
+const doc = await loadPdf(Buffer.concat(chunks));
+const { bytes } = await doc.saveIncremental({ sign: { field: 'candidate', signer, reason: 'Accepted' } });
+fs.writeFileSync(out, bytes);
+const signatures = (await loadPdf(bytes)).signatures;
+console.log(`wrote ${out}:`, signatures.map((s) => `${s.field} (revision ${s.revision}, covers the whole file: ${s.coversWholeFile})`).join('; '));

package/examples/write.mjs

@@ -0,0 +1,53 @@
+// Text, an image, a table drawn with paths, a link and bookmarks, using the standard fonts (no files needed).
+//
+//   node examples/write.mjs [out.pdf]
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+import { createPdf } from '../dist/index.js';
+
+const out = process.argv[2] ?? 'write.pdf';
+const pdf = createPdf(fs.createWriteStream(out), { title: 'Quarterly report', author: 'Example Ltd' });
+const regular = pdf.standardFont('Helvetica'), bold = pdf.standardFont('Helvetica-Bold');
+
+// A 32 x 32 RGBA PNG made here so the example needs no image file (use fs.readFileSync('logo.png') in real code).
+function png(w, h, pixel) {
+  const chunk = (type, data) => {
+    const b = Buffer.alloc(12 + data.length); b.writeUInt32BE(data.length, 0); b.write(type, 4, 'latin1'); data.copy(b, 8);
+    b.writeUInt32BE(zlib.crc32(b.subarray(4, 8 + data.length)), 8 + data.length); return b;
+  };
+  const ihdr = Buffer.alloc(13); ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4); ihdr.set([8, 6, 0, 0, 0], 8);
+  const raw = Buffer.alloc(h * (1 + w * 4));
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) raw.set(pixel(x, y), y * (1 + w * 4) + 1 + x * 4);
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+}
+const logo = await pdf.embedImage(png(32, 32, (x, y) => [31, 78, 121, (x - 16) ** 2 + (y - 16) ** 2 < 256 ? 255 : 0]));
+
+const page = pdf.addPage();                                     // A4; origin top-left, y down, in points
+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('Revenue grew in every region. The table below is drawn with paths: a filled header row, ' +
+  'rules between rows and right-aligned numbers.', { x: 40, y: 90, width: 515, font: regular, size: 11, align: 'justify' });
+
+// A table from paths: no table primitive is needed.
+const rows = [['Region', 'Q1', 'Q2'], ['North', '1,204', '1,390'], ['South', '980', '1,122'], ['West', '1,510', '1,488']];
+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' });
+rows.forEach((r, i) => {
+  const y = top + i * rowH;
+  r.forEach((cell, c) => {
+    const font = i === 0 ? bold : regular, size = 11;
+    const x = c === 0 ? cols[c] + 6 : (cols[c + 1] ?? right) - 6 - font.widthOfText(cell, size);
+    page.text(cell, { x, y: y + 5, font, size, 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 });
+});
+
+page.text('Read the full report online', { x: 40, y: top + rows.length * rowH + 20, font: regular, color: '#0645ad' });
+page.link(40, top + rows.length * rowH + 20, 160, 14, { url: 'https://example.com/report' });
+
+const p2 = pdf.addPage();
+p2.text('Appendix', { x: 40, y: 40, font: bold, size: 18 });
+pdf.outline([{ title: 'Quarterly report', page: 1 }, { title: 'Appendix', page: 2, level: 1 }]);
+await page.end(); await p2.end();
+const { pages, bytes, warnings } = await pdf.end();
+console.log(`wrote ${out}: ${pages} pages, ${bytes} bytes`, warnings.length ? warnings : '');

package/fflate.d.ts

@@ -0,0 +1,3 @@
+// @reportwright/pdf/fflate: the fflate (MIT) this package bundles, for a bundle that also uses fflate (the ReportWright
+// engine) to share one copy. Its types are fflate's own (npm i -D fflate@0.8.3 to have them).
+export * from 'fflate';

package/index.d.ts

@@ -64,6 +64,13 @@ export interface PdfOptions {
   creationDate?: Date;
   /** Flate-compress content, fonts, object streams (default true). */
   compress?: boolean;
+  /**
+   * The zlib level (0–9) the object streams (the small objects, packed together) and the cross-reference stream are
+   * compressed at. Unset: the object streams at 6 and the cross-reference stream by the bundled fflate at 6, as before
+   * beta.7. Set, both go through the platform's zlib (Node's) at that level: 9 makes the file a little smaller and
+   * slower. The same input and options give the same bytes.
+   */
+  objectStreamLevel?: number;
   /**
    * PDF/A: an output intent (sRGB, or outputIntent: your RGB or CMYK ICC output/monitor profile) and XMP
    * identification. Fonts must be embedded; device colour must match the intent (CMYK needs a CMYK intent, RGB an RGB one).
@@ -329,6 +336,9 @@ export interface Path {
   svg(d: string): this;
 }
 
+/** SVG path data `d` as PDF path operators (m, l, c, h) in SVG user space; scaleY -1 flips y. Malformed data throws a TypeError. */
+export function svgPathOps(d: string, opts?: { scaleY?: number }): string;
+
 /** A gradient or tiling pattern made by a page of this document (an opaque handle: copies and forgeries are refused). */
 export interface Gradient { readonly type: 'gradient' }
 export interface TilingPattern { readonly type: 'tiling' }
@@ -540,6 +550,22 @@ export interface Field {
   readonly type: 'field';
   readonly kind: 'text' | 'checkbox' | 'radio' | 'combo' | 'list' | 'button' | 'signature';
   readonly name: string;
+  /** the widget's object number (field and widget are one dictionary), for a structure tree's OBJR; 0 when flattened. Not on a radio group */
+  readonly widgetRef?: number;
+}
+/**
+ * A caller's own appearance for a field (pdf.core callers): each state's content-stream operators (Latin-1), written
+ * exactly as the normal appearance (/AP /N); resources: the object number of its Resources ("12 0 R", written through
+ * pdf.core), default the shared Resources (which hold every font registered with core.resource('Font', …)).
+ */
+export interface OwnAppearance { normal: string; resources?: string }
+/** A caller's appearance, /DA and structure link for a text-bearing field */
+export interface OwnTextLook {
+  appearance?: OwnAppearance;
+  /** the default appearance written as /DA ("/F1 12 Tf 0 g": printable ASCII with Tf); with appearance, font is not needed */
+  da?: string;
+  /** /StructParent, for a caller's own structure tree (not with tagged: the built-in tagger links fields itself) */
+  structParent?: number;
 }
 /** Where a widget goes: a page of this PDF and a box (top-left space). */
 export interface WidgetBox { page: Page; x?: number; y?: number; width: number; height: number }
@@ -565,7 +591,9 @@ export interface FieldTextOptions {
   align?: 'left' | 'center' | 'right';
 }
 export type CheckStyle = 'check' | 'cross' | 'circle' | 'square' | 'diamond' | 'star';
-export interface TextFieldOptions extends FieldOptions, FieldTextOptions {
+export interface TextFieldOptions extends FieldOptions, Omit<FieldTextOptions, 'font'>, OwnTextLook {
+  /** required unless both appearance and da are given */
+  font?: Font;
   /** at most 100,000 characters (and maxLen); line breaks only when multiline */
   value?: string;
   defaultValue?: string;
@@ -585,6 +613,10 @@ export interface CheckboxOptions extends FieldOptions {
   style?: CheckStyle;
   /** the mark's colour */
   color?: Color;
+  /** the caller's own on and off appearances (operators), instead of the drawn mark */
+  appearance?: { on: string; off: string; resources?: string };
+  /** /StructParent, for a caller's own structure tree */
+  structParent?: number;
 }
 export interface RadioGroupOptions extends Omit<FieldOptions, keyof WidgetBox> {
   /** 1–1000 buttons, each with its own export value (the same one only with radiosInUnison) */
@@ -600,7 +632,9 @@ export interface RadioGroupOptions extends Omit<FieldOptions, keyof WidgetBox> {
 }
 /** an option: one string (export value and display text), or [export value, display text] */
 export type ChoiceOption = string | readonly [string, string];
-export interface ChoiceOptions extends FieldOptions, FieldTextOptions {
+export interface ChoiceOptions extends FieldOptions, Omit<FieldTextOptions, 'font'>, OwnTextLook {
+  /** required unless both appearance and da are given */
+  font?: Font;
   /** at most 10,000, in the order given (the Sort flag is never set); export values unique */
   options: ChoiceOption[];
 }
@@ -626,7 +660,11 @@ export interface ButtonOptions extends FieldOptions, Partial<FieldTextOptions> {
   /** the face when pressed (/D; not in PDF/A, whose appearances have /N only) */
   pressedBackground?: Color;
 }
-export interface SignatureOptions extends FieldOptions {
+/** No width and height: an invisible field (a zero /Rect, /F 132), on page when given (still open), else on no page (AcroForm only) */
+export interface SignatureOptions extends Omit<FieldOptions, 'page' | 'width' | 'height'> {
+  page?: Page;
+  width?: number;
+  height?: number;
   /** /Lock: the fields signing locks */
   lock?: { action?: 'All' } | { action: 'Include' | 'Exclude'; fields: (string | Field)[] };
 }
@@ -644,12 +682,85 @@ export interface FormScope {
   signature(name: string, o: SignatureOptions): Field;
 }
 
+/**
+ * The extension API (`pdf.core`): the object writer, the shared Resources, the catalog and the end-of-document hooks
+ * that every feature module works through (ARCHITECTURE.md, "Extension points"). A caller writing its own content
+ * streams and objects (the ReportWright engine) uses it beside the Pdf methods. Not covered by semver in 0.x.
+ * Object text is PDF syntax: `"12 0 R"`, `"<< /Type /XObject … >>"`. In an encrypted file every string in it (literal
+ * or hex) is encrypted when the object is written.
+ */
+export interface PdfCore {
+  /** a new object number, for an object written later with write() (or writeStream, writeBig) */
+  reserve(): number;
+  /** write object n now: a dictionary or any value, and for a stream its bytes already filtered (/Length is added). Small objects go into object streams */
+  write(n: number, dict: string, stream?: Uint8Array): Promise<void> | undefined;
+  /** write object n as a stream of raw bytes, Flate-compressed (adding /Filter) unless compress is off */
+  writeStream(n: number, dict: string, raw: Uint8Array): Promise<void> | undefined;
+  /** write object n whose text may be too long to hold (head, the parts as they come, tail) */
+  writeBig(n: number, head: string, parts: Iterable<string>, tail: string): Promise<void>;
+  /** reserve and write */
+  object(dict: string, stream?: Uint8Array): Promise<number>;
+  /** a name (without the slash) in the shared Resources dictionary of every page for a value ("12 0 R" or an inline dictionary); the same value gets the same name */
+  resource(kind: 'Font' | 'XObject' | 'ExtGState' | 'Pattern' | 'Shading' | 'ColorSpace' | 'Properties', value: string, name?: string): string;
+  /**
+   * an embedded image (pdf.embedImage) for a caller's own content stream: its name in the shared Resources, its object
+   * number, whether it has transparency (the page then needs a transparency /Group, as page.image sets) and its EXIF
+   * orientation as a unit-square matrix. Draw it with `q w 0 0 h x y cm <orientation> cm /<name> Do Q`
+   */
+  imageResource(image: Image): { name: string; ref: number; alpha: boolean; orientation: [number, number, number, number, number, number] };
+  /** the shared Resources dictionary's object number (a form XObject drawing with page resources uses it) */
+  readonly resourcesRef: number;
+  /** a catalog entry (key without the slash), read when the catalog is written: finishers may still set it */
+  catalog(key: string, value: string): void;
+  /** run fn at end(), after the last page is written and before the fonts and the catalog; in registration order */
+  onFinish(fn: () => Promise<void> | void): void;
+  /** a font object written after every finisher (see Font in src/document.js) */
+  addFont(font: unknown): void;
+  /** page i's object number (0-based), reserved ahead when the page does not exist yet */
+  pageRef(i: number): number;
+  /** page i's height, once the page exists */
+  pageHeight(i: number): number | undefined;
+  readonly pageCount: number;
+  /** a warning in end()'s result */
+  warn(message: string): void;
+  /** run fn after every write queued before it (writes outside a page or a finisher must go through it: the object writer is not re-entrant) */
+  serial<T>(fn: () => Promise<T>): Promise<T>;
+  /** the first failure of a queued write, or null */
+  readonly failed: unknown;
+  /** the options a module must respect */
+  readonly compress: boolean;
+  readonly pdfa: boolean;
+  readonly pdfaLevel: { part: 1 | 2 | 3; conformance: 'a' | 'b' | 'u'; unicode: boolean } | null;
+  readonly tagged: boolean;
+  readonly signal: AbortSignal;
+  /** the Info dictionary's text to write instead of the one made from the options (null: made from the options) */
+  info: string | null;
+  /** the XMP packet to write instead of the one made from the options */
+  xmp: Uint8Array | null;
+  /** more XMP schemas (standards/xmp.js Extension), pushed before the end */
+  xmpExtensions: unknown[];
+  /** made to be signed (createPdf's sign option): every byte is hashed */
+  readonly signing: boolean;
+  /** the AcroForm's /SigFlags (pdf.sign sets 3) */
+  sigFlags: number;
+  /** the signature dictionary written as the file's last object (security/sign.js); internal */
+  last: unknown;
+  /** the structure tree (tags/tags.js) when tagged, else null: tags.link(page, annotRef, 'Link' | 'Annot') gives an annotation its element (with an OBJR) and returns its /StructParent */
+  tags: { link(page: Page, annotRef: number, type?: 'Link' | 'Annot'): number; [k: string]: unknown } | null;
+  /** internal: the page queue (used by Page and createPdf) */
+  newPage(page: unknown): number;
+  opened(page: unknown): void;
+  queuePage(page: unknown): Promise<void>;
+  finish(blank: () => unknown): Promise<{ pages: number; bytes: number; warnings: string[] }>;
+}
+
 export interface Pdf {
   standardFont(name: StandardFontName): Font;
-  /** a TrueType or OpenType/CFF font; subset by default; shaper: text goes through it (complex scripts) */
-  embedFont(bytes: Uint8Array | ArrayBuffer, o?: { subset?: boolean | Subsetter; shaper?: Shaper }): Promise<Font>;
+  /** a TrueType or OpenType/CFF font; subset by default; shaper: text goes through it (complex scripts);
+   * textMapping: 'carrier' (default: Firefox, pdf.js, search) or 'actualText' (a shaped cluster's text only in its ActualText: MuPDF, AI pipelines) */
+  embedFont(bytes: Uint8Array | ArrayBuffer, o?: { subset?: boolean | Subsetter; shaper?: Shaper; textMapping?: 'carrier' | 'actualText' }): Promise<Font>;
   /** a JPEG or PNG, written now as an image XObject. colorSpace: an ICC colour space with the image's component count */
-  embedImage(bytes: Uint8Array | ArrayBuffer, o?: { colorSpace?: IccColorSpace; /** the decoded size a PNG with alpha or interlacing may have; default 64 MB */ maxDecodedBytes?: number }): Promise<Image>;
+  embedImage(bytes: Uint8Array | ArrayBuffer, o?: { colorSpace?: IccColorSpace; /** the decoded size a PNG with alpha or interlacing may have; default 64 MB */ maxDecodedBytes?: number; /** zlib level for a re-compressed PNG (alpha, interlacing): 'default' = 6, or 3 above 2 megapixels; 'fast' = 1; or 1–9 */ compression?: 'default' | 'fast' | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }): Promise<Image>;
   /** a spot colour: its name and the device colour (gray, RGB, CMYK) shown for it at full tint. One definition per name */
   spotColor(name: string, alternate: number | string | readonly number[]): SpotColor;
   /** an ICC-based colour space from a gray, RGB or CMYK profile (its header is checked) */
@@ -683,7 +794,7 @@ export interface Pdf {
   /** end open pages, write the rest, end the sink */
   end(): Promise<{ pages: number; bytes: number; warnings: string[] }>;
   /** the extension API (ARCHITECTURE.md); not covered by semver in 0.x */
-  readonly core: unknown;
+  readonly core: PdfCore;
 }
 
 export function createPdf(sink: Sink, options?: PdfOptions): Pdf;
@@ -691,6 +802,38 @@ export function createPdf(sink: Sink, options?: PdfOptions): Pdf;
 export function toBytes(build: (pdf: Pdf) => unknown, options?: PdfOptions): Promise<Uint8Array>;
 export const STANDARD_NAMES: StandardFontName[];
 
+/** A font file read for metrics and glyph lookup. Throws a TypeError on bytes that are not a TrueType or OpenType font. */
+export interface FontInfo {
+  /** glyph count (maxp) */
+  readonly numGlyphs: number;
+  /** PostScript name (name ID 6), as written in the file */
+  readonly postscriptName: string;
+  /** OS/2 fsType embedding flags (0 means installable embedding) */
+  readonly fsType: number;
+  readonly unitsPerEm: number;
+  /** hhea ascent, in font units */
+  readonly ascent: number;
+  /** hhea descent, in font units (negative) */
+  readonly descent: number;
+  /** true for an OpenType font with CFF outlines */
+  readonly isCFF: boolean;
+  /** horizontal advance of a glyph ID, in font units; 0 for an ID past numGlyphs */
+  advance(glyphId: number): number;
+  /** whether the Unicode cmap maps this code point to a glyph */
+  hasGlyph(codePoint: number): boolean;
+  /** the glyph ID for a code point, 0 when none */
+  glyphForCodePoint(codePoint: number): number;
+}
+
+/** Read a font file's metrics and cmap. */
+export function readFont(bytes: Uint8Array): FontInfo;
+
+/**
+ * Check a font subset before embedding it. Returns a description of the first problem (header, table directory, loca
+ * order, CFF INDEXes), or null when the subset is well formed. Never throws.
+ */
+export function checkSubset(bytes: Uint8Array): string | null;
+
 // ---- reading and modifying (group H) ----
 
 export type PdfReadErrorCode = 'E_MALFORMED' | 'E_BUDGET' | 'E_DEPTH' | 'E_CYCLE' | 'E_TIMEOUT' | 'E_ABORTED' | 'E_PASSWORD' | 'E_ENCRYPTED' | 'E_UNSUPPORTED' | 'E_ACTIVE' | 'E_SIGNED';
@@ -845,3 +988,38 @@ export interface LoadedPdf {
 export function loadPdf(bytes: Uint8Array | ArrayBuffer, options?: LoadOptions): Promise<LoadedPdf>;
 /** every page of each document, in order, in a new file (the first one's catalog, with what the others bring) */
 export function mergePdfs(docs: LoadedPdf[], options?: SaveOptions): Promise<SaveResult & { bytes: Uint8Array }>;
+/** the tasks bulk() runs, by name (no functions cross to a worker) */
+export type BulkTask = 'extractText' | 'merge' | 'split' | 'encrypt';
+export const BULK_TASKS: readonly BulkTask[];
+/** what each task takes per item, and gives back */
+export interface BulkTaskTypes {
+  extractText: { input: Uint8Array | ArrayBuffer; value: string };
+  merge: { input: (Uint8Array | ArrayBuffer)[]; value: Uint8Array };
+  split: { input: Uint8Array | ArrayBuffer; value: Uint8Array[] };
+  encrypt: { input: Uint8Array | ArrayBuffer; value: Uint8Array };
+}
+export type BulkResult<V> = { ok: true; value: V } | { ok: false; error: { name: string; code?: string; message: string } };
+export interface BulkOptions {
+  /** worker threads (1 to 64); default os.availableParallelism() - 1 (at least 1). 1, or no node:worker_threads (browsers): one at a time, in this thread.
+   * Workers are kept warm (unref'd) for 2 s after a call, for the next; small files are sent several at a time */
+  workers?: number;
+  /** each worker's heap cap in MB (resourceLimits.maxOldGenerationSizeMb), 16 to 16384, default 512: an item past it fails with E_WORKER, alone */
+  memoryMb?: number;
+  /** loadPdf's options, for every input */
+  password?: string;
+  budget?: ReadBudget;
+  timeoutMs?: number;
+  /** the encrypt task's encryption */
+  encrypt?: EncryptOptions;
+  /** save()'s options for merge, split and encrypt */
+  save?: SaveOptions;
+  /** each item's result as it finishes (index in inputs) */
+  onResult?: (index: number, result: BulkResult<unknown>) => void;
+  /** each item's time limit in a worker, default 120000, at most 2147483647: past it the worker is ended, the item fails with E_TIMEOUT and the rest go on.
+   * With one input, workers: 1, or a host where workers resolve to 1 (2 CPUs), items run in the calling thread: no time limit and no heap cap apply there. */
+  itemTimeoutMs?: number;
+  /** stops the call: its workers are ended (not kept warm) and bulk rejects with the signal's reason (AbortSignal.timeout(ms) for a time limit) */
+  signal?: AbortSignal;
+}
+/** One named task over many inputs, in parallel worker threads (Node); results in input order, a failing item never stops the rest. */
+export function bulk<T extends BulkTask>(inputs: Iterable<BulkTaskTypes[T]['input']>, task: T, options?: BulkOptions): Promise<BulkResult<BulkTaskTypes[T]['value']>[]>;