@llamaindex/liteparse 2.13.1 → 2.14.0

package/dist/lib.d.cts

@@ -0,0 +1,911 @@
+interface NativeWordBox {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface NativeTextItem {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontName?: string;
+    fontSize?: number;
+    fontHeight?: number;
+    fontAscent?: number;
+    fontDescent?: number;
+    fontWeight?: number;
+    textWidth?: number;
+    fontIsBuggy?: boolean;
+    mcid?: number;
+    fillColor?: string;
+    strokeColor?: string;
+    charCodes?: number[];
+    trailingSpaceGenerated?: boolean;
+    confidence?: number;
+    rotation?: number;
+    words?: NativeWordBox[];
+}
+interface NativeRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface NativeParsedPage {
+    pageNum: number;
+    width: number;
+    height: number;
+    contentBounds?: NativeRect;
+    text: string;
+    markdown: string;
+    textItems: NativeTextItem[];
+    complexity?: NativePageComplexityStats;
+    vectorGraphics?: NativeVectorGraphics;
+    annotations?: NativeDocumentAnnotation[];
+    formFields?: NativeFormField[];
+    structureTree?: NativeStructureTree;
+    blocks?: NativeLayoutBlock[];
+}
+interface NativeLayoutCell {
+    text: string;
+    bbox?: NativeRect;
+}
+interface NativeLayoutBlock {
+    kind: string;
+    text?: string;
+    level?: number;
+    bold?: boolean;
+    italic?: boolean;
+    ordered?: boolean;
+    marker?: string;
+    lines?: string[];
+    lang?: string;
+    header?: NativeLayoutCell[];
+    rows?: NativeLayoutCell[][];
+    id?: string;
+    format?: string;
+    bbox?: NativeRect;
+}
+interface NativeStructureAttribute {
+    name: string;
+    booleanValue?: boolean;
+    numberValue?: number;
+    stringValue?: string;
+}
+interface NativeStructureTree {
+    roots: NativeStructureTreeElement[];
+}
+interface NativeStructureTreeElement {
+    elementType: string;
+    id?: string;
+    actualText?: string;
+    altText?: string;
+    title?: string;
+    attributes: NativeStructureAttribute[];
+    markedContentIds: number[];
+    children: NativeStructureTreeElement[];
+    annotations: NativeDocumentAnnotation[];
+}
+interface NativeVectorGraphics {
+    shapes: Array<{
+        bbox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        stroke: boolean;
+        strokeColor?: string;
+        fill: boolean;
+        fillColor?: string;
+        hasCurve: boolean;
+    }>;
+    lines: Array<{
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+        stroke: boolean;
+        strokeWidth?: number;
+        strokeColor?: string;
+        fill: boolean;
+        fillColor?: string;
+    }>;
+}
+interface NativeAnnotationRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface NativeDocumentAnnotation {
+    subtype: string;
+    contents?: string;
+    created?: string;
+    modified?: string;
+    title?: string;
+    rect?: NativeAnnotationRect;
+    quadpointRects: NativeAnnotationRect[];
+    uri?: string;
+}
+interface NativeFormField {
+    id: string;
+    fieldType: string;
+    page: number;
+    annotationIndex: number;
+    widgetIndex: number;
+    objectNumber?: number;
+    name?: string;
+    alternateName?: string;
+    value?: string;
+    exportValue?: string;
+    fieldFlags: number;
+    controlCount?: number;
+    controlIndex?: number;
+    checked?: boolean;
+    rect?: NativeAnnotationRect;
+    options: string[];
+    selectedOptions: string[];
+}
+interface NativeExtractedImage {
+    id: string;
+    name: string;
+    path?: string;
+    page: number;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    width: number;
+    height: number;
+    rotation: number;
+    format: string;
+    duplicateOf?: string;
+    bytes: Buffer;
+}
+interface NativeParseResult {
+    totalPages: number;
+    pages: NativeParsedPage[];
+    pageErrors: Array<{
+        pageNum: number;
+        message: string;
+    }>;
+    text: string;
+    images: NativeExtractedImage[];
+    screenshots: NativeScreenshotResult[];
+    imageErrorCount: number;
+    formType?: number;
+    creator?: string;
+    producer?: string;
+    docMeta?: NativeDocumentMetadata;
+    xfaPackets?: NativeXfaPacket[];
+}
+interface NativeDocumentMetadata {
+    creationDate?: string;
+    modDate?: string;
+    fileVersion?: number;
+    isEncrypted?: boolean;
+    securityHandlerRevision?: number;
+    permissions?: number;
+    eofSectionCount?: number;
+    startxrefCount?: number;
+    trailerIdPairDiffers?: boolean;
+    rawFileSize?: number;
+    xmp?: string;
+    xmpTruncated?: boolean;
+    signatureCount?: number;
+    signatureByteRangeReachesEof?: boolean;
+}
+interface NativeXfaPacket {
+    index: number;
+    name?: string;
+    contentLength: number;
+    content?: string;
+}
+interface NativeScreenshotResult {
+    pageNum: number;
+    width: number;
+    height: number;
+    imageBuffer: Buffer;
+    isSolidFill: boolean;
+    rects: NativeScreenshotRect[];
+}
+interface NativeScreenshotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color: string;
+    isLine: boolean;
+}
+interface NativeLayoutComplexityStats {
+    columnCount: number;
+    ruledTableCount: number;
+    ruledTableCoverage: number;
+    textTableRunCount: number;
+    figureCount: number;
+    figureCoverage: number;
+    isComplex: boolean;
+    reasons: string[];
+}
+interface NativePageComplexityStats {
+    pageNumber: number;
+    textLength: number;
+    textCoverage: number;
+    hasSubstantialImages: boolean;
+    imageBlockCount: number;
+    imageCoverage: number;
+    largestImageCoverage: number;
+    fullPageImage: boolean;
+    uncoveredVectorArea?: number;
+    isGarbled: boolean;
+    pageArea: number;
+    needsOcr: boolean;
+    reasons: string[];
+    layout?: NativeLayoutComplexityStats;
+}
+
+/** A pooled parse exceeded `parseTimeoutMs` and its worker was killed.
+ *
+ * Only thrown in pool mode, where the deadline is enforced by killing the
+ * worker process — the timed-out parse is guaranteed dead, not still running
+ * in the background. `source` names the document (file path, or `<N bytes>`
+ * for byte inputs); log it to identify the documents that stall your
+ * pipeline.
+ */
+declare class ParseTimeoutError extends Error {
+    readonly source: string;
+    readonly timeoutMs: number;
+    constructor(message: string, source: string, timeoutMs: number);
+}
+
+type LiteParseInput = string | Buffer | Uint8Array;
+type OutputFormat = "json" | "text" | "markdown";
+type ImageMode = "off" | "placeholder" | "embed";
+/** Options for pool mode: parsing in persistent, killable worker processes. */
+interface PoolOptions {
+    /**
+     * Route `parse()` through a pool of this many persistent worker processes.
+     * Call `close()` when done (an idle pool never keeps the event loop alive,
+     * but explicit shutdown frees workers immediately).
+     */
+    poolSize?: number;
+    /**
+     * Hard per-parse deadline in milliseconds. Requires `poolSize`.
+     * The pool enforces the deadline by SIGKILLing the worker. On expiry
+     * the parse rejects with {@link ParseTimeoutError} (naming the document)
+     * and a fresh worker replaces the killed one.
+     */
+    parseTimeoutMs?: number;
+}
+interface LiteParseConfig {
+    ocrLanguage: string;
+    ocrEnabled: boolean;
+    ocrServerUrl?: string;
+    /** Extra HTTP headers sent with every request to `ocrServerUrl`. */
+    ocrServerHeaders?: Record<string, string>;
+    tessdataPath?: string;
+    maxPages: number;
+    targetPages?: string;
+    /** Render parsed pages to PNG and return them in `ParseResult.screenshots`. */
+    extractScreenshots: boolean;
+    /** Continue after page-level extraction failures and collect `pageErrors`. */
+    continueOnPageError: boolean;
+    dpi: number;
+    outputFormat: OutputFormat;
+    /** How to surface raster images in markdown output (default: "placeholder"). */
+    imageMode: ImageMode;
+    /** Extract embedded image bytes and metadata (default: false). */
+    extractImages: boolean;
+    /** Directory where extracted embedded image files are written. Requires `extractImages`. */
+    imageOutputDir?: string;
+    /** Render hyperlink annotations as `[text](url)` in markdown output (default: true). */
+    extractLinks: boolean;
+    /** Keep running headers/footers in markdown output instead of stripping repeated page-band lines and page chrome (default: false). */
+    keepHeadersFooters: boolean;
+    /** Extract all PDF annotations into each parsed page (default: false). */
+    extractAnnotations: boolean;
+    /** Extract AcroForm widget fields and values (default: false). */
+    extractFormFields: boolean;
+    /** Extract the tagged-PDF logical structure tree (default: false). */
+    extractStructureTree: boolean;
+    /**
+     * Emit each page's classified layout blocks with bounding boxes
+     * (default: false). This is the same decomposition the Markdown renderer
+     * consumes, exposed as data; enabling it never changes the rendered Markdown.
+     */
+    extractBlocks: boolean;
+    /** Extract raw XFA packets (name + XML content) into `ParseResult.xfaPackets` (default: false). */
+    extractXfaPackets: boolean;
+    /**
+     * Collect document provenance metadata into `result.docMeta`. Default
+     * false: Absent for inputs converted from a non-PDF format.
+     */
+    extractDocumentMetadata: boolean;
+    /** Emit each page's `contentBounds` (union bbox of top-level content objects) (default: false). */
+    extractContentBounds: boolean;
+    /** Detect solid rectangles/lines in rendered page screenshots (default: false). */
+    detectScreenshotRects: boolean;
+    /** Draw AcroForm field appearances into rendered rasters (screenshots and OCR inputs; runs document open/JS actions; default: false). */
+    renderFormFields: boolean;
+    preserveVerySmallText: boolean;
+    password?: string;
+    quiet: boolean;
+    numWorkers: number;
+    /**
+     * Whether a systemic OCR failure (every OCR task failed and at least one was
+     * a text-sparse page) aborts the whole parse (default: true). Set false to
+     * keep already-recovered native text and return partial results instead of
+     * rejecting — for callers that prefer a degraded document over a hard failure.
+     */
+    ocrFailureFatal: boolean;
+    /**
+     * OCR request-hedging schedule (ms). Empty (default) = no hedging. Multiple
+     * delays (e.g. `[0, 5000, 10000, 15000, 20000]`) fire duplicate requests per
+     * OCR attempt and take the first success — lower tail latency on a slow/stuck
+     * OCR pod, at the cost of extra OCR-server load. HTTP OCR engine only.
+     */
+    ocrHedgeDelaysMs: number[];
+    /**
+     * Emit per-word sub-boxes on each text item ({@link TextItem.words}).
+     * Default false. Word boxes roughly double the text-item payload (size + napi
+     * marshalling), so enable only when doing word-level bbox attribution.
+     */
+    emitWordBoxes: boolean;
+    /** Include rich PDF text metadata on returned text items. Default false. */
+    extractTextMetadata?: boolean;
+    /**
+     * Restrict output to a page sub-region. Each field is the fraction of the
+     * page cropped away from that side (top-left origin), so `{ left: 0.5 }`
+     * discards the left half. A text item survives only when it lies entirely
+     * inside the remaining rectangle. Undefined (default) keeps the whole page.
+     * Applied after OCR merge, so OCR text outside the region is dropped too.
+     */
+    cropBox?: CropBox;
+    /**
+     * Drop diagonal text — items whose rotation is more than 2° off the nearest
+     * right angle (0/90/180/270). Default false. Use to exclude rotated
+     * watermarks/stamps from the output.
+     */
+    skipDiagonalText: boolean;
+    /**
+     * Compute per-page complexity signals during {@link LiteParse.parse} and
+     * attach them to each page as {@link ParsedPage.complexity} (the same signals
+     * {@link LiteParse.isComplex} returns). Default false; enabling it runs an
+     * extra vector-text detection pass.
+     */
+    includeComplexity: boolean;
+    /** Expose page-scoped vector shapes and merged H/V line segments. Default false. */
+    extractVectorGraphics: boolean;
+}
+/**
+ * A page sub-region expressed as the fraction cropped from each side
+ * (top-left origin, each value in `[0, 1]`).
+ */
+interface CropBox {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * One word's bounding box within a {@link TextItem}, in the same viewport space
+ * (top-left origin, 72 DPI). `text` excludes inter-word spaces.
+ */
+interface WordBox {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface TextItem {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    fontName?: string;
+    fontSize?: number;
+    /** Font size after applying the text matrix's vertical scale. */
+    fontHeight?: number;
+    fontAscent?: number;
+    fontDescent?: number;
+    fontWeight?: number;
+    /** Sum of source glyph widths in points. */
+    textWidth?: number;
+    fontIsBuggy?: boolean;
+    /** Marked-content ID from the PDF structure tree. */
+    mcid?: number;
+    /** Fill color as an eight-character ARGB hex string. */
+    fillColor?: string;
+    /** Stroke color as an eight-character ARGB hex string. */
+    strokeColor?: string;
+    /** Raw PDF content-stream character codes for the source glyphs. */
+    charCodes?: number[];
+    /** True when the trailing source space was synthesized by PDFium. */
+    trailingSpaceGenerated?: boolean;
+    /** OCR confidence score (0.0-1.0). Undefined for native PDF text. */
+    confidence?: number;
+    /** Rotation in degrees (viewport space). Defaults to 0 when omitted. */
+    rotation?: number;
+    /**
+     * Per-word sub-boxes within this item. A text item groups several words
+     * together (breaking only at line/column boundaries), so this carries the
+     * finer word-level geometry for bbox attribution. Empty/undefined for items
+     * with no word split (e.g. OCR-sourced or single-token items).
+     */
+    words?: WordBox[];
+}
+/**
+ * A vector-graphic primitive supplied to {@link LiteParse.parsePages}. `kind`
+ * selects the variant: `"stroke"` (uses `x1/y1/x2/y2`) or `"rect"` (uses
+ * `x/y/width/height`, top-left origin). Coordinates are viewport space (72 DPI),
+ * matching the text items. `hasFill`/`hasStroke` carry the paint intent even
+ * when the color is unknown, so ruled-table edge detection still treats a
+ * colorless stroked rect as stroked.
+ */
+interface Graphic {
+    kind: "stroke" | "rect";
+    x1?: number;
+    y1?: number;
+    x2?: number;
+    y2?: number;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    hasFill?: boolean;
+    hasStroke?: boolean;
+    fillColor?: string;
+    strokeColor?: string;
+    lineWidth?: number;
+}
+/**
+ * A page of pre-extracted text supplied to {@link LiteParse.parsePages}.
+ * Coordinates are viewport space (top-left origin, 72 DPI). `graphics` is
+ * optional; when supplied it enables ruled-table and horizontal-rule detection.
+ */
+interface PageInput {
+    pageNumber: number;
+    pageWidth: number;
+    pageHeight: number;
+    textItems: TextItem[];
+    graphics?: Graphic[];
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ParsedPage {
+    pageNum: number;
+    width: number;
+    height: number;
+    /**
+     * Union bbox of the page's top-level content objects in viewport coords
+     * (visible content extent). Absent for empty pages.
+     */
+    /** Present only when `extractContentBounds` is enabled. */
+    contentBounds?: Rect;
+    text: string;
+    markdown: string;
+    textItems: TextItem[];
+    /**
+     * Per-page complexity signals (the same {@link LiteParse.isComplex} returns).
+     * Present only when parsing with `includeComplexity: true`; `undefined`
+     * otherwise.
+     */
+    complexity?: PageComplexityStats;
+    /** Present only when parsing with `extractVectorGraphics: true`. */
+    vectorGraphics?: VectorGraphics;
+    /** Present only when `extractAnnotations` is enabled. */
+    annotations?: DocumentAnnotation[];
+    /** Present only when `extractFormFields` is enabled. */
+    formFields?: FormField[];
+    /** Present only when `extractStructureTree` is enabled. */
+    structureTree?: StructureTree;
+    /**
+     * Classified layout blocks in reading order — the same blocks, in the same
+     * order, the page's Markdown is built from. Present only when
+     * `extractBlocks` is enabled.
+     */
+    blocks?: LayoutBlock[];
+}
+/** One table cell: its text and the region of the page it was read from. */
+interface LayoutCell {
+    text: string;
+    /**
+     * Absent for cells with no ink behind them — padding inserted to square off
+     * a ragged grid, or halves of a merged run split at an estimated position.
+     */
+    bbox?: Rect;
+}
+/** A classified block of page content, discriminated by `kind`. */
+interface LayoutBlock {
+    kind: "heading" | "paragraph" | "list_item" | "code" | "table" | "grid_fallback" | "rule" | "figure";
+    /** Rendered text for `heading`, `paragraph`, and `list_item`. */
+    text?: string;
+    /** Heading level (1-6), or list nesting depth for `list_item`. */
+    level?: number;
+    bold?: boolean;
+    italic?: boolean;
+    /** `list_item` only. `marker` is the marker as it appeared on the page. */
+    ordered?: boolean;
+    marker?: string;
+    /** Verbatim source lines for `code` and `grid_fallback`. */
+    lines?: string[];
+    /** Best-effort language hint for `code`. */
+    lang?: string;
+    /** `table` only. */
+    header?: LayoutCell[];
+    rows?: LayoutCell[][];
+    /** `figure` only, matching the `img_{id}.{format}` Markdown target. */
+    id?: string;
+    format?: string;
+    /**
+     * Region this block occupies, in the same top-left 72-DPI viewport space as
+     * `textItems`. The union of every source line that fed the block.
+     */
+    bbox?: Rect;
+}
+type StructureAttributeValue = boolean | number | string;
+interface StructureTree {
+    roots: StructureTreeElement[];
+}
+interface StructureTreeElement {
+    type: string;
+    id?: string;
+    actualText?: string;
+    altText?: string;
+    title?: string;
+    attributes: Record<string, StructureAttributeValue>;
+    markedContentIds: number[];
+    children: StructureTreeElement[];
+    annotations: DocumentAnnotation[];
+}
+interface VectorGraphics {
+    shapes: VectorShape[];
+    lines: VectorLine[];
+}
+interface VectorShape {
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    stroke: boolean;
+    strokeColor?: string;
+    fill: boolean;
+    fillColor?: string;
+    hasCurve: boolean;
+}
+interface VectorLine {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stroke: boolean;
+    strokeWidth?: number;
+    strokeColor?: string;
+    fill: boolean;
+    fillColor?: string;
+}
+interface AnnotationRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface DocumentAnnotation {
+    subtype: string;
+    contents?: string;
+    created?: string;
+    modified?: string;
+    title?: string;
+    rect?: AnnotationRect;
+    quadpointRects: AnnotationRect[];
+    uri?: string;
+}
+interface FormField {
+    id: string;
+    type: string;
+    page: number;
+    annotationIndex: number;
+    widgetIndex: number;
+    objectNumber?: number;
+    name?: string;
+    alternateName?: string;
+    value?: string;
+    exportValue?: string;
+    fieldFlags: number;
+    controlCount?: number;
+    controlIndex?: number;
+    checked?: boolean;
+    rect?: AnnotationRect;
+    options: string[];
+    selectedOptions: string[];
+}
+interface ExtractedImage {
+    /** Reference id used in the markdown output (e.g. `![](img_p1_1.png)` → `"p1_1"`). */
+    id: string;
+    /** File name used when `imageOutputDir` is configured. */
+    name: string;
+    /** Written file path, absent for in-memory-only extraction. */
+    path?: string;
+    page: number;
+    /** Placement on the page in viewport coordinates (top-left origin, 72 DPI). */
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Intrinsic pixel dimensions of the image resource. */
+    width: number;
+    height: number;
+    /** Clockwise page-object rotation in degrees. */
+    rotation: number;
+    format: string;
+    /** First occurrence with identical encoded source data, when duplicated. */
+    duplicateOf?: string;
+    bytes: Buffer;
+}
+interface ParseResult {
+    /** Total source-document pages before `targetPages` or `maxPages` filtering. */
+    totalPages: number;
+    pages: ParsedPage[];
+    /** Page-level PDFium extraction failures when tolerance is enabled. */
+    pageErrors: Array<{
+        pageNum: number;
+        message: string;
+    }>;
+    text: string;
+    /** Populated only when `extractImages` is true. */
+    images: ExtractedImage[];
+    /** PNG screenshots of parsed pages when `extractScreenshots` is enabled. */
+    screenshots: ScreenshotResult[];
+    /** Embedded image objects that PDFium could not render or encode. */
+    imageErrorCount: number;
+    /** PDFium form type, present only when `extractFormFields` is enabled. */
+    formType?: number;
+    /** The document's `/Info` `Creator` entry, when present. */
+    creator?: string;
+    /** The document's `/Info` `Producer` entry, when present. */
+    producer?: string;
+    /**
+     * Document-level provenance metadata from PDFium and the source PDF.
+     * Present only when `extractDocumentMetadata` is enabled and the input was
+     * a real PDF (not converted from DOCX/XLSX/an image).
+     */
+    docMeta?: DocumentMetadata;
+    /** Raw XFA packets; present only when `extractXfaPackets` is enabled. */
+    xfaPackets?: XfaPacket[];
+}
+interface ParseBatchOptions {
+    /** Pages materialized in one batch. Default: 25. */
+    batchSize?: number;
+}
+interface ParseBatch {
+    /** First source page in this batch (1-indexed). */
+    startPage: number;
+    /** Last source page in this batch (1-indexed, inclusive). */
+    endPage: number;
+    /** Total source-document pages, before the parser's `maxPages` cap. */
+    totalPages: number;
+    result: ParseResult;
+}
+/** Provenance and tamper-analysis facts extracted from the source PDF. */
+interface DocumentMetadata {
+    creationDate?: string;
+    modDate?: string;
+    /** Encoded PDF version (`14` means PDF 1.4). */
+    fileVersion?: number;
+    isEncrypted?: boolean;
+    securityHandlerRevision?: number;
+    permissions?: number;
+    eofSectionCount?: number;
+    startxrefCount?: number;
+    trailerIdPairDiffers?: boolean;
+    rawFileSize?: number;
+    /**
+     * The document catalog's `/Metadata` XMP packet, capped at 64 KiB. Absent
+     * when the document has none, when it is too large to resolve cheaply, or
+     * in WASM builds.
+     */
+    xmp?: string;
+    /** True when the catalog's XMP stream exceeded the 64 KiB cap. */
+    xmpTruncated?: boolean;
+    signatureCount?: number;
+    /** False when bytes were appended after a readable signature byte range. */
+    signatureByteRangeReachesEof?: boolean;
+}
+/** One raw packet from an XFA form document's `/XFA` array. */
+interface XfaPacket {
+    index: number;
+    name?: string;
+    contentLength: number;
+    /** Packet content (usually XML), lossily decoded as UTF-8. */
+    content?: string;
+}
+interface ScreenshotResult {
+    pageNum: number;
+    width: number;
+    height: number;
+    imageBuffer: Buffer;
+    /** True when every pixel has the same color (blank page after render). */
+    isSolidFill: boolean;
+    /** Solid rectangles/lines detected in the raster (viewport coords). Populated only with `detectScreenshotRects`. */
+    rects: ScreenshotRect[];
+}
+/** One solid rectangle (or line) detected in a rendered page bitmap. */
+interface ScreenshotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Fill color as ARGB hex string (e.g. "ff1a2b3c"). */
+    color: string;
+    /** True when the region is a solid line rather than a filled area. */
+    isLine: boolean;
+}
+/**
+ * Per-page complexity signals from {@link LiteParse.isComplex}, used to decide
+ * whether a document needs OCR or other advanced parsing.
+ */
+interface PageComplexityStats {
+    pageNumber: number;
+    textLength: number;
+    /** Fraction of the page area covered by native text (0–1). */
+    textCoverage: number;
+    hasSubstantialImages: boolean;
+    /**
+     * Number of counted raster images — inline figures only; full-page
+     * backgrounds are excluded (see {@link fullPageImage}).
+     */
+    imageBlockCount: number;
+    /**
+     * Summed image-bbox area over page area, clamped to 1. Counts inline figures
+     * only: a full-page scan raster contributes 0 here — check
+     * {@link fullPageImage} for that.
+     */
+    imageCoverage: number;
+    /**
+     * Largest single *counted* image's area over page area, clamped to 1. Same
+     * exclusion as {@link imageCoverage}: a full-page raster contributes 0.
+     */
+    largestImageCoverage: number;
+    /**
+     * A single raster covers ≥90% of the page. Full-page backgrounds are excluded
+     * from the image coverage fields, so this is the only signal that tells a scan
+     * apart from a blank page — both otherwise report no text and no images.
+     */
+    fullPageImage: boolean;
+    /**
+     * Filled vector-outline area not covered by native text, in pt². `undefined`
+     * when a cheaper signal already decided the page, so this walk was skipped.
+     */
+    uncoveredVectorArea?: number;
+    isGarbled: boolean;
+    pageArea: number;
+    /** Verdict: whether this page needs more than the cheap text-only path. */
+    needsOcr: boolean;
+    /**
+     * Every reason the page was flagged (e.g. `"scanned"`, `"sparse-text"`,
+     * `"garbled"`). Empty exactly when `needsOcr` is false. This is the value to
+     * route on; new reasons may be added over time.
+     */
+    reasons: string[];
+    /**
+     * Layout-difficulty signals (columns, tables, dense graphics). Orthogonal to
+     * `needsOcr`: none of these imply OCR — they signal that the text-only path
+     * may mangle reading order or structure. Present in `isComplex()` results
+     * and `includeComplexity` parses.
+     */
+    layout?: LayoutComplexityStats;
+}
+/**
+ * Layout-difficulty signals for one page, computed from the real
+ * grid-projection pass.
+ */
+interface LayoutComplexityStats {
+    /** Side-by-side text columns found by the layout pass (1 = single column). */
+    columnCount: number;
+    /** Ruled-table grids detected on the page. */
+    ruledTableCount: number;
+    /** Combined ruled-table area over page area, clamped to 1. */
+    ruledTableCoverage: number;
+    /**
+     * Borderless table runs found by track-aligned text detection (description
+     * lists excluded). Ruled tables can appear here too — don't sum with
+     * `ruledTableCount`; the two discriminate ruled from borderless.
+     */
+    textTableRunCount: number;
+    /** Figure regions clustered from vector graphics. */
+    figureCount: number;
+    /** Combined figure area over page area, clamped to 1. */
+    figureCoverage: number;
+    /** Verdict: whether any layout reason fired. */
+    isComplex: boolean;
+    /**
+     * Every layout reason (e.g. `"multi-column"`, `"table-likely"`,
+     * `"dense-graphics"`). Empty exactly when `isComplex` is false; new reasons
+     * may be added over time.
+     */
+    reasons: string[];
+}
+declare class LiteParse {
+    private _native;
+    private _config;
+    private _pool;
+    constructor(userConfig?: Partial<LiteParseConfig> & PoolOptions);
+    parse(input: LiteParseInput): Promise<ParseResult>;
+    /**
+     * Resolves once every pool worker is initialized. No-op without `poolSize`.
+     *
+     * Optional: the first parse on each worker waits for its init anyway. Call
+     * this before latency-sensitive traffic to avoid paying worker startup on
+     * the first request.
+     */
+    warmUp(): Promise<void>;
+    /**
+     * Shut down pool workers, if pool mode is enabled. Idempotent.
+     *
+     * Without `poolSize` this is a no-op. An idle pool never keeps the event
+     * loop alive and workers exit when the parent does, so forgetting to call
+     * this leaks nothing past process exit.
+     */
+    close(): void;
+    /**
+     * Parse a document in bounded-memory page batches of `batchSize` pages.
+     *
+     * Each yielded result is independent and becomes collectible once the caller
+     * advances the iterator, so a consumer that does not retain batches never
+     * holds more than one batch of pages in memory. A non-PDF source is
+     * converted once when the iterator starts, not once per batch; its temporary
+     * file is released when iteration ends — including an early `break` or
+     * `throw`, which run the generator's cleanup.
+     *
+     * Cross-page passes see only the pages in their own batch, so repeated
+     * header/footer removal and image deduplication are batch-local and the
+     * output can differ from `parse()`. Prefer `parse()` unless the size of the
+     * materialized result is the problem.
+     *
+     * As with any async generator, work starts on the first `next()` call, so
+     * errors (an unreadable file, or a parser configured with `targetPages` —
+     * ambiguous with generated batch ranges) surface on the first iteration
+     * rather than when `parseBatches()` itself is called.
+     */
+    parseBatches(input: LiteParseInput, options?: ParseBatchOptions): AsyncGenerator<ParseBatch>;
+    /**
+     * Parse from pre-extracted pages, skipping PDFium text extraction. Runs only
+     * grid projection + the configured output formatter, so the caller's own
+     * text-extraction / font-recovery owns the text content. Synchronous: no
+     * PDFium load and no OCR on this path.
+     */
+    parsePages(pages: PageInput[]): ParseResult;
+    /**
+     * Determine per-page complexity without running a full parse. Returns one
+     * entry per page with signals and a `needsOcr` verdict — a cheap pre-OCR
+     * check to decide whether a document needs advanced parsing.
+     */
+    isComplex(input: LiteParseInput): Promise<PageComplexityStats[]>;
+    screenshot(input: LiteParseInput, pageNumbers?: number[]): Promise<ScreenshotResult[]>;
+    getConfig(): LiteParseConfig;
+}
+/** @internal Exported for pool-worker.ts only; not public API. */
+declare function toParseResult(result: NativeParseResult): ParseResult;
+interface SearchItemsOptions {
+    phrase: string;
+    caseSensitive?: boolean;
+}
+declare function searchItems(items: TextItem[], options: SearchItemsOptions): TextItem[];
+
+export { type AnnotationRect, type CropBox, type DocumentAnnotation, type DocumentMetadata, type ExtractedImage, type FormField, type Graphic, type ImageMode, type LayoutBlock, type LayoutCell, type LayoutComplexityStats, LiteParse, type LiteParseConfig, type LiteParseInput, type OutputFormat, type PageComplexityStats, type PageInput, type ParseBatch, type ParseBatchOptions, type ParseResult, ParseTimeoutError, type ParsedPage, type PoolOptions, type Rect, type ScreenshotRect, type ScreenshotResult, type SearchItemsOptions, type StructureAttributeValue, type StructureTree, type StructureTreeElement, type TextItem, type VectorGraphics, type VectorLine, type VectorShape, type WordBox, type XfaPacket, LiteParse as default, searchItems, toParseResult };