@arcships/light-ocr 0.5.3 → 0.5.5

package/README.md

@@ -1,10 +1,31 @@
 # @arcships/light-ocr
 
-The default PP-OCRv6 Small entry for `light-ocr`. It exact-pins one compatible model-free runtime and one Small model package, and remains the only owner of the `light-ocr` command.
+The stable PP-OCRv6 Small entry for local image and PDF OCR on Node.js 22 and 24.
 
 ```bash
 npm install @arcships/light-ocr
-light-ocr info --version
+light-ocr image.png --format text
+light-ocr report.pdf --pages 1-10 --format jsonl
+light-ocr doctor --json
 ```
 
-`0.4.0` is the N2 topology cutover: the facade contains only Small model configuration and delegates the API, native loading, EXIF handling, and CLI implementation to the shared runtime. Tiny and Medium use separate packages and commands, so installing this package still installs only Small.
+The package exact-pins one model-free runtime, the Small model, and the native
+component and PDFium renderer for the current platform. It has no install
+script and its complete release closure is tested with npm offline and scripts
+disabled.
+
+```js
+const { createEngine } = require('@arcships/light-ocr');
+
+const engine = await createEngine();
+try {
+  const result = await engine.recognizeEncoded(imageBytes);
+  console.log(result.lines);
+} finally {
+  await engine.close();
+}
+```
+
+The main package exports `recognizeDocument()` and `createDocumentEngine()`.
+PDFium's native files are inside the platform npm package, so neither install
+nor runtime performs a secondary download.

package/package.json

@@ -7,9 +7,9 @@
   },
   "dependencies": {
     "@arcships/light-ocr-model-ppocrv6-small": "0.3.4",
-    "@arcships/light-ocr-runtime": "0.1.3"
+    "@arcships/light-ocr-runtime": "0.1.5"
   },
-  "description": "Offline PP-OCRv6 Small OCR for Node.js — the stable default tier",
+  "description": "Offline image and PDF OCR for Node.js — the stable PP-OCRv6 Small tier",
   "engines": {
     "node": "^22.0.0 || ^24.0.0"
   },
@@ -18,7 +18,8 @@
       "import": "./src/index.mjs",
       "require": "./src/index.cjs",
       "types": "./src/index.d.ts"
-    }
+    },
+    "./document-cli": "./src/document-cli.cjs"
   },
   "files": [
     "src/",
@@ -31,9 +32,6 @@
   "main": "./src/index.cjs",
   "module": "./src/index.mjs",
   "name": "@arcships/light-ocr",
-  "optionalDependencies": {
-    "pdfium-native": "0.6.1"
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -44,5 +42,5 @@
   },
   "type": "commonjs",
   "types": "./src/index.d.ts",
-  "version": "0.5.3"
+  "version": "0.5.5"
 }

package/src/cli.cjs

@@ -35,10 +35,40 @@ const cli = createCli({
   loadNative,
 });
 
