@cj-tech-master/excelts 8.0.0 → 8.1.0

package/dist/browser/modules/pdf/reader/pdf-parser.d.ts

@@ -0,0 +1,65 @@
+/**
+ * PDF object parser.
+ *
+ * Parses PDF tokens into typed PDF objects: dictionaries, arrays, strings,
+ * numbers, booleans, names, null, indirect references, and streams.
+ *
+ * @see PDF Reference 1.7, Chapter 3 - Objects
+ */
+import type { Token, PdfTokenizer } from "./pdf-tokenizer.js";
+/** A PDF indirect object reference: `N gen R` */
+export interface PdfRef {
+    readonly type: "ref";
+    readonly objNum: number;
+    readonly gen: number;
+}
+/** A PDF stream: dictionary + raw data bytes */
+export interface PdfStream {
+    readonly type: "stream";
+    readonly dict: PdfDictValue;
+    readonly data: Uint8Array;
+}
+/** A PDF dictionary: key-value pairs where keys are names */
+export type PdfDictValue = Map<string, PdfObject>;
+/** A PDF array */
+export type PdfArrayValue = PdfObject[];
+/**
+ * Union type for all possible PDF object values.
+ */
+export type PdfObject = number | string | boolean | null | Uint8Array | PdfRef | PdfDictValue | PdfArrayValue | PdfStream;
+export declare function isPdfRef(obj: PdfObject | undefined): obj is PdfRef;
+export declare function isPdfStream(obj: PdfObject | undefined): obj is PdfStream;
+export declare function isPdfDict(obj: PdfObject | undefined): obj is PdfDictValue;
+export declare function isPdfArray(obj: PdfObject | undefined): obj is PdfArrayValue;
+/** Get a string value from a PDF dictionary */
+export declare function dictGetName(dict: PdfDictValue, key: string): string | undefined;
+/** Get a number value from a PDF dictionary */
+export declare function dictGetNumber(dict: PdfDictValue, key: string): number | undefined;
+/** Get a boolean value from a PDF dictionary */
+export declare function dictGetBool(dict: PdfDictValue, key: string): boolean | undefined;
+/** Get a dictionary value from a PDF dictionary */
+export declare function dictGetDict(dict: PdfDictValue, key: string): PdfDictValue | undefined;
+/** Get an array value from a PDF dictionary */
+export declare function dictGetArray(dict: PdfDictValue, key: string): PdfArrayValue | undefined;
+/** Get a ref from a PDF dictionary */
+export declare function dictGetRef(dict: PdfDictValue, key: string): PdfRef | undefined;
+/** Get bytes (string as Uint8Array) from a PDF dictionary */
+export declare function dictGetBytes(dict: PdfDictValue, key: string): Uint8Array | undefined;
+/** Get a string value that may be either a name (string) or bytes decoded as latin1 */
+export declare function dictGetString(dict: PdfDictValue, key: string): string | undefined;
+/**
+ * Decode PDF string bytes to a JavaScript string.
+ * Handles UTF-16BE (BOM = FEFF) and PDFDocEncoding (Latin-1 superset).
+ */
+export declare function decodePdfStringBytes(bytes: Uint8Array): string;
+/**
+ * Parse a single PDF object from the tokenizer.
+ *
+ * Handles all PDF object types including dictionaries (with possible streams),
+ * arrays, strings, numbers, names, booleans, null, and indirect references.
+ */
+export declare function parseObject(tokenizer: PdfTokenizer): PdfObject;
+/**
+ * Parse a PDF object given the first token has already been consumed.
+ */
+export declare function parseObjectFromToken(tokenizer: PdfTokenizer, token: Token): PdfObject;

package/dist/browser/modules/pdf/reader/pdf-parser.js

