@cj-tech-master/excelts 8.0.0 → 8.1.0

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

@@ -0,0 +1,63 @@
+/**
+ * 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 type { PdfDocument } from "./pdf-document.js";
+import type { PdfDictValue } from "./pdf-parser.js";
+/** Rectangle in PDF coordinate space [x1, y1, x2, y2] */
+export interface PdfRect {
+    /** Left edge (x1) */
+    x1: number;
+    /** Bottom edge (y1) */
+    y1: number;
+    /** Right edge (x2) */
+    x2: number;
+    /** Top edge (y2) */
+    y2: number;
+}
+/** A PDF annotation extracted from a page. */
+export interface PdfAnnotation {
+    /** Annotation subtype (e.g. "Link", "Text", "Highlight", "FreeText", "Stamp") */
+    subtype: string;
+    /** Bounding rectangle in page coordinates (points) */
+    rect: PdfRect;
+    /** Text content (/Contents entry) */
+    contents: string;
+    /** Author / title (/T entry) */
+    author: string;
+    /** Subject (/Subj entry) */
+    subject: string;
+    /** Modification date (/M entry) — raw PDF date string */
+    modifiedDate: string;
+    /** For Link annotations: the destination URI */
+    uri: string;
+    /** For Link annotations: named destination */
+    destination: string;
+    /** Annotation flags (/F entry) */
+    flags: number;
+    /** Color (/C entry) — array of 0-3 values in [0,1] */
+    color: number[];
+}
+/**
+ * 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 declare function extractAnnotationsFromPage(pageDict: PdfDictValue, doc: PdfDocument): PdfAnnotation[];

package/dist/browser/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));
+}

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

@@ -0,0 +1,70 @@
+/**
+ * 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
+ */
+/**
+ * A parsed CMap that maps character codes to Unicode strings.
+ */
+export declare class CMap {
+    private codeSpaceRanges;
+    private bfChars;
+    private bfRanges;
+    /** Number of bytes per character code (detected from codespace ranges) */
+    bytesPerCode: number;
+    constructor();
+    /**
+     * Look up the Unicode string for a character code.
+     * Uses binary search over sorted bfRanges for efficient lookup.
+     */
+    lookup(code: number): string | undefined;
+    /**
+     * Add a code space range.
+     */
+    addCodeSpaceRange(low: number, high: number, bytes: number): void;
+    /**
+     * Add a bfchar mapping.
+     */
+    addBfChar(code: number, unicode: string): void;
+    /**
+     * Add a bfrange mapping.
+     */
+    addBfRange(low: number, high: number, mapping: string | string[]): void;
+    /**
+     * Sort bfRanges by low value for binary search.
+     * Should be called after all ranges have been added.
+     */
+    sortRanges(): void;
+    /**
+     * 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: number): number;
+    /**
+     * Check if this CMap has any mappings.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Check if this CMap has codespace ranges defined.
+     */
+    get hasCodeSpaceRanges(): boolean;
+}
+/**
+ * Parse a CMap program (typically from a /ToUnicode stream).
+ */
+export declare function parseCMap(data: Uint8Array): CMap;

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

@@ -0,0 +1,321 @@
+/**
+ * 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
+ */
+import { PdfTokenizer, TokenType } from "./pdf-tokenizer.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * A parsed CMap that maps character codes to Unicode strings.
+ */
+export 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;
+    }
+}
+// =============================================================================
+// CMap Parser
+// =============================================================================
+/**
+ * Parse a CMap program (typically from a /ToUnicode stream).
+ */
+export function parseCMap(data) {
+    const cmap = new CMap();
+    const tokenizer = new PdfTokenizer(data);
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === TokenType.EOF) {
+            break;
+        }
+        if (token.type === 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 === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword && token.strValue === "endcodespacerange") {
+            break;
+        }
+        // Expect two hex strings: low high
+        if (token.type === TokenType.HexString) {
+            const lowBytes = token.rawBytes;
+            const highToken = tokenizer.next();
+            if (highToken.type === 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 === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword && token.strValue === "endbfchar") {
+            break;
+        }
+        if (token.type === TokenType.HexString) {
+            const code = bytesToInt(token.rawBytes);
+            const target = tokenizer.next();
+            if (target.type === 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 === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword && token.strValue === "endbfrange") {
+            break;
+        }
+        if (token.type === TokenType.HexString) {
+            const low = bytesToInt(token.rawBytes);
+            const highToken = tokenizer.next();
+            if (highToken.type !== TokenType.HexString) {
+                continue;
+            }
+            const high = bytesToInt(highToken.rawBytes);
+            const mappingToken = tokenizer.next();
+            if (mappingToken.type === TokenType.HexString) {
+                // Sequential mapping from base string
+                const unicode = decodeUtf16BE(mappingToken.rawBytes);
+                cmap.addBfRange(low, high, unicode);
+            }
+            else if (mappingToken.type === TokenType.ArrayBegin) {
+                // Array of individual mappings
+                const mappings = [];
+                while (true) {
+                    const elem = tokenizer.next();
+                    if (elem.type === TokenType.ArrayEnd || elem.type === TokenType.EOF) {
+                        break;
+                    }
+                    if (elem.type === 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;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * PDF content stream interpreter for text extraction.
+ *
+ * Implements a full PDF graphics state machine that processes content stream
+ * operators to extract positioned text fragments. These fragments are then
+ * assembled into readable text by the text reconstruction module.
+ *
+ * Supported operator categories:
+ * - Text state: Tf, Tc, Tw, Tz, TL, Ts, Tr
+ * - Text positioning: Td, TD, Tm, T*
+ * - Text showing: Tj, TJ, ', "
+ * - Text objects: BT, ET
+ * - Graphics state: q, Q, cm, gs, i, M, ri, W, W*
+ * - Color: CS, cs, SC, sc, SCN, scn
+ * - Marked content: BDC, BMC, EMC, MP, DP
+ * - Type3 glyph: d0, d1
+ * - Shading: sh
+ * - Inline images: BI/ID/EI
+ * - XObject invocation: Do (for form XObjects containing text)
+ *
+ * @see PDF Reference 1.7, Chapter 5 - Text
+ * @see PDF Reference 1.7, Chapter 4 - Graphics
+ */
+import type { PdfDocument } from "./pdf-document.js";
+import type { PdfDictValue } from "./pdf-parser.js";
+/**
+ * A text fragment extracted from a PDF page.
+ * Contains the text string and its position in page coordinates.
+ */
+export interface TextFragment {
+    /** The extracted text */
+    text: string;
+    /** X position in page coordinates (points, origin = bottom-left) */
+    x: number;
+    /** Y position in page coordinates */
+    y: number;
+    /** Font size in points */
+    fontSize: number;
+    /** Font name */
+    fontName: string;
+    /** Width of the text in points */
+    width: number;
+    /** Character spacing */
+    charSpacing: number;
+    /** Word spacing */
+    wordSpacing: number;
+    /** Horizontal scaling factor (100 = normal) */
+    horizontalScaling: number;
+    /** Whether the text is vertical (WMode=1) */
+    isVertical: boolean;
+    /** Whether the text is right-to-left (Arabic, Hebrew, etc.) */
+    isRtl: boolean;
+}
+/**
+ * Extract text fragments from a page's content stream(s).
+ */
+export declare function extractTextFromPage(pageDict: PdfDictValue, doc: PdfDocument): TextFragment[];