@reportwright/pdf 0.1.0-beta.0 → 0.1.0-beta.2

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/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/factur-x.mjs

@@ -0,0 +1,37 @@
+// A Factur-X (ZUGFeRD 2.1+) invoice: a tagged PDF/A-3a page with the CII XML embedded as factur-x.xml.
+//
+//   node examples/factur-x.mjs invoice.xml font.ttf out.pdf [profile]
+//
+// The XML must be a UN/CEFACT CrossIndustryInvoice whose GuidelineSpecifiedDocumentContextParameter ID names the
+// profile (EN 16931 by default: urn:cen.eu:en16931:2017). pdf.facturX checks that, refuses any DOCTYPE or entity, and
+// writes the fx XMP schema; it does not validate the invoice itself (run the Factur-X XSD and Schematron for that).
+// The page here only shows a few fields; a real one draws the whole invoice from the same data as the XML.
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+
+const [xmlFile, fontFile, outFile, profile = 'EN 16931'] = process.argv.slice(2);
+if (!outFile) { console.error('node examples/factur-x.mjs invoice.xml font.ttf out.pdf [profile]'); process.exit(2); }
+const xml = fs.readFileSync(xmlFile);
+const text = xml.toString('utf8');
+/** the first <ram:tag> after anchor (display only: the page shows a few fields of the XML) */
+const field = (tag, anchor = '') => new RegExp(`${anchor}[\\s\\S]*?<ram:${tag}[^>]*>([^<]*)<`).exec(text)?.[1] ?? '';
+const number = field('ID', '<rsm:ExchangedDocument>'), seller = field('Name', '<ram:SellerTradeParty>');
+
+const pdf = createPdf(fs.createWriteStream(outFile), {
+  title: `Invoice ${number}`, author: seller, subject: 'Factur-X invoice', keywords: `invoice, Factur-X, ${profile}`,
+  pdfa: { part: 3, conformance: 'a' }, tagged: { lang: 'en' },
+});
+const font = await pdf.embedFont(fs.readFileSync(fontFile));
+const page = pdf.addPage({ trimBox: [0, 0, 595.28, 841.89] });
+const line = (s, y, size = 11) => page.text(s, { x: 56, y, font, size });
+page.artifact({ type: 'Pagination', subtype: 'Header' }, () => line('Factur-X invoice: the XML inside this PDF is the legal invoice', 24, 8));
+page.tag('H1', () => line(`Invoice ${number}`, 60, 22));
+page.tag('P', () => line(`Seller: ${seller}`, 110));
+page.tag('Table', () => {
+  page.tag('TR', () => ['Net', 'VAT', 'Total'].forEach((h, i) => page.tag('TH', () => page.text(h, { x: 56 + i * 140, y: 150, font }), { scope: 'Column', id: `h${i}` })));
+  page.tag('TR', () => [field('TaxBasisTotalAmount'), field('TaxTotalAmount'), field('GrandTotalAmount')].forEach((v, i) =>
+    page.tag('TD', () => page.text(`${v} ${field('InvoiceCurrencyCode')}`, { x: 56 + i * 140, y: 170, font }), { headers: [`h${i}`] })));
+});
+await pdf.facturX(xml, { profile });
+await pdf.end();
+console.log(`wrote ${outFile}: PDF/A-3a with factur-x.xml (${profile})`);

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/harfbuzz-shaper.mjs

@@ -0,0 +1,27 @@
+// A shaper for @reportwright/pdf's embedFont(bytes, { shaper }) built on harfbuzzjs (npm i harfbuzzjs). harfbuzzjs is
+// not a dependency of @reportwright/pdf: copy this file, or import it where harfbuzzjs is installed.
+//
+//   import { harfbuzzShaper } from './harfbuzz-shaper.mjs';
+//   const bytes = fs.readFileSync('NotoSansArabic-Regular.ttf');
+//   const arabic = await pdf.embedFont(bytes, { shaper: harfbuzzShaper(bytes) });
+//   page.text('مرحبا بالعالم', { x: 40, y: 40, font: arabic, size: 18, direction: 'rtl' });
+//
+// The shaper gets one run (one font, one direction) and returns its glyphs in visual order, in font units:
+// { g: glyph ID, cl: cluster (UTF-16 index of its first character), ax: x advance, dx, dy: offsets }.
+import * as hb from 'harfbuzzjs';
+
+const NO_KERN = [new hb.Feature('kern', 0)];
+
+/** @param {Uint8Array} fontBytes the same bytes passed to embedFont */
+export function harfbuzzShaper(fontBytes) {
+  const font = new hb.Font(new hb.Face(new hb.Blob(fontBytes))); // scale: units per em, so positions are font units
+  return (text, _font, { direction, kerning }) => {
+    const b = new hb.Buffer();
+    b.addText(text); // clusters are UTF-16 indices, as JavaScript strings count
+    b.guessSegmentProperties(); // script and language from the text
+    b.setDirection(direction === 'rtl' ? hb.Direction.RTL : hb.Direction.LTR);
+    hb.shape(font, b, kerning ? [] : NO_KERN);
+    const pos = b.getGlyphPositions();
+    return b.getGlyphInfos().map((g, i) => ({ g: g.codepoint, cl: g.cluster, ax: pos[i].xAdvance, dx: pos[i].xOffset, dy: pos[i].yOffset }));
+  };
+}

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/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/index.d.ts

@@ -74,6 +74,11 @@ export interface PdfOptions {
   pdfa?: boolean | { part?: 1 | 2 | 3; conformance?: 'a' | 'b' | 'u'; outputIntent?: Uint8Array | ArrayBuffer };
   /** PDF/UA-1: a structure tree from page.tag(). Needs title; fonts must be embedded. */
   tagged?: boolean | { lang?: string };
+  /**
+   * false: no XMP metadata stream, the Info dictionary only (about 1 KB smaller: a one-page invoice). Default true.
+   * Refused with pdfa or tagged: PDF/A and PDF/UA require the XMP.
+   */
+  metadata?: boolean;
   /** stop the export: pending and later calls reject with signal.reason */
   signal?: AbortSignal;
   /** stop the export after this many milliseconds (a TimeoutError, code 'ETIMEDOUT') */
@@ -641,8 +646,9 @@ export interface FormScope {
 
 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>;
   /** a spot colour: its name and the device colour (gray, RGB, CMYK) shown for it at full tint. One definition per name */
@@ -703,7 +709,7 @@ export interface ReadBudget {
   maxSteps?: number;
   /** cross-reference entries and scanned objects held (default 5,000,000) */
   maxObjects?: number;
-  /** pieces of text one page's extraction holds (default 2,000,000) */
+  /** pieces of text one page's extraction holds (default 1,000,000; a page also stops at 16,000,000 characters) */
   maxTextItems?: number;
 }
 export interface LoadOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportwright/pdf",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "description": "A streaming PDF writer for Node and browsers with no runtime dependencies: flat memory, PDF/A-1b to 3a, PDF/UA-1, Factur-X, embedded TrueType with Unicode text.",
   "type": "module",
   "license": "MIT",
@@ -12,10 +12,11 @@
   "publishConfig": { "access": "public" },
   "exports": {
     ".": { "types": "./index.d.ts", "default": "./dist/index.js" },
+    "./examples/*": "./examples/*",
     "./package.json": "./package.json"
   },
   "types": "./index.d.ts",
-  "files": ["dist", "index.d.ts", "README.md", "LICENSE", "THIRD-PARTY-NOTICES.md"],
+  "files": ["dist", "index.d.ts", "examples", "README.md", "LICENSE", "THIRD-PARTY-NOTICES.md"],
   "engines": { "node": ">=20.16" },
   "sideEffects": false
 }