@cj-tech-master/excelts 8.0.0 → 8.1.0

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

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractAnnotationsFromPage = extractAnnotationsFromPage;
+const pdf_parser_1 = require("./pdf-parser");
+const reader_utils_1 = require("./reader-utils");
+// =============================================================================
+// 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
+ */
+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 (!(0, pdf_parser_1.isPdfArray)(annotsResolved)) {
+        return [];
+    }
+    const annotations = [];
+    for (const annotRef of annotsResolved) {
+        try {
+            const annotDict = doc.derefDict(annotRef);
+            if (!annotDict) {
+                continue;
+            }
+            const subtype = (0, pdf_parser_1.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 = (0, reader_utils_1.getDictStringValue)(dict, "Contents", doc);
+    const author = (0, reader_utils_1.getDictStringValue)(dict, "T", doc);
+    const subject = (0, reader_utils_1.getDictStringValue)(dict, "Subj", doc);
+    const modifiedDate = (0, reader_utils_1.getDictStringValue)(dict, "M", doc);
+    const flags = (0, pdf_parser_1.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 = (0, pdf_parser_1.dictGetName)(actionObj, "S");
+            if (actionType === "URI") {
+                uri = (0, reader_utils_1.getDictStringValue)(actionObj, "URI", doc);
+            }
+            else if (actionType === "GoTo") {
+                const dest = actionObj.get("D");
+                if (typeof dest === "string") {
+                    destination = dest;
+                }
+            }
+            else if (actionType === "GoToR") {
+                uri = (0, reader_utils_1.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 = (0, pdf_parser_1.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 (!(0, pdf_parser_1.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 (!(0, pdf_parser_1.isPdfArray)(resolved)) {
+        return [];
+    }
+    return resolved.map(v => (typeof v === "number" ? v : 0));
+}

package/dist/cjs/modules/pdf/reader/cmap-parser.js

@@ -0,0 +1,326 @@
+"use strict";
+/**
+ * CMap parser for PDF text extraction.
+ *
+ * Parses /ToUnicode CMap programs to build character code → Unicode mappings.
+ * This is essential for extracting text from PDFs that use CIDFonts or
+ * custom encodings.
+ *
+ * Supports:
+ * - beginbfchar / endbfchar (single character mappings)
+ * - beginbfrange / endbfrange (range mappings, including array form)
+ * - begincodespacerange / endcodespacerange
+ * - Multi-byte character codes (1-4 bytes)
+ * - UTF-16BE encoded target strings (including surrogate pairs)
+ *
+ * @see PDF Reference 1.7, §5.9 - ToUnicode CMaps
+ * @see Adobe Technical Note #5411 - CMap Resources
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CMap = void 0;
+exports.parseCMap = parseCMap;
+const pdf_tokenizer_1 = require("./pdf-tokenizer");
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * A parsed CMap that maps character codes to Unicode strings.
+ */
+class CMap {
+    constructor() {
+        this.codeSpaceRanges = [];
+        this.bfChars = new Map();
+        this.bfRanges = [];
+        this.bytesPerCode = 1;
+    }
+    /**
+     * Look up the Unicode string for a character code.
+     * Uses binary search over sorted bfRanges for efficient lookup.
+     */
+    lookup(code) {
+        // Check bfchar mappings first (exact match)
+        const charMapping = this.bfChars.get(code);
+        if (charMapping !== undefined) {
+            return charMapping;
+        }
+        // Check bfrange mappings using binary search
+        const ranges = this.bfRanges;
+        let lo = 0;
+        let hi = ranges.length - 1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >>> 1;
+            const range = ranges[mid];
+            if (code < range.low) {
+                hi = mid - 1;
+            }
+            else if (code > range.high) {
+                lo = mid + 1;
+            }
+            else {
+                // code is within this range
+                if (typeof range.mapping === "string") {
+                    // Single base string — offset the code point
+                    const offset = code - range.low;
+                    const baseCode = stringToCodePoint(range.mapping);
+                    return String.fromCodePoint(baseCode + offset);
+                }
+                // Array mapping
+                const index = code - range.low;
+                if (index < range.mapping.length) {
+                    return range.mapping[index];
+                }
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Add a code space range.
+     */
+    addCodeSpaceRange(low, high, bytes) {
+        this.codeSpaceRanges.push({ low, high, bytes });
+        if (bytes > this.bytesPerCode) {
+            this.bytesPerCode = bytes;
+        }
+    }
+    /**
+     * Add a bfchar mapping.
+     */
+    addBfChar(code, unicode) {
+        this.bfChars.set(code, unicode);
+    }
+    /**
+     * Add a bfrange mapping.
+     */
+    addBfRange(low, high, mapping) {
+        this.bfRanges.push({ low, high, mapping });
+    }
+    /**
+     * Sort bfRanges by low value for binary search.
+     * Should be called after all ranges have been added.
+     */
+    sortRanges() {
+        this.bfRanges.sort((a, b) => a.low - b.low);
+    }
+    /**
+     * Determine the code length (in bytes) for a given first byte,
+     * using the codespace ranges. When multiple ranges match (e.g. a 1-byte
+     * range covering 0x00-0xFF and a 2-byte range whose first byte overlaps),
+     * returns the longest match per the PDF spec's greedy matching rule.
+     * Falls back to bytesPerCode if no range matches.
+     */
+    getCodeLength(firstByte) {
+        let bestLen = 0;
+        for (const range of this.codeSpaceRanges) {
+            if (range.bytes === 1) {
+                if (firstByte >= (range.low & 0xff) && firstByte <= (range.high & 0xff)) {
+                    if (bestLen < 1) {
+                        bestLen = 1;
+                    }
+                }
+            }
+            else if (range.bytes === 2) {
+                const highByteLow = (range.low >> 8) & 0xff;
+                const highByteHigh = (range.high >> 8) & 0xff;
+                if (firstByte >= highByteLow && firstByte <= highByteHigh) {
+                    if (bestLen < 2) {
+                        bestLen = 2;
+                    }
+                }
+            }
+            else {
+                // For multi-byte ranges (3+ bytes), check the high byte
+                const hiLow = range.low >>> ((range.bytes - 1) * 8);
+                const hiHigh = range.high >>> ((range.bytes - 1) * 8);
+                if (firstByte >= hiLow && firstByte <= hiHigh) {
+                    if (range.bytes > bestLen) {
+                        bestLen = range.bytes;
+                    }
+                }
+            }
+        }
+        return bestLen > 0 ? bestLen : this.bytesPerCode; // fallback
+    }
+    /**
+     * Check if this CMap has any mappings.
+     */
+    get isEmpty() {
+        return this.bfChars.size === 0 && this.bfRanges.length === 0;
+    }
+    /**
+     * Check if this CMap has codespace ranges defined.
+     */
+    get hasCodeSpaceRanges() {
+        return this.codeSpaceRanges.length > 0;
+    }
+}
+exports.CMap = CMap;
+// =============================================================================
+// CMap Parser
+// =============================================================================
+/**
+ * Parse a CMap program (typically from a /ToUnicode stream).
+ */
+function parseCMap(data) {
+    const cmap = new CMap();
+    const tokenizer = new pdf_tokenizer_1.PdfTokenizer(data);
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === 11 /* TokenType.EOF */) {
+            break;
+        }
+        if (token.type === 6 /* TokenType.Keyword */) {
+            const kw = token.strValue;
+            if (kw === "begincodespacerange") {
+                parseCodeSpaceRange(tokenizer, cmap);
+            }
+            else if (kw === "beginbfchar") {
+                parseBfChar(tokenizer, cmap);
+            }
+            else if (kw === "beginbfrange") {
+                parseBfRange(tokenizer, cmap);
+            }
+        }
+    }
+    // Sort bfRanges for binary search lookup
+    cmap.sortRanges();
+    return cmap;
+}
+/**
+ * Parse codespacerange section.
+ */
+function parseCodeSpaceRange(tokenizer, cmap) {
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === 11 /* TokenType.EOF */) {
+            break;
+        }
+        if (token.type === 6 /* TokenType.Keyword */ && token.strValue === "endcodespacerange") {
+            break;
+        }
+        // Expect two hex strings: low high
+        if (token.type === 2 /* TokenType.HexString */) {
+            const lowBytes = token.rawBytes;
+            const highToken = tokenizer.next();
+            if (highToken.type === 2 /* TokenType.HexString */) {
+                const highBytes = highToken.rawBytes;
+                const low = bytesToInt(lowBytes);
+                const high = bytesToInt(highBytes);
+                cmap.addCodeSpaceRange(low, high, lowBytes.length);
+            }
+        }
+    }
+}
+/**
+ * Parse bfchar section.
+ * Format: <srcCode> <dstString>
+ */
+function parseBfChar(tokenizer, cmap) {
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === 11 /* TokenType.EOF */) {
+            break;
+        }
+        if (token.type === 6 /* TokenType.Keyword */ && token.strValue === "endbfchar") {
+            break;
+        }
+        if (token.type === 2 /* TokenType.HexString */) {
+            const code = bytesToInt(token.rawBytes);
+            const target = tokenizer.next();
+            if (target.type === 2 /* TokenType.HexString */) {
+                const unicode = decodeUtf16BE(target.rawBytes);
+                cmap.addBfChar(code, unicode);
+            }
+        }
+    }
+}
+/**
+ * Parse bfrange section.
+ * Formats:
+ *   <low> <high> <dstString>           — sequential mapping
+ *   <low> <high> [<str1> <str2> ...]   — array mapping
+ */
+function parseBfRange(tokenizer, cmap) {
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === 11 /* TokenType.EOF */) {
+            break;
+        }
+        if (token.type === 6 /* TokenType.Keyword */ && token.strValue === "endbfrange") {
+            break;
+        }
+        if (token.type === 2 /* TokenType.HexString */) {
+            const low = bytesToInt(token.rawBytes);
+            const highToken = tokenizer.next();
+            if (highToken.type !== 2 /* TokenType.HexString */) {
+                continue;
+            }
+            const high = bytesToInt(highToken.rawBytes);
+            const mappingToken = tokenizer.next();
+            if (mappingToken.type === 2 /* TokenType.HexString */) {
+                // Sequential mapping from base string
+                const unicode = decodeUtf16BE(mappingToken.rawBytes);
+                cmap.addBfRange(low, high, unicode);
+            }
+            else if (mappingToken.type === 9 /* TokenType.ArrayBegin */) {
+                // Array of individual mappings
+                const mappings = [];
+                while (true) {
+                    const elem = tokenizer.next();
+                    if (elem.type === 10 /* TokenType.ArrayEnd */ || elem.type === 11 /* TokenType.EOF */) {
+                        break;
+                    }
+                    if (elem.type === 2 /* TokenType.HexString */) {
+                        mappings.push(decodeUtf16BE(elem.rawBytes));
+                    }
+                }
+                cmap.addBfRange(low, high, mappings);
+            }
+        }
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Convert a byte array to a big-endian integer.
+ * Uses multiplication instead of bitshift to avoid overflow for large codes.
+ */
+function bytesToInt(bytes) {
+    let result = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        result = result * 256 + bytes[i];
+    }
+    return result;
+}
+/**
+ * Decode a UTF-16BE byte array to a JavaScript string.
+ */
+function decodeUtf16BE(bytes) {
+    let result = "";
+    for (let i = 0; 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);
+    }
+    // Single-byte code: treat as direct character code
+    if (bytes.length === 1) {
+        return String.fromCharCode(bytes[0]);
+    }
+    return result;
+}
+/**
+ * Get the first code point from a string.
+ */
+function stringToCodePoint(str) {
+    return str.codePointAt(0) ?? 0;
+}