+function shouldUseDocumentCli(argv) {
+  if (argv[0] === 'document') return true;
+  const source = argv[0] === 'recognize' ? argv[1] : argv[0];
+  return typeof source === 'string' && /\.pdf$/i.test(source);
+}
+
+async function main(argv) {
+  if (shouldUseDocumentCli(argv)) {
+    const selectedArgs = argv[0] === 'document' ? argv.slice(1) : argv;
+    return require('./document-cli.cjs').main(selectedArgs);
+  }
+  const code = await cli.main(argv);
+  if (
+    code === cli.EXIT.success
+    && argv.includes('--help')
+    && !argv.some((argument) => ['recognize', 'detect', 'info', 'doctor'].includes(argument))
+  ) {
+    process.stdout.write(
+      '\nPDF: light-ocr <document.pdf> [--pages N-M] or '
+      + 'light-ocr document <source...> [options]\n',
+    );
+  }
+  return code;
+}
+
 if (require.main === module) {
-  cli.main(process.argv.slice(2)).then((code) => {
+  const argv = process.argv.slice(2);
+  main(argv).then((code) => {
     if (code !== cli.EXIT.success) process.exitCode = code;
   });
 }
 
-module.exports = cli;
+module.exports = { ...cli, main };
+Object.defineProperty(module.exports, 'shouldUseDocumentCli', {
+  value: shouldUseDocumentCli,
+  enumerable: false,
+});

package/src/document-cli.cjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  createDocumentEngine,
+  getVersion,
+  hasPdfSupport,
+  OcrError,
+} = require('./index.cjs');
+
+const USAGE = `light-ocr - local image, PDF, and multi-page OCR
+
+Usage:
+  light-ocr [recognize] <document.pdf> [options]
+  light-ocr document <source...> [options]
+
+Options:
+  --format <json|jsonl|text>  Output format (default: json)
+  --pages <N|N-M>             Inclusive PDF page range
+  --dpi <36-600>              PDF raster DPI (default: 150)
+  --max-pages <n>             Maximum pages (default: 100)
+  --max-page-pixels <n>       Maximum rendered pixels per page
+  --max-total-pixels <n>      Maximum rendered pixels for the request
+  --max-file-bytes <n>        Maximum bytes per input
+  --provider <auto|cpu|apple|webgpu>
+  --quiet                     Suppress progress output
+  -h, --help                  Show help
+  -v, --version               Show version`;
+
+const EXIT_CODES = Object.freeze({
+  invalid_argument: 65,
+  invalid_image: 66,
+  unsupported_capability: 67,
+  invalid_model_bundle: 68,
+  resource_limit_exceeded: 69,
+  package_load_failed: 70,
+  inference_failed: 71,
+  internal_error: 72,
+});
+
+function argumentError(message) {
+  return new OcrError('invalid_argument', message);
+}
+
+function takeValue(args, index, flag) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith('-')) {
+    throw argumentError(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function parseInteger(value, flag) {
+  if (!/^[1-9]\d*$/.test(value)) {
+    throw argumentError(`${flag} must be a positive integer`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw argumentError(`${flag} is too large`);
+  }
+  return parsed;
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  if (args[0] === 'recognize') args.shift();
+  const sources = [];
+  const documentOptions = {};
+  let format = 'json';
+  let provider = 'auto';
+  let quiet = false;
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--quiet') {
+      quiet = true;
+    } else if (arg === '--format') {
+      format = takeValue(args, index, arg);
+      index++;
+      if (!['json', 'jsonl', 'text'].includes(format)) {
+        throw argumentError('--format must be json, jsonl, or text');
+      }
+    } else if (arg === '--pages') {
+      const value = takeValue(args, index, arg);
+      index++;
+      const match = /^([1-9]\d*)(?:-([1-9]\d*))?$/.exec(value);
+      if (!match) throw argumentError('--pages must be N or N-M');
+      const start = parseInteger(match[1], '--pages');
+      const end = parseInteger(match[2] ?? match[1], '--pages');
+      if (end < start) throw argumentError('--pages end must not precede its start');
+      documentOptions.pageRange = { start, end };
+    } else if (
+      [
+        '--dpi',
+        '--max-pages',
+        '--max-page-pixels',
+        '--max-total-pixels',
+        '--max-file-bytes',
+      ].includes(arg)
+    ) {
+      const value = parseInteger(takeValue(args, index, arg), arg);
+      index++;
+      const keys = {
+        '--dpi': 'dpi',
+        '--max-pages': 'maxPages',
+        '--max-page-pixels': 'maxPagePixels',
+        '--max-total-pixels': 'maxTotalPixels',
+        '--max-file-bytes': 'maxFileBytes',
+      };
+      documentOptions[keys[arg]] = value;
+    } else if (arg === '--provider') {
+      provider = takeValue(args, index, arg);
+      index++;
+      if (!['auto', 'cpu', 'apple', 'webgpu'].includes(provider)) {
+        throw argumentError('--provider must be auto, cpu, apple, or webgpu');
+      }
+    } else if (arg.startsWith('-')) {
+      throw argumentError(`unknown option: ${arg}`);
+    } else {
+      sources.push(arg);
+    }
+  }
+  if (sources.length === 0) throw argumentError('at least one source is required');
+  return { documentOptions, format, provider, quiet, sources };
+}
+
+function writeLine(stream, value = '') {
+  stream.write(`${value}\n`);
+}
+
+async function main(
+  argv = process.argv.slice(2),
+  io = { stdout: process.stdout, stderr: process.stderr },
+) {
+  if (
+    argv.length === 0
+    || argv[0] === 'help'
+    || argv.includes('--help')
+    || argv.includes('-h')
+  ) {
+    writeLine(io.stdout, USAGE);
+    return 0;
+  }
+  if (argv.includes('--version') || argv.includes('-v')) {
+    writeLine(io.stdout, getVersion());
+    return 0;
+  }
+  if (argv[0] === 'info') {
+    writeLine(io.stdout, JSON.stringify({
+      name: '@arcships/light-ocr',
+      version: getVersion(),
+      pdfSupport: hasPdfSupport(),
+    }));
+    return 0;
+  }
+
+  let parsed;
+  let engine;
+  try {
+    parsed = parseArgs(argv);
+    engine = await createDocumentEngine({
+      engineOptions: { execution: { provider: parsed.provider } },
+    });
+    const source = parsed.sources.length === 1 ? parsed.sources[0] : parsed.sources;
+    const pages = parsed.format === 'json' ? [] : undefined;
+    let count = 0;
+    for await (const page of engine.recognizeDocument(source, parsed.documentOptions)) {
+      count++;
+      if (pages) pages.push(page);
+      if (parsed.format === 'jsonl') writeLine(io.stdout, JSON.stringify(page));
+      if (parsed.format === 'text') {
+        if (count > 1) writeLine(io.stdout);
+        for (const line of page.lines) writeLine(io.stdout, line.text);
+      }
+      if (!parsed.quiet) io.stderr.write(`\rProcessed page ${count}`);
+    }
+    if (!parsed.quiet) writeLine(io.stderr);
+    if (pages) {
+      writeLine(io.stdout, JSON.stringify({
+        schemaVersion: 1,
+        source: {
+          kind: pages[0]?.source.kind === 'pdf' ? 'pdf' : 'page-images',
+          mediaType: pages[0]?.source.mediaType ?? 'application/octet-stream',
+          identity: {},
+          pageCount: pages.length,
+        },
+        pages,
+      }, null, 2));
+    }
+    return 0;
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      writeLine(io.stderr, 'The operation was aborted');
+      return 72;
+    }
+    if (error instanceof OcrError) {
+      writeLine(io.stderr, `${error.code}: ${error.message}`);
+      return EXIT_CODES[error.code] ?? 72;
+    }
+    writeLine(io.stderr, `internal_error: ${error?.message ?? String(error)}`);
+    return 72;
+  } finally {
+    await engine?.close();
+  }
+}
+
+if (require.main === module) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      console.error(error);
+      process.exitCode = 72;
+    },
+  );
+}
+
+module.exports = { main, parseArgs, USAGE };

