pdf-lite 1.7.3-alpha.1 → 1.7.4-alpha.0

package/dist/acroform/appearance/pdf-choice-appearance-stream.d.ts

@@ -3,9 +3,6 @@ import { PdfAppearanceStream } from './pdf-appearance-stream.js';
 import type { PdfDictionary } from '../../core/objects/pdf-dictionary.js';
 import type { PdfFont } from '../../fonts/pdf-font.js';
 import { PdfFormFieldFlags } from '../fields/pdf-form-field-flags.js';
-/**
- * Appearance stream for choice fields (dropdowns, list boxes).
- */
 export declare class PdfChoiceAppearanceStream extends PdfAppearanceStream {
     constructor(ctx: {
         rect: [number, number, number, number];
@@ -18,5 +15,6 @@ export declare class PdfChoiceAppearanceStream extends PdfAppearanceStream {
         reverseEncodingMap?: Map<string, number>;
         displayOptions?: string[];
         selectedIndex?: number;
+        quadding?: number;
     });
 }

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

@@ -4,6 +4,14 @@ import { PdfFormFieldFlags } from '../fields/pdf-form-field-flags.js';
 /**
  * Appearance stream for choice fields (dropdowns, list boxes).
  */
+/** Compute the X offset for a line of text given the quadding value. */
+function calcTextX(quadding, padding, availableWidth, textWidth) {
+    if (quadding === 2)
+        return padding + Math.max(availableWidth - textWidth, 0);
+    if (quadding === 1)
+        return padding + Math.max((availableWidth - textWidth) / 2, 0);
+    return padding;
+}
 export class PdfChoiceAppearanceStream extends PdfAppearanceStream {
     constructor(ctx) {
         const [x1, y1, x2, y2] = ctx.rect;
@@ -17,10 +25,14 @@ export class PdfChoiceAppearanceStream extends PdfAppearanceStream {
         const isUnicode = ctx.isUnicode ?? false;
         const reverseEncodingMap = ctx.reverseEncodingMap;
         const padding = 2;
+        const availableWidth = width - 2 * padding;
         const isCombo = new PdfFormFieldFlags(ctx.flags).combo;
+        const quadding = ctx.quadding ?? 0;
         const g = new PdfGraphics({ resolvedFonts: ctx.resolvedFonts });
         g.beginMarkedContent();
         g.save();
+        // Set DA early so measureTextWidth works for alignment calculations
+        g.setDefaultAppearance(ctx.da);
         if (!isCombo && ctx.displayOptions && ctx.displayOptions.length > 0) {
             // Listbox: render all items, highlight the selected one
             const lineHeight = ctx.da.fontSize + 4;
@@ -39,9 +51,10 @@ export class PdfChoiceAppearanceStream extends PdfAppearanceStream {
                     g.restore();
                 }
                 const textY = itemY + lineHeight * 0.25;
+                const textX = calcTextX(quadding, padding, availableWidth, g.measureTextWidth(ctx.displayOptions[i]));
                 g.beginText();
                 g.setDefaultAppearance(ctx.da);
-                g.moveTo(padding, textY);
+                g.moveTo(textX, textY);
                 g.showText(ctx.displayOptions[i], isUnicode, reverseEncodingMap);
                 g.endText();
             }
@@ -49,9 +62,10 @@ export class PdfChoiceAppearanceStream extends PdfAppearanceStream {
         else {
             // Combo (dropdown) or no options: show selected value only
             const textY = (height - ctx.da.fontSize) / 2 + ctx.da.fontSize * 0.2;
+            const textX = calcTextX(quadding, padding, availableWidth, g.measureTextWidth(ctx.value));
             g.beginText();
             g.setDefaultAppearance(ctx.da);
-            g.moveTo(padding, textY);
+            g.moveTo(textX, textY);
             g.showText(ctx.value, isUnicode, reverseEncodingMap);
             g.endText();
             if (isCombo) {

package/dist/acroform/appearance/pdf-text-appearance-stream.d.ts

@@ -21,5 +21,6 @@ export declare class PdfTextAppearanceStream extends PdfAppearanceStream {
         reverseEncodingMap?: Map<string, number>;
         markdown?: string;
         fontVariantNames?: FontVariantNames;
+        quadding?: number;
     });
 }

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

@@ -2,6 +2,19 @@ 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;
+/** Compute the X offset for a line of text given the quadding value. */
+function calcTextX(quadding, padding, availableWidth, textWidth) {
+    if (quadding === 2) {
+        // Right-aligned
+        return padding + Math.max(availableWidth - textWidth, 0);
+    }
+    if (quadding === 1) {
+        // Center-aligned
+        return padding + Math.max((availableWidth - textWidth) / 2, 0);
+    }
+    // Left-aligned (default)
+    return padding;
+}
 /**
  * Appearance stream for text fields (single-line, multiline, comb).
  * Enhanced with word wrapping and automatic font scaling.
@@ -18,6 +31,7 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
         const availableWidth = width - 2 * padding;
         const availableHeight = height - 2 * padding;
         const autoSize = ctx.da.fontSize <= 0;
+        const quadding = ctx.quadding ?? 0;
         // Create graphics with font context for text measurement
         const g = new PdfGraphics({
             resolvedFonts: ctx.resolvedFonts,
@@ -108,11 +122,18 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
             }
             else {
                 g.beginText();
-                g.moveTo(padding, startY);
+                let prevLineX = 0;
                 for (let i = 0; i < lines.length; i++) {
-                    if (i > 0)
-                        g.moveTo(0, -renderLineHeight);
-                    g.showText(lines[i].replace(/\r/g, ''), isUnicode, reverseEncodingMap);
+                    const lineText = lines[i].replace(/\r/g, '');
+                    const lineX = calcTextX(quadding, padding, availableWidth, g.measureTextWidth(lineText));
+                    if (i === 0) {
+                        g.moveTo(lineX, startY);
+                    }
+                    else {
+                        g.moveTo(lineX - prevLineX, -renderLineHeight);
+                    }
+                    prevLineX = lineX;
+                    g.showText(lineText, isUnicode, reverseEncodingMap);
                 }
                 g.endText();
             }
@@ -126,12 +147,14 @@ export class PdfTextAppearanceStream extends PdfAppearanceStream {
                 }
             }
             const textY = (height - finalFontSize) / 2 + finalFontSize * 0.2;
+            const textWidth = g.measureTextWidth(value);
+            const textX = calcTextX(quadding, padding, availableWidth, textWidth);
             if (ctx.markdown) {
-                g.showMarkdown(ctx.markdown, isUnicode, reverseEncodingMap, padding, textY, finalFontSize);
+                g.showMarkdown(ctx.markdown, isUnicode, reverseEncodingMap, textX, textY, finalFontSize);
             }
             else {
                 g.beginText();
-                g.moveTo(padding, textY);
+                g.moveTo(textX, textY);
                 g.showText(value, isUnicode, reverseEncodingMap);
                 g.endText();
             }

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

@@ -101,6 +101,7 @@ export class PdfChoiceFormField extends PdfFormField {
             reverseEncodingMap,
             displayOptions: this.options.map((opt) => opt.label),
             selectedIndex: this.selectedIndex,
+            quadding: this.quadding,
         });
         if (options?.makeReadOnly) {
             this.readOnly = true;

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

@@ -600,6 +600,7 @@ export class PdfFormField extends PdfWidgetAnnotation {
     }
     set quadding(q) {
         this.content.set('Q', new PdfNumber(q));
+        this.updateAppearance();
     }
     get defaultAppearance() {
         return (this.content.get('DA')?.as(PdfString)?.value ??

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

@@ -54,6 +54,7 @@ export class PdfTextFormField extends PdfFormField {
             reverseEncodingMap,
             markdown: this.markdownValue,
             fontVariantNames: variantNames,
+            quadding: this.quadding,
         });
         if (options?.makeReadOnly) {
             this.readOnly = true;

package/dist/crypto/key-derivation/key-derivation-aes256.js

@@ -1,3 +1,4 @@
+import { PdfInvalidPasswordError } from '../../errors.js';
 import { aes128CbcNoPaddingEncrypt, aes256CbcNoPaddingDecrypt, sha256, sha384, sha512, } from '../../utils/algos.js';
 import { assert } from '../../utils/assert.js';
 /**
@@ -162,7 +163,7 @@ export async function getFileKey(userPassword, ownerPassword, u, ue, o, oe) {
             return key;
         }
         catch (e) {
-            throw new Error('Invalid password');
+            throw new PdfInvalidPasswordError();
         }
     }
 }

package/dist/errors.d.ts

@@ -20,3 +20,17 @@ export declare class UnexpectedTokenError extends Error {
  */
 export declare class FoundCompressedObjectError extends Error {
 }
+/**
+ * Error thrown when a PDF is encrypted and the blank password
+ * does not grant access. Callers should catch this and prompt
+ * the user for a password, then retry with the `password` option.
+ */
+export declare class PdfPasswordProtectedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a provided password is invalid for decrypting a PDF.
+ */
+export declare class PdfInvalidPasswordError extends Error {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -22,3 +22,21 @@ export class UnexpectedTokenError extends Error {
  */
 export class FoundCompressedObjectError extends Error {
 }
+/**
+ * Error thrown when a PDF is encrypted and the blank password
+ * does not grant access. Callers should catch this and prompt
+ * the user for a password, then retry with the `password` option.
+ */
+export class PdfPasswordProtectedError extends Error {
+    constructor(message) {
+        super(message ?? 'PDF is password protected');
+    }
+}
+/**
+ * Error thrown when a provided password is invalid for decrypting a PDF.
+ */
+export class PdfInvalidPasswordError extends Error {
+    constructor(message) {
+        super(message ?? 'Invalid password');
+    }
+}

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

@@ -47,6 +47,8 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     private _updating;
     private _finalized;
     private _signed;
+    /** @internal */
+    _batching: boolean;
     /**
      * Creates a new PDF document instance.
      *
@@ -71,14 +73,48 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     get pages(): PdfPages;
     get header(): PdfComment | undefined;
     set header(comment: PdfComment | undefined);
+    /**
+     * Loads PDF objects into the document, organizing them into revisions.
+     * Parses objects into revisions based on EOF comments.
+     *
+     * @param objects - Array of PDF objects to load into the document
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
+     */
+    loadObjects(objects: PdfObject[], options?: {
+        password?: string;
+        ownerPassword?: string;
+        incremental?: boolean;
+    }): Promise<this>;
+    /**
+     * Loads a PDF document from a byte stream, parsing it into objects and revisions.
+     * @param input - Async or sync iterable of byte arrays representing the PDF file
+     * @param options - Optional security and mode configuration
+     * @returns A promise that resolves to the loaded PdfDocument instance
+     */
+    load(input: AsyncIterable<ByteArray> | Iterable<ByteArray>, options?: {
+        password?: string;
+        ownerPassword?: string;
+        incremental?: boolean;
+    }): Promise<this>;
     /**
      * Creates a PdfDocument from an array of PDF objects.
      * Parses objects into revisions based on EOF comments.
      *
      * @param objects - Array of PDF objects to construct the document from
-     * @returns A new PdfDocument instance
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
+     * @returns A promise that resolves to the new PdfDocument instance
      */
-    static fromObjects(objects: PdfObject[]): PdfDocument;
+    static fromObjects(objects: PdfObject[], options?: {
+        password?: string;
+        ownerPassword?: string;
+        incremental?: boolean;
+    }): Promise<PdfDocument>;
     /**
      * Starts a new revision for incremental updates.
      * Creates a new revision linked to the previous one.
@@ -94,6 +130,31 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
      * @param objects - PDF objects to add to the document
      */
     add(...objects: PdfObject[]): void;
+    /**
+     * Recursively collects and adds all missing referenced objects in batches.
+     * More efficient than recursive add() calls since it collects all missing
+     * objects before processing them.
+     * @private
+     */
+    private addAllMissingReferences;
+    /**
+     * Creates a batch for adding multiple objects with a single update pass.
+     * This is significantly faster than calling `add()` multiple times when
+     * adding objects with many sub-references (e.g. fonts with descriptors,
+     * CIDToGIDMap streams, ToUnicode CMaps).
+     *
+     * @example
+     * ```typescript
+     * const batch = document.batch()
+     * batch.add(font1)
+     * batch.add(font2)
+     * batch.add(imageStream)
+     * batch.commit()
+     * ```
+     *
+     * @returns A PdfDocumentBatch instance
+     */
+    batch(): PdfDocumentBatch;
     /**
      * Packs non-stream indirect objects into compressed ObjStm containers.
      * Objects that already have an object number are left unchanged.
@@ -289,8 +350,9 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     private updateRevisions;
     /**
      * Performs a full update cycle to ensure all revisions are consistent and offsets are correct.
+     * @internal
      */
-    private update;
+    update(): void;
     /**
      * Walks all objects in the document and registers any newly created
      * PdfIndirectObjects that are referenced but not yet part of the document
@@ -318,6 +380,20 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
             objects: object[];
         }[];
     };
+    /**
+     * Creates a new PdfDocument instance.
+     *
+     * @param options - Configuration options for the document
+     * @returns A new PdfDocument instance
+     */
+    static newDocument(options?: {
+        revisions?: PdfRevision[];
+        version?: string | PdfComment;
+        password?: string;
+        ownerPassword?: string;
+        securityHandler?: PdfSecurityHandler;
+        signer?: PdfSigner;
+    }): PdfDocument;
     /**
      * Creates a PdfDocument from a byte stream.
      *
@@ -337,3 +413,29 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
      */
     verifySignatures(): Promise<PdfDocumentVerificationResult>;
 }
+/**
+ * Batches multiple `add()` calls into a single update pass.
+ * Created via {@link PdfDocument.batch}.
+ */
+export declare class PdfDocumentBatch {
+    private _document;
+    private _completed;
+    private _addedObjects;
+    /** @internal */
+    constructor(document: PdfDocument);
+    /**
+     * Adds one or more objects to the document without triggering an update.
+     *
+     * @param objects - PDF objects to add
+     */
+    add(...objects: PdfObject[]): this;
+    /**
+     * Commits the batch, running a single update pass for all added objects.
+     */
+    commit(): void;
+    /**
+     * Rolls back the batch, removing all objects that were added and
+     * restoring the document to its state before the batch was created.
+     */
+    rollback(): void;
+}

package/dist/pdf/pdf-document.js

@@ -15,12 +15,13 @@ import { PdfByteOffsetToken } from '../core/tokens/byte-offset-token.js';
 import { PdfNumberToken } from '../core/tokens/number-token.js';
 import { PdfXRefTableEntryToken } from '../core/tokens/xref-table-entry-token.js';
 import { PdfStartXRef } from '../core/objects/pdf-start-xref.js';
-import { FoundCompressedObjectError } from '../errors.js';
+import { FoundCompressedObjectError, PdfPasswordProtectedError, } from '../errors.js';
 import { PdfReader } from './pdf-reader.js';
 import { PdfSigner } from '../signing/signer.js';
 import { concatUint8Arrays } from '../utils/concatUint8Arrays.js';
 import { PdfAcroForm } from '../acroform/pdf-acro-form.js';
 import { PdfPages } from './pdf-pages.js';
+import { PdfObjectStream } from '../index.js';
 /**
  * Represents a PDF document with support for reading, writing, and modifying PDF files.
  * Handles document structure, revisions, encryption, and digital signatures.
@@ -55,6 +56,8 @@ export class PdfDocument extends PdfObject {
     _updating = false;
     _finalized = false;
     _signed = false;
+    /** @internal */
+    _batching = false;
     /**
      * Creates a new PDF document instance.
      *
@@ -75,18 +78,18 @@ export class PdfDocument extends PdfObject {
         else {
             this.setVersion(options?.version ?? '2.0');
         }
-        if (options?.password) {
-            this.setPassword(options.password);
-        }
-        if (options?.ownerPassword) {
-            this.setOwnerPassword(options.ownerPassword);
-        }
         this.signer = options?.signer ?? new PdfSigner({ document: this });
         this.linkRevisions();
         this.wireResolvers(...this.objects.filter((x) => x instanceof PdfIndirectObject), ...this.revisions.map((rev) => rev.xref.trailerDict));
         this.calculateOffsets();
         this.originalSecurityHandler = options?.securityHandler;
         this.resetSecurityHandler();
+        if (options?.password) {
+            this.setPassword(options.password);
+        }
+        if (options?.ownerPassword) {
+            this.setOwnerPassword(options.ownerPassword);
+        }
     }
     resolve(objectNumber, generationNumber) {
         const cacheKey = `${objectNumber} ${generationNumber}`;
@@ -132,13 +135,16 @@ export class PdfDocument extends PdfObject {
             this.revisions[0].header = comment;
     }
     /**
-     * Creates a PdfDocument from an array of PDF objects.
+     * Loads PDF objects into the document, organizing them into revisions.
      * Parses objects into revisions based on EOF comments.
      *
-     * @param objects - Array of PDF objects to construct the document from
-     * @returns A new PdfDocument instance
+     * @param objects - Array of PDF objects to load into the document
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
      */
-    static fromObjects(objects) {
+    async loadObjects(objects, options) {
         let header;
         const revisions = [];
         let currentObjects = [];
@@ -156,7 +162,111 @@ export class PdfDocument extends PdfObject {
         if (currentObjects.length > 0) {
             revisions.push(new PdfRevision({ objects: currentObjects }));
         }
-        return new PdfDocument({ revisions, version: header });
+        this.revisions = revisions;
+        if (header) {
+            this.header = header;
+        }
+        this.linkRevisions();
+        this.wireResolvers(...this.objects.filter((x) => x instanceof PdfIndirectObject), ...this.revisions.map((rev) => rev.xref.trailerDict));
+        this.calculateOffsets();
+        // Reset security handler to detect and initialize encryption from the PDF
+        // Preserve any passwords that were set before load() was called
+        let presetPassword = options?.password;
+        let presetOwnerPassword = options?.ownerPassword;
+        if (this.securityHandler instanceof PdfStandardSecurityHandler) {
+            const pw = this.securityHandler.getPassword();
+            const opw = this.securityHandler.getOwnerPassword();
+            if (!presetPassword && pw.length > 0) {
+                presetPassword = new TextDecoder().decode(pw);
+            }
+            if (!presetOwnerPassword && opw) {
+                presetOwnerPassword = new TextDecoder().decode(opw);
+            }
+        }
+        this.resetSecurityHandler();
+        // Apply passwords
+        if (presetPassword) {
+            this.setPassword(presetPassword);
+        }
+        if (presetOwnerPassword) {
+            this.setOwnerPassword(presetOwnerPassword);
+        }
+        // Handle encryption/decryption
+        let shouldDecrypt = Boolean(this.encryptionDictionary);
+        const hasExplicitPassword = !!presetPassword || !!presetOwnerPassword;
+        // If encrypted, verify the password is valid before attempting decryption
+        if (shouldDecrypt &&
+            this.securityHandler instanceof PdfStandardSecurityHandler) {
+            const valid = await this.securityHandler.testPassword();
+            if (!valid) {
+                if (!hasExplicitPassword) {
+                    throw new PdfPasswordProtectedError();
+                }
+                this.resetSecurityHandler();
+                shouldDecrypt = false;
+            }
+        }
+        if (options?.incremental) {
+            // Lock revisions first to preserve the original bytes
+            // (including encrypted data) via cached tokens.
+            this.setIncremental(true);
+            // Then decrypt the live object data so built-in operations
+            // (AcroForm, fonts, etc.) can read it. The cached tokens
+            // still produce the original encrypted bytes on serialization.
+            if (shouldDecrypt) {
+                try {
+                    await this.decryptObjects();
+                }
+                catch (e) {
+                    if (!hasExplicitPassword) {
+                        throw new PdfPasswordProtectedError();
+                    }
+                    this.resetSecurityHandler();
+                }
+            }
+        }
+        else if (shouldDecrypt) {
+            try {
+                await this.decryptObjects();
+            }
+            catch (e) {
+                if (!hasExplicitPassword) {
+                    throw new PdfPasswordProtectedError();
+                }
+                this.resetSecurityHandler();
+            }
+        }
+        return this;
+    }
+    /**
+     * Loads a PDF document from a byte stream, parsing it into objects and revisions.
+     * @param input - Async or sync iterable of byte arrays representing the PDF file
+     * @param options - Optional security and mode configuration
+     * @returns A promise that resolves to the loaded PdfDocument instance
+     */
+    async load(input, options) {
+        const objectStream = new PdfObjectStream(input);
+        const objects = [];
+        for await (const obj of objectStream) {
+            objects.push(obj);
+        }
+        return await this.loadObjects(objects, options);
+    }
+    /**
+     * Creates a PdfDocument from an array of PDF objects.
+     * Parses objects into revisions based on EOF comments.
+     *
+     * @param objects - Array of PDF objects to construct the document from
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
+     * @returns A promise that resolves to the new PdfDocument instance
+     */
+    static async fromObjects(objects, options) {
+        const document = new PdfDocument();
+        await document.loadObjects(objects, options);
+        return document;
     }
     /**
      * Starts a new revision for incremental updates.
@@ -193,16 +303,54 @@ export class PdfDocument extends PdfObject {
             }
             this.latestRevision.addObject(obj);
         }
-        // Auto-add any referenced-but-missing objects
-        const missing = this.collectMissingReferences(...objects);
-        if (missing.length > 0) {
-            this.add(...missing);
+        // Auto-add any referenced-but-missing objects recursively in one pass
+        this.addAllMissingReferences(objects);
+        if (!this._batching) {
+            this.update();
         }
-        this.update();
         for (const obj of objects) {
             obj.setModified(false);
         }
     }
+    /**
+     * Recursively collects and adds all missing referenced objects in batches.
+     * More efficient than recursive add() calls since it collects all missing
+     * objects before processing them.
+     * @private
+     */
+    addAllMissingReferences(objects) {
+        let batch = this.collectMissingReferences(...objects);
+        while (batch.length > 0) {
+            for (const obj of batch) {
+                this.wireResolvers(obj);
+                if (!this.hasObjectInLatestRevision(obj)) {
+                    this.latestRevision.addObject(obj);
+                }
+            }
+            // Check if these newly added objects reference more missing objects
+            batch = this.collectMissingReferences(...batch);
+        }
+    }
+    /**
+     * Creates a batch for adding multiple objects with a single update pass.
+     * This is significantly faster than calling `add()` multiple times when
+     * adding objects with many sub-references (e.g. fonts with descriptors,
+     * CIDToGIDMap streams, ToUnicode CMaps).
+     *
+     * @example
+     * ```typescript
+     * const batch = document.batch()
+     * batch.add(font1)
+     * batch.add(font2)
+     * batch.add(imageStream)
+     * batch.commit()
+     * ```
+     *
+     * @returns A PdfDocumentBatch instance
+     */
+    batch() {
+        return new PdfDocumentBatch(this);
+    }
     /**
      * Packs non-stream indirect objects into compressed ObjStm containers.
      * Objects that already have an object number are left unchanged.
@@ -826,9 +974,9 @@ export class PdfDocument extends PdfObject {
             }
         }
     }
-    linkOffsets() {
+    linkOffsets(tokens) {
         const refMap = new Map();
-        const tokens = this.toTokens();
+        tokens = tokens ?? this.toTokens();
         for (let i = 0; i < tokens.length; i++) {
             const token = tokens[i];
             let main;
@@ -862,11 +1010,13 @@ export class PdfDocument extends PdfObject {
             }
         }
     }
-    calculateOffsets() {
+    calculateOffsets(cachedTokens) {
         const serializer = new PdfTokenSerializer();
-        serializer.feedMany(this.toTokens());
+        const tokens = cachedTokens ?? this.toTokens();
+        this.linkOffsets(tokens);
+        serializer.feedMany(tokens);
         serializer.calculateOffsets();
-        this.linkOffsets();
+        return tokens;
     }
     updateRevisions() {
         let modified = false;
@@ -890,6 +1040,7 @@ export class PdfDocument extends PdfObject {
     }
     /**
      * Performs a full update cycle to ensure all revisions are consistent and offsets are correct.
+     * @internal
      */
     update() {
         if (this._updating)
@@ -899,17 +1050,17 @@ export class PdfDocument extends PdfObject {
             this.commitIncrementalUpdates();
             this.flushResolvedCache();
             this.registerNewReferences();
+            // First pass: generate tokens and calculate offsets
             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();
+            // from xref stream), shifting objects that follow it. Regenerate tokens
+            // to capture xref changes, then recalculate offsets.
+            const tokens = 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();
+            // Third pass: reuse tokens from second pass since xref should now be stable
+            // (xref binary size should not change because W widths and entry count are same).
+            this.calculateOffsets(tokens);
         }
         finally {
             this._updating = false;
@@ -961,11 +1112,13 @@ export class PdfDocument extends PdfObject {
      */
     cloneImpl() {
         const clonedRevisions = this.revisions.map((rev) => rev.clone());
-        return new PdfDocument({
+        const cloned = new PdfDocument({
             revisions: clonedRevisions,
             version: this.header?.clone(),
-            securityHandler: this.securityHandler,
+            securityHandler: this.securityHandler?.clone(),
         });
+        cloned.hasEncryptionDictionary = this.hasEncryptionDictionary;
+        return cloned;
     }
     toJSON() {
         return {
@@ -973,6 +1126,15 @@ export class PdfDocument extends PdfObject {
             revisions: this.revisions.map((rev) => rev.toJSON()),
         };
     }
+    /**
+     * Creates a new PdfDocument instance.
+     *
+     * @param options - Configuration options for the document
+     * @returns A new PdfDocument instance
+     */
+    static newDocument(options) {
+        return new PdfDocument(options);
+    }
     /**
      * Creates a PdfDocument from a byte stream.
      *
@@ -994,3 +1156,56 @@ export class PdfDocument extends PdfObject {
         return await this.signer.verify();
     }
 }
+/**
+ * Batches multiple `add()` calls into a single update pass.
+ * Created via {@link PdfDocument.batch}.
+ */
+export class PdfDocumentBatch {
+    _document;
+    _completed = false;
+    _addedObjects = [];
+    /** @internal */
+    constructor(document) {
+        this._document = document;
+        this._document._batching = true;
+    }
+    /**
+     * Adds one or more objects to the document without triggering an update.
+     *
+     * @param objects - PDF objects to add
+     */
+    add(...objects) {
+        if (this._completed) {
+            throw new Error('Batch already completed (committed or rolled back)');
+        }
+        this._addedObjects.push(...objects);
+        this._document.add(...objects);
+        return this;
+    }
+    /**
+     * Commits the batch, running a single update pass for all added objects.
+     */
+    commit() {
+        if (this._completed) {
+            throw new Error('Batch already completed (committed or rolled back)');
+        }
+        this._completed = true;
+        this._document._batching = false;
+        this._document.update();
+    }
+    /**
+     * Rolls back the batch, removing all objects that were added and
+     * restoring the document to its state before the batch was created.
+     */
+    rollback() {
+        if (this._completed) {
+            throw new Error('Batch already completed (committed or rolled back)');
+        }
+        this._completed = true;
+        this._document._batching = false;
+        // Remove all objects that were added during this batch
+        for (const obj of this._addedObjects) {
+            this._document.deleteObject(obj);
+        }
+    }
+}

package/dist/pdf/pdf-reader.js

@@ -1,4 +1,3 @@
-import { PdfObjectStream } from '../core/streams/object-stream.js';
 import { PdfDocument } from './pdf-document.js';
 /**
  * A reader for parsing PDF data into PdfDocument instances.
@@ -31,7 +30,7 @@ export class PdfReader {
         for await (const obj of this.objectStream) {
             objects.push(obj);
         }
-        return PdfDocument.fromObjects(objects);
+        return await PdfDocument.fromObjects(objects);
     }
     /**
      * Creates a PdfDocument directly from a byte stream.
@@ -41,41 +40,8 @@ export class PdfReader {
      * @returns A promise that resolves to the parsed PdfDocument
      */
     static async fromBytes(input, options) {
-        const reader = new PdfReader(new PdfObjectStream(input));
-        const document = await reader.read();
-        let shouldDecrypt = Boolean(document.encryptionDictionary);
-        if (typeof options?.password === 'string') {
-            document.setPassword(options.password);
-            shouldDecrypt = true;
-        }
-        if (typeof options?.ownerPassword === 'string') {
-            document.setOwnerPassword(options.ownerPassword);
-            shouldDecrypt = true;
-        }
-        if (options?.incremental) {
-            // Lock revisions first to preserve the original bytes
-            // (including encrypted data) via cached tokens.
-            document.setIncremental(true);
-            // Then decrypt the live object data so built-in operations
-            // (AcroForm, fonts, etc.) can read it. The cached tokens
-            // still produce the original encrypted bytes on serialization.
-            if (shouldDecrypt) {
-                try {
-                    await document.decryptObjects();
-                }
-                catch (e) {
-                    document.resetSecurityHandler();
-                }
-            }
-        }
-        else if (shouldDecrypt) {
-            try {
-                await document.decryptObjects();
-            }
-            catch (e) {
-                document.resetSecurityHandler();
-            }
-        }
+        const document = new PdfDocument();
+        await document.load(input, options);
         return document;
     }
 }

package/dist/security/handlers/base.d.ts

@@ -116,6 +116,11 @@ export declare abstract class PdfSecurityHandler {
      * Writes the encryption dictionary with computed keys.
      */
     abstract write(): Promise<void>;
+    /**
+     * Tests whether the current password can decrypt this document.
+     * Returns true if the password is valid, false otherwise.
+     */
+    abstract testPassword(): Promise<boolean>;
     /**
      * Builds the numeric permission flags from a PdfPermissions object.
      *
@@ -123,6 +128,12 @@ export declare abstract class PdfSecurityHandler {
      * @returns The numeric permission flags.
      */
     protected buildPermissions(perm: PdfPermissions): number;
+    /**
+     * Creates a shallow clone of this security handler with an independent
+     * encryption dictionary, so that mutating the clone (e.g. during
+     * finalize/encrypt) does not affect the original.
+     */
+    clone(): this;
     /**
      * Recursively decrypts all strings and streams within an indirect object.
      *
@@ -213,6 +224,11 @@ export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHand
      * @returns The document ID, or undefined if not set.
      */
     getDocumentId(): PdfId | undefined;
+    /**
+     * Tests whether the current password can decrypt this document.
+     * Attempts to compute the master key and returns true if successful.
+     */
+    testPassword(): Promise<boolean>;
     /**
      * Sets the user password.
      *
@@ -225,6 +241,18 @@ export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHand
      * @param ownerPassword - The owner password string or bytes.
      */
     setOwnerPassword(ownerPassword: string | ByteArray): void;
+    /**
+     * Gets the user password.
+     *
+     * @returns The user password as bytes.
+     */
+    getPassword(): ByteArray;
+    /**
+     * Gets the owner password.
+     *
+     * @returns The owner password as bytes, or undefined if not set.
+     */
+    getOwnerPassword(): ByteArray | undefined;
     /**
      * Checks if metadata encryption is enabled.
      *
@@ -243,6 +271,13 @@ export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHand
      * @returns The computed user key.
      */
     protected abstract computeUserKey(): Promise<ByteArray>;
+    /**
+     * Computes the master encryption key from the password.
+     *
+     * @returns The computed master key.
+     * @throws Error if the password is incorrect or required parameters are missing.
+     */
+    protected abstract computeMasterKey(): Promise<ByteArray>;
     /**
      * Computes the owner key (O value) for the encryption dictionary.
      *

package/dist/security/handlers/base.js

@@ -69,6 +69,17 @@ export class PdfSecurityHandler {
         }
         return flags | 0xfffff000; // ensure unused high bits are set
     }
+    /**
+     * Creates a shallow clone of this security handler with an independent
+     * encryption dictionary, so that mutating the clone (e.g. during
+     * finalize/encrypt) does not affect the original.
+     */
+    clone() {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        Object.assign(cloned, this);
+        cloned.dict = this.dict.clone();
+        return cloned;
+    }
     /**
      * Recursively decrypts all strings and streams within an indirect object.
      *
@@ -241,6 +252,19 @@ export class PdfStandardSecurityHandler extends PdfSecurityHandler {
     getDocumentId() {
         return this.documentId;
     }
+    /**
+     * Tests whether the current password can decrypt this document.
+     * Attempts to compute the master key and returns true if successful.
+     */
+    async testPassword() {
+        try {
+            await this.computeMasterKey();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Sets the user password.
      *
@@ -261,6 +285,22 @@ export class PdfStandardSecurityHandler extends PdfSecurityHandler {
                 ? stringToBytes(ownerPassword)
                 : ownerPassword;
     }
+    /**
+     * Gets the user password.
+     *
+     * @returns The user password as bytes.
+     */
+    getPassword() {
+        return this.password;
+    }
+    /**
+     * Gets the owner password.
+     *
+     * @returns The owner password as bytes, or undefined if not set.
+     */
+    getOwnerPassword() {
+        return this.ownerPassword;
+    }
     /**
      * Checks if metadata encryption is enabled.
      *

package/dist/security/handlers/pubSec.d.ts

@@ -36,6 +36,7 @@ export declare class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
         permissions?: PdfPermissions | number;
         encryptMetadata?: boolean;
     });
+    clone(): this;
     /**
      * Gets the security handler filter name.
      *
@@ -66,6 +67,7 @@ export declare class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
      * @returns True if the underlying handler is ready.
      */
     isReady(): boolean;
+    testPassword(): Promise<boolean>;
     /**
      * Gets the encryption version number.
      *

package/dist/security/handlers/pubSec.js

@@ -50,6 +50,11 @@ export class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
         pkcs7Input[23] = this.permissions & 0xff;
         this.recipientsCms = this.getRecipientsPkcs7(pkcs7Input);
     }
+    clone() {
+        const cloned = super.clone();
+        cloned.standardSecurityHandler = this.standardSecurityHandler.clone();
+        return cloned;
+    }
     /**
      * Gets the security handler filter name.
      *
@@ -90,6 +95,9 @@ export class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
     isReady() {
         return this.standardSecurityHandler.isReady();
     }
+    async testPassword() {
+        return this.standardSecurityHandler.testPassword();
+    }
     /**
      * Gets the encryption version number.
      *

package/dist/security/handlers/v4.d.ts

@@ -58,6 +58,7 @@ export declare class PdfV4SecurityHandler extends PdfV2SecurityHandler {
      * @param filter - The crypt filter instance.
      */
     setCryptFilter(name: string, filter: PdfCryptFilter): void;
+    clone(): this;
     /**
      * Gets the encryption revision number.
      *

package/dist/security/handlers/v4.js

@@ -84,6 +84,16 @@ export class PdfV4SecurityHandler extends PdfV2SecurityHandler {
         filter.setSecurityHandler(this);
         this.cryptFilters.set(name, filter);
     }
+    clone() {
+        const cloned = super.clone();
+        cloned.cryptFilters = new Map();
+        cloned.cryptFiltersByType = { ...this.cryptFiltersByType };
+        for (const [name, filter] of this.cryptFilters) {
+            cloned.cryptFilters.set(name, filter);
+            filter.setSecurityHandler(cloned);
+        }
+        return cloned;
+    }
     /**
      * Gets the encryption revision number.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-lite",
-  "version": "1.7.3-alpha.1",
+  "version": "1.7.4-alpha.0",
   "main": "dist/index.js",
   "type": "module",
   "exports": {