@cj-tech-master/excelts 9.1.0 → 9.2.0

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

@@ -0,0 +1,324 @@
+/**
+ * PDF bookmark (outline) extractor.
+ *
+ * Extracts the document outline tree from a PDF's `/Outlines` dictionary.
+ * Each outline item has a title, a target page index, and optional children
+ * forming a hierarchical bookmark tree.
+ *
+ * Supports:
+ * - Direct destinations (`/Dest` as array or named destination)
+ * - Action-based destinations (`/A << /S /GoTo /D ... >>`)
+ * - Nested bookmarks (children via `/First`/`/Last` chains)
+ * - Circular reference protection
+ *
+ * @see PDF Reference 1.7, §12.3 - Document-Level Navigation
+ */
+import { isPdfArray, isPdfRef, dictGetName, decodePdfStringBytes } from "./pdf-parser.js";
+import { getDictStringValue } from "./reader-utils.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Maximum depth for recursive outline traversal to prevent stack overflow. */
+const MAX_OUTLINE_DEPTH = 100;
+/** Maximum number of siblings at any level to prevent infinite /Next chains. */
+const MAX_SIBLINGS = 10000;
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Extract bookmarks (outlines) from a PDF document.
+ *
+ * Reads the `/Outlines` dictionary from the catalog and recursively
+ * traverses the outline tree following `/First` → `/Next` chains.
+ *
+ * @param doc - The PDF document
+ * @returns Array of top-level bookmarks with nested children
+ */
+export function extractBookmarks(doc) {
+    try {
+        const catalog = doc.getCatalog();
+        const outlinesObj = catalog.get("Outlines");
+        if (!outlinesObj) {
+            return [];
+        }
+        const outlinesDict = doc.derefDict(outlinesObj);
+        if (!outlinesDict) {
+            return [];
+        }
+        // Build a page reference → index map for resolving destinations
+        const pageMap = buildPageMap(doc);
+        // The outline root's /First points to the first top-level item
+        const visited = new Set();
+        return collectSiblings(outlinesDict, doc, pageMap, visited, 0);
+    }
+    catch {
+        return [];
+    }
+}
+// =============================================================================
+// Page Map
+// =============================================================================
+/**
+ * Build a map from page object reference identity to 0-based page index.
+ *
+ * We map by object number since page dicts resolved from different refs
+ * will share the same objNum.
+ */
+function buildPageMap(doc) {
+    const pages = doc.getPagesWithObjInfo();
+    const map = new Map();
+    for (let i = 0; i < pages.length; i++) {
+        const { objNum } = pages[i];
+        if (objNum !== 0) {
+            map.set(objNum, i);
+        }
+    }
+    return map;
+}
+// =============================================================================
+// Outline Tree Traversal
+// =============================================================================
+/**
+ * Collect the sibling chain starting from the `/First` child of a parent node.
+ */
+function collectSiblings(parentDict, doc, pageMap, visited, depth) {
+    if (depth > MAX_OUTLINE_DEPTH) {
+        return [];
+    }
+    const firstObj = parentDict.get("First");
+    if (!firstObj) {
+        return [];
+    }
+    const bookmarks = [];
+    let currentObj = firstObj;
+    let count = 0;
+    while (currentObj != null && count < MAX_SIBLINGS) {
+        count++;
+        // Guard against circular references using object numbers
+        if (isPdfRef(currentObj)) {
+            if (visited.has(currentObj.objNum)) {
+                break;
+            }
+            visited.add(currentObj.objNum);
+        }
+        const itemDict = doc.derefDict(currentObj);
+        if (!itemDict) {
+            break;
+        }
+        const bookmark = parseOutlineItem(itemDict, doc, pageMap, visited, depth);
+        if (bookmark) {
+            bookmarks.push(bookmark);
+        }
+        // Follow /Next to the next sibling
+        currentObj = itemDict.get("Next");
+    }
+    return bookmarks;
+}
+/**
+ * Parse a single outline item dictionary into a PdfBookmark.
+ */
+function parseOutlineItem(dict, doc, pageMap, visited, depth) {
+    // Extract title — required per spec
+    const title = getOutlineTitle(dict, doc);
+    if (!title) {
+        return null;
+    }
+    // Resolve destination to a page index
+    const pageIndex = resolveDestination(dict, doc, pageMap);
+    // Collect children (nested bookmarks)
+    const children = collectSiblings(dict, doc, pageMap, visited, depth + 1);
+    return { title, pageIndex, children };
+}
+// =============================================================================
+// Title Extraction
+// =============================================================================
+/**
+ * Extract the title string from an outline item dictionary.
+ * The /Title entry is a text string (may be Uint8Array or string).
+ */
+function getOutlineTitle(dict, doc) {
+    return getDictStringValue(dict, "Title", doc);
+}
+// =============================================================================
+// Destination Resolution
+// =============================================================================
+/**
+ * Resolve an outline item's destination to a 0-based page index.
+ *
+ * Checks /Dest first, then falls back to /A (action) with /S /GoTo.
+ * Returns -1 if the destination cannot be resolved.
+ */
+function resolveDestination(dict, doc, pageMap) {
+    // 1. Try /Dest (direct destination)
+    const destObj = dict.get("Dest");
+    if (destObj != null) {
+        const pageIndex = resolveDestValue(destObj, doc, pageMap);
+        if (pageIndex >= 0) {
+            return pageIndex;
+        }
+    }
+    // 2. Try /A (action dictionary) with /S /GoTo
+    const actionObj = dict.get("A");
+    if (actionObj != null) {
+        const actionDict = doc.derefDict(actionObj);
+        if (actionDict) {
+            const actionType = dictGetName(actionDict, "S");
+            if (actionType === "GoTo") {
+                const actionDest = actionDict.get("D");
+                if (actionDest != null) {
+                    return resolveDestValue(actionDest, doc, pageMap);
+                }
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Resolve a destination value (from /Dest or /A.D) to a page index.
+ *
+ * Destination formats (PDF Reference 1.7, §12.3.2):
+ * - Array: `[pageRef /XYZ left top zoom]`, `[pageRef /Fit]`, etc.
+ * - Named string: looked up in the document's /Dests or /Names.Dests
+ */
+function resolveDestValue(destObj, doc, pageMap) {
+    const resolved = doc.deref(destObj);
+    if (resolved == null) {
+        return -1;
+    }
+    // Array destination: first element is the page reference
+    if (isPdfArray(resolved) && resolved.length >= 1) {
+        return resolvePageRef(resolved[0], doc, pageMap);
+    }
+    // Named destination (string) — look up in /Dests or /Names tree
+    if (typeof resolved === "string") {
+        return resolveNamedDest(resolved, doc, pageMap);
+    }
+    // Byte string named destination
+    if (resolved instanceof Uint8Array) {
+        const name = decodePdfStringBytes(resolved);
+        return resolveNamedDest(name, doc, pageMap);
+    }
+    return -1;
+}
+/**
+ * Resolve a page reference (from the first element of a dest array) to a page index.
+ */
+function resolvePageRef(pageObj, doc, pageMap) {
+    // If it's a direct reference, use the object number
+    if (isPdfRef(pageObj)) {
+        const idx = pageMap.get(pageObj.objNum);
+        return idx !== undefined ? idx : -1;
+    }
+    // If it's a page number (integer), use it directly as 0-based index
+    if (typeof pageObj === "number" && Number.isInteger(pageObj)) {
+        return pageObj;
+    }
+    return -1;
+}
+/**
+ * Look up a named destination in the catalog's /Dests dictionary
+ * or /Names.Dests name tree.
+ */
+function resolveNamedDest(name, doc, pageMap) {
+    const catalog = doc.getCatalog();
+    // 1. Try /Dests dictionary (older PDFs)
+    const destsObj = catalog.get("Dests");
+    if (destsObj != null) {
+        const destsDict = doc.derefDict(destsObj);
+        if (destsDict) {
+            const entry = destsDict.get(name);
+            if (entry != null) {
+                return resolveDestEntry(entry, doc, pageMap);
+            }
+        }
+    }
+    // 2. Try /Names.Dests name tree (PDF 1.2+)
+    const namesObj = catalog.get("Names");
+    if (namesObj != null) {
+        const namesDict = doc.derefDict(namesObj);
+        if (namesDict) {
+            const destsTreeObj = namesDict.get("Dests");
+            if (destsTreeObj != null) {
+                const value = lookupNameTree(destsTreeObj, name, doc);
+                if (value != null) {
+                    return resolveDestEntry(value, doc, pageMap);
+                }
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Resolve a destination entry value. It may be a dict with /D key,
+ * or a direct array destination.
+ */
+function resolveDestEntry(entry, doc, pageMap) {
+    const resolved = doc.deref(entry);
+    if (resolved == null) {
+        return -1;
+    }
+    // Direct array destination
+    if (isPdfArray(resolved) && resolved.length >= 1) {
+        return resolvePageRef(resolved[0], doc, pageMap);
+    }
+    // Dictionary with /D entry (destination dictionary)
+    if (resolved instanceof Map) {
+        const d = resolved.get("D");
+        if (d != null) {
+            return resolveDestValue(d, doc, pageMap);
+        }
+    }
+    return -1;
+}
+/**
+ * Look up a key in a PDF name tree.
+ *
+ * Name trees use either /Names (leaf) or /Kids (intermediate) arrays.
+ * /Names is an array of alternating [key, value, key, value, ...] pairs.
+ *
+ * @see PDF Reference 1.7, §7.9.6 - Name Trees
+ */
+function lookupNameTree(treeObj, name, doc, depth = 0) {
+    if (depth > MAX_OUTLINE_DEPTH) {
+        return null;
+    }
+    const treeDict = doc.derefDict(treeObj);
+    if (!treeDict) {
+        return null;
+    }
+    // Check leaf /Names array
+    const namesArr = treeDict.get("Names");
+    if (namesArr != null) {
+        const resolved = doc.deref(namesArr);
+        if (isPdfArray(resolved)) {
+            // Alternating [key, value, key, value, ...]
+            for (let i = 0; i + 1 < resolved.length; i += 2) {
+                const key = doc.deref(resolved[i]);
+                let keyStr = null;
+                if (typeof key === "string") {
+                    keyStr = key;
+                }
+                else if (key instanceof Uint8Array) {
+                    keyStr = decodePdfStringBytes(key);
+                }
+                if (keyStr === name) {
+                    return resolved[i + 1];
+                }
+            }
+        }
+    }
+    // Check intermediate /Kids array
+    const kidsArr = treeDict.get("Kids");
+    if (kidsArr != null) {
+        const resolved = doc.deref(kidsArr);
+        if (isPdfArray(resolved)) {
+            for (const kid of resolved) {
+                const result = lookupNameTree(kid, name, doc, depth + 1);
+                if (result != null) {
+                    return result;
+                }
+            }
+        }
+    }
+    return null;
+}

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

@@ -10,7 +10,8 @@
  * @see PDF Reference 1.7, §3.5 - Encryption
  * @see PDF 2.0 (ISO 32000-2), §7.6 - Encryption
  */
-import { rc4, md5, sha256, aesCbcDecrypt, aesCbcDecryptRaw, concatArrays } from "../core/crypto.js";
+import { rc4, md5, sha256, aesCbcDecrypt, aesCbcDecryptRaw } from "../../../utils/crypto.browser.js";
+import { concatUint8Arrays } from "../../../utils/binary.js";
 import { dictGetNumber, dictGetName, dictGetBytes, dictGetArray, dictGetBool } from "./pdf-parser.js";
 import { PdfStructureError } from "../errors.js";
 // =============================================================================
@@ -164,13 +165,13 @@ function tryUserPasswordV5(passwordBytes, uValue, ueValue) {
     const uValidationSalt = uValue.subarray(32, 40);
     const uKeySalt = uValue.subarray(40, 48);
     // Validate: SHA-256(password + validation salt) == first 32 bytes of U
-    const validateInput = concatArrays(passwordBytes, uValidationSalt);
+    const validateInput = concatUint8Arrays([passwordBytes, uValidationSalt]);
     const computedHash = sha256(validateInput);
     if (!arraysEqual(computedHash, uHash)) {
         return null;
     }
     // Derive key: SHA-256(password + key salt) => use as AES-256 key to decrypt UE
-    const keyInput = concatArrays(passwordBytes, uKeySalt);
+    const keyInput = concatUint8Arrays([passwordBytes, uKeySalt]);
     const keyHash = sha256(keyInput);
     // Decrypt UE with this key using AES-256-CBC with zero IV
     const zeroIv = new Uint8Array(16);
@@ -188,13 +189,13 @@ function tryOwnerPasswordV5(passwordBytes, oValue, oeValue, uValue) {
     const oKeySalt = oValue.subarray(40, 48);
     const u48 = uValue.subarray(0, 48);
     // Validate: SHA-256(password + validation salt + U(0..47)) == first 32 bytes of O
-    const validateInput = concatArrays(passwordBytes, oValidationSalt, u48);
+    const validateInput = concatUint8Arrays([passwordBytes, oValidationSalt, u48]);
     const computedHash = sha256(validateInput);
     if (!arraysEqual(computedHash, oHash)) {
         return null;
     }
     // Derive key: SHA-256(password + key salt + U(0..47))
-    const keyInput = concatArrays(passwordBytes, oKeySalt, u48);
+    const keyInput = concatUint8Arrays([passwordBytes, oKeySalt, u48]);
     const keyHash = sha256(keyInput);
     // Decrypt OE with this key using AES-256-CBC with zero IV
     const zeroIv = new Uint8Array(16);

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

@@ -52,7 +52,9 @@ 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 { PdfBookmark } from "./bookmark-extractor.js";
 import type { PdfMetadata } from "./metadata-reader.js";
+import type { PdfTable } from "./table-extractor.js";
 /**
  * Options for reading a PDF.
  */
@@ -94,6 +96,17 @@ export interface ReadPdfOptions {
      * @default true
      */
     extractFormFields?: boolean;
+    /**
+     * Whether to extract bookmarks (document outline / table of contents).
+     * @default true
+     */
+    extractBookmarks?: boolean;
+    /**
+     * Whether to extract tables from pages using text positioning heuristics.
+     * Opt-in since table detection is heavier than plain text extraction.
+     * @default false
+     */
+    extractTables?: boolean;
 }
 /**
  * A single page from a read PDF.
@@ -111,6 +124,8 @@ export interface ReadPdfPage {
     images: ExtractedImage[];
     /** Extracted annotations (links, comments, highlights, etc.) */
     annotations: PdfAnnotation[];
+    /** Tables detected from text fragment positioning (opt-in via extractTables) */
+    tables: PdfTable[];
     /** Page width in points */
     width: number;
     /** Page height in points */
@@ -130,6 +145,8 @@ export interface ReadPdfResult {
     metadata: PdfMetadata;
     /** Form fields extracted from AcroForm (document-level) */
     formFields: PdfFormField[];
+    /** Bookmarks (document outline) extracted from the outline tree */
+    bookmarks: PdfBookmark[];
 }
 /**
  * Read a PDF file and extract text, images, and metadata.

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

@@ -54,7 +54,9 @@ 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 { extractBookmarks } from "./bookmark-extractor.js";
 import { extractMetadata } from "./metadata-reader.js";
+import { extractTables } from "./table-extractor.js";
 import { PdfStructureError } from "../errors.js";
 import { yieldToEventLoop } from "../../../utils/utils.base.js";
 // =============================================================================
@@ -93,7 +95,9 @@ function prepareRead(data, options) {
         extractImages: options?.extractImages ?? true,
         extractMetadata: options?.extractMetadata ?? true,
         extractAnnotations: options?.extractAnnotations ?? true,
-        extractFormFields: options?.extractFormFields ?? true
+        extractFormFields: options?.extractFormFields ?? true,
+        extractBookmarks: options?.extractBookmarks ?? true,
+        extractTables: options?.extractTables ?? false
     };
     const doc = new PdfDocument(data);
     if (isEncrypted(doc)) {
@@ -150,6 +154,16 @@ function processPage(pageDict, pageIdx, doc, opts) {
         }
     }
     const { width, height } = getPageDimensions(pageDict, doc);
+    let tables = [];
+    if (opts.extractTables) {
+        try {
+            tables = extractTables(textFragments, width, height);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            warnings.push(`Table extraction failed on page ${pageNumber}: ${msg}`);
+        }
+    }
     return {
         pageNumber,
         text,
@@ -157,6 +171,7 @@ function processPage(pageDict, pageIdx, doc, opts) {
         textFragments,
         images,
         annotations,
+        tables,
         width,
         height,
         warnings
@@ -179,7 +194,16 @@ function finalizeRead(pages, totalPageCount, metadata, opts, doc) {
             // Non-fatal — just return empty
         }
     }
-    return { text: allText, pages, metadata, formFields };
+    let bookmarks = [];
+    if (opts.extractBookmarks) {
+        try {
+            bookmarks = extractBookmarks(doc);
+        }
+        catch {
+            // Non-fatal — just return empty
+        }
+    }
+    return { text: allText, pages, metadata, formFields, bookmarks };
 }
 // =============================================================================
 // Helpers

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

@@ -0,0 +1,69 @@
+/**
+ * Table extraction from PDF pages using text fragment positioning.
+ *
+ * Detects tabular structures by analyzing the spatial layout of text fragments.
+ * Since PDF content streams typically render tables as positioned text (with or
+ * without drawn grid lines), this module uses a text-only heuristic:
+ *
+ * 1. Group fragments into lines by Y proximity
+ * 2. Detect column boundaries from consistent X-position clusters
+ * 3. Identify contiguous blocks of multi-column lines as tables
+ * 4. Map fragments to cells based on column/line membership
+ *
+ * @see content-interpreter.ts for TextFragment extraction
+ * @see text-reconstruction.ts for line grouping logic
+ */
+import type { TextFragment } from "./content-interpreter.js";
+/**
+ * A single cell in a PDF table.
+ */
+export interface PdfTableCell {
+    /** Text content of the cell */
+    text: string;
+    /** X position in page coordinates (points) */
+    x: number;
+    /** Y position in page coordinates (points) */
+    y: number;
+    /** Width of the cell in points */
+    width: number;
+    /** Height of the cell in points */
+    height: number;
+    /** Number of rows this cell spans (default 1) */
+    rowSpan?: number;
+    /** Number of columns this cell spans (default 1) */
+    colSpan?: number;
+}
+/**
+ * A single row in a PDF table.
+ */
+export interface PdfTableRow {
+    /** Cells in this row, ordered left-to-right */
+    cells: PdfTableCell[];
+}
+/**
+ * A table extracted from a PDF page.
+ */
+export interface PdfTable {
+    /** Rows in this table, ordered top-to-bottom */
+    rows: PdfTableRow[];
+    /** X position of the table (left edge) in page coordinates */
+    x: number;
+    /** Y position of the table (top edge) in page coordinates */
+    y: number;
+    /** Width of the table in points */
+    width: number;
+    /** Height of the table in points */
+    height: number;
+}
+/**
+ * Extract tables from a page's text fragments.
+ *
+ * Uses text positioning heuristics to detect tabular structures without
+ * relying on drawn lines or grid paths.
+ *
+ * @param fragments - Text fragments from `extractTextFromPage`
+ * @param pageWidth - Page width in points
+ * @param pageHeight - Page height in points
+ * @returns Array of detected tables
+ */
+export declare function extractTables(fragments: TextFragment[], pageWidth: number, pageHeight: number): PdfTable[];