@cj-tech-master/excelts 8.0.0 → 8.1.0

package/dist/esm/modules/pdf/core/encryption.js

@@ -1,310 +1,137 @@
 /**
- * PDF encryption support (Standard Security Handler, Revision 3).
+ * PDF encryption support (Standard Security Handler, V=5, R=5).
  *
- * Implements RC4-128 encryption compatible with PDF 1.4.
+ * Implements AES-256 encryption compatible with PDF 2.0 (ISO 32000-2:2020).
  * Supports:
  * - User password (required to open the document)
  * - Owner password (grants full access)
  * - Permission flags (print, copy, modify, etc.)
  *
- * @see PDF Reference 1.7, §3.5 - Encryption
+ * The file encryption key (FEK) is a random 256-bit key.
+ * All streams and strings are encrypted using AES-256-CBC with a random
+ * 16-byte IV prepended to each encrypted value.
+ *
+ * @see ISO 32000-2:2020, §7.6 — Encryption
  */
-// =============================================================================
-// Constants
-// =============================================================================
-/** PDF password padding string (32 bytes) per PDF spec §3.5.2 */
-const PASSWORD_PADDING = new Uint8Array([
-    0x28, 0xbf, 0x4e, 0x5e, 0x4e, 0x75, 0x8a, 0x41, 0x64, 0x00, 0x4e, 0x56, 0xff, 0xfa, 0x01, 0x08,
-    0x2e, 0x2e, 0x00, 0xb6, 0xd0, 0x68, 0x3e, 0x80, 0x2f, 0x0c, 0xa9, 0xfe, 0x64, 0x53, 0x69, 0x7a
-]);
+import { sha256, aesCbcEncrypt, aesCbcEncryptRaw, aesEcbEncrypt, randomBytes, concatArrays } from "./crypto.js";
 // =============================================================================
 // Public API
 // =============================================================================
 /**
- * Initialize encryption state from the given options.
+ * Initialize encryption state for AES-256 (V=5, R=5).
  */
 export function initEncryption(options) {
-    const userPwd = options.userPassword ?? "";
-    const ownerPwd = options.ownerPassword;
+    const userPwd = truncatePassword(options.userPassword ?? "");
+    const ownerPwd = truncatePassword(options.ownerPassword);
     const perms = computePermissions(options.permissions);
-    const fileId = generateFileId();
-    // Step 1: Compute O value
-    const oValue = computeOValue(ownerPwd, userPwd);
-    // Step 2: Compute encryption key
-    const encryptionKey = computeEncryptionKey(userPwd, oValue, perms, fileId);
+    // Step 1: Generate random 32-byte file encryption key
+    const encryptionKey = randomBytes(32);
+    // Step 2: Generate random salts
+    const uValidationSalt = randomBytes(8);
+    const uKeySalt = randomBytes(8);
+    const oValidationSalt = randomBytes(8);
+    const oKeySalt = randomBytes(8);
     // Step 3: Compute U value
-    const uValue = computeUValue(encryptionKey, fileId);
-    return { encryptionKey, oValue, uValue, permissions: perms, fileId };
-}
-/**
- * Encrypt a string or stream for a specific PDF object.
- * Per-object encryption key = MD5(encryptionKey + objectNumber + generation).
- */
-export function encryptData(data, objectNumber, generation, encryptionKey) {
-    // Compute per-object key: MD5(encryptionKey + objNum(3LE) + genNum(2LE))
-    const keyInput = new Uint8Array(encryptionKey.length + 5);
-    keyInput.set(encryptionKey);
-    keyInput[encryptionKey.length] = objectNumber & 0xff;
-    keyInput[encryptionKey.length + 1] = (objectNumber >> 8) & 0xff;
-    keyInput[encryptionKey.length + 2] = (objectNumber >> 16) & 0xff;
-    keyInput[encryptionKey.length + 3] = generation & 0xff;
-    keyInput[encryptionKey.length + 4] = (generation >> 8) & 0xff;
-    const objKey = md5(keyInput);
-    // Use min(n+5, 16) bytes of the hash as the RC4 key
-    const keyLen = Math.min(encryptionKey.length + 5, 16);
-    const rc4Key = objKey.subarray(0, keyLen);
-    return rc4(rc4Key, data);
+    // U hash = SHA-256(userPassword + uValidationSalt)
+    const uHash = sha256(concatArrays(userPwd, uValidationSalt));
+    const uValue = concatArrays(uHash, uValidationSalt, uKeySalt);
+    // Step 4: Compute UE value
+    // UE = AES-256-CBC-encrypt(encryptionKey, SHA-256(userPassword + uKeySalt), zeroIV)
+    // Actually: the key for encrypting UE is SHA-256(password + key_salt),
+    // and we encrypt the file encryption key with it.
+    const ueKey = sha256(concatArrays(userPwd, uKeySalt));
+    const zeroIv = new Uint8Array(16);
+    const ueValue = aesCbcEncryptRaw(encryptionKey, ueKey, zeroIv);
+    // Step 5: Compute O value
+    // O hash = SHA-256(ownerPassword + oValidationSalt + U(0..47))
+    const oHash = sha256(concatArrays(ownerPwd, oValidationSalt, uValue));
+    const oValue = concatArrays(oHash, oValidationSalt, oKeySalt);
+    // Step 6: Compute OE value
+    // OE = AES-256-CBC-encrypt(encryptionKey, SHA-256(ownerPassword + oKeySalt + U(0..47)), zeroIV)
+    const oeKey = sha256(concatArrays(ownerPwd, oKeySalt, uValue));
+    const oeValue = aesCbcEncryptRaw(encryptionKey, oeKey, zeroIv);
+    // Step 7: Compute Perms value
+    // 16-byte block: P(4 LE bytes) + 0xFF(4 bytes) + 'T' or 'F' (encryptMetadata) + 'a' 'd' 'b' + 0(3 bytes)
+    const permsBlock = new Uint8Array(16);
+    const permsView = new DataView(permsBlock.buffer);
+    permsView.setInt32(0, perms, true); // P value in little-endian
+    permsBlock[4] = 0xff;
+    permsBlock[5] = 0xff;
+    permsBlock[6] = 0xff;
+    permsBlock[7] = 0xff;
+    permsBlock[8] = 0x54; // 'T' — EncryptMetadata = true
+    permsBlock[9] = 0x61; // 'a'
+    permsBlock[10] = 0x64; // 'd'
+    permsBlock[11] = 0x62; // 'b'
+    // bytes 12-15 are zero
+    const permsValue = aesEcbEncrypt(permsBlock, encryptionKey);
+    // File ID (random 16 bytes, used in trailer)
+    const fileId = randomBytes(16);
+    return {
+        encryptionKey,
+        oValue,
+        uValue,
+        oeValue,
+        ueValue,
+        permsValue,
+        permissions: perms,
+        fileId
+    };
 }