package/src/document.cjs

@@ -0,0 +1,447 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { OcrError } = require('@arcships/light-ocr-runtime');
+
+const DEFAULTS = Object.freeze({
+  dpi: 150,
+  maxPages: 100,
+  maxPagePixels: 4096 * 4096,
+  maxTotalPixels: 100 * 1024 * 1024,
+  maxFileBytes: 100 * 1024 * 1024,
+});
+
+let pdfium;
+let pdfiumLoaded = false;
+let defaultCreateEngine;
+
+function platformPdfiumPackage() {
+  const packages = {
+    'darwin-arm64': '@arcships/light-ocr-darwin-arm64',
+    'darwin-x64': '@arcships/light-ocr-darwin-x64',
+    'linux-arm64': '@arcships/light-ocr-linux-arm64-gnu',
+    'linux-x64': '@arcships/light-ocr-linux-x64-gnu',
+    'win32-arm64': '@arcships/light-ocr-win32-arm64',
+    'win32-x64': '@arcships/light-ocr-win32-x64',
+  };
+  return packages[`${process.platform}-${process.arch}`];
+}
+
+function loadPdfium() {
+  if (!pdfiumLoaded) {
+    pdfiumLoaded = true;
+    try {
+      const developmentModule = process.env.LIGHT_OCR_PDFIUM_MODULE;
+      if (developmentModule) {
+        pdfium = require(path.resolve(developmentModule));
+      } else {
+        const packageName = platformPdfiumPackage();
+        if (!packageName) {
+          throw new Error(`unsupported platform ${process.platform}-${process.arch}`);
+        }
+        pdfium = require(`${packageName}/pdfium`);
+      }
+    } catch {
+      // Workspace tests may use the upstream module directly. Published packages
+      // do not depend on it: production PDFium lives in the platform npm package.
+      try {
+        pdfium = require('pdfium-native');
+      } catch {
+        pdfium = undefined;
+      }
+    }
+  }
+  return pdfium;
+}
+
+function hasPdfSupport() {
+  return loadPdfium() !== undefined;
+}
+
+function getVersion() {
+  return require('../package.json').version;
+}
+
+function invalidArgument(message) {
+  return new OcrError('invalid_argument', message);
+}
+
+function positiveInteger(value, name, fallback, maximum = Number.MAX_SAFE_INTEGER) {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+    throw invalidArgument(`${name} must be an integer between 1 and ${maximum}`);
+  }
+  return value;
+}
+
+function normalizeOptions(options) {
+  if (options === undefined) options = {};
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw invalidArgument('document options must be an object');
+  }
+  const normalized = {
+    ...options,
+    dpi: positiveInteger(options.dpi, 'dpi', DEFAULTS.dpi, 600),
+    maxPages: positiveInteger(options.maxPages, 'maxPages', DEFAULTS.maxPages, 10000),
+    maxPagePixels: positiveInteger(
+      options.maxPagePixels,
+      'maxPagePixels',
+      DEFAULTS.maxPagePixels,
+    ),
+    maxTotalPixels: positiveInteger(
+      options.maxTotalPixels,
+      'maxTotalPixels',
+      DEFAULTS.maxTotalPixels,
+    ),
+    maxFileBytes: positiveInteger(
+      options.maxFileBytes,
+      'maxFileBytes',
+      DEFAULTS.maxFileBytes,
+    ),
+  };
+  if (normalized.dpi < 36) {
+    throw invalidArgument('dpi must be an integer between 36 and 600');
+  }
+  if (options.pageRange !== undefined) {
+    const range = options.pageRange;
+    if (
+      range === null
+      || typeof range !== 'object'
+      || Array.isArray(range)
+      || !Number.isSafeInteger(range.start)
+      || !Number.isSafeInteger(range.end)
+      || range.start < 1
+      || range.end < range.start
+    ) {
+      throw invalidArgument('pageRange must contain 1-based integers with start <= end');
+    }
+  }
+  return normalized;
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw signal.reason === undefined
+      ? new DOMException('The operation was aborted', 'AbortError')
+      : signal.reason;
+  }
+}
+
+function isBytes(value) {
+  return value instanceof Uint8Array;
+}
+
+function isPdf(value) {
+  return value?.length >= 4
+    && value[0] === 0x25
+    && value[1] === 0x50
+    && value[2] === 0x44
+    && value[3] === 0x46;
+}
+
+function mediaType(value) {
+  if (
+    value?.length >= 4
+    && value[0] === 0x89
+    && value[1] === 0x50
+    && value[2] === 0x4e
+    && value[3] === 0x47
+  ) {
+    return 'image/png';
+  }
+  if (value?.length >= 3 && value[0] === 0xff && value[1] === 0xd8 && value[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  return 'application/octet-stream';
+}
+
+async function readInput(source, maxFileBytes) {
+  if (typeof source === 'string') {
+    const stats = await fs.stat(source);
+    if (stats.size > maxFileBytes) {
+      throw new OcrError(
+        'resource_limit_exceeded',
+        `File size ${stats.size} exceeds maxFileBytes ${maxFileBytes}`,
+      );
+    }
+    return fs.readFile(source);
+  }
+  if (!isBytes(source)) {
+    throw invalidArgument('document inputs must be file paths or Uint8Array values');
+  }
+  if (source.byteLength > maxFileBytes) {
+    throw new OcrError(
+      'resource_limit_exceeded',
+      `Input size ${source.byteLength} exceeds maxFileBytes ${maxFileBytes}`,
+    );
+  }
+  return source;
+}
+
+function linesFrom(result) {
+  return result.lines.map((line, index) => ({
+    id: `L${index}`,
+    text: line.text,
+    confidence: line.confidence,
+    box: line.box,
+  }));
+}
+
+function pageRect(page, box) {
+  if (
+    box
+    && [box.left, box.bottom, box.right, box.top].every(Number.isFinite)
+  ) {
+    return {
+      x: box.left,
+      y: box.bottom,
+      width: box.right - box.left,
+      height: box.top - box.bottom,
+    };
+  }
+  return { x: 0, y: 0, width: page.width, height: page.height };
+}
+
+async function* processPdf(engine, input, options) {
+  const renderer = loadPdfium();
+  if (!renderer) {
+    throw new OcrError(
+      'unsupported_capability',
+      'PDF support is unavailable; reinstall @arcships/light-ocr without --omit=optional',
+    );
+  }
+  const pdf = await readInput(input, options.maxFileBytes);
+  const document = await renderer.loadDocument(
+    Buffer.from(pdf.buffer, pdf.byteOffset, pdf.byteLength),
+  );
+  let totalPixels = 0;
+  try {
+    const start = options.pageRange?.start ?? 1;
+    const end = Math.min(options.pageRange?.end ?? document.pageCount, document.pageCount);
+    const requestedPages = Math.max(0, end - start + 1);
+    if (start > document.pageCount) {
+      throw invalidArgument(`pageRange starts after the document's ${document.pageCount} pages`);
+    }
+    if (requestedPages > options.maxPages) {
+      throw new OcrError(
+        'resource_limit_exceeded',
+        `Page count ${requestedPages} exceeds maxPages ${options.maxPages}`,
+      );
+    }
+
+    for (let pageNumber = start; pageNumber <= end; pageNumber++) {
+      throwIfAborted(options.signal);
+      const page = await document.getPage(pageNumber - 1);
+      let result;
+      try {
+        const scale = options.dpi / 72;
+        const renderedWidth = Math.ceil(page.width * scale);
+        const renderedHeight = Math.ceil(page.height * scale);
+        const renderedPixels = renderedWidth * renderedHeight;
+        if (
+          !Number.isSafeInteger(renderedPixels)
+          || renderedPixels > options.maxPagePixels
+        ) {
+          throw new OcrError(
+            'resource_limit_exceeded',
+            `Page ${pageNumber} rendered pixels ${renderedPixels} `
+              + `exceeds maxPagePixels ${options.maxPagePixels}`,
+          );
+        }
+        totalPixels += renderedPixels;
+        if (!Number.isSafeInteger(totalPixels) || totalPixels > options.maxTotalPixels) {
+          throw new OcrError(
+            'resource_limit_exceeded',
+            `Total rendered pixels ${totalPixels} exceeds maxTotalPixels `
+              + `${options.maxTotalPixels}`,
+          );
+        }
+
+        const renderStart = performance.now();
+        const png = await page.render({ scale });
+        const renderUs = Math.round((performance.now() - renderStart) * 1000);
+        throwIfAborted(options.signal);
+        const ocrStart = performance.now();
+        const ocr = await engine.recognizeEncoded(png, {
+          ...options.ocrOptions,
+          signal: options.signal,
+        });
+        const ocrUs = Math.round((performance.now() - ocrStart) * 1000);
+        result = {
+          index: pageNumber - 1,
+          width: ocr.imageWidth,
+          height: ocr.imageHeight,
+          coordinateSpace: 'pageSpace',
+          structure: 'ocr-order',
+          lines: linesFrom(ocr),
+          source: {
+            kind: 'pdf',
+            mediaType: 'application/pdf',
+            identity: { pageIndex: pageNumber - 1 },
+            appliedTransforms: {
+              pdf: {
+                rotation: Number(page.rotation ?? 0) * 90,
+                mediaBox: { x: 0, y: 0, width: page.width, height: page.height },
+                cropBox: pageRect(page, page.cropBox),
+                dpi: options.dpi,
+                scale,
+              },
+            },
+          },
+          timingUs: { total: renderUs + ocrUs, decode: renderUs, ocr: ocrUs },
+          modelBundleId: ocr.modelBundleId,
+        };
+      } finally {
+        await page.close();
+      }
+      yield result;
+    }
+  } finally {
+    await document.destroy();
+  }
+}
+
+async function* processImages(engine, inputs, options) {
+  if (inputs.length > options.maxPages) {
+    throw new OcrError(
+      'resource_limit_exceeded',
+      `Page count ${inputs.length} exceeds maxPages ${options.maxPages}`,
+    );
+  }
+  let totalPixels = 0;
+  for (let index = 0; index < inputs.length; index++) {
+    throwIfAborted(options.signal);
+    const image = await readInput(inputs[index], options.maxFileBytes);
+    const started = performance.now();
+    const ocr = await engine.recognizeEncoded(image, {
+      ...options.ocrOptions,
+      applyExif: true,
+      signal: options.signal,
+    });
+    const ocrUs = Math.round((performance.now() - started) * 1000);
+    const pixels = ocr.imageWidth * ocr.imageHeight;
+    if (!Number.isSafeInteger(pixels) || pixels > options.maxPagePixels) {
+      throw new OcrError(
+        'resource_limit_exceeded',
+        `Image ${index + 1} pixels ${pixels} exceeds maxPagePixels ${options.maxPagePixels}`,
+      );
+    }
+    totalPixels += pixels;
+    if (!Number.isSafeInteger(totalPixels) || totalPixels > options.maxTotalPixels) {
+      throw new OcrError(
+        'resource_limit_exceeded',
+        `Total image pixels ${totalPixels} exceeds maxTotalPixels ${options.maxTotalPixels}`,
+      );
+    }
+    yield {
+      index,
+      width: ocr.imageWidth,
+      height: ocr.imageHeight,
+      coordinateSpace: 'pageSpace',
+      structure: 'ocr-order',
+      lines: linesFrom(ocr),
+      source: {
+        kind: 'image',
+        mediaType: mediaType(image),
+        identity: { index },
+        appliedTransforms: {},
+      },
+      timingUs: { total: ocrUs, decode: 0, ocr: ocrUs },
+      modelBundleId: ocr.modelBundleId,
+    };
+  }
+}
+
+class DocumentEngine {
+  #engine;
+  #ownsEngine;
+  #closed = false;
+
+  constructor(engine, ownsEngine) {
+    this.#engine = engine;
+    this.#ownsEngine = ownsEngine;
+  }
+
+  async *recognizeDocument(source, options) {
+    if (this.#closed) throw new OcrError('invalid_engine', 'Document engine is closed');
+    const normalized = normalizeOptions(options);
+    if (Array.isArray(source)) {
+      if (source.length === 0) throw invalidArgument('document source array must not be empty');
+      yield* processImages(this.#engine, source, normalized);
+      return;
+    }
+    if (typeof source !== 'string' && !isBytes(source)) {
+      throw invalidArgument(
+        'document source must be a file path, Uint8Array, or a non-empty array of them',
+      );
+    }
+    if (
+      (typeof source === 'string' && path.extname(source).toLowerCase() === '.pdf')
+      || (isBytes(source) && isPdf(source))
+    ) {
+      yield* processPdf(this.#engine, source, normalized);
+      return;
+    }
+    yield* processImages(this.#engine, [source], normalized);
+  }
+
+  recognizePdf(source, options) {
+    if (this.#closed) throw new OcrError('invalid_engine', 'Document engine is closed');
+    return processPdf(this.#engine, source, normalizeOptions(options));
+  }
+
+  recognizeImages(sources, options) {
+    if (this.#closed) throw new OcrError('invalid_engine', 'Document engine is closed');
+    if (!Array.isArray(sources) || sources.length === 0) {
+      throw invalidArgument('image sources must be a non-empty array');
+    }
+    return processImages(this.#engine, sources, normalizeOptions(options));
+  }
+
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    if (this.#ownsEngine) await this.#engine.close();
+  }
+}
+
+async function createDocumentEngine(options = {}) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw invalidArgument('createDocumentEngine options must be an object');
+  }
+  const ownsEngine = options.engine === undefined;
+  const engine = options.engine ?? await defaultCreateEngine(options.engineOptions);
+  return new DocumentEngine(engine, ownsEngine);
+}
+
+async function* recognizeDocument(source, options = {}) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    throw invalidArgument('recognizeDocument options must be an object');
+  }
+  const documentEngine = await createDocumentEngine({
+    engine: options.engine,
+    engineOptions: options.engineOptions,
+  });
+  try {
+    yield* documentEngine.recognizeDocument(source, options);
+  } finally {
+    await documentEngine.close();
+  }
+}
+
+function createDocumentApi(createEngine) {
+  if (typeof createEngine !== 'function') {
+    throw new TypeError('createDocumentApi requires createEngine');
+  }
+  defaultCreateEngine = createEngine;
+  return Object.freeze({
+    createDocumentEngine,
+    getVersion,
+    hasPdfSupport,
+    recognizeDocument,
+  });
+}
+
+module.exports = { createDocumentApi };

package/src/index.cjs

@@ -1,18 +1,7 @@
 'use strict';
 
-const path = require('node:path');
-
-// Try to use workspace dependencies, fallback to local paths
-let createModelFacade;
-try {
-  ({ createModelFacade } = require('@arcships/light-ocr-runtime/facade'));
-} catch {
-  // Fallback to local runtime
-  const facadePath = path.join(__dirname, '..', '..', 'runtime', 'src', 'facade.cjs');
-  ({ createModelFacade } = require(facadePath));
-}
-
-const fs = require('node:fs');
+const { createModelFacade } = require('@arcships/light-ocr-runtime/facade');
+const { createDocumentApi } = require('./document.cjs');
 
 const facade = createModelFacade({
   model: 'ppocrv6-small',
@@ -38,249 +27,7 @@ const facade = createModelFacade({
   },
 });
 
-// Lazy load pdfium-native
-let pdfium = null;
-let pdfiumLoaded = false;
-
-function loadPdfium() {
-  if (pdfiumLoaded) return pdfium;
-  pdfiumLoaded = true;
-  try {
-    pdfium = require('pdfium-native');
-  } catch {
-    pdfium = null;
-  }
-  return pdfium;
-}
-
-function hasPdfSupport() {
-  return loadPdfium() !== null;
-}
-
-async function* processPdf(engine, pdfBuffer, options = {}) {
-  const pdfiumNative = loadPdfium();
-  if (!pdfiumNative) {
-    throw new facade.OcrError('unsupported_capability', 'PDF support not available. Install pdfium-native.');
-  }
-
-  const {
-    pageRange,
-    dpi = 150,
-    maxPages = 100,
-    maxPagePixels = 4096 * 4096,
-    maxTotalPixels = 100 * 1024 * 1024,
-    maxFileBytes = 100 * 1024 * 1024,
-    signal,
-    ocrOptions = {}
-  } = options;
-
-  // Check file size
-  if (pdfBuffer.byteLength > maxFileBytes) {
-    throw new facade.OcrError('resource_limit_exceeded', 
-      `File size ${pdfBuffer.byteLength} exceeds maxFileBytes ${maxFileBytes}`);
-  }
-
-  let totalPixels = 0;
-
-  // Open PDF document
-  const doc = await pdfiumNative.loadDocument(pdfBuffer);
-  
-  try {
-    const pageCount = doc.pageCount;
-    
-    // Apply page range
-    const start = pageRange?.start ? Math.max(1, pageRange.start) : 1;
-    const end = pageRange?.end ? Math.min(pageCount, pageRange.end) : pageCount;
-    
-    // Check page limits
-    if (end - start + 1 > maxPages) {
-      throw new facade.OcrError('resource_limit_exceeded', 
-        `Page count ${end - start + 1} exceeds maxPages ${maxPages}`);
-    }
-
-    for (let i = start; i <= end; i++) {
-      // Check abort signal
-      if (signal?.aborted) {
-        throw new facade.OcrError('internal_error', 'Operation aborted');
-      }
-
-      const page = await doc.getPage(i - 1); // 0-indexed
-      
-      // Get page dimensions
-      const { width, height } = page;
-      const pagePixels = width * height;
-      
-      // Check pixel limits
-      if (pagePixels > maxPagePixels) {
-        throw new facade.OcrError('resource_limit_exceeded', 
-          `Page ${i} pixels ${pagePixels} exceeds maxPagePixels ${maxPagePixels}`);
-      }
-      
-      totalPixels += pagePixels;
-      if (totalPixels > maxTotalPixels) {
-        throw new facade.OcrError('resource_limit_exceeded', 
-          `Total pixels ${totalPixels} exceeds maxTotalPixels ${maxTotalPixels}`);
-      }
-
-      // Render page to PNG
-      const renderStart = Date.now();
-      const scale = dpi / 72; // PDF default is 72 DPI
-      const pngBuffer = await page.render({ scale });
-      const renderTime = (Date.now() - renderStart) * 1000;
-
-      // OCR the rendered image
-      const ocrStart = Date.now();
-      const ocrResult = await engine.recognizeEncoded(pngBuffer, ocrOptions);
-      const ocrTime = (Date.now() - ocrStart) * 1000;
-
-      // Close page to free native memory
-      await page.close();
-
-      // Build page result
-      const pageResult = {
-        index: i - 1,
-        width: ocrResult.imageWidth,
-        height: ocrResult.imageHeight,
-        coordinateSpace: 'pageSpace',
-        structure: 'ocr-order',
-        lines: ocrResult.lines.map((line, idx) => ({
-          id: `L${idx}`,
-          text: line.text,
-          confidence: line.confidence,
-          box: line.box
-        })),
-        source: {
-          kind: 'pdf',
-          mediaType: 'application/pdf',
-          identity: { pageIndex: i - 1 },
-          appliedTransforms: {
-            pdf: {
-              rotation: 0,
-              mediaBox: { x: 0, y: 0, width, height },
-              cropBox: { x: 0, y: 0, width, height },
-              dpi,
-              scale: dpi / 72
-            }
-          }
-        },
-        timingUs: {
-          total: renderTime + ocrTime,
-          decode: renderTime,
-          ocr: ocrTime
-        },
-        modelBundleId: ocrResult.modelBundleId
-      };
-
-      yield pageResult;
-    }
-  } finally {
-    doc.destroy();
-  }
-}
-
-async function* processImages(engine, imageBuffers, options = {}) {
-  const { signal, ocrOptions = {} } = options;
-
-  for (let i = 0; i < imageBuffers.length; i++) {
-    if (signal?.aborted) {
-      throw new facade.OcrError('internal_error', 'Operation aborted');
-    }
-
-    const buffer = imageBuffers[i];
-    
-    const ocrStart = Date.now();
-    const ocrResult = await engine.recognizeEncoded(buffer, {
-      ...ocrOptions,
-      applyExif: true
-    });
-    const ocrTime = (Date.now() - ocrStart) * 1000;
-
-    const pageResult = {
-      index: i,
-      width: ocrResult.imageWidth,
-      height: ocrResult.imageHeight,
-      coordinateSpace: 'pageSpace',
-      structure: 'ocr-order',
-      lines: ocrResult.lines.map((line, idx) => ({
-        id: `L${idx}`,
-        text: line.text,
-        confidence: line.confidence,
-        box: line.box
-      })),
-      source: {
-        kind: 'image',
-        mediaType: 'image/png',
-        identity: { index: i },
-        appliedTransforms: {
-          exif: { orientation: 1, applied: false }
-        }
-      },
-      timingUs: {
-        total: ocrTime,
-        decode: 0,
-        ocr: ocrTime
-      },
-      modelBundleId: ocrResult.modelBundleId
-    };
-
-    yield pageResult;
-  }
-}
-
-async function* recognizeDocument(source, options = {}) {
-  // Create engine if not provided
-  let engine = options.engine;
-  let engineCreated = false;
-  
-  if (!engine) {
-    engine = await facade.createEngine();
-    engineCreated = true;
-  }
-  
-  try {
-    let buffers;
-    let isPdf = false;
-    
-    if (Array.isArray(source)) {
-      // Multiple images
-      buffers = [];
-      for (const s of source) {
-        if (typeof s === 'string') {
-          buffers.push(fs.readFileSync(s));
-        } else {
-          buffers.push(s);
-        }
-      }
-    } else if (typeof source === 'string') {
-      // File path
-      const ext = path.extname(source).toLowerCase();
-      if (ext === '.pdf') {
-        isPdf = true;
-        buffers = [fs.readFileSync(source)];
-      } else {
-        buffers = [fs.readFileSync(source)];
-      }
-    } else {
-      // Buffer
-      isPdf = source[0] === 0x25 && source[1] === 0x50 && source[2] === 0x44 && source[3] === 0x46;
-      buffers = [source];
-    }
-    
-    if (isPdf) {
-      yield* processPdf(engine, buffers[0], options);
-    } else {
-      yield* processImages(engine, buffers, options);
-    }
-  } finally {
-    if (engineCreated) {
-      await engine.close();
-    }
-  }
-}
-
-// Export facade + document capabilities
-module.exports = {
+module.exports = Object.freeze({
   ...facade,
-  hasPdfSupport,
-  recognizeDocument
-};
+  ...createDocumentApi(facade.createEngine),
+});

package/src/index.d.ts

@@ -19,3 +19,112 @@ export const modelProfile: ModelProfile & {
   readonly model: BuiltInModel;
   readonly maturity: 'stable';
 };
+
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface Rect {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface DocumentLine {
+  readonly id: string;
+  readonly text: string;
+  readonly confidence: number;
+  readonly box: readonly [Point, Point, Point, Point];
+}
+
+export interface PdfTransform {
+  readonly rotation: number;
+  readonly mediaBox: Rect;
+  readonly cropBox: Rect;
+  readonly dpi: number;
+  readonly scale: number;
+}
+
+export interface PageSource {
+  readonly kind: 'image' | 'pdf';
+  readonly mediaType: string;
+  readonly identity: Readonly<Record<string, unknown>>;
+  readonly appliedTransforms: {
+    readonly pdf?: PdfTransform;
+  };
+}
+
+export interface DocumentPage {
+  readonly index: number;
+  readonly width: number;
+  readonly height: number;
+  readonly coordinateSpace: 'pageSpace';
+  readonly structure: 'ocr-order';
+  readonly lines: ReadonlyArray<DocumentLine>;
+  readonly source: PageSource;
+  readonly timingUs: {
+    readonly total: number;
+    readonly decode: number;
+    readonly ocr: number;
+  };
+  readonly modelBundleId?: string;
+}
+
+export type DocumentInput = string | Uint8Array;
+
+export interface DocumentOptions {
+  /** Inclusive, one-based PDF page range. */
+  readonly pageRange?: { readonly start: number; readonly end: number };
+  /** PDF raster resolution. Must be an integer from 36 through 600. Default: 150. */
+  readonly dpi?: number;
+  /** Maximum bytes accepted for each input. Default: 100 MiB. */
+  readonly maxFileBytes?: number;
+  /** Maximum number of pages. Default: 100. */
+  readonly maxPages?: number;
+  /** Maximum rendered pixels for one page. Default: 4096 × 4096. */
+  readonly maxPagePixels?: number;
+  /** Maximum rendered pixels across the request. Default: 100 Mi pixels. */
+  readonly maxTotalPixels?: number;
+  readonly signal?: AbortSignal;
+  readonly ocrOptions?: import('@arcships/light-ocr-runtime').RecognizeOptions;
+}
+
+export interface DocumentEngine {
+  recognizePdf(
+    source: DocumentInput,
+    options?: DocumentOptions,
+  ): AsyncGenerator<DocumentPage>;
+  recognizeImages(
+    sources: ReadonlyArray<DocumentInput>,
+    options?: DocumentOptions,
+  ): AsyncGenerator<DocumentPage>;
+  recognizeDocument(
+    source: DocumentInput | ReadonlyArray<DocumentInput>,
+    options?: DocumentOptions,
+  ): AsyncGenerator<DocumentPage>;
+  close(): Promise<void>;
+}
+
+export interface CreateDocumentEngineOptions {
+  readonly engine?: OcrEngine;
+  readonly engineOptions?: CreateEngineOptions;
+}
+
+export interface RecognizeDocumentOptions extends DocumentOptions {
+  readonly engine?: OcrEngine;
+  readonly engineOptions?: CreateEngineOptions;
+}
+
+export function createDocumentEngine(
+  options?: CreateDocumentEngineOptions,
+): Promise<DocumentEngine>;
+
+export function recognizeDocument(
+  source: DocumentInput | ReadonlyArray<DocumentInput>,
+  options?: RecognizeDocumentOptions,
+): AsyncGenerator<DocumentPage>;
+
+export function getVersion(): string;
+export function hasPdfSupport(): boolean;

package/src/index.mjs

@@ -3,3 +3,7 @@ import cjs from './index.cjs';
 export const createEngine = cjs.createEngine;
 export const OcrError = cjs.OcrError;
 export const modelProfile = cjs.modelProfile;
+export const createDocumentEngine = cjs.createDocumentEngine;
+export const getVersion = cjs.getVersion;
+export const hasPdfSupport = cjs.hasPdfSupport;
+export const recognizeDocument = cjs.recognizeDocument;