pdf-lite 1.6.0 → 1.6.2

package/README.md

@@ -92,6 +92,89 @@ await document.encrypt()
 console.log(document.toString())
 ```
 
+### Filling AcroForms
+
+```typescript
+import { PdfDocument } from 'pdf-lite/pdf/pdf-document'
+import { readFile, writeFile } from 'fs/promises'
+
+const pdfBytes = await readFile('form.pdf')
+const doc = await PdfDocument.fromBytes([pdfBytes])
+
+const form = doc.acroform
+if (!form) throw new Error('No AcroForm found')
+
+// Set multiple field values at once
+form.setValues({
+    name: 'John Doe',
+    email: 'john@example.com',
+    subscribe: 'Yes', // checkbox: 'Yes' or 'Off'
+})
+
+// Or work with individual fields
+const field = form.fields.find((f) => f.name === 'name')
+field.value = 'Jane Doe'
+
+// Export all current values
+const values = form.exportData()
+// => { name: 'Jane Doe', email: 'john@example.com', subscribe: 'Yes' }
+
+await writeFile('filled.pdf', doc.toBytes())
+```
+
+### Generating Appearances
+
+Appearance streams control how form fields render visually. The library can automatically generate them when field values are set, or you can generate them manually.
+
+```typescript
+// Auto-generate appearances when setting values (default behavior)
+field.value = 'Hello' // appearance is generated automatically
+
+// Or generate manually with options
+field.generateAppearance({ makeReadOnly: true })
+
+// Configure font and size for a field
+field.fontSize = 14
+field.fontName = 'Helv'
+
+// For checkbox fields
+const checkbox = form.fields.find((f) => f.name === 'agree')
+checkbox.checked = true
+checkbox.generateAppearance()
+
+// For choice fields (dropdowns/listboxes)
+const dropdown = form.fields.find((f) => f.name === 'country')
+dropdown.value = 'US'
+dropdown.generateAppearance()
+```
+
+### Working with Fonts
+
+```typescript
+import { PdfFont } from 'pdf-lite'
+
+// Standard PDF fonts (built into all PDF readers)
+const helvetica = PdfFont.fromStandardFont('Helvetica')
+const timesBold = PdfFont.fromStandardFont('Times-Bold')
+const courier = PdfFont.fromStandardFont('Courier')
+
+// Embed custom fonts from file bytes (auto-detects TTF, OTF, WOFF)
+import { readFileSync } from 'fs'
+const fontData = readFileSync('MyFont.ttf')
+const customFont = PdfFont.fromBytes(fontData)
+
+// Use pre-defined font constants
+const font = PdfFont.HELVETICA_BOLD
+
+// Assign resource names for use in content streams
+customFont.resourceName = 'F1'
+
+// Add to document
+document.add(customFont)
+```
+
+**Standard font names:** Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique, Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic, Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique, Symbol, ZapfDingbats
+
 ### Signing PDFs
 
 ```typescript
@@ -187,14 +270,47 @@ Long-Term Validation (LTV) support ensures that digital signatures remain valid
 - [x] Timestamping
 - [x] Verification of existing signatures
 
-### AcroForm filling
+### AcroForms
+
+Supports reading, filling, and creating AcroForm fields within PDF documents.
 
-Supports filling out AcroForm forms within PDF documents, allowing for dynamic content generation and user interaction.
+**Field types:**
 
-- [x] Text fields
+- [x] Text fields (single-line, multi-line, comb, password)
 - [x] Checkboxes
 - [x] Radio buttons
-- [x] Dropdowns
+- [x] Dropdowns (combo boxes)
+- [x] List boxes
+- [x] Signature fields
+
+**Form operations:**
+
+- [x] Import/export field values (`importData`, `exportData`, `setValues`)
+- [x] Read individual field properties (name, value, type, flags)
+- [x] Hierarchical field support (parent/child/sibling fields)
+
+### Appearance Streams
+
+Automatic generation of visual appearance streams for form fields, so filled forms render correctly in all PDF viewers without relying on `NeedAppearances`.
+
+- [x] Text field rendering (word wrap, auto-sizing, comb layout)
+- [x] Checkbox/radio button rendering
+- [x] Dropdown/list box rendering
+- [x] Font resolution from field, form, or document resources
+- [x] Auto-size font (fontSize=0) for single-line text fields
+- [x] Custom font color via Default Appearance strings
+
+### Fonts
+
+Supports standard PDF fonts and embedding custom fonts.
+
+- [x] All 14 standard PDF fonts (Helvetica, Times, Courier, Symbol, ZapfDingbats + variants)
+- [x] TrueType font embedding (TTF)
+- [x] OpenType font embedding (OTF, non-CFF)
+- [x] WOFF font embedding
+- [x] Auto-detect font format via `PdfFont.fromBytes()`
+- [x] Font encoding maps (WinAnsi, Unicode/Identity-H)
+- [x] Character width metrics
 
 ### XFA Forms
 