-// =============================================================================
-// RC4 Cipher
-// =============================================================================
 /**
- * RC4 stream cipher implementation.
+ * Encrypt data for a PDF object using AES-256-CBC.
+ *
+ * For V=5/R=5, the file encryption key is used directly (no per-object key derivation).
+ * A random 16-byte IV is prepended to the ciphertext.
  */
-export function rc4(key, data) {
-    // Key Scheduling Algorithm (KSA)
-    const s = new Uint8Array(256);
-    for (let i = 0; i < 256; i++) {
-        s[i] = i;
-    }
-    let j = 0;
-    for (let i = 0; i < 256; i++) {
-        j = (j + s[i] + key[i % key.length]) & 0xff;
-        [s[i], s[j]] = [s[j], s[i]];
-    }
-    // Pseudo-Random Generation Algorithm (PRGA)
-    const result = new Uint8Array(data.length);
-    let ii = 0;
-    let jj = 0;
-    for (let k = 0; k < data.length; k++) {
-        ii = (ii + 1) & 0xff;
-        jj = (jj + s[ii]) & 0xff;
-        [s[ii], s[jj]] = [s[jj], s[ii]];
-        result[k] = data[k] ^ s[(s[ii] + s[jj]) & 0xff];
-    }
+export function encryptData(data, _objectNumber, _generation, encryptionKey) {
+    const iv = randomBytes(16);
+    const ciphertext = aesCbcEncrypt(data, encryptionKey, iv);
+    // Prepend IV to ciphertext per PDF spec
+    const result = new Uint8Array(16 + ciphertext.length);
+    result.set(iv);
+    result.set(ciphertext, 16);
     return result;
 }
 // =============================================================================
-// MD5 Hash
-// =============================================================================
-/**
- * MD5 hash implementation (RFC 1321).
- * Returns 16-byte digest.
- */
-export function md5(input) {
-    // Pre-processing: padding
-    const msgLen = input.length;
-    const bitLen = msgLen * 8;
-    // Pad to 64-byte boundary (56 bytes mod 64, then 8 bytes length)
-    const padLen = ((56 - ((msgLen + 1) % 64) + 64) % 64) + 1;
-    const padded = new Uint8Array(msgLen + padLen + 8);
-    padded.set(input);
-    padded[msgLen] = 0x80;
-    // Append length in bits as 64-bit little-endian
-    const view = new DataView(padded.buffer);
-    view.setUint32(padded.length - 8, bitLen >>> 0, true);
-    view.setUint32(padded.length - 4, 0, true); // high 32 bits (always 0 for our sizes)
-    // Initialize hash values
-    let a0 = 0x67452301;
-    let b0 = 0xefcdab89;
-    let c0 = 0x98badcfe;
-    let d0 = 0x10325476;
-    // Process each 64-byte block
-    for (let i = 0; i < padded.length; i += 64) {
-        const M = new Uint32Array(16);
-        for (let j = 0; j < 16; j++) {
-            M[j] = view.getUint32(i + j * 4, true);
-        }
-        let A = a0;
-        let B = b0;
-        let C = c0;
-        let D = d0;
-        for (let j = 0; j < 64; j++) {
-            let F;
-            let g;
-            if (j < 16) {
-                F = (B & C) | (~B & D);
-                g = j;
-            }
-            else if (j < 32) {
-                F = (D & B) | (~D & C);
-                g = (5 * j + 1) % 16;
-            }
-            else if (j < 48) {
-                F = B ^ C ^ D;
-                g = (3 * j + 5) % 16;
-            }
-            else {
-                F = C ^ (B | ~D);
-                g = (7 * j) % 16;
-            }
-            F = (F + A + K[j] + M[g]) >>> 0;
-            A = D;
-            D = C;
-            C = B;
-            B = (B + rotl(F, S[j])) >>> 0;
-        }
-        a0 = (a0 + A) >>> 0;
-        b0 = (b0 + B) >>> 0;
-        c0 = (c0 + C) >>> 0;
-        d0 = (d0 + D) >>> 0;
-    }
-    // Produce the 128-bit digest
-    const digest = new Uint8Array(16);
-    const dv = new DataView(digest.buffer);
-    dv.setUint32(0, a0, true);
-    dv.setUint32(4, b0, true);
-    dv.setUint32(8, c0, true);
-    dv.setUint32(12, d0, true);
-    return digest;
-}
-function rotl(x, n) {
-    return ((x << n) | (x >>> (32 - n))) >>> 0;
-}
-// MD5 per-round shift amounts
-const S = [
-    7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9, 14,
-    20, 5, 9, 14, 20, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15, 21, 6,
-    10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21
-];
-// MD5 per-round constants (floor(2^32 × abs(sin(i+1))))
-const K = new Uint32Array([
-    0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, 0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501,
-    0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be, 0x6b901122, 0xfd987193, 0xa679438e, 0x49b40821,
-    0xf61e2562, 0xc040b340, 0x265e5a51, 0xe9b6c7aa, 0xd62f105d, 0x02441453, 0xd8a1e681, 0xe7d3fbc8,
-    0x21e1cde6, 0xc33707d6, 0xf4d50d87, 0x455a14ed, 0xa9e3e905, 0xfcefa3f8, 0x676f02d9, 0x8d2a4c8a,
-    0xfffa3942, 0x8771f681, 0x6d9d6122, 0xfde5380c, 0xa4beea44, 0x4bdecfa9, 0xf6bb4b60, 0xbebfbc70,
-    0x289b7ec6, 0xeaa127fa, 0xd4ef3085, 0x04881d05, 0xd9d4d039, 0xe6db99e5, 0x1fa27cf8, 0xc4ac5665,
-    0xf4292244, 0x432aff97, 0xab9423a7, 0xfc93a039, 0x655b59c3, 0x8f0ccc92, 0xffeff47d, 0x85845dd1,
-    0x6fa87e4f, 0xfe2ce6e0, 0xa3014314, 0x4e0811a1, 0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391
-]);
-// =============================================================================
-// PDF Password / Key Computation
+// Internal Helpers
 // =============================================================================
 /**
- * Pad or truncate a password to 32 bytes using the PDF password padding.
+ * Truncate password to 127 bytes (UTF-8) per PDF 2.0 spec.
  */
-function padPassword(password) {
-    const result = new Uint8Array(32);
+function truncatePassword(password) {
     const bytes = new TextEncoder().encode(password);
-    const len = Math.min(bytes.length, 32);
-    result.set(bytes.subarray(0, len));
-    result.set(PASSWORD_PADDING.subarray(0, 32 - len), len);
-    return result;
-}
-/**
- * Compute the O (owner) value.
- * Algorithm 3 from PDF spec §3.5.2.
- */
-function computeOValue(ownerPassword, userPassword) {
-    // Step 1: MD5 hash of padded owner password
-    let hash = md5(padPassword(ownerPassword));
-    // Step 2: For revision 3, hash 50 more times
-    for (let i = 0; i < 50; i++) {
-        hash = md5(hash);
-    }
-    // Use first 16 bytes as RC4 key (128-bit / key length = 16)
-    const rc4Key = hash.subarray(0, 16);
-    // Step 3: RC4-encrypt the padded user password
-    let result = rc4(rc4Key, padPassword(userPassword));
-    // Step 4: For revision 3, iterate 1-19 with modified key
-    for (let i = 1; i <= 19; i++) {
-        const modKey = new Uint8Array(16);
-        for (let j = 0; j < 16; j++) {
-            modKey[j] = rc4Key[j] ^ i;
-        }
-        result = rc4(modKey, result);
-    }
-    return result;
-}
-/**
- * Compute the encryption key.
- * Algorithm 2 from PDF spec §3.5.2.
- */
-function computeEncryptionKey(userPassword, oValue, permissions, fileId) {
-    // Concatenate: padded password + O value + P value (4 LE bytes) + file ID
-    const paddedPwd = padPassword(userPassword);
-    const input = new Uint8Array(32 + 32 + 4 + fileId.length);
-    input.set(paddedPwd);
-    input.set(oValue, 32);
-    const pView = new DataView(input.buffer, input.byteOffset);
-    pView.setInt32(64, permissions, true);
-    input.set(fileId, 68);
-    let hash = md5(input);
-    // For revision 3, hash 50 more times
-    for (let i = 0; i < 50; i++) {
-        hash = md5(hash.subarray(0, 16));
-    }
-    return hash.subarray(0, 16); // 128-bit key
-}
-/**
- * Compute the U (user) value.
- * Algorithm 5 from PDF spec §3.5.2 (revision 3).
- */
-function computeUValue(encryptionKey, fileId) {
-    // Step 1: MD5 hash of padding + file ID
-    const hashInput = new Uint8Array(32 + fileId.length);
-    hashInput.set(PASSWORD_PADDING);
-    hashInput.set(fileId, 32);
-    const hash = md5(hashInput);
-    // Step 2: RC4-encrypt with the encryption key
-    let result = rc4(encryptionKey, hash);
-    // Step 3: Iterate 1-19 with modified key
-    for (let i = 1; i <= 19; i++) {
-        const modKey = new Uint8Array(16);
-        for (let j = 0; j < 16; j++) {
-            modKey[j] = encryptionKey[j] ^ i;
-        }
-        result = rc4(modKey, result);
-    }
-    // Pad to 32 bytes with arbitrary padding
-    const uValue = new Uint8Array(32);
-    uValue.set(result);
-    return uValue;
+    return bytes.length > 127 ? bytes.subarray(0, 127) : bytes;
 }
 /**
  * Compute the permissions integer (P value) from permission flags.
  */
 function computePermissions(perms) {
-    // Start with all bits set that are "reserved" and must be 1
-    // Bits 1-2, 7-8 must be 0; bits 13-32 must be 1 (per spec)
-    let p = 0xfffff000 | 0b11000000; // bits 7-8 = reserved 1, high bits = 1
+    // Start with all reserved bits set to 1
+    let p = 0xfffff000 | 0b11000000;
     if (perms?.print) {
-        p |= 1 << 2; // bit 3
+        p |= 1 << 2;
     }
     if (perms?.modify) {
-        p |= 1 << 3; // bit 4
+        p |= 1 << 3;
     }
     if (perms?.copy) {
-        p |= 1 << 4; // bit 5
+        p |= 1 << 4;
     }
     if (perms?.annotate) {
-        p |= 1 << 5; // bit 6
+        p |= 1 << 5;
     }
     if (perms?.fillForms) {
-        p |= 1 << 8; // bit 9
+        p |= 1 << 8;
     }
     if (perms?.accessibility) {
-        p |= 1 << 9; // bit 10
+        p |= 1 << 9;
     }
     if (perms?.assemble) {
-        p |= 1 << 10; // bit 11
+        p |= 1 << 10;
     }
     if (perms?.printHighQuality) {
-        p |= 1 << 11; // bit 12
+        p |= 1 << 11;
     }
-    // Convert to signed 32-bit
     return p | 0;
 }
-/**
- * Generate a random file identifier (16 bytes).
- */
-function generateFileId() {
-    // Use MD5 of current timestamp + random for determinism in tests
-    const seed = new Uint8Array(16);
-    const now = Date.now();
-    const view = new DataView(seed.buffer);
-    view.setFloat64(0, now, true);
-    view.setFloat64(8, Math.random() * 1e15, true);
-    return md5(seed);
-}

package/dist/esm/modules/pdf/core/pdf-writer.js

@@ -1,14 +1,16 @@
 /**
  * PDF file writer.
  *
- * Assembles a complete PDF document from indirect objects.
+ * Assembles a complete PDF 2.0 document from indirect objects.
  * Handles the four sections of a PDF file:
- * 1. Header (%PDF-1.4)
+ * 1. Header (%PDF-2.0)
  * 2. Body (indirect objects)
  * 3. Cross-reference table
  * 4. Trailer (with document catalog reference)
  *
- * @see PDF Reference 1.7, Chapter 3.4 - File Structure
+ * Encryption uses AES-256 (V=5, R=5) per ISO 32000-2:2020.
+ *
+ * @see ISO 32000-2:2020, Chapter 7.5 — File Structure
  */
 import { PdfDict, pdfRef, pdfString, pdfHexString, pdfDate, pdfNumber } from "./pdf-object.js";
 import { PdfStructureError } from "../errors.js";
@@ -19,7 +21,7 @@ import { encryptData } from "./encryption.js";
 // PDF Writer
 // =============================================================================
 /**
- * Constructs a valid PDF 1.4 file from a set of indirect objects.
+ * Constructs a valid PDF 2.0 file from a set of indirect objects.
  *
  * Usage:
  * 1. Allocate object numbers with allocObject()
@@ -168,7 +170,7 @@ export class PdfWriter {
         let byteOffset = 0;
         // --- Header ---
         // Include a comment with high bytes to signal binary content per PDF spec §3.4.1
-        const headerStr = "%PDF-1.4\n";
+        const headerStr = "%PDF-2.0\n";
         const headerStrBytes = encoder.encode(headerStr);
         chunks.push(headerStrBytes);
         byteOffset += headerStrBytes.length;
@@ -220,16 +222,23 @@ export class PdfWriter {
             chunks.push(objFooter);
             byteOffset += objFooter.length;
         }
-        // --- Encrypt dictionary (must be added before xref) ---
+        // --- Encrypt dictionary (V=5, R=5, AES-256) ---
         if (this.encryption) {
             const encDict = new PdfDict()
                 .set("Filter", "/Standard")
-                .set("V", "2")
-                .set("R", "3")
-                .set("Length", "128")
+                .set("V", "5")
+                .set("R", "5")
+                .set("Length", "256")
                 .set("P", String(this.encryption.permissions))
                 .set("O", pdfHexString(this.encryption.oValue))
-                .set("U", pdfHexString(this.encryption.uValue));
+                .set("U", pdfHexString(this.encryption.uValue))
+                .set("OE", pdfHexString(this.encryption.oeValue))
+                .set("UE", pdfHexString(this.encryption.ueValue))
+                .set("Perms", pdfHexString(this.encryption.permsValue))
+                .set("EncryptMetadata", "true")
+                .set("CF", "<< /StdCF << /Type /CryptFilter /CFM /AESV3 /AuthEvent /DocOpen /Length 32 >> >>")
+                .set("StmF", "/StdCF")
+                .set("StrF", "/StdCF");
             const encContent = encDict.toString();
             const encObj = {
                 objectNumber: encryptObjNum,

package/dist/esm/modules/pdf/index.js

@@ -1,9 +1,9 @@
 /**
  * PDF module for excelts.
  *
- * A full-featured, zero-dependency PDF engine.
+ * A full-featured, zero-dependency PDF engine for both writing and reading.
  *
- * @example Standalone:
+ * @example Standalone PDF generation:
  * ```typescript
  * import { pdf } from "excelts/pdf";
  *
@@ -25,15 +25,33 @@
  * const bytes = excelToPdf(workbook);
  * ```
  *
+ * @example Read PDF — extract text, images, and metadata:
+ * ```typescript
+ * import { readPdf } from "excelts/pdf";
+ *
+ * const result = readPdf(pdfBytes);
+ * console.log(result.text);               // All text
+ * console.log(result.pages[0].text);      // Page 1 text
+ * console.log(result.pages[0].images);    // Page 1 images
+ * console.log(result.pages[0].annotations); // Page 1 annotations
+ * console.log(result.metadata.title);     // Document title
+ * console.log(result.formFields);         // Form fields
+ * ```
+ *
  * @module pdf
  */
 // =============================================================================
-// Public API
+// Public API — Writing
 // =============================================================================
 /** Standalone PDF generation — accepts plain arrays, sheet objects, or workbooks. */
 export { pdf } from "./pdf.js";
 /** Excel-to-PDF conversion — accepts an Excel Workbook instance. */
 export { excelToPdf } from "./excel-bridge.js";
+// =============================================================================
+// Public API — Reading
+// =============================================================================
+/** Read a PDF file and extract text, images, and metadata. */
+export { readPdf } from "./reader/pdf-reader.js";
 export { PageSizes } from "./types.js";
 // =============================================================================
 // Errors

package/dist/esm/modules/pdf/reader/annotation-extractor.js

@@ -0,0 +1,155 @@
+/**
+ * PDF annotation extractor.
+ *
+ * Extracts annotations from a PDF page's `/Annots` array.
+ * Supports all standard annotation subtypes defined in PDF Reference 1.7, §12.5.
+ *
+ * Common annotation types:
+ * - **Link** — Hyperlinks (URI, GoTo, GoToR)
+ * - **Text** — Sticky notes / comments
+ * - **FreeText** — Inline text annotations
+ * - **Highlight / Underline / StrikeOut / Squiggly** — Text markup
+ * - **Stamp** — Rubber stamp annotations
+ * - **Popup** — Associated popup windows
+ * - **Widget** — Form field widgets (handled separately by form-extractor)
+ *
+ * @see PDF Reference 1.7, §12.5 - Annotations
+ */
+import { isPdfArray, dictGetName, dictGetNumber, decodePdfStringBytes } from "./pdf-parser.js";
+import { getDictStringValue } from "./reader-utils.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Extract annotations from a PDF page.
+ *
+ * Skips Widget annotations (form fields) — those are handled by the form extractor.
+ *
+ * @param pageDict - The page dictionary
+ * @param doc - The PDF document for resolving references
+ * @returns Array of extracted annotations
+ */
+export function extractAnnotationsFromPage(pageDict, doc) {
+    const annotsObj = pageDict.get("Annots");
+    if (!annotsObj) {
+        return [];
+    }
+    // Resolve the Annots array (may be an indirect reference)
+    const annotsResolved = doc.deref(annotsObj);
+    if (!isPdfArray(annotsResolved)) {
+        return [];
+    }
+    const annotations = [];
+    for (const annotRef of annotsResolved) {
+        try {
+            const annotDict = doc.derefDict(annotRef);
+            if (!annotDict) {
+                continue;
+            }
+            const subtype = dictGetName(annotDict, "Subtype") ?? "";
+            // Skip Widget annotations — handled by form-extractor
+            if (subtype === "Widget") {
+                continue;
+            }
+            // Skip Popup annotations — they are auxiliary
+            if (subtype === "Popup") {
+                continue;
+            }
+            const annotation = parseAnnotation(annotDict, subtype, doc);
+            if (annotation) {
+                annotations.push(annotation);
+            }
+        }
+        catch {
+            // Skip malformed annotations
+        }
+    }
+    return annotations;
+}
+// =============================================================================
+// Parsing
+// =============================================================================
+function parseAnnotation(dict, subtype, doc) {
+    const rect = parseRect(dict.get("Rect"), doc);
+    if (!rect) {
+        return null;
+    }
+    const contents = getDictStringValue(dict, "Contents", doc);
+    const author = getDictStringValue(dict, "T", doc);
+    const subject = getDictStringValue(dict, "Subj", doc);
+    const modifiedDate = getDictStringValue(dict, "M", doc);
+    const flags = dictGetNumber(dict, "F") ?? 0;
+    const color = parseColorArray(dict.get("C"), doc);
+    // Extract link-specific fields
+    let uri = "";
+    let destination = "";
+    if (subtype === "Link") {
+        const actionObj = doc.derefDict(dict.get("A"));
+        if (actionObj) {
+            const actionType = dictGetName(actionObj, "S");
+            if (actionType === "URI") {
+                uri = getDictStringValue(actionObj, "URI", doc);
+            }
+            else if (actionType === "GoTo") {
+                const dest = actionObj.get("D");
+                if (typeof dest === "string") {
+                    destination = dest;
+                }
+            }
+            else if (actionType === "GoToR") {
+                uri = getDictStringValue(actionObj, "F", doc);
+            }
+        }
+        // Check /Dest directly (older PDFs use this instead of /A)
+        if (!uri && !destination) {
+            const destObj = dict.get("Dest");
+            if (destObj) {
+                const resolved = doc.deref(destObj);
+                if (typeof resolved === "string") {
+                    destination = resolved;
+                }
+                else if (resolved instanceof Uint8Array) {
+                    destination = decodePdfStringBytes(resolved);
+                }
+            }
+        }
+    }
+    return {
+        subtype,
+        rect,
+        contents,
+        author,
+        subject,
+        modifiedDate,
+        uri,
+        destination,
+        flags,
+        color
+    };
+}
+function parseRect(obj, doc) {
+    if (!obj) {
+        return null;
+    }
+    const resolved = doc.deref(obj);
+    if (!isPdfArray(resolved) || resolved.length < 4) {
+        return null;
+    }
+    const nums = resolved.map(v => (typeof v === "number" ? v : 0));
+    return {
+        x1: nums[0],
+        y1: nums[1],
+        x2: nums[2],
+        y2: nums[3]
+    };
+}
+function parseColorArray(obj, doc) {
+    if (!obj) {
+        return [];
+    }
+    const resolved = doc.deref(obj);
+    if (!isPdfArray(resolved)) {
+        return [];
+    }
+    return resolved.map(v => (typeof v === "number" ? v : 0));
+}