@llamaindex/liteparse 2.13.1 → 2.14.0

package/dist/cli.js

@@ -1,430 +1,1268 @@
 #!/usr/bin/env node
+
+// src/cli.ts
 import { program } from "commander";
-import { LiteParse } from "./lib.js";
-import { parseResultToCliJson } from "./cli-json.js";
-import { readFileSync, writeFileSync, mkdirSync, readdirSync } from "node:fs";
-import { join, relative, parse as parsePath } from "node:path";
-program
-    .name("liteparse")
-    .description("Fast, lightweight PDF and document parsing")
-    .version("2.0.0");
-/**
- * Resolve a CLI `<file>` argument into a parser input. `-` means read the
- * document from stdin (e.g. `curl -sL … | liteparse parse -`); anything else is
- * passed through as a path. Streaming stdin (rather than `readFileSync(0)`)
- * avoids EAGAIN on non-blocking pipes.
- */
-async function resolveInput(file) {
-    if (file !== "-")
-        return file;
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(chunk);
+
+// src/native.ts
+import { createRequire } from "module";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var require2 = createRequire(import.meta.url);
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function loadNative() {
+  const triples = {
+    "darwin-x64": "@llamaindex/liteparse-darwin-x64",
+    "darwin-arm64": "@llamaindex/liteparse-darwin-arm64",
+    "linux-x64-gnu": "@llamaindex/liteparse-linux-x64-gnu",
+    "linux-x64-musl": "@llamaindex/liteparse-linux-x64-musl",
+    "linux-arm64-gnu": "@llamaindex/liteparse-linux-arm64-gnu",
+    "linux-arm64-musl": "@llamaindex/liteparse-linux-arm64-musl",
+    "win32-x64-msvc": "@llamaindex/liteparse-win32-x64-msvc",
+    "win32-arm64-msvc": "@llamaindex/liteparse-win32-arm64-msvc"
+  };
+  const platform = process.platform;
+  const arch = process.arch;
+  const candidates = [];
+  if (platform === "linux") {
+    candidates.push(`${platform}-${arch}-gnu`);
+    candidates.push(`${platform}-${arch}-musl`);
+  } else if (platform === "win32") {
+    candidates.push(`${platform}-${arch}-msvc`);
+  } else {
+    candidates.push(`${platform}-${arch}`);
+  }
+  for (const key of candidates) {
+    const pkg = triples[key];
+    if (pkg) {
+      try {
+        return require2(pkg);
+      } catch {
+      }
     }
-    const bytes = Buffer.concat(chunks);
-    if (bytes.length === 0) {
-        throw new Error("no data on stdin (input `-` expects a document piped in, e.g. `curl … | liteparse parse -`)");
+  }
+  const searchDirs = [__dirname, join(__dirname, ".."), join(__dirname, "..", "..")];
+  const fileNames = [
+    ...candidates.map((c) => `liteparse.${c}.node`),
+    `liteparse.${platform}-${arch}.node`,
+    "liteparse.node"
+  ];
+  for (const dir of searchDirs) {
+    for (const fileName of fileNames) {
+      try {
+        return require2(join(dir, fileName));
+      } catch {
+      }
     }
-    return bytes;
+  }
+  throw new Error(
+    `Failed to load native module for ${platform}-${arch}. Ensure the correct optional dependency is installed.`
+  );
 }
-/** Collect repeated `--ocr-server-header "Name: Value"` flags into an object. */
-function collectHeader(value, previous = {}) {
-    const idx = value.indexOf(":");
-    if (idx === -1) {
-        throw new Error(`invalid header '${value}', expected 'Name: Value'`);
+var native = loadNative();
+
+// src/pool.ts
+import { fork } from "child_process";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var ParseTimeoutError = class extends Error {
+  source;
+  timeoutMs;
+  constructor(message, source, timeoutMs) {
+    super(message);
+    this.name = "ParseTimeoutError";
+    this.source = source;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var WorkerTimeout = class extends Error {
+};
+var WorkerCrashed = class extends Error {
+};
+var WORKER_PATH = fileURLToPath2(new URL("./pool-worker.js", import.meta.url));
+function reviveBuffers(result) {
+  for (const image of result.images ?? []) {
+    if (image.bytes && !Buffer.isBuffer(image.bytes)) {
+      const b = image.bytes;
+      image.bytes = Buffer.from(b.buffer, b.byteOffset, b.byteLength);
     }
-    const name = value.slice(0, idx).trim();
-    if (name === "") {
-        throw new Error(`invalid header '${value}', empty header name`);
+  }
+  for (const shot of result.screenshots ?? []) {
+    if (shot.imageBuffer && !Buffer.isBuffer(shot.imageBuffer)) {
+      const b = shot.imageBuffer;
+      shot.imageBuffer = Buffer.from(b.buffer, b.byteOffset, b.byteLength);
     }
-    previous[name] = value.slice(idx + 1).trim();
-    return previous;
+  }
+  return result;
 }
-program
-    .command("parse")
-    .description("Parse a document and extract text")
-    .argument("<file>", "Path to the document file")
-    .option("-o, --output <file>", "Output file path")
-    .option("--format <format>", 'Output format: json|text|markdown (default: "text")')
-    .option("--image-mode <mode>", "How to surface raster images in markdown: off|placeholder|embed (default: placeholder)")
-    .option("--image-output-dir <dir>", "Directory to write embedded images to when --image-mode embed is set")
-    .option("--extract-images", "Extract embedded image bytes and metadata")
-    .option("--no-links", "Disable hyperlink extraction (emit plain anchor text)")
-    .option("--keep-headers-footers", "Keep running headers/footers in markdown output instead of stripping them")
-    .option("--extract-annotations", "Include all PDF annotations in page output")
-    .option("--extract-form-fields", "Include AcroForm widget fields and values")
-    .option("--extract-structure-tree", "Include the tagged-PDF logical structure tree")
-    .option("--extract-blocks", "Include each page's classified layout blocks with bounding boxes")
-    .option("--extract-xfa-packets", "Include raw XFA packets (name + XML content) in JSON output")
-    .option("--extract-content-bounds", "Include each page's content_bounds in JSON output")
-    .option("--ocr-server-url <url>", "HTTP OCR server URL")
-    .option("--ocr-server-header <header>", 'Extra header for OCR server requests, "Name: Value" (repeatable)', collectHeader)
-    .option("--no-ocr", "Disable OCR")
-    .option("--ocr-language <lang>", "OCR language (default: eng)")
-    .option("--max-pages <n>", "Max pages to parse", parseInt)
-    .option("--target-pages <pages>", 'Pages to parse (e.g., "1-5,10,15-20")')
-    .option("--continue-on-page-error", "Continue after page-level extraction errors and report them in JSON")
-    .option("--dpi <dpi>", "Rendering DPI", parseFloat)
-    .option("--preserve-small-text", "Keep very small text")
-    .option("--extract-text-metadata", "Include rich PDF text metadata in text items and JSON output")
-    .option("--password <password>", "Password for encrypted documents")
-    .option("--config <file>", "JSON config file path")
-    .option("-q, --quiet", "Suppress progress output")
-    .option("--num-workers <n>", "Number of concurrent OCR workers", parseInt)
-    .option("--complexity", "Include per-page complexity signals in JSON output")
-    .option("--extract-vector-graphics", "Include page-scoped vector shapes and merged horizontal/vertical lines")
-    .action(async (file, opts) => {
+var WorkerHandle = class {
+  child;
+  readyPromise;
+  pending = null;
+  dead = false;
+  constructor(config) {
+    this.child = fork(WORKER_PATH, [], {
+      serialization: "advanced",
+      // stdout/stderr inherited: parse logs and crash traces stay visible.
+      stdio: ["ignore", "inherit", "inherit", "ipc"]
+    });
+    let readyResolve;
+    let readyReject;
+    this.readyPromise = new Promise((resolve, reject) => {
+      readyResolve = resolve;
+      readyReject = reject;
+    });
+    this.readyPromise.catch(() => {
+    });
+    this.child.on("message", (msg) => {
+      if (msg.type === "ready") {
+        readyResolve();
+        if (this.pending === null) this.idle();
+      } else if (msg.type === "initError") {
+        readyReject(new Error(msg.message));
+      } else if (this.pending) {
+        const { resolve, reject } = this.pending;
+        this.pending = null;
+        this.idle();
+        if (msg.type === "ok") resolve(reviveBuffers(msg.result));
+        else reject(new WorkerCrashed(msg.message));
+      }
+    });
+    const onGone = (cause) => {
+      this.dead = true;
+      readyReject(new WorkerCrashed(cause));
+      if (this.pending) {
+        const { reject } = this.pending;
+        this.pending = null;
+        reject(new WorkerCrashed(cause));
+      }
+    };
+    this.child.on("error", (e) => onGone(e.message));
+    this.child.on(
+      "exit",
+      (code, signal) => onGone(`worker exited (code=${code}, signal=${signal})`)
+    );
+    this.child.send({ type: "init", config });
+  }
+  /** Resolves when the worker's native parser is constructed. Init time
+   * never counts toward the parse deadline — the deadline is a promise about
+   * parsing, not about process startup. */
+  ready() {
+    return this.readyPromise;
+  }
+  /** An idle pool must not hold the parent's event loop open. */
+  idle() {
+    this.child.unref();
+    this.child.channel?.unref();
+  }
+  request(payload, timeoutMs) {
+    if (this.dead) {
+      return Promise.reject(new WorkerCrashed("worker already exited"));
+    }
+    this.child.ref();
+    this.child.channel?.ref();
+    return new Promise((resolve, reject) => {
+      let timer;
+      const settle = (fn) => (value) => {
+        if (timer !== void 0) clearTimeout(timer);
+        fn(value);
+      };
+      this.pending = {
+        resolve: settle(resolve),
+        reject: settle(reject)
+      };
+      if (timeoutMs !== void 0) {
+        timer = setTimeout(() => {
+          if (this.pending) {
+            const { reject: rejectPending } = this.pending;
+            this.pending = null;
+            rejectPending(new WorkerTimeout());
+          }
+        }, timeoutMs);
+      }
+      this.child.send({ type: "parse", payload });
+    });
+  }
+  kill() {
+    this.dead = true;
+    this.child.kill("SIGKILL");
+  }
+  /** Graceful shutdown; escalates to SIGKILL if the worker doesn't exit. */
+  stop() {
+    if (this.dead) return;
+    this.dead = true;
     try {
-        const config = {};
-        // Load config file if provided
-        if (opts.config) {
-            const fileConfig = JSON.parse(readFileSync(opts.config, "utf-8"));
-            Object.assign(config, fileConfig);
-        }
-        // CLI options override config file
-        if (opts.format)
-            config.outputFormat = opts.format;
-        if (opts.imageMode)
-            config.imageMode = opts.imageMode;
-        if (opts.imageOutputDir)
-            config.imageOutputDir = opts.imageOutputDir;
-        if (opts.extractImages)
-            config.extractImages = true;
-        if (opts.links === false)
-            config.extractLinks = false;
-        if (opts.keepHeadersFooters)
-            config.keepHeadersFooters = true;
-        if (opts.extractAnnotations)
-            config.extractAnnotations = true;
-        if (opts.extractFormFields)
-            config.extractFormFields = true;
-        if (opts.extractStructureTree)
-            config.extractStructureTree = true;
-        if (opts.extractBlocks)
-            config.extractBlocks = true;
-        if (opts.extractXfaPackets)
-            config.extractXfaPackets = true;
-        if (opts.extractContentBounds)
-            config.extractContentBounds = true;
-        if (opts.ocrServerUrl)
-            config.ocrServerUrl = opts.ocrServerUrl;
-        if (opts.ocrServerHeader)
-            config.ocrServerHeaders = opts.ocrServerHeader;
-        if (opts.ocr === false)
-            config.ocrEnabled = false;
-        if (opts.ocrLanguage)
-            config.ocrLanguage = opts.ocrLanguage;
-        if (opts.maxPages)
-            config.maxPages = opts.maxPages;
-        if (opts.targetPages)
-            config.targetPages = opts.targetPages;
-        if (opts.continueOnPageError)
-            config.continueOnPageError = true;
-        if (opts.dpi)
-            config.dpi = opts.dpi;
-        if (opts.preserveSmallText)
-            config.preserveVerySmallText = true;
-        if (opts.extractTextMetadata)
-            config.extractTextMetadata = true;
-        if (opts.password)
-            config.password = opts.password;
-        if (opts.quiet)
-            config.quiet = true;
-        if (opts.numWorkers)
-            config.numWorkers = opts.numWorkers;
-        if (opts.complexity)
-            config.includeComplexity = true;
-        if (opts.extractVectorGraphics)
-            config.extractVectorGraphics = true;
-        // Default CLI output to text (library defaults to json)
-        if (!config.outputFormat)
-            config.outputFormat = "text";
-        const parser = new LiteParse(config);
-        const result = await parser.parse(await resolveInput(file));
-        // JSON output carries pageErrors itself; text/markdown would silently
-        // omit the failed pages, so always surface them on stderr.
-        for (const error of result.pageErrors) {
-            console.error(`[liteparse] page ${error.pageNum} failed to extract and was skipped: ${error.message}`);
-        }
-        const output = config.outputFormat === "json"
-            ? JSON.stringify(parseResultToCliJson(result, {
-                extractTextMetadata: config.extractTextMetadata,
-            }), null, 2)
-            : result.text;
-        if (opts.output) {
-            writeFileSync(opts.output, output, "utf-8");
-        }
-        else {
-            process.stdout.write(output);
-        }
+      this.child.send({ type: "stop" });
+    } catch {
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+    const escalate = setTimeout(() => this.child.kill("SIGKILL"), 5e3);
+    escalate.unref();
+    this.child.once("exit", () => clearTimeout(escalate));
+    this.idle();
+  }
+};
+var WorkerPool = class {
+  config;
+  timeoutMs;
+  workers = /* @__PURE__ */ new Set();
+  idle = [];
+  waiters = [];
+  closed = false;
+  constructor(config, poolSize, parseTimeoutMs) {
+    if (!Number.isInteger(poolSize) || poolSize < 1) {
+      throw new Error("poolSize must be an integer >= 1");
     }
-});
-program
-    .command("is-complex")
-    .description("Check if a document is 'complex' enough to require OCR or other advanced parsing")
-    .argument("<file>", "Path to the document file")
-    .option("--compact", "Emit dense, whitespace-free JSON instead of pretty")
-    .option("--max-pages <n>", "Max pages to parse", parseInt)
-    .option("--target-pages <pages>", 'Pages to check (e.g., "1-5,10,15-20")')
-    .option("--password <password>", "Password for encrypted documents")
-    .option("-q, --quiet", "Suppress progress output")
-    .action(async (file, opts) => {
+    if (parseTimeoutMs !== void 0 && !(parseTimeoutMs > 0)) {
+      throw new Error("parseTimeoutMs must be > 0");
+    }
+    this.config = config;
+    this.timeoutMs = parseTimeoutMs;
+    for (let i = 0; i < poolSize; i++) {
+      this.spawnWorker();
+    }
+  }
+  spawnWorker() {
+    const worker = new WorkerHandle(this.config);
+    this.workers.add(worker);
+    this.release(worker);
+  }
+  acquire() {
+    const worker = this.idle.pop();
+    if (worker !== void 0) return Promise.resolve(worker);
+    return new Promise(
+      (resolve, reject) => this.waiters.push({ resolve, reject })
+    );
+  }
+  release(worker) {
+    if (this.closed) {
+      this.workers.delete(worker);
+      worker.stop();
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter !== void 0) waiter.resolve(worker);
+    else this.idle.push(worker);
+  }
+  retire(worker) {
+    worker.kill();
+    this.workers.delete(worker);
+    if (!this.closed) this.spawnWorker();
+  }
+  /** Run one parse on an idle worker.
+   *
+   * Waits for a free worker first; `parseTimeoutMs` bounds the parse itself,
+   * not the wait. */
+  async parse(payload, source) {
+    if (this.closed) throw new Error("parser pool is closed");
+    const worker = await this.acquire();
     try {
-        const config = {};
-        if (opts.maxPages)
-            config.maxPages = opts.maxPages;
-        if (opts.targetPages)
-            config.targetPages = opts.targetPages;
-        if (opts.password)
-            config.password = opts.password;
-        if (opts.quiet)
-            config.quiet = true;
-        const parser = new LiteParse(config);
-        const stats = await parser.isComplex(await resolveInput(file));
-        const complexPages = stats.filter((s) => s.needsOcr).length;
-        // Always emit JSON on stdout so the command composes with `jq` without a
-        // flag. Pretty by default; `--compact` drops the whitespace. Both parse
-        // identically for any reader.
-        process.stdout.write(opts.compact
-            ? JSON.stringify(stats)
-            : JSON.stringify(stats, null, 2));
-        process.stdout.write("\n");
-        // Human verdict goes to stderr so it never pollutes the JSON on stdout;
-        // the exit code below carries the same signal for scripts.
-        if (!opts.quiet) {
-            const verdict = complexPages > 0 ? "COMPLEX" : "SIMPLE";
-            const layoutCount = (reason) => stats.filter((s) => s.layout?.reasons.includes(reason)).length;
-            console.error(`${verdict} — ${complexPages}/${stats.length} page(s) need OCR; ` +
-                `layout: ${layoutCount("multi-column")} multi-column, ` +
-                `${layoutCount("table-likely")} table, ` +
-                `${layoutCount("dense-graphics")} graphics-dense`);
-        }
-        // Exit non-zero when any page needs OCR, so the command is usable as a
-        // shell predicate (e.g. `is-complex doc.pdf && parse --no-ocr`).
-        if (complexPages > 0)
-            process.exit(1);
+      await worker.ready();
+      const result = await worker.request(payload, this.timeoutMs);
+      this.release(worker);
+      return result;
+    } catch (e) {
+      this.retire(worker);
+      if (e instanceof WorkerTimeout) {
+        throw new ParseTimeoutError(
+          `parse of ${source} exceeded ${this.timeoutMs}ms; the worker process was killed`,
+          source,
+          this.timeoutMs
+        );
+      }
+      if (e instanceof WorkerCrashed) {
+        throw new Error(
+          `liteparse worker process died while parsing ${source}: ${e.message}`
+        );
+      }
+      throw e;
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+  }
+  /** Resolves when every worker is initialized. Optional — the first parse
+   * per worker waits for init anyway. */
+  async warmUp() {
+    await Promise.all([...this.workers].map((w) => w.ready()));
+  }
+  /** Shut down all workers. Idempotent. Busy workers are stopped as their
+   * in-flight parses finish. */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const waiter of this.waiters.splice(0)) {
+      waiter.reject(new Error("parser pool is closed"));
     }
-});
-program
-    .command("screenshot")
-    .description("Generate screenshots of document pages")
-    .argument("<file>", "Path to the document file")
-    .option("-o, --output-dir <dir>", "Output directory for screenshots", "./screenshots")
-    .option("--target-pages <pages>", 'Pages to screenshot (e.g., "1,3,5" or "1-5")')
-    .option("--dpi <dpi>", "Rendering DPI", parseFloat)
-    .option("--password <password>", "Password for encrypted documents")
-    .option("-q, --quiet", "Suppress progress output")
-    .action(async (file, opts) => {
+    for (const worker of this.idle.splice(0)) {
+      this.workers.delete(worker);
+      worker.stop();
+    }
+  }
+};
+
+// src/lib.ts
+var LiteParse = class {
+  _native;
+  _config;
+  _pool = null;
+  constructor(userConfig = {}) {
+    const nativeConfig = {
+      ocrLanguage: userConfig.ocrLanguage,
+      ocrEnabled: userConfig.ocrEnabled,
+      ocrServerUrl: userConfig.ocrServerUrl,
+      ocrServerHeaders: userConfig.ocrServerHeaders,
+      tessdataPath: userConfig.tessdataPath,
+      maxPages: userConfig.maxPages,
+      targetPages: userConfig.targetPages,
+      extractScreenshots: userConfig.extractScreenshots,
+      continueOnPageError: userConfig.continueOnPageError,
+      dpi: userConfig.dpi,
+      outputFormat: userConfig.outputFormat,
+      imageMode: userConfig.imageMode,
+      extractImages: userConfig.extractImages,
+      imageOutputDir: userConfig.imageOutputDir,
+      extractLinks: userConfig.extractLinks,
+      keepHeadersFooters: userConfig.keepHeadersFooters,
+      extractAnnotations: userConfig.extractAnnotations,
+      extractFormFields: userConfig.extractFormFields,
+      extractStructureTree: userConfig.extractStructureTree,
+      extractBlocks: userConfig.extractBlocks,
+      extractXfaPackets: userConfig.extractXfaPackets,
+      extractDocumentMetadata: userConfig.extractDocumentMetadata,
+      extractContentBounds: userConfig.extractContentBounds,
+      detectScreenshotRects: userConfig.detectScreenshotRects,
+      renderFormFields: userConfig.renderFormFields,
+      preserveVerySmallText: userConfig.preserveVerySmallText,
+      password: userConfig.password,
+      quiet: userConfig.quiet,
+      numWorkers: userConfig.numWorkers,
+      ocrFailureFatal: userConfig.ocrFailureFatal,
+      ocrHedgeDelaysMs: userConfig.ocrHedgeDelaysMs,
+      emitWordBoxes: userConfig.emitWordBoxes,
+      extractTextMetadata: userConfig.extractTextMetadata,
+      cropBox: userConfig.cropBox,
+      skipDiagonalText: userConfig.skipDiagonalText,
+      includeComplexity: userConfig.includeComplexity,
+      extractVectorGraphics: userConfig.extractVectorGraphics
+    };
+    this._native = new native.LiteParse(nativeConfig);
+    if (userConfig.parseTimeoutMs !== void 0 && userConfig.poolSize === void 0) {
+      throw new Error(
+        "parseTimeoutMs requires poolSize"
+      );
+    }
+    if (userConfig.poolSize !== void 0) {
+      this._pool = new WorkerPool(
+        nativeConfig,
+        userConfig.poolSize,
+        userConfig.parseTimeoutMs
+      );
+    }
+    const resolved = this._native.config;
+    this._config = {
+      ocrLanguage: resolved.ocrLanguage ?? "eng",
+      ocrEnabled: resolved.ocrEnabled ?? true,
+      ocrServerUrl: resolved.ocrServerUrl ?? void 0,
+      ocrServerHeaders: resolved.ocrServerHeaders ?? void 0,
+      tessdataPath: resolved.tessdataPath ?? void 0,
+      maxPages: resolved.maxPages ?? 1e3,
+      targetPages: resolved.targetPages ?? void 0,
+      extractScreenshots: resolved.extractScreenshots ?? false,
+      continueOnPageError: resolved.continueOnPageError ?? false,
+      dpi: resolved.dpi ?? 150,
+      outputFormat: resolved.outputFormat ?? "json",
+      imageMode: resolved.imageMode ?? "placeholder",
+      extractImages: resolved.extractImages ?? false,
+      imageOutputDir: resolved.imageOutputDir ?? void 0,
+      extractLinks: resolved.extractLinks ?? true,
+      keepHeadersFooters: resolved.keepHeadersFooters ?? false,
+      extractAnnotations: resolved.extractAnnotations ?? false,
+      extractFormFields: resolved.extractFormFields ?? false,
+      extractStructureTree: resolved.extractStructureTree ?? false,
+      extractBlocks: resolved.extractBlocks ?? false,
+      extractXfaPackets: resolved.extractXfaPackets ?? false,
+      extractDocumentMetadata: resolved.extractDocumentMetadata ?? false,
+      extractContentBounds: resolved.extractContentBounds ?? false,
+      detectScreenshotRects: resolved.detectScreenshotRects ?? false,
+      renderFormFields: resolved.renderFormFields ?? false,
+      preserveVerySmallText: resolved.preserveVerySmallText ?? false,
+      password: resolved.password ?? void 0,
+      quiet: resolved.quiet ?? false,
+      numWorkers: resolved.numWorkers ?? 1,
+      ocrFailureFatal: resolved.ocrFailureFatal ?? true,
+      ocrHedgeDelaysMs: resolved.ocrHedgeDelaysMs ?? [],
+      emitWordBoxes: resolved.emitWordBoxes ?? false,
+      extractTextMetadata: resolved.extractTextMetadata ?? false,
+      cropBox: resolved.cropBox ?? void 0,
+      skipDiagonalText: resolved.skipDiagonalText ?? false,
+      includeComplexity: resolved.includeComplexity ?? false,
+      extractVectorGraphics: resolved.extractVectorGraphics ?? false
+    };
+  }
+  async parse(input) {
+    const nativeInput = typeof input === "string" ? input : Buffer.from(input);
+    if (this._pool !== null) {
+      const source = typeof nativeInput === "string" ? nativeInput : `<${nativeInput.byteLength} bytes>`;
+      return this._pool.parse(nativeInput, source);
+    }
+    const result = await this._native.parse(nativeInput);
+    return toParseResult(result);
+  }
+  /**
+   * 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.
+   */
+  async warmUp() {
+    if (this._pool !== null) await this._pool.warmUp();
+  }
+  /**
+   * 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() {
+    if (this._pool !== null) this._pool.close();
+  }
+  /**
+   * 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.
+   */
+  async *parseBatches(input, options = {}) {
+    const nativeInput = typeof input === "string" ? input : Buffer.from(input);
+    const session = await this._native.openBatchSession(
+      nativeInput,
+      options.batchSize
+    );
     try {
-        const config = {};
-        if (opts.dpi)
-            config.dpi = opts.dpi;
-        if (opts.password)
-            config.password = opts.password;
-        if (opts.quiet)
-            config.quiet = true;
-        if (opts.targetPages)
-            config.targetPages = opts.targetPages;
-        const parser = new LiteParse(config);
-        // Parse target pages into number array
-        let pageNumbers;
-        if (opts.targetPages) {
-            pageNumbers = [];
-            for (const part of opts.targetPages.split(",")) {
-                const trimmed = part.trim();
-                if (trimmed.includes("-")) {
-                    const [start, end] = trimmed.split("-").map(Number);
-                    for (let i = start; i <= end; i++)
-                        pageNumbers.push(i);
-                }
-                else {
-                    pageNumbers.push(Number(trimmed));
-                }
-            }
-        }
-        const outputDir = opts.outputDir;
-        mkdirSync(outputDir, { recursive: true });
-        const results = await parser.screenshot(file, pageNumbers);
-        for (const result of results) {
-            const outputPath = join(outputDir, `page_${result.pageNum}.png`);
-            writeFileSync(outputPath, result.imageBuffer);
-            if (!opts.quiet) {
-                console.error(`[liteparse] screenshot page ${result.pageNum} → ${outputPath}`);
-            }
+      const totalPages = session.totalPages;
+      for (; ; ) {
+        const batch = await session.nextBatch();
+        if (batch == null) {
+          return;
         }
+        yield {
+          startPage: batch.startPage,
+          endPage: batch.endPage,
+          totalPages,
+          result: toParseResult(batch.result)
+        };
+      }
+    } finally {
+      await session.close();
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+  }
+  /**
+   * 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) {
+    const nativePages = pages.map((p) => ({
+      pageNumber: p.pageNumber,
+      pageWidth: p.pageWidth,
+      pageHeight: p.pageHeight,
+      textItems: p.textItems,
+      graphics: p.graphics
+    }));
+    const result = this._native.parsePages(nativePages);
+    return toParseResult(result);
+  }
+  /**
+   * 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.
+   */
+  async isComplex(input) {
+    const nativeInput = typeof input === "string" ? input : Buffer.from(input);
+    const stats = await this._native.isComplex(nativeInput);
+    return stats.map(toComplexity);
+  }
+  async screenshot(input, pageNumbers) {
+    const nativeInput = typeof input === "string" ? input : Buffer.from(input);
+    const results = await this._native.screenshot(
+      nativeInput,
+      pageNumbers ?? null
+    );
+    return results.map((r) => ({
+      pageNum: r.pageNum,
+      width: r.width,
+      height: r.height,
+      imageBuffer: r.imageBuffer,
+      isSolidFill: r.isSolidFill,
+      rects: r.rects
+    }));
+  }
+  getConfig() {
+    return { ...this._config };
+  }
+};
+function toComplexity(s) {
+  return {
+    pageNumber: s.pageNumber,
+    textLength: s.textLength,
+    textCoverage: s.textCoverage,
+    hasSubstantialImages: s.hasSubstantialImages,
+    imageBlockCount: s.imageBlockCount,
+    imageCoverage: s.imageCoverage,
+    largestImageCoverage: s.largestImageCoverage,
+    fullPageImage: s.fullPageImage,
+    uncoveredVectorArea: s.uncoveredVectorArea ?? void 0,
+    isGarbled: s.isGarbled,
+    pageArea: s.pageArea,
+    needsOcr: s.needsOcr,
+    reasons: s.reasons,
+    layout: s.layout ? {
+      columnCount: s.layout.columnCount,
+      ruledTableCount: s.layout.ruledTableCount,
+      ruledTableCoverage: s.layout.ruledTableCoverage,
+      textTableRunCount: s.layout.textTableRunCount,
+      figureCount: s.layout.figureCount,
+      figureCoverage: s.layout.figureCoverage,
+      isComplex: s.layout.isComplex,
+      reasons: s.layout.reasons
+    } : void 0
+  };
+}
+function toParseResult(result) {
+  return {
+    totalPages: result.totalPages,
+    pages: result.pages.map(toPage),
+    pageErrors: result.pageErrors ?? [],
+    text: result.text,
+    images: (result.images ?? []).map(toImage),
+    screenshots: (result.screenshots ?? []).map(toScreenshot),
+    imageErrorCount: result.imageErrorCount ?? 0,
+    formType: result.formType,
+    creator: result.creator,
+    producer: result.producer,
+    docMeta: result.docMeta,
+    xfaPackets: result.xfaPackets
+  };
+}
+function toPage(p) {
+  return {
+    pageNum: p.pageNum,
+    width: p.width,
+    height: p.height,
+    contentBounds: p.contentBounds,
+    text: p.text,
+    markdown: p.markdown,
+    textItems: p.textItems.map(toTextItem),
+    complexity: p.complexity ? toComplexity(p.complexity) : void 0,
+    vectorGraphics: p.vectorGraphics ?? void 0,
+    annotations: p.annotations,
+    formFields: p.formFields?.map((field) => ({
+      id: field.id,
+      type: field.fieldType,
+      page: field.page,
+      annotationIndex: field.annotationIndex,
+      widgetIndex: field.widgetIndex,
+      objectNumber: field.objectNumber,
+      name: field.name,
+      alternateName: field.alternateName,
+      value: field.value,
+      exportValue: field.exportValue,
+      fieldFlags: field.fieldFlags,
+      controlCount: field.controlCount,
+      controlIndex: field.controlIndex,
+      checked: field.checked,
+      rect: field.rect,
+      options: field.options,
+      selectedOptions: field.selectedOptions
+    })),
+    structureTree: p.structureTree ? { roots: p.structureTree.roots.map(toStructureTreeElement) } : void 0,
+    blocks: p.blocks
+  };
+}
+function toStructureTreeElement(element) {
+  const attributes = {};
+  for (const attribute of element.attributes) {
+    if (attribute.booleanValue !== void 0) {
+      attributes[attribute.name] = attribute.booleanValue;
+    } else if (attribute.numberValue !== void 0) {
+      attributes[attribute.name] = attribute.numberValue;
+    } else if (attribute.stringValue !== void 0) {
+      attributes[attribute.name] = attribute.stringValue;
     }
-});
-program
-    .command("batch-parse")
-    .description("Parse multiple documents in batch mode")
-    .argument("<input-dir>", "Input directory")
-    .argument("<output-dir>", "Output directory")
-    .option("--format <format>", 'Output format: json|text|markdown (default: "text")')
-    .option("--no-ocr", "Disable OCR")
-    .option("--ocr-language <lang>", "OCR language (default: eng)")
-    .option("--ocr-server-url <url>", "HTTP OCR server URL")
-    .option("--ocr-server-header <header>", 'Extra header for OCR server requests, "Name: Value" (repeatable)', collectHeader)
-    .option("--max-pages <n>", "Max pages to parse per file", parseInt)
-    .option("--dpi <dpi>", "Rendering DPI", parseFloat)
-    .option("--recursive", "Recursively search input directory")
-    .option("--extension <ext>", "Only process files with this extension")
-    .option("--password <password>", "Password for encrypted documents")
-    .option("-q, --quiet", "Suppress progress output")
-    .option("--num-workers <n>", "Number of concurrent OCR workers", parseInt)
-    .option("--extract-text-metadata", "Include rich PDF text metadata in text items and JSON output")
-    .option("--extract-images", "Extract embedded image bytes and metadata")
-    .option("--extract-annotations", "Include all PDF annotations in page output")
-    .option("--extract-form-fields", "Include AcroForm widget fields and values")
-    .option("--extract-structure-tree", "Include the tagged-PDF logical structure tree")
-    .option("--extract-blocks", "Include each page's classified layout blocks with bounding boxes")
-    .option("--extract-xfa-packets", "Include raw XFA packets (name + XML content) in JSON output")
-    .option("--extract-content-bounds", "Include each page's content_bounds in JSON output")
-    .option("--extract-vector-graphics", "Include page-scoped vector shapes and merged horizontal/vertical lines")
-    .action(async (inputDir, outputDir, opts) => {
-    try {
-        const config = {};
-        const format = opts.format ?? "text";
-        config.outputFormat = format;
-        if (opts.ocr === false)
-            config.ocrEnabled = false;
-        if (opts.ocrLanguage)
-            config.ocrLanguage = opts.ocrLanguage;
-        if (opts.ocrServerUrl)
-            config.ocrServerUrl = opts.ocrServerUrl;
-        if (opts.ocrServerHeader)
-            config.ocrServerHeaders = opts.ocrServerHeader;
-        if (opts.maxPages)
-            config.maxPages = opts.maxPages;
-        if (opts.dpi)
-            config.dpi = opts.dpi;
-        if (opts.password)
-            config.password = opts.password;
-        if (opts.quiet)
-            config.quiet = true;
-        if (opts.numWorkers)
-            config.numWorkers = opts.numWorkers;
-        if (opts.extractTextMetadata)
-            config.extractTextMetadata = true;
-        if (opts.extractImages)
-            config.extractImages = true;
-        if (opts.extractAnnotations)
-            config.extractAnnotations = true;
-        if (opts.extractFormFields)
-            config.extractFormFields = true;
-        if (opts.extractStructureTree)
-            config.extractStructureTree = true;
-        if (opts.extractBlocks)
-            config.extractBlocks = true;
-        if (opts.extractXfaPackets)
-            config.extractXfaPackets = true;
-        if (opts.extractContentBounds)
-            config.extractContentBounds = true;
-        if (opts.extractContentBounds)
-            config.extractContentBounds = true;
-        if (opts.extractXfaPackets)
-            config.extractXfaPackets = true;
-        if (opts.extractContentBounds)
-            config.extractContentBounds = true;
-        if (opts.extractVectorGraphics)
-            config.extractVectorGraphics = true;
-        const parser = new LiteParse(config);
-        const outExt = format === "json" ? ".json" : format === "markdown" ? ".md" : ".txt";
-        mkdirSync(outputDir, { recursive: true });
-        const extFilter = opts.extension
-            ? opts.extension.startsWith(".")
-                ? opts.extension.toLowerCase()
-                : `.${opts.extension.toLowerCase()}`
-            : undefined;
-        const files = collectFiles(inputDir, !!opts.recursive, extFilter);
-        if (files.length === 0) {
-            console.error(`[liteparse] no matching files found in ${inputDir}`);
-            return;
+  }
+  return {
+    type: element.elementType,
+    id: element.id,
+    actualText: element.actualText,
+    altText: element.altText,
+    title: element.title,
+    attributes,
+    markedContentIds: element.markedContentIds,
+    children: element.children.map(toStructureTreeElement),
+    annotations: element.annotations
+  };
+}
+function toImage(img) {
+  return {
+    id: img.id,
+    name: img.name,
+    path: img.path,
+    page: img.page,
+    bbox: img.bbox,
+    width: img.width,
+    height: img.height,
+    rotation: img.rotation,
+    format: img.format,
+    duplicateOf: img.duplicateOf,
+    bytes: img.bytes
+  };
+}
+function toScreenshot(result) {
+  return {
+    pageNum: result.pageNum,
+    width: result.width,
+    height: result.height,
+    imageBuffer: result.imageBuffer,
+    isSolidFill: result.isSolidFill,
+    rects: result.rects
+  };
+}
+function toTextItem(item) {
+  return {
+    text: item.text,
+    x: item.x,
+    y: item.y,
+    width: item.width,
+    height: item.height,
+    fontName: item.fontName,
+    fontSize: item.fontSize,
+    fontHeight: item.fontHeight,
+    fontAscent: item.fontAscent,
+    fontDescent: item.fontDescent,
+    fontWeight: item.fontWeight,
+    textWidth: item.textWidth,
+    fontIsBuggy: item.fontIsBuggy,
+    mcid: item.mcid,
+    fillColor: item.fillColor,
+    strokeColor: item.strokeColor,
+    charCodes: item.charCodes,
+    trailingSpaceGenerated: item.trailingSpaceGenerated,
+    confidence: item.confidence,
+    rotation: item.rotation,
+    words: item.words
+  };
+}
+
+// src/cli-json.ts
+function textItemToCliJson(item, extractTextMetadata) {
+  return {
+    text: item.text,
+    x: item.x,
+    y: item.y,
+    width: item.width,
+    height: item.height,
+    ...extractTextMetadata && item.rotation !== void 0 ? { rotation: item.rotation } : {},
+    ...item.fontName !== void 0 ? { font_name: item.fontName } : {},
+    ...item.fontSize !== void 0 ? { font_size: item.fontSize } : {},
+    ...item.fontHeight !== void 0 ? { font_height: item.fontHeight } : {},
+    ...item.fontAscent !== void 0 ? { font_ascent: item.fontAscent } : {},
+    ...item.fontDescent !== void 0 ? { font_descent: item.fontDescent } : {},
+    ...item.fontWeight !== void 0 ? { font_weight: item.fontWeight } : {},
+    ...item.textWidth !== void 0 ? { text_width: item.textWidth } : {},
+    ...item.fontIsBuggy !== void 0 ? { font_is_buggy: item.fontIsBuggy } : {},
+    ...item.mcid !== void 0 ? { mcid: item.mcid } : {},
+    ...item.fillColor !== void 0 ? { fill_color: item.fillColor } : {},
+    ...item.strokeColor !== void 0 ? { stroke_color: item.strokeColor } : {},
+    ...item.charCodes?.length ? { char_codes: item.charCodes } : {},
+    ...item.trailingSpaceGenerated ? { trailing_space_generated: true } : {},
+    // The CLI JSON format reports native text as fully confident, matching the
+    // Rust CLI. The `confidence` field on TextItem itself stays undefined for
+    // native text so it can discriminate OCR-derived items.
+    confidence: item.confidence ?? 1
+  };
+}
+function structureTreeElementToCliJson(element) {
+  return {
+    type: element.type,
+    ...element.id !== void 0 ? { id: element.id } : {},
+    ...element.actualText !== void 0 ? { actual_text: element.actualText } : {},
+    ...element.altText !== void 0 ? { alt_text: element.altText } : {},
+    ...element.title !== void 0 ? { title: element.title } : {},
+    ...Object.keys(element.attributes).length ? { attributes: element.attributes } : {},
+    marked_content_ids: element.markedContentIds,
+    children: element.children.map(structureTreeElementToCliJson),
+    annotations: element.annotations.map(annotationToCliJson)
+  };
+}
+function complexityToCliJson(complexity) {
+  return {
+    page_number: complexity.pageNumber,
+    text_length: complexity.textLength,
+    text_coverage: complexity.textCoverage,
+    has_substantial_images: complexity.hasSubstantialImages,
+    image_block_count: complexity.imageBlockCount,
+    image_coverage: complexity.imageCoverage,
+    largest_image_coverage: complexity.largestImageCoverage,
+    full_page_image: complexity.fullPageImage,
+    ...complexity.uncoveredVectorArea !== void 0 ? { uncovered_vector_area: complexity.uncoveredVectorArea } : {},
+    is_garbled: complexity.isGarbled,
+    page_area: complexity.pageArea,
+    needs_ocr: complexity.needsOcr,
+    reasons: complexity.reasons,
+    ...complexity.layout ? {
+      layout: {
+        column_count: complexity.layout.columnCount,
+        ruled_table_count: complexity.layout.ruledTableCount,
+        ruled_table_coverage: complexity.layout.ruledTableCoverage,
+        text_table_run_count: complexity.layout.textTableRunCount,
+        figure_count: complexity.layout.figureCount,
+        figure_coverage: complexity.layout.figureCoverage,
+        is_complex: complexity.layout.isComplex,
+        reasons: complexity.layout.reasons
+      }
+    } : {}
+  };
+}
+function vectorGraphicsToCliJson(vectorGraphics) {
+  return {
+    shapes: vectorGraphics.shapes.map((shape) => ({
+      bbox: {
+        x: shape.bbox.x,
+        y: shape.bbox.y,
+        width: shape.bbox.width,
+        height: shape.bbox.height
+      },
+      stroke: shape.stroke,
+      ...shape.strokeColor !== void 0 ? { stroke_color: shape.strokeColor } : {},
+      fill: shape.fill,
+      ...shape.fillColor !== void 0 ? { fill_color: shape.fillColor } : {},
+      has_curve: shape.hasCurve
+    })),
+    lines: vectorGraphics.lines.map((line) => ({
+      x1: line.x1,
+      y1: line.y1,
+      x2: line.x2,
+      y2: line.y2,
+      stroke: line.stroke,
+      ...line.strokeWidth !== void 0 ? { stroke_width: line.strokeWidth } : {},
+      ...line.strokeColor !== void 0 ? { stroke_color: line.strokeColor } : {},
+      fill: line.fill,
+      ...line.fillColor !== void 0 ? { fill_color: line.fillColor } : {}
+    }))
+  };
+}
+function annotationToCliJson(annotation) {
+  return {
+    subtype: annotation.subtype,
+    ...annotation.contents !== void 0 ? { contents: annotation.contents } : {},
+    ...annotation.created !== void 0 ? { created: annotation.created } : {},
+    ...annotation.modified !== void 0 ? { modified: annotation.modified } : {},
+    ...annotation.title !== void 0 ? { title: annotation.title } : {},
+    ...annotation.rect !== void 0 ? { rect: annotation.rect } : {},
+    ...annotation.quadpointRects.length ? {
+      quadpoint_rects: annotation.quadpointRects.map((rect) => ({
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height
+      }))
+    } : {},
+    ...annotation.uri !== void 0 ? { uri: annotation.uri } : {}
+  };
+}
+function formFieldToCliJson(field) {
+  return {
+    id: field.id,
+    type: field.type,
+    page: field.page,
+    annotation_index: field.annotationIndex,
+    widget_index: field.widgetIndex,
+    ...field.objectNumber !== void 0 ? { object_number: field.objectNumber } : {},
+    ...field.name !== void 0 ? { name: field.name } : {},
+    ...field.alternateName !== void 0 ? { alternate_name: field.alternateName } : {},
+    ...field.value !== void 0 ? { value: field.value } : {},
+    ...field.exportValue !== void 0 ? { export_value: field.exportValue } : {},
+    field_flags: field.fieldFlags,
+    ...field.controlCount !== void 0 ? { control_count: field.controlCount } : {},
+    ...field.controlIndex !== void 0 ? { control_index: field.controlIndex } : {},
+    ...field.checked !== void 0 ? { checked: field.checked } : {},
+    ...field.rect !== void 0 ? { rect: field.rect } : {},
+    ...field.options.length ? { options: field.options } : {},
+    ...field.selectedOptions.length ? { selected_options: field.selectedOptions } : {}
+  };
+}
+function xfaPacketToCliJson(packet) {
+  return {
+    index: packet.index,
+    ...packet.name !== void 0 ? { name: packet.name } : {},
+    content_length: packet.contentLength,
+    ...packet.content !== void 0 ? { content: packet.content } : {}
+  };
+}
+function imageToCliJson(image) {
+  return {
+    id: image.id,
+    name: image.name,
+    ...image.path !== void 0 ? { path: image.path } : {},
+    page: image.page,
+    bbox: {
+      x: image.bbox.x,
+      y: image.bbox.y,
+      width: image.bbox.width,
+      height: image.bbox.height
+    },
+    width: image.width,
+    height: image.height,
+    rotation: image.rotation,
+    format: image.format,
+    ...image.duplicateOf !== void 0 ? { duplicate_of: image.duplicateOf } : {}
+  };
+}
+function parseResultToCliJson(result, options = {}) {
+  const extractTextMetadata = options.extractTextMetadata ?? false;
+  return {
+    pages: result.pages.map((page) => ({
+      page: page.pageNum,
+      width: page.width,
+      height: page.height,
+      ...page.contentBounds ? {
+        content_bounds: {
+          x: page.contentBounds.x,
+          y: page.contentBounds.y,
+          width: page.contentBounds.width,
+          height: page.contentBounds.height
         }
-        if (!opts.quiet) {
-            console.error(`[liteparse] found ${files.length} files to process`);
+      } : {},
+      text: page.text,
+      text_items: page.textItems.map(
+        (item) => textItemToCliJson(item, extractTextMetadata)
+      ),
+      ...page.complexity ? { complexity: complexityToCliJson(page.complexity) } : {},
+      ...page.vectorGraphics ? { vector_graphics: vectorGraphicsToCliJson(page.vectorGraphics) } : {},
+      ...page.annotations !== void 0 ? { annotations: page.annotations.map(annotationToCliJson) } : {},
+      ...page.formFields !== void 0 ? { form_fields: page.formFields.map(formFieldToCliJson) } : {},
+      ...page.structureTree !== void 0 ? {
+        structure_tree: {
+          roots: page.structureTree.roots.map(structureTreeElementToCliJson)
         }
-        let success = 0;
-        let errors = 0;
-        for (const filePath of files) {
-            const t0 = Date.now();
-            const rel = relative(inputDir, filePath);
-            const parsed = parsePath(rel);
-            const outPath = join(outputDir, parsed.dir, parsed.name + outExt);
-            mkdirSync(join(outputDir, parsed.dir), { recursive: true });
-            try {
-                const result = await parser.parse(filePath);
-                const output = format === "json"
-                    ? JSON.stringify(parseResultToCliJson(result, {
-                        extractTextMetadata: config.extractTextMetadata,
-                    }), null, 2)
-                    : result.text;
-                writeFileSync(outPath, output, "utf-8");
-                success++;
-                if (!opts.quiet) {
-                    const elapsed = Date.now() - t0;
-                    console.error(`[liteparse] ${filePath} → ${outPath} (${elapsed}ms)`);
-                }
-            }
-            catch (err) {
-                console.error(`[liteparse] error parsing ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
-                errors++;
-            }
+      } : {}
+    })),
+    ...result.images.length ? { images: result.images.map(imageToCliJson) } : {},
+    ...result.imageErrorCount ? { image_error_count: result.imageErrorCount } : {},
+    ...result.formType !== void 0 ? { form_type: result.formType } : {},
+    ...result.xfaPackets !== void 0 ? { xfa_packets: result.xfaPackets.map(xfaPacketToCliJson) } : {}
+  };
+}
+
+// src/cli.ts
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import { join as join2, relative, parse as parsePath } from "path";
+program.name("liteparse").description("Fast, lightweight PDF and document parsing").version("2.0.0");
+async function resolveInput(file) {
+  if (file !== "-") return file;
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const bytes = Buffer.concat(chunks);
+  if (bytes.length === 0) {
+    throw new Error(
+      "no data on stdin (input `-` expects a document piped in, e.g. `curl \u2026 | liteparse parse -`)"
+    );
+  }
+  return bytes;
+}
+function collectHeader(value, previous = {}) {
+  const idx = value.indexOf(":");
+  if (idx === -1) {
+    throw new Error(`invalid header '${value}', expected 'Name: Value'`);
+  }
+  const name = value.slice(0, idx).trim();
+  if (name === "") {
+    throw new Error(`invalid header '${value}', empty header name`);
+  }
+  previous[name] = value.slice(idx + 1).trim();
+  return previous;
+}
+program.command("parse").description("Parse a document and extract text").argument("<file>", "Path to the document file").option("-o, --output <file>", "Output file path").option("--format <format>", 'Output format: json|text|markdown (default: "text")').option(
+  "--image-mode <mode>",
+  "How to surface raster images in markdown: off|placeholder|embed (default: placeholder)"
+).option(
+  "--image-output-dir <dir>",
+  "Directory to write embedded images to when --image-mode embed is set"
+).option("--extract-images", "Extract embedded image bytes and metadata").option("--no-links", "Disable hyperlink extraction (emit plain anchor text)").option(
+  "--keep-headers-footers",
+  "Keep running headers/footers in markdown output instead of stripping them"
+).option("--extract-annotations", "Include all PDF annotations in page output").option("--extract-form-fields", "Include AcroForm widget fields and values").option("--extract-structure-tree", "Include the tagged-PDF logical structure tree").option(
+  "--extract-blocks",
+  "Include each page's classified layout blocks with bounding boxes"
+).option(
+  "--extract-xfa-packets",
+  "Include raw XFA packets (name + XML content) in JSON output"
+).option(
+  "--extract-content-bounds",
+  "Include each page's content_bounds in JSON output"
+).option("--ocr-server-url <url>", "HTTP OCR server URL").option(
+  "--ocr-server-header <header>",
+  'Extra header for OCR server requests, "Name: Value" (repeatable)',
+  collectHeader
+).option("--no-ocr", "Disable OCR").option("--ocr-language <lang>", "OCR language (default: eng)").option("--max-pages <n>", "Max pages to parse", parseInt).option(
+  "--target-pages <pages>",
+  'Pages to parse (e.g., "1-5,10,15-20")'
+).option(
+  "--continue-on-page-error",
+  "Continue after page-level extraction errors and report them in JSON"
+).option("--dpi <dpi>", "Rendering DPI", parseFloat).option("--preserve-small-text", "Keep very small text").option(
+  "--extract-text-metadata",
+  "Include rich PDF text metadata in text items and JSON output"
+).option("--password <password>", "Password for encrypted documents").option("--config <file>", "JSON config file path").option("-q, --quiet", "Suppress progress output").option("--num-workers <n>", "Number of concurrent OCR workers", parseInt).option(
+  "--complexity",
+  "Include per-page complexity signals in JSON output"
+).option(
+  "--extract-vector-graphics",
+  "Include page-scoped vector shapes and merged horizontal/vertical lines"
+).action(async (file, opts) => {
+  try {
+    const config = {};
+    if (opts.config) {
+      const fileConfig = JSON.parse(
+        readFileSync(opts.config, "utf-8")
+      );
+      Object.assign(config, fileConfig);
+    }
+    if (opts.format) config.outputFormat = opts.format;
+    if (opts.imageMode)
+      config.imageMode = opts.imageMode;
+    if (opts.imageOutputDir)
+      config.imageOutputDir = opts.imageOutputDir;
+    if (opts.extractImages) config.extractImages = true;
+    if (opts.links === false) config.extractLinks = false;
+    if (opts.keepHeadersFooters) config.keepHeadersFooters = true;
+    if (opts.extractAnnotations) config.extractAnnotations = true;
+    if (opts.extractFormFields) config.extractFormFields = true;
+    if (opts.extractStructureTree) config.extractStructureTree = true;
+    if (opts.extractBlocks) config.extractBlocks = true;
+    if (opts.extractXfaPackets) config.extractXfaPackets = true;
+    if (opts.extractContentBounds) config.extractContentBounds = true;
+    if (opts.ocrServerUrl)
+      config.ocrServerUrl = opts.ocrServerUrl;
+    if (opts.ocrServerHeader)
+      config.ocrServerHeaders = opts.ocrServerHeader;
+    if (opts.ocr === false) config.ocrEnabled = false;
+    if (opts.ocrLanguage) config.ocrLanguage = opts.ocrLanguage;
+    if (opts.maxPages) config.maxPages = opts.maxPages;
+    if (opts.targetPages) config.targetPages = opts.targetPages;
+    if (opts.continueOnPageError) config.continueOnPageError = true;
+    if (opts.dpi) config.dpi = opts.dpi;
+    if (opts.preserveSmallText) config.preserveVerySmallText = true;
+    if (opts.extractTextMetadata) config.extractTextMetadata = true;
+    if (opts.password) config.password = opts.password;
+    if (opts.quiet) config.quiet = true;
+    if (opts.numWorkers) config.numWorkers = opts.numWorkers;
+    if (opts.complexity) config.includeComplexity = true;
+    if (opts.extractVectorGraphics) config.extractVectorGraphics = true;
+    if (!config.outputFormat) config.outputFormat = "text";
+    const parser = new LiteParse(config);
+    const result = await parser.parse(await resolveInput(file));
+    for (const error of result.pageErrors) {
+      console.error(
+        `[liteparse] page ${error.pageNum} failed to extract and was skipped: ${error.message}`
+      );
+    }
+    const output = config.outputFormat === "json" ? JSON.stringify(
+      parseResultToCliJson(result, {
+        extractTextMetadata: config.extractTextMetadata
+      }),
+      null,
+      2
+    ) : result.text;
+    if (opts.output) {
+      writeFileSync(opts.output, output, "utf-8");
+    } else {
+      process.stdout.write(output);
+    }
+  } catch (err) {
+    console.error(
+      `Error: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+});
+program.command("is-complex").description(
+  "Check if a document is 'complex' enough to require OCR or other advanced parsing"
+).argument("<file>", "Path to the document file").option("--compact", "Emit dense, whitespace-free JSON instead of pretty").option("--max-pages <n>", "Max pages to parse", parseInt).option(
+  "--target-pages <pages>",
+  'Pages to check (e.g., "1-5,10,15-20")'
+).option("--password <password>", "Password for encrypted documents").option("-q, --quiet", "Suppress progress output").action(async (file, opts) => {
+  try {
+    const config = {};
+    if (opts.maxPages) config.maxPages = opts.maxPages;
+    if (opts.targetPages) config.targetPages = opts.targetPages;
+    if (opts.password) config.password = opts.password;
+    if (opts.quiet) config.quiet = true;
+    const parser = new LiteParse(config);
+    const stats = await parser.isComplex(await resolveInput(file));
+    const complexPages = stats.filter((s) => s.needsOcr).length;
+    process.stdout.write(
+      opts.compact ? JSON.stringify(stats) : JSON.stringify(stats, null, 2)
+    );
+    process.stdout.write("\n");
+    if (!opts.quiet) {
+      const verdict = complexPages > 0 ? "COMPLEX" : "SIMPLE";
+      const layoutCount = (reason) => stats.filter((s) => s.layout?.reasons.includes(reason)).length;
+      console.error(
+        `${verdict} \u2014 ${complexPages}/${stats.length} page(s) need OCR; layout: ${layoutCount("multi-column")} multi-column, ${layoutCount("table-likely")} table, ${layoutCount("dense-graphics")} graphics-dense`
+      );
+    }
+    if (complexPages > 0) process.exit(1);
+  } catch (err) {
+    console.error(
+      `Error: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
+});
+program.command("screenshot").description("Generate screenshots of document pages").argument("<file>", "Path to the document file").option(
+  "-o, --output-dir <dir>",
+  "Output directory for screenshots",
+  "./screenshots"
+).option(
+  "--target-pages <pages>",
+  'Pages to screenshot (e.g., "1,3,5" or "1-5")'
+).option("--dpi <dpi>", "Rendering DPI", parseFloat).option("--password <password>", "Password for encrypted documents").option("-q, --quiet", "Suppress progress output").action(async (file, opts) => {
+  try {
+    const config = {};
+    if (opts.dpi) config.dpi = opts.dpi;
+    if (opts.password) config.password = opts.password;
+    if (opts.quiet) config.quiet = true;
+    if (opts.targetPages) config.targetPages = opts.targetPages;
+    const parser = new LiteParse(config);
+    let pageNumbers;
+    if (opts.targetPages) {
+      pageNumbers = [];
+      for (const part of opts.targetPages.split(",")) {
+        const trimmed = part.trim();
+        if (trimmed.includes("-")) {
+          const [start, end] = trimmed.split("-").map(Number);
+          for (let i = start; i <= end; i++) pageNumbers.push(i);
+        } else {
+          pageNumbers.push(Number(trimmed));
         }
-        console.error(`[liteparse] batch complete: ${success} succeeded, ${errors} failed`);
-        if (errors > 0)
-            process.exit(1);
+      }
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+    const outputDir = opts.outputDir;
+    mkdirSync(outputDir, { recursive: true });
+    const results = await parser.screenshot(file, pageNumbers);
+    for (const result of results) {
+      const outputPath = join2(outputDir, `page_${result.pageNum}.png`);
+      writeFileSync(outputPath, result.imageBuffer);
+      if (!opts.quiet) {
+        console.error(
+          `[liteparse] screenshot page ${result.pageNum} \u2192 ${outputPath}`
+        );
+      }
     }
+  } catch (err) {
+    console.error(
+      `Error: ${err instanceof Error ? err.message : String(err)}`
+    );
+    process.exit(1);
+  }
 });
-const SUPPORTED_EXTENSIONS = new Set([
-    ".pdf",
-    ".doc", ".docx", ".docm", ".dot", ".dotm", ".dotx", ".odt", ".ott", ".rtf", ".pages",
-    ".ppt", ".pptx", ".pptm", ".pot", ".potm", ".potx", ".odp", ".otp", ".key",
-    ".xls", ".xlsx", ".xlsm", ".xlsb", ".ods", ".ots", ".csv", ".tsv", ".numbers",
-    ".jpg", ".jpeg", ".png", ".gif", ".bmp", ".tiff", ".tif", ".webp", ".svg",
-    ".txt", ".md", ".markdown", ".log",
+program.command("batch-parse").description("Parse multiple documents in batch mode").argument("<input-dir>", "Input directory").argument("<output-dir>", "Output directory").option("--format <format>", 'Output format: json|text|markdown (default: "text")').option("--no-ocr", "Disable OCR").option("--ocr-language <lang>", "OCR language (default: eng)").option("--ocr-server-url <url>", "HTTP OCR server URL").option(
+  "--ocr-server-header <header>",
+  'Extra header for OCR server requests, "Name: Value" (repeatable)',
+  collectHeader
+).option("--max-pages <n>", "Max pages to parse per file", parseInt).option("--dpi <dpi>", "Rendering DPI", parseFloat).option("--recursive", "Recursively search input directory").option("--extension <ext>", "Only process files with this extension").option("--password <password>", "Password for encrypted documents").option("-q, --quiet", "Suppress progress output").option("--num-workers <n>", "Number of concurrent OCR workers", parseInt).option(
+  "--extract-text-metadata",
+  "Include rich PDF text metadata in text items and JSON output"
+).option("--extract-images", "Extract embedded image bytes and metadata").option("--extract-annotations", "Include all PDF annotations in page output").option("--extract-form-fields", "Include AcroForm widget fields and values").option("--extract-structure-tree", "Include the tagged-PDF logical structure tree").option(
+  "--extract-blocks",
+  "Include each page's classified layout blocks with bounding boxes"
+).option(
+  "--extract-xfa-packets",
+  "Include raw XFA packets (name + XML content) in JSON output"
+).option(
+  "--extract-content-bounds",
+  "Include each page's content_bounds in JSON output"
+).option(
+  "--extract-vector-graphics",
+  "Include page-scoped vector shapes and merged horizontal/vertical lines"
+).action(
+  async (inputDir, outputDir, opts) => {
+    try {
+      const config = {};
+      const format = opts.format ?? "text";
+      config.outputFormat = format;
+      if (opts.ocr === false) config.ocrEnabled = false;
+      if (opts.ocrLanguage) config.ocrLanguage = opts.ocrLanguage;
+      if (opts.ocrServerUrl)
+        config.ocrServerUrl = opts.ocrServerUrl;
+      if (opts.ocrServerHeader)
+        config.ocrServerHeaders = opts.ocrServerHeader;
+      if (opts.maxPages) config.maxPages = opts.maxPages;
+      if (opts.dpi) config.dpi = opts.dpi;
+      if (opts.password) config.password = opts.password;
+      if (opts.quiet) config.quiet = true;
+      if (opts.numWorkers) config.numWorkers = opts.numWorkers;
+      if (opts.extractTextMetadata) config.extractTextMetadata = true;
+      if (opts.extractImages) config.extractImages = true;
+      if (opts.extractAnnotations) config.extractAnnotations = true;
+      if (opts.extractFormFields) config.extractFormFields = true;
+      if (opts.extractStructureTree) config.extractStructureTree = true;
+      if (opts.extractBlocks) config.extractBlocks = true;
+      if (opts.extractXfaPackets) config.extractXfaPackets = true;
+      if (opts.extractContentBounds) config.extractContentBounds = true;
+      if (opts.extractContentBounds) config.extractContentBounds = true;
+      if (opts.extractXfaPackets) config.extractXfaPackets = true;
+      if (opts.extractContentBounds) config.extractContentBounds = true;
+      if (opts.extractVectorGraphics) config.extractVectorGraphics = true;
+      const parser = new LiteParse(config);
+      const outExt = format === "json" ? ".json" : format === "markdown" ? ".md" : ".txt";
+      mkdirSync(outputDir, { recursive: true });
+      const extFilter = opts.extension ? opts.extension.startsWith(".") ? opts.extension.toLowerCase() : `.${opts.extension.toLowerCase()}` : void 0;
+      const files = collectFiles(
+        inputDir,
+        !!opts.recursive,
+        extFilter
+      );
+      if (files.length === 0) {
+        console.error(
+          `[liteparse] no matching files found in ${inputDir}`
+        );
+        return;
+      }
+      if (!opts.quiet) {
+        console.error(
+          `[liteparse] found ${files.length} files to process`
+        );
+      }
+      let success = 0;
+      let errors = 0;
+      for (const filePath of files) {
+        const t0 = Date.now();
+        const rel = relative(inputDir, filePath);
+        const parsed = parsePath(rel);
+        const outPath = join2(
+          outputDir,
+          parsed.dir,
+          parsed.name + outExt
+        );
+        mkdirSync(join2(outputDir, parsed.dir), { recursive: true });
+        try {
+          const result = await parser.parse(filePath);
+          const output = format === "json" ? JSON.stringify(
+            parseResultToCliJson(result, {
+              extractTextMetadata: config.extractTextMetadata
+            }),
+            null,
+            2
+          ) : result.text;
+          writeFileSync(outPath, output, "utf-8");
+          success++;
+          if (!opts.quiet) {
+            const elapsed = Date.now() - t0;
+            console.error(
+              `[liteparse] ${filePath} \u2192 ${outPath} (${elapsed}ms)`
+            );
+          }
+        } catch (err) {
+          console.error(
+            `[liteparse] error parsing ${filePath}: ${err instanceof Error ? err.message : String(err)}`
+          );
+          errors++;
+        }
+      }
+      console.error(
+        `[liteparse] batch complete: ${success} succeeded, ${errors} failed`
+      );
+      if (errors > 0) process.exit(1);
+    } catch (err) {
+      console.error(
+        `Error: ${err instanceof Error ? err.message : String(err)}`
+      );
+      process.exit(1);
+    }
+  }
+);
+var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".docm",
+  ".dot",
+  ".dotm",
+  ".dotx",
+  ".odt",
+  ".ott",
+  ".rtf",
+  ".pages",
+  ".ppt",
+  ".pptx",
+  ".pptm",
+  ".pot",
+  ".potm",
+  ".potx",
+  ".odp",
+  ".otp",
+  ".key",
+  ".xls",
+  ".xlsx",
+  ".xlsm",
+  ".xlsb",
+  ".ods",
+  ".ots",
+  ".csv",
+  ".tsv",
+  ".numbers",
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".bmp",
+  ".tiff",
+  ".tif",
+  ".webp",
+  ".svg",
+  ".txt",
+  ".md",
+  ".markdown",
+  ".log"
 ]);
 function collectFiles(dir, recursive, extFilter) {
-    const files = [];
-    collectFilesInner(dir, recursive, extFilter, files);
-    files.sort();
-    return files;
+  const files = [];
+  collectFilesInner(dir, recursive, extFilter, files);
+  files.sort();
+  return files;
 }
 function collectFilesInner(dir, recursive, extFilter, files) {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const fullPath = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (recursive)
-                collectFilesInner(fullPath, recursive, extFilter, files);
-            continue;
-        }
-        const lower = entry.name.toLowerCase();
-        if (extFilter) {
-            if (!lower.endsWith(extFilter))
-                continue;
-        }
-        else {
-            const ext = lower.lastIndexOf(".") >= 0 ? lower.slice(lower.lastIndexOf(".")) : "";
-            if (!SUPPORTED_EXTENSIONS.has(ext))
-                continue;
-        }
-        files.push(fullPath);
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive) collectFilesInner(fullPath, recursive, extFilter, files);
+      continue;
+    }
+    const lower = entry.name.toLowerCase();
+    if (extFilter) {
+      if (!lower.endsWith(extFilter)) continue;
+    } else {
+      const ext = lower.lastIndexOf(".") >= 0 ? lower.slice(lower.lastIndexOf(".")) : "";
+      if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
     }
+    files.push(fullPath);
+  }
 }
 program.parse(process.argv);
 //# sourceMappingURL=cli.js.map