@@ -0,0 +1,285 @@
+/**
+ * PDF object parser.
+ *
+ * Parses PDF tokens into typed PDF objects: dictionaries, arrays, strings,
+ * numbers, booleans, names, null, indirect references, and streams.
+ *
+ * @see PDF Reference 1.7, Chapter 3 - Objects
+ */
+import { TokenType } from "./pdf-tokenizer.js";
+import { PdfStructureError } from "../errors.js";
+// =============================================================================
+// Type Guards
+// =============================================================================
+export function isPdfRef(obj) {
+    return obj !== null && typeof obj === "object" && "type" in obj && obj.type === "ref";
+}
+export function isPdfStream(obj) {
+    return obj !== null && typeof obj === "object" && "type" in obj && obj.type === "stream";
+}
+export function isPdfDict(obj) {
+    return obj instanceof Map;
+}
+export function isPdfArray(obj) {
+    return Array.isArray(obj);
+}
+// =============================================================================
+// Dictionary Helpers
+// =============================================================================
+/** Get a string value from a PDF dictionary */
+export function dictGetName(dict, key) {
+    const val = dict.get(key);
+    return typeof val === "string" ? val : undefined;
+}
+/** Get a number value from a PDF dictionary */
+export function dictGetNumber(dict, key) {
+    const val = dict.get(key);
+    return typeof val === "number" ? val : undefined;
+}
+/** Get a boolean value from a PDF dictionary */
+export function dictGetBool(dict, key) {
+    const val = dict.get(key);
+    return typeof val === "boolean" ? val : undefined;
+}
+/** Get a dictionary value from a PDF dictionary */
+export function dictGetDict(dict, key) {
+    const val = dict.get(key);
+    return isPdfDict(val) ? val : undefined;
+}
+/** Get an array value from a PDF dictionary */
+export function dictGetArray(dict, key) {
+    const val = dict.get(key);
+    return isPdfArray(val) ? val : undefined;
+}
+/** Get a ref from a PDF dictionary */
+export function dictGetRef(dict, key) {
+    const val = dict.get(key);
+    return isPdfRef(val) ? val : undefined;
+}
+/** Get bytes (string as Uint8Array) from a PDF dictionary */
+export function dictGetBytes(dict, key) {
+    const val = dict.get(key);
+    return val instanceof Uint8Array ? val : undefined;
+}
+/** Get a string value that may be either a name (string) or bytes decoded as latin1 */
+export function dictGetString(dict, key) {
+    const val = dict.get(key);
+    if (typeof val === "string") {
+        return val;
+    }
+    if (val instanceof Uint8Array) {
+        return decodePdfStringBytes(val);
+    }
+    return undefined;
+}
+/**
+ * Decode PDF string bytes to a JavaScript string.
+ * Handles UTF-16BE (BOM = FEFF) and PDFDocEncoding (Latin-1 superset).
+ */
+export function decodePdfStringBytes(bytes) {
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        // UTF-16BE
+        let result = "";
+        for (let i = 2; i + 1 < bytes.length; i += 2) {
+            const code = (bytes[i] << 8) | bytes[i + 1];
+            // Handle surrogate pairs
+            if (code >= 0xd800 && code <= 0xdbff && i + 3 < bytes.length) {
+                const low = (bytes[i + 2] << 8) | bytes[i + 3];
+                if (low >= 0xdc00 && low <= 0xdfff) {
+                    const cp = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+                    result += String.fromCodePoint(cp);
+                    i += 2;
+                    continue;
+                }
+            }
+            result += String.fromCharCode(code);
+        }
+        return result;
+    }
+    // UTF-8 BOM
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return new TextDecoder("utf-8").decode(bytes.subarray(3));
+    }
+    // PDFDocEncoding (identical to Latin-1 / ISO 8859-1 for 0x00-0xFF,
+    // with some differences in 0x80-0x9F range)
+    return decodePdfDocEncoding(bytes);
+}
+/** Decode bytes using PDFDocEncoding */
+function decodePdfDocEncoding(bytes) {
+    let result = "";
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        const mapped = PDF_DOC_ENCODING[b];
+        result += mapped !== undefined ? String.fromCodePoint(mapped) : String.fromCharCode(b);
+    }
+    return result;
+}
+/**
+ * PDFDocEncoding differences from Latin-1 in the 0x80-0xAD range.
+ * @see PDF Reference 1.7, Table D.2
+ */
+const PDF_DOC_ENCODING = {
+    0x80: 0x2022, // •
+    0x81: 0x2020, // †
+    0x82: 0x2021, // ‡
+    0x83: 0x2026, // …
+    0x84: 0x2014, // —
+    0x85: 0x2013, // –
+    0x86: 0x0192, // ƒ
+    0x87: 0x2044, // ⁄
+    0x88: 0x2039, // ‹
+    0x89: 0x203a, // ›
+    0x8a: 0x2212, // −
+    0x8b: 0x2030, // ‰
+    0x8c: 0x201e, // „
+    0x8d: 0x201c, // "
+    0x8e: 0x201d, // "
+    0x8f: 0x2018, // '
+    0x90: 0x2019, // '
+    0x91: 0x201a, // ‚
+    0x92: 0x2122, // ™
+    0x93: 0xfb01, // fi
+    0x94: 0xfb02, // fl
+    0x95: 0x0141, // Ł
+    0x96: 0x0152, // Œ
+    0x97: 0x0160, // Š
+    0x98: 0x0178, // Ÿ
+    0x99: 0x017d, // Ž
+    0x9a: 0x0131, // ı
+    0x9b: 0x0142, // ł
+    0x9c: 0x0153, // œ
+    0x9d: 0x0161, // š
+    0x9e: 0x017e, // ž
+    0xa0: 0x20ac, // €
+    0xad: 0x02c7 //  ˇ
+};
+// =============================================================================
+// PDF Object Parser
+// =============================================================================
+/**
+ * Parse a single PDF object from the tokenizer.
+ *
+ * Handles all PDF object types including dictionaries (with possible streams),
+ * arrays, strings, numbers, names, booleans, null, and indirect references.
+ */
+export function parseObject(tokenizer) {
+    const token = tokenizer.next();
+    return parseObjectFromToken(tokenizer, token);
+}
+/**
+ * Parse a PDF object given the first token has already been consumed.
+ */
+export function parseObjectFromToken(tokenizer, token) {
+    switch (token.type) {
+        case TokenType.Number: {
+            // Could be: number, or start of indirect ref (N gen R) or indirect obj (N gen obj)
+            const num = token.numValue;
+            const savedPos = tokenizer.pos;
+            const next = tokenizer.next();
+            if (next.type === TokenType.Number) {
+                const gen = next.numValue;
+                const next2 = tokenizer.next();
+                if (next2.type === TokenType.Keyword && next2.strValue === "R") {
+                    // Indirect reference: N gen R
+                    return { type: "ref", objNum: num, gen };
+                }
+                if (next2.type === TokenType.Keyword && next2.strValue === "obj") {
+                    // Indirect object definition: N gen obj ... endobj
+                    const obj = parseObject(tokenizer);
+                    // Check if it's a stream
+                    if (isPdfDict(obj)) {
+                        tokenizer.skipWhitespaceAndComments();
+                        const peekPos = tokenizer.pos;
+                        const maybeStream = tokenizer.next();
+                        if (maybeStream.type === TokenType.Keyword && maybeStream.strValue === "stream") {
+                            const length = dictGetNumber(obj, "Length") ?? -1;
+                            const streamData = tokenizer.readStreamContent(length);
+                            // Consume endobj
+                            const endobj = tokenizer.next();
+                            if (endobj.type !== TokenType.Keyword || endobj.strValue !== "endobj") {
+                                // Some PDFs don't have endobj after endstream — tolerate
+                                tokenizer.pos = endobj.offset;
+                            }
+                            return { type: "stream", dict: obj, data: streamData };
+                        }
+                        // Not a stream — restore position
+                        tokenizer.pos = peekPos;
+                    }
+                    // Consume endobj
+                    tokenizer.skipWhitespaceAndComments();
+                    const peekEnd = tokenizer.pos;
+                    const endTok = tokenizer.next();
+                    if (endTok.type !== TokenType.Keyword || endTok.strValue !== "endobj") {
+                        tokenizer.pos = peekEnd;
+                    }
+                    return obj;
+                }
+                // Not a ref or obj definition — restore
+                tokenizer.pos = savedPos;
+                return num;
+            }
+            // Not followed by another number — just a number
+            tokenizer.pos = savedPos;
+            return num;
+        }
+        case TokenType.LiteralString:
+        case TokenType.HexString:
+            return token.rawBytes ?? new Uint8Array(0);
+        case TokenType.Name:
+            return token.strValue;
+        case TokenType.Boolean:
+            return token.boolValue;
+        case TokenType.Null:
+            return null;
+        case TokenType.DictBegin:
+            return parseDictionary(tokenizer);
+        case TokenType.ArrayBegin:
+            return parseArray(tokenizer);
+        case TokenType.EOF:
+            throw new PdfStructureError("Unexpected end of input while parsing PDF object");
+        default:
+            // Keywords like "endobj", "stream" etc. are unexpected in object context
+            // Return them as-is for the caller to handle
+            return token.strValue ?? null;
+    }
+}
+/**
+ * Parse a PDF dictionary (after the `<<` token has been consumed).
+ */
+function parseDictionary(tokenizer) {
+    const dict = new Map();
+    while (true) {
+        const keyToken = tokenizer.next();
+        if (keyToken.type === TokenType.DictEnd) {
+            break;
+        }
+        if (keyToken.type === TokenType.EOF) {
+            throw new PdfStructureError("Unexpected EOF in dictionary");
+        }
+        if (keyToken.type !== TokenType.Name) {
+            // Some malformed PDFs have non-name keys — skip and try again
+            continue;
+        }
+        const key = keyToken.strValue;
+        const value = parseObject(tokenizer);
+        dict.set(key, value);
+    }
+    return dict;
+}
+/**
+ * Parse a PDF array (after the `[` token has been consumed).
+ */
+function parseArray(tokenizer) {
+    const arr = [];
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === TokenType.ArrayEnd) {
+            break;
+        }
+        if (token.type === TokenType.EOF) {
+            throw new PdfStructureError("Unexpected EOF in array");
+        }
+        arr.push(parseObjectFromToken(tokenizer, token));
+    }
+    return arr;
+}

package/dist/browser/modules/pdf/reader/pdf-reader.d.ts

@@ -0,0 +1,143 @@
+/**
+ * PDF reader — public API.
+ *
+ * Provides a high-level, zero-dependency interface for reading PDF files.
+ * Supports:
+ * - Text extraction with multilingual support (WinAnsi, MacRoman, CJK via
+ *   ToUnicode CMap, Identity-H/V, Symbol, ZapfDingbats)
+ * - Image extraction (JPEG, JPEG2000, raw/Flate, CCITT, JBIG2)
+ * - Annotation extraction (links, comments, highlights, stamps, etc.)
+ * - Form field extraction (AcroForm: text inputs, checkboxes, radio buttons, dropdowns)
+ * - Metadata reading (Info dictionary + XMP)
+ * - Encrypted PDFs:
+ *   - RC4 (40-bit and 128-bit) — tested via roundtrip
+ *   - AES-128 (V=4, R=4) — implemented, requires external test fixtures
+ *   - AES-256 (V=5, R=5) — implemented, requires external test fixtures
+ * - Cross-reference tables and streams (PDF 1.5+)
+ * - Incremental updates and xref recovery
+ *
+ * @example Basic text extraction:
+ * ```typescript
+ * import { readPdf } from "excelts/pdf";
+ *
+ * const pdf = readPdf(pdfBytes);
+ * console.log(pdf.text);           // All text from all pages
+ * console.log(pdf.pages[0].text);  // Text from page 1
+ * ```
+ *
+ * @example Image extraction:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes);
+ * for (const image of pdf.pages[0].images) {
+ *   console.log(image.format, image.width, image.height);
+ *   fs.writeFileSync(`image.${image.format}`, image.data);
+ * }
+ * ```
+ *
+ * @example Metadata:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes);
+ * console.log(pdf.metadata.title);
+ * console.log(pdf.metadata.author);
+ * console.log(pdf.metadata.pageCount);
+ * ```
+ *
+ * @example Encrypted PDF:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes, { password: "secret" });
+ * ```
+ */
+import type { TextLine } from "./text-reconstruction.js";
+import type { TextFragment } from "./content-interpreter.js";
+import type { ExtractedImage } from "./image-extractor.js";
+import type { PdfAnnotation } from "./annotation-extractor.js";
+import type { PdfFormField } from "./form-extractor.js";
+import type { PdfMetadata } from "./metadata-reader.js";
+/**
+ * Options for reading a PDF.
+ */
+export interface ReadPdfOptions {
+    /**
+     * Password for encrypted PDFs.
+     * Can be either the user password or owner password.
+     * @default ""
+     */
+    password?: string;
+    /**
+     * Which pages to extract (1-based).
+     * If omitted, all pages are extracted.
+     * @example [1, 3, 5] — extract pages 1, 3, and 5
+     */
+    pages?: number[];
+    /**
+     * Whether to extract text.
+     * @default true
+     */
+    extractText?: boolean;
+    /**
+     * Whether to extract images.
+     * @default true
+     */
+    extractImages?: boolean;
+    /**
+     * Whether to extract metadata.
+     * @default true
+     */
+    extractMetadata?: boolean;
+    /**
+     * Whether to extract annotations (links, comments, highlights, etc.).
+     * @default true
+     */
+    extractAnnotations?: boolean;
+    /**
+     * Whether to extract form fields (AcroForm: text inputs, checkboxes, dropdowns, etc.).
+     * @default true
+     */
+    extractFormFields?: boolean;
+}
+/**
+ * A single page from a read PDF.
+ */
+export interface ReadPdfPage {
+    /** 1-based page number */
+    pageNumber: number;
+    /** Extracted text content */
+    text: string;
+    /** Structured text lines with position information */
+    textLines: TextLine[];
+    /** Raw text fragments with exact positions */
+    textFragments: TextFragment[];
+    /** Extracted images */
+    images: ExtractedImage[];
+    /** Extracted annotations (links, comments, highlights, etc.) */
+    annotations: PdfAnnotation[];
+    /** Page width in points */
+    width: number;
+    /** Page height in points */
+    height: number;
+    /** Warnings encountered during extraction (non-fatal errors) */
+    warnings: string[];
+}
+/**
+ * Result of reading a PDF.
+ */
+export interface ReadPdfResult {
+    /** All text from all pages concatenated */
+    text: string;
+    /** Per-page results */
+    pages: ReadPdfPage[];
+    /** Document metadata */
+    metadata: PdfMetadata;
+    /** Form fields extracted from AcroForm (document-level) */
+    formFields: PdfFormField[];
+}
+/**
+ * Read a PDF file and extract text, images, and metadata.
+ *
+ * @param data - Raw PDF file bytes
+ * @param options - Extraction options
+ * @returns Extracted content
+ * @throws {PdfStructureError} If the PDF structure is invalid
+ * @throws {PdfError} If decryption fails (wrong password)
+ */
+export declare function readPdf(data: Uint8Array, options?: ReadPdfOptions): ReadPdfResult;

package/dist/browser/modules/pdf/reader/pdf-reader.js

@@ -0,0 +1,200 @@
+/**
+ * PDF reader — public API.
+ *
+ * Provides a high-level, zero-dependency interface for reading PDF files.
+ * Supports:
+ * - Text extraction with multilingual support (WinAnsi, MacRoman, CJK via
+ *   ToUnicode CMap, Identity-H/V, Symbol, ZapfDingbats)
+ * - Image extraction (JPEG, JPEG2000, raw/Flate, CCITT, JBIG2)
+ * - Annotation extraction (links, comments, highlights, stamps, etc.)
+ * - Form field extraction (AcroForm: text inputs, checkboxes, radio buttons, dropdowns)
+ * - Metadata reading (Info dictionary + XMP)
+ * - Encrypted PDFs:
+ *   - RC4 (40-bit and 128-bit) — tested via roundtrip
+ *   - AES-128 (V=4, R=4) — implemented, requires external test fixtures
+ *   - AES-256 (V=5, R=5) — implemented, requires external test fixtures
+ * - Cross-reference tables and streams (PDF 1.5+)
+ * - Incremental updates and xref recovery
+ *
+ * @example Basic text extraction:
+ * ```typescript
+ * import { readPdf } from "excelts/pdf";
+ *
+ * const pdf = readPdf(pdfBytes);
+ * console.log(pdf.text);           // All text from all pages
+ * console.log(pdf.pages[0].text);  // Text from page 1
+ * ```
+ *
+ * @example Image extraction:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes);
+ * for (const image of pdf.pages[0].images) {
+ *   console.log(image.format, image.width, image.height);
+ *   fs.writeFileSync(`image.${image.format}`, image.data);
+ * }
+ * ```
+ *
+ * @example Metadata:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes);
+ * console.log(pdf.metadata.title);
+ * console.log(pdf.metadata.author);
+ * console.log(pdf.metadata.pageCount);
+ * ```
+ *
+ * @example Encrypted PDF:
+ * ```typescript
+ * const pdf = readPdf(pdfBytes, { password: "secret" });
+ * ```
+ */
+import { PdfDocument } from "./pdf-document.js";
+import { initDecryption, isEncrypted } from "./pdf-decrypt.js";
+import { extractTextFromPage } from "./content-interpreter.js";
+import { reconstructText, reconstructTextLines } from "./text-reconstruction.js";
+import { extractImagesFromPage } from "./image-extractor.js";
+import { extractAnnotationsFromPage } from "./annotation-extractor.js";
+import { extractFormFields } from "./form-extractor.js";
+import { extractMetadata } from "./metadata-reader.js";
+import { PdfStructureError } from "../errors.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Read a PDF file and extract text, images, and metadata.
+ *
+ * @param data - Raw PDF file bytes
+ * @param options - Extraction options
+ * @returns Extracted content
+ * @throws {PdfStructureError} If the PDF structure is invalid
+ * @throws {PdfError} If decryption fails (wrong password)
+ */
+export function readPdf(data, options) {
+    const opts = {
+        password: options?.password ?? "",
+        pages: options?.pages,
+        extractText: options?.extractText ?? true,
+        extractImages: options?.extractImages ?? true,
+        extractMetadata: options?.extractMetadata ?? true,
+        extractAnnotations: options?.extractAnnotations ?? true,
+        extractFormFields: options?.extractFormFields ?? true
+    };
+    // Parse document structure
+    const doc = new PdfDocument(data);
+    // Handle encryption
+    if (isEncrypted(doc)) {
+        const success = initDecryption(doc, opts.password);
+        if (!success) {
+            throw new PdfStructureError("Failed to decrypt PDF: incorrect password");
+        }
+    }
+    // Extract metadata
+    const metadata = opts.extractMetadata ? extractMetadata(doc) : createEmptyMetadata();
+    // Get pages (with object identity for correct decryption)
+    const pagesInfo = doc.getPagesWithObjInfo();
+    const pageIndicesToProcess = opts.pages
+        ? opts.pages.map(p => p - 1).filter(p => p >= 0 && p < pagesInfo.length)
+        : Array.from({ length: pagesInfo.length }, (_, i) => i);
+    // Process each page
+    const pages = [];
+    for (const pageIdx of pageIndicesToProcess) {
+        const { dict: pageDict } = pagesInfo[pageIdx];
+        const pageNumber = pageIdx + 1;
+        const warnings = [];
+        // Extract text
+        let text = "";
+        let textLines = [];
+        let textFragments = [];
+        if (opts.extractText) {
+            try {
+                textFragments = extractTextFromPage(pageDict, doc);
+                text = reconstructText(textFragments);
+                textLines = reconstructTextLines(textFragments);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Text extraction failed on page ${pageNumber}: ${msg}`);
+            }
+        }
+        // Extract images
+        let images = [];
+        if (opts.extractImages) {
+            try {
+                images = extractImagesFromPage(pageDict, doc);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Image extraction failed on page ${pageNumber}: ${msg}`);
+            }
+        }
+        // Extract annotations
+        let annotations = [];
+        if (opts.extractAnnotations) {
+            try {
+                annotations = extractAnnotationsFromPage(pageDict, doc);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                warnings.push(`Annotation extraction failed on page ${pageNumber}: ${msg}`);
+            }
+        }
+        // Get page dimensions
+        const { width, height } = getPageDimensions(pageDict, doc);
+        pages.push({
+            pageNumber,
+            text,
+            textLines,
+            textFragments,
+            images,
+            annotations,
+            width,
+            height,
+            warnings
+        });
+    }
+    // Concatenate all page text
+    const allText = pages.map(p => p.text).join("\n\n");
+    // Update page count in metadata
+    if (opts.extractMetadata) {
+        metadata.pageCount = pagesInfo.length;
+    }
+    // Extract form fields (document-level, not per-page)
+    let formFields = [];
+    if (opts.extractFormFields) {
+        try {
+            formFields = extractFormFields(doc);
+        }
+        catch {
+            // Non-fatal — just return empty
+        }
+    }
+    return {
+        text: allText,
+        pages,
+        metadata,
+        formFields
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function getPageDimensions(pageDict, doc) {
+    return doc.resolvePageBox(pageDict) ?? { width: 612, height: 792 }; // Default: US Letter
+}
+function createEmptyMetadata() {
+    return {
+        title: "",
+        author: "",
+        subject: "",
+        keywords: "",
+        creator: "",
+        producer: "",
+        creationDate: null,
+        modDate: null,
+        pdfVersion: "",
+        pageCount: 0,
+        encrypted: false,
+        pageSize: null,
+        xmpXml: null,
+        custom: {}
+    };
+}