package/dist/acroform/appearance/pdf-graphics.js

@@ -192,13 +192,14 @@ export class PdfGraphics {
         const startSize = this.currentFont.size;
         const minSize = 0.5;
         const fits = (size) => {
-            if (this.measureTextWidth(text, size) > maxWidth)
-                return false;
             if (maxHeight !== undefined) {
+                // Wrapping mode: text is allowed to span multiple lines,
+                // so only check that the wrapped result fits the box.
                 const lines = this.wrapTextToLines(text, maxWidth, size);
                 return lines.length * size * lineHeight <= maxHeight;
             }
-            return true;
+            // Single-line mode: text must fit within maxWidth.
+            return this.measureTextWidth(text, size) <= maxWidth;
         };
         if (fits(startSize))
             return startSize;

package/dist/acroform/appearance/pdf-text-appearance-stream.js

@@ -1,6 +1,7 @@
 import { PdfDefaultAppearance } from '../fields/pdf-default-appearance.js';
 import { PdfAppearanceStream } from './pdf-appearance-stream.js';
 import { PdfGraphics } from './pdf-graphics.js';
+const DEFAULT_FONT_SIZE = 12;
 /**
  * Appearance stream for text fields (single-line, multiline, comb).
  * Enhanced with word wrapping and automatic font scaling.
@@ -16,29 +17,44 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         const padding = 2;
         const availableWidth = width - 2 * padding;
         const availableHeight = height - 2 * padding;
+        const autoSize = ctx.da.fontSize <= 0;
         // Create graphics with font context for text measurement
         const g = new PdfGraphics({
             resolvedFonts: ctx.resolvedFonts,
         });
         g.beginMarkedContent();
         g.save();
-        // Set initial font to enable measurement
-        g.setDefaultAppearance(ctx.da);
-        let finalFontSize = ctx.da.fontSize;
-        let lines = [];
-        if (ctx.multiline) {
+        // Bootstrap with a reference size so measureTextWidth works
+        g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, DEFAULT_FONT_SIZE, ctx.da.colorOp));
+        // ── Determine font size ──────────────────────────────────────
+        let finalFontSize;
+        if (autoSize) {
+            // Acrobat auto-size: default to 12pt with wrapping, then
+            // shrink only if the wrapped text still doesn't fit.
+            finalFontSize = DEFAULT_FONT_SIZE;
             const testLines = g.wrapTextToLines(value, availableWidth);
-            const lineHeight = finalFontSize * 1.2;
-            if (testLines.length * lineHeight > availableHeight) {
-                // Scale font down to fit
+            if (testLines.length * DEFAULT_FONT_SIZE * 1.2 > availableHeight) {
                 finalFontSize = g.calculateFittingFontSize(value, availableWidth, availableHeight, 1.2);
-                const adjustedDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
-                g.setDefaultAppearance(adjustedDA);
-                lines = g.wrapTextToLines(value, availableWidth);
             }
-            else {
-                lines = testLines;
+            finalFontSize = Math.max(finalFontSize, 0.5);
+        }
+        else {
+            finalFontSize = ctx.da.fontSize;
+        }
+        // ── Render ───────────────────────────────────────────────────
+        const finalDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
+        g.setDefaultAppearance(finalDA);
+        let lines = [];
+        if (ctx.multiline || autoSize) {
+            if (!autoSize) {
+                const testLines = g.wrapTextToLines(value, availableWidth);
+                const lineHeight = finalFontSize * 1.2;
+                if (testLines.length * lineHeight > availableHeight) {
+                    finalFontSize = g.calculateFittingFontSize(value, availableWidth, availableHeight, 1.2);
+                    g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+                }
             }
+            lines = g.wrapTextToLines(value, availableWidth);
             const renderLineHeight = finalFontSize * 1.2;
             const startY = height - padding - finalFontSize;
             g.beginText();
@@ -53,7 +69,6 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         else if (ctx.comb && ctx.maxLen) {
             const cellWidth = width / ctx.maxLen;
             const chars = [...value];
-            // Calculate font size to fit the widest character in its cell
             let maxCharWidth = 0;
             let widestChar = chars[0] ?? '';
             for (const char of chars) {
@@ -65,8 +80,7 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             }
             if (maxCharWidth > cellWidth) {
                 finalFontSize = g.calculateFittingFontSize(widestChar, cellWidth);
-                const adjustedDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
-                g.setDefaultAppearance(adjustedDA);
+                g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
             }
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
             g.beginText();
@@ -79,12 +93,13 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             g.endText();
         }
         else {
-            // Single line text
-            const textWidth = g.measureTextWidth(value);
-            if (textWidth > availableWidth) {
-                finalFontSize = g.calculateFittingFontSize(value, availableWidth);
-                const adjustedDA = new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp);
-                g.setDefaultAppearance(adjustedDA);
+            // Single line — for non-auto-size, shrink if text overflows
+            if (!autoSize) {
+                const textWidth = g.measureTextWidth(value);
+                if (textWidth > availableWidth) {
+                    finalFontSize = g.calculateFittingFontSize(value, availableWidth);
+                    g.setDefaultAppearance(new PdfDefaultAppearance(ctx.da.fontName, finalFontSize, ctx.da.colorOp));
+                }
             }
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
             g.beginText();

package/dist/acroform/fields/pdf-button-form-field.js

@@ -20,20 +20,35 @@ export class PdfButtonFormField extends PdfFormField {
             this.content.delete('AS');
             return false;
         }
-        this.content.set('V', new PdfName(strVal));
-        fieldParent?.content.set('V', new PdfName(strVal));
-        this.content.set('AS', new PdfName(strVal));
+        // Check if the value matches an existing appearance state;
+        // otherwise map truthy values to the widget's "on" state (the
+        // first state that isn't "Off"), falling back to "Yes".
+        const states = this.appearanceStates;
+        let resolved;
+        if (states.includes(strVal)) {
+            resolved = strVal;
+        }
+        else if (strVal === 'Off' || strVal === 'No') {
+            resolved = 'Off';
+        }
+        else {
+            resolved = states.find((s) => s !== 'Off') ?? 'Yes';
+        }
+        this.content.set('V', new PdfName(resolved));
+        fieldParent?.content.set('V', new PdfName(resolved));
+        this.content.set('AS', new PdfName(resolved));
         return true;
     }
     get checked() {
         const v = this.content.get('V') ?? this.parent?.content.get('V');
-        return v instanceof PdfName && v.value === 'Yes';
+        return v instanceof PdfName && v.value !== 'Off';
     }
     set checked(isChecked) {
         const target = this.parent ?? this;
         if (isChecked) {
-            target.content.set('V', new PdfName('Yes'));
-            this.content.set('AS', new PdfName('Yes'));
+            const onState = this.appearanceStates.find((s) => s !== 'Off') ?? 'Yes';
+            target.content.set('V', new PdfName(onState));
+            this.content.set('AS', new PdfName(onState));
         }
         else {
             target.content.set('V', new PdfName('Off'));
@@ -56,8 +71,9 @@ export class PdfButtonFormField extends PdfFormField {
             height,
             contentStream: '',
         });
+        const onState = this.appearanceStates.find((s) => s !== 'Off') ?? 'Yes';
         this.setAppearanceStream({
-            Yes: yesAppearance,
+            [onState]: yesAppearance,
             Off: noAppearance,
         });
         if (options?.makeReadOnly) {

package/dist/acroform/fields/pdf-default-appearance.js

@@ -46,14 +46,11 @@ export class PdfDefaultAppearance extends PdfString {
         return `/${this._fontName} ${this._fontSize} Tf ${this._colorOp}`;
     }
     static parse(da) {
-        const fontMatch = da.match(/\/(\w+)\s+([\d.]+)\s+Tf/);
+        const fontMatch = da.match(/\/([\w-]+)\s+([\d.]+)\s+Tf/);
         if (!fontMatch)
             return null;
         const fontName = fontMatch[1];
-        let fontSize = parseFloat(fontMatch[2]);
-        if (!fontSize || fontSize <= 0) {
-            fontSize = 12;
-        }
+        const fontSize = parseFloat(fontMatch[2]) || 0;
         let colorOp = '0 g';
         const rgMatch = da.match(/([\d.]+\s+[\d.]+\s+[\d.]+)\s+rg/);
         const gMatch = da.match(/([\d.]+)\s+g/);

package/dist/acroform/fields/pdf-form-field.d.ts

@@ -107,6 +107,11 @@ export declare abstract class PdfFormField extends PdfWidgetAnnotation {
     setAppearanceStream(stream: PdfIndirectObject | {
         [key: string]: PdfIndirectObject;
     }): void;
+    /**
+     * Returns the list of appearance state names from the normal appearance
+     * dictionary (e.g. ["Yes", "Off"] for a checkbox).
+     */
+    get appearanceStates(): string[];
     getAppearanceStream(setting?: string): PdfIndirectObject<PdfStream> | null;
     private static _fallbackCtor?;
     private static _registry;

package/dist/acroform/fields/pdf-form-field.js

@@ -480,6 +480,17 @@ export class PdfFormField extends PdfWidgetAnnotation {
             this.appearanceStreamDict.set('N', dict);
         }
     }
+    /**
+     * Returns the list of appearance state names from the normal appearance
+     * dictionary (e.g. ["Yes", "Off"] for a checkbox).
+     */
+    get appearanceStates() {
+        const n = this.appearanceStreamDict?.get('N');
+        if (n instanceof PdfDictionary) {
+            return Array.from(n.entries(), ([key]) => key);
+        }
+        return [];
+    }
     getAppearanceStream(setting) {
         const n = this.appearanceStreamDict?.get('N');
         if (!n)

package/dist/core/objects/pdf-stream.d.ts

@@ -94,6 +94,9 @@ export declare class PdfStream<T extends PdfDictionary = PdfDictionary> extends
     static fromString(data: string): PdfStream;
 }
 export declare class PdfObjStream extends PdfStream {
+    private _parsedObjects?;
+    set raw(data: ByteArray);
+    get raw(): ByteArray;
     constructor(options: {
         header: PdfDictionary;
         original: ByteArray | string;
@@ -101,6 +104,7 @@ export declare class PdfObjStream extends PdfStream {
     });
     static fromObjects(objects: Iterable<PdfIndirectObject>): PdfObjStream;
     getObjectStream(): Generator<PdfIndirectObject>;
+    private getParsedObjects;
     getObject(options: {
         objectNumber: number;
     }): PdfIndirectObject | undefined;

package/dist/core/objects/pdf-stream.js

@@ -486,6 +486,14 @@ export class PdfStream extends PdfObject {
     }
 }
 export class PdfObjStream extends PdfStream {
+    _parsedObjects;
+    set raw(data) {
+        super.raw = data;
+        this._parsedObjects = undefined;
+    }
+    get raw() {
+        return super.raw;
+    }
     constructor(options) {
         super(options);
         if (!this.isType('ObjStm')) {
@@ -548,8 +556,11 @@ export class PdfObjStream extends PdfStream {
             const { value: obj, done } = reader.next();
             if (done)
                 break;
-            if (obj instanceof PdfNumber) {
-                // Collect object numbers and byte offsets
+            if (obj instanceof PdfNumber &&
+                (totalObjects === 0 || numbers.length < totalObjects * 2)) {
+                // Collect object numbers and byte offsets from the header section.
+                // Stop once we have all 2*N pairs so that object values that happen
+                // to be plain integers are not mistakenly treated as header entries.
                 numbers.push(obj);
             }
             else {
@@ -574,16 +585,20 @@ export class PdfObjStream extends PdfStream {
             }
         }
     }
-    getObject(options) {
-        for (const obj of this.getObjectStream()) {
-            if (obj.objectNumber === options.objectNumber) {
-                return obj;
+    getParsedObjects() {
+        if (!this._parsedObjects) {
+            this._parsedObjects = new Map();
+            for (const obj of this.getObjectStream()) {
+                this._parsedObjects.set(obj.objectNumber, obj);
             }
         }
-        return undefined;
+        return this._parsedObjects;
+    }
+    getObject(options) {
+        return this.getParsedObjects().get(options.objectNumber);
     }
     getObjects() {
-        return Array.from(this.getObjectStream());
+        return Array.from(this.getParsedObjects().values());
     }
     cloneImpl() {
         return new PdfObjStream({

package/dist/pdf/pdf-document.d.ts

@@ -42,7 +42,9 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     private originalSecurityHandler?;
     private hasEncryptionDictionary?;
     private _resolvedCache;
+    private _objStreamCache;
     private _committing;
+    private _updating;
     private _finalized;
     private _signed;
     /**

package/dist/pdf/pdf-document.js

@@ -50,7 +50,9 @@ export class PdfDocument extends PdfObject {
     originalSecurityHandler;
     hasEncryptionDictionary = false;
     _resolvedCache = new Map();
+    _objStreamCache = new Map();
     _committing = false;
+    _updating = false;
     _finalized = false;
     _signed = false;
     /**
@@ -452,6 +454,14 @@ export class PdfDocument extends PdfObject {
                         continue;
                     }
                     if (obj.isModified()) {
+                        // Pre-register any new objects referenced by obj before
+                        // cloning so the clone gets correct object numbers.
+                        // Without this, proxy references (objectNumber = -1) get
+                        // frozen into the clone as "-1 0 R" — a dangling reference.
+                        const missing = this.collectMissingReferences(obj);
+                        if (missing.length > 0) {
+                            this.add(...missing);
+                        }
                         const adding = obj.clone();
                         this.add(adding);
                         adding.setModified(false);
@@ -573,19 +583,21 @@ export class PdfDocument extends PdfObject {
         if (!(xrefEntry instanceof PdfXRefStreamCompressedEntry)) {
             throw new Error('Cannot find object inside object stream via PdfDocument.findObject');
         }
-        const objectStreamIndirect = this.findUncompressedObject({
-            objectNumber: xrefEntry.objectStreamNumber.value,
-        })?.clone();
-        if (!objectStreamIndirect) {
-            throw new Error(`Cannot find object stream ${xrefEntry.objectStreamNumber.value} for object ${options.objectNumber}`);
-        }
-        const objectStream = objectStreamIndirect.content
-            .as(PdfStream)
-            .parseAs(PdfObjStream);
-        const decompressedObject = objectStream.getObject({
-            objectNumber: options.objectNumber,
-        });
-        return decompressedObject;
+        const streamNumber = xrefEntry.objectStreamNumber.value;
+        let objectStream = this._objStreamCache.get(streamNumber);
+        if (!objectStream) {
+            const objectStreamIndirect = this.findUncompressedObject({
+                objectNumber: streamNumber,
+            });
+            if (!objectStreamIndirect) {
+                throw new Error(`Cannot find object stream ${streamNumber} for object ${options.objectNumber}`);
+            }
+            objectStream = objectStreamIndirect.content
+                .as(PdfStream)
+                .parseAs(PdfObjStream);
+            this._objStreamCache.set(streamNumber, objectStream);
+        }
+        return objectStream.getObject({ objectNumber: options.objectNumber });
     }
     /**
      * Finds an uncompressed indirect object by its object number.
@@ -880,20 +892,28 @@ export class PdfDocument extends PdfObject {
      * Performs a full update cycle to ensure all revisions are consistent and offsets are correct.
      */
     update() {
-        this.commitIncrementalUpdates();
-        this.flushResolvedCache();
-        this.registerNewReferences();
-        this.calculateOffsets();
-        this.updateRevisions();
-        // Second pass: xref binary may have changed size (e.g. FlateDecode removed
-        // from xref stream), shifting objects that follow it. Recalculate so entry
-        // byteOffset refs hold the new positions, then rebuild the xref binary once
-        // more so the baked bytes match those positions.
-        this.calculateOffsets();
-        this.updateRevisions();
-        // Third pass: confirm positions are stable (xref binary size should not
-        // change again because W widths and entry count are the same).
-        this.calculateOffsets();
+        if (this._updating)
+            return;
+        this._updating = true;
+        try {
+            this.commitIncrementalUpdates();
+            this.flushResolvedCache();
+            this.registerNewReferences();
+            this.calculateOffsets();
+            this.updateRevisions();
+            // Second pass: xref binary may have changed size (e.g. FlateDecode removed
+            // from xref stream), shifting objects that follow it. Recalculate so entry
+            // byteOffset refs hold the new positions, then rebuild the xref binary once
+            // more so the baked bytes match those positions.
+            this.calculateOffsets();
+            this.updateRevisions();
+            // Third pass: confirm positions are stable (xref binary size should not
+            // change again because W widths and entry count are the same).
+            this.calculateOffsets();
+        }
+        finally {
+            this._updating = false;
+        }
     }
     /**
      * Walks all objects in the document and registers any newly created
@@ -907,9 +927,11 @@ export class PdfDocument extends PdfObject {
         }
     }
     flushResolvedCache() {
+        const existing = new Set(this.objects);
         for (const [, obj] of this._resolvedCache) {
-            if (obj.isModified() && !this.objects.includes(obj)) {
+            if (obj.isModified() && !existing.has(obj)) {
                 this.add(obj);
+                existing.add(obj);
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-lite",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "main": "dist/index.js",
   "type": "module",
   "exports": {