@arcships/light-ocr 0.5.4 → 0.5.6

package/README.md

@@ -1,36 +1,299 @@
 # @arcships/light-ocr
 
-The stable PP-OCRv6 Small entry for local image OCR on Node.js 22 and 24.
+[![npm version](https://img.shields.io/npm/v/%40arcships%2Flight-ocr?color=CB3837)](https://www.npmjs.com/package/@arcships/light-ocr)
+[![Node.js 22 and 24](https://img.shields.io/badge/Node.js-22%20%7C%2024-339933)](https://nodejs.org/)
+[![Apache-2.0](https://img.shields.io/npm/l/%40arcships%2Flight-ocr)](https://github.com/arcships/light-ocr/blob/main/LICENSE)
+
+![light-ocr](https://raw.githubusercontent.com/arcships/light-ocr/main/docs/assets/light-ocr-banner.png)
+
+**Offline image and PDF OCR for Node.js — prebuilt, typed, and
+self-contained.**
+
+`@arcships/light-ocr` is the stable PP-OCRv6 Small package. It recognizes
+JPEG, PNG, PDF, decoded pixels, and multi-page image jobs without Python,
+cloud APIs, postinstall downloads, or local native compilation.
+
+| | |
+| --- | --- |
+| **Input** | JPEG, PNG, PDF, `Uint8Array`, or decoded pixel buffers |
+| **Output** | text lines in reading order, confidence, quadrilateral boxes, and timing |
+| **Runtime** | CommonJS + ESM + bundled TypeScript declarations |
+| **Platforms** | macOS, Linux glibc, and Windows on x64 and ARM64 |
+| **Node.js** | 22 and 24 |
+
+## Install
 
 ```bash
 npm install @arcships/light-ocr
+```
+
+That single command installs the Small model, shared JavaScript runtime, and
+the native OCR/PDF package matching the current platform. The package has no
+install script and remains installable with scripts disabled.
+
+## Quick start
+
+### Recognize an image
+
+```js
+import { createEngine } from "@arcships/light-ocr";
+import { readFile } from "node:fs/promises";
+
+const engine = await createEngine();
+
+try {
+  const result = await engine.recognizeEncoded(
+    await readFile("receipt.png"),
+  );
+
+  for (const line of result.lines) {
+    console.log(line.text, line.confidence, line.box);
+  }
+} finally {
+  await engine.close();
+}
+```
+
+CommonJS uses the same API:
+
+```js
+const { createEngine } = require("@arcships/light-ocr");
+```
+
+### Stream pages from a PDF
+
+```js
+import { recognizeDocument } from "@arcships/light-ocr";
+
+for await (const page of recognizeDocument("report.pdf", {
+  dpi: 200,
+  pageRange: { start: 1, end: 10 },
+})) {
+  console.log(`page ${page.index + 1}`);
+  for (const line of page.lines) console.log(line.text);
+}
+```
+
+`recognizeDocument()` accepts a file path, PDF/image bytes, or an array of
+image paths and byte buffers. Pages are yielded as they finish, so callers do
+not need to retain the complete document result.
+
+### Use the CLI
+
+The `light-ocr` command is included:
+
+```bash
+# Image OCR
 light-ocr image.png --format text
+
+# PDF OCR; PDFium and the fallback font are already installed
+light-ocr report.pdf --pages 1-10 --format jsonl
+
+# Multiple images as one document
+light-ocr document scan-1.png scan-2.png scan-3.png --format text
+
+# Detection only
+light-ocr detect screenshot.png
+
+# Voluntary hardware/provider diagnostics
 light-ocr doctor --json
 ```
 
-The package exact-pins one model-free runtime, the Small model, and the native
-component for the current platform. It has no install script and its complete
-release closure is tested with npm offline and scripts disabled.
+## Everything needed for PDF OCR is included
+
+The package does not defer essential files to an installer or first-run
+download:
+
+| Component | Distribution |
+| --- | --- |
+| PP-OCRv6 Small model | exact-pinned required npm dependency |
+| JavaScript runtime and types | exact-pinned required npm dependency |
+| Native OCR addon and runtime libraries | matching platform npm dependency |
+| PDFium addon and shared library | inside the matching platform package |
+| Noto Sans SC fallback font and OFL license | inside the matching platform package |
+
+The bundled, checksum-pinned fallback font is used when a PDF references a
+common Chinese font without embedding its glyphs. PDFium therefore renders the
+page correctly before OCR instead of handing missing-glyph boxes to the model.
+
+There is no postinstall fetch, runtime font/model/PDFium download, GitHub
+access, compiler requirement, or system Chinese-font requirement on customer
+machines.
+
+## Node.js API
+
+### Main exports
+
+| Export | Purpose |
+| --- | --- |
+| `createEngine(options?)` | Create a reusable image OCR engine |
+| `recognizeDocument(source, options?)` | Stream PDF or image pages with automatic cleanup |
+| `createDocumentEngine(options?)` | Reuse one engine across multiple document jobs |
+| `hasPdfSupport()` | Check that the bundled PDF renderer can be loaded |
+| `modelProfile` | Inspect the selected model tier and language metadata |
+| `OcrError` | Stable typed error with a machine-readable `code` |
+
+### Recognize decoded pixels
+
+Applications that already decode images can avoid re-encoding:
+
+```js
+const result = await engine.recognize({
+  data: rgbaBytes,
+  width,
+  height,
+  stride: width * 4,
+  pixelFormat: "rgba8",
+});
+```
+
+Supported pixel formats are `gray8`, `rgb8`, `bgr8`, and `rgba8`.
+
+### Region, cancellation, and execution provider
 
 ```js
-const { createEngine } = require('@arcships/light-ocr');
+const controller = new AbortController();
+
+const engine = await createEngine({
+  execution: { provider: "auto" },
+  queueCapacity: 4,
+});
 
-const engine = await createEngine();
 try {
-  const result = await engine.recognizeEncoded(imageBytes);
+  const result = await engine.recognizeEncoded(imageBytes, {
+    region: { x: 100, y: 80, width: 640, height: 320 },
+    applyExif: true,
+    signal: controller.signal,
+  });
+
   console.log(result.lines);
+  console.log(engine.info.execution.selectionTrace);
 } finally {
   await engine.close();
 }
 ```
 
-PDF and multi-page processing are intentionally separate:
+Recognition runs on a dedicated worker instead of blocking the JavaScript main
+thread. Queues are bounded, `AbortSignal` is supported, and engines must be
+closed explicitly when the application is finished with them.
+
+### Document resource limits
+
+PDF and multi-page calls apply conservative defaults before or during
+rendering:
+
+| Option | Default |
+| --- | ---: |
+| `dpi` | 150 |
+| `maxFileBytes` | 100 MiB per input |
+| `maxPages` | 100 |
+| `maxPagePixels` | 4096 × 4096 |
+| `maxTotalPixels` | 100 Mi pixels |
+
+Limits are configurable per call. Violations reject with
+`OcrError.code === "resource_limit_exceeded"`.
+
+### Result shape
+
+Image OCR returns one line entry per recognized line:
+
+```json
+{
+  "text": "TOTAL 42.00",
+  "confidence": 0.98,
+  "box": [
+    { "x": 24, "y": 80 },
+    { "x": 190, "y": 80 },
+    { "x": 190, "y": 108 },
+    { "x": 24, "y": 108 }
+  ]
+}
+```
+
+Coordinates use `pageSpace`: top-left origin, positive x to the right, and
+positive y downward after EXIF correction. Document pages add a stable page
+index, source metadata, dimensions, applied PDF transforms, and timing.
+
+## CLI reference
+
+| Command | Purpose |
+| --- | --- |
+| `light-ocr [recognize] <image>` | Full image OCR; `recognize` is optional |
+| `light-ocr <document.pdf>` | Stream a PDF through document OCR |
+| `light-ocr document <source...>` | Process a PDF or multiple page images |
+| `light-ocr detect <image>` | Return text-region boxes without recognition |
+| `light-ocr info --version` | Print package/Core version information |
+| `light-ocr info --model-info` | Print model and execution information |
+| `light-ocr doctor --json` | Print voluntary system/provider diagnostics |
+
+Image OCR supports `--format json|jsonl|text`, `--region x,y,w,h`,
+`--provider auto|cpu|apple|webgpu`, `--stdin`, and automatic EXIF correction.
+Document OCR adds `--pages N-M`, `--dpi`, and the page/file/pixel limit flags.
+
+`detect` always emits structured JSON and does not accept `--format`.
+Diagnostics do not include the hostname or a stable device identifier.
+
+## Platform acceleration
+
+The default `provider: "auto"` chooses a qualified accelerator when available
+and ends with CPU as the stable fallback:
+
+| Platform | Auto path |
+| --- | --- |
+| macOS 15+ on Apple Silicon | Core ML, then CPU |
+| macOS on Intel | CPU |
+| Linux x64 with glibc | WebGPU through Vulkan, then CPU |
+| Linux arm64 with glibc | CPU |
+| Windows x64 | WebGPU through D3D12, then CPU |
+| Windows arm64 | CPU |
+
+Explicit `cpu`, `apple`, and `webgpu` requests fail closed when the requested
+provider is unavailable; they do not silently switch providers.
+
+## Model tiers
+
+This package is the stable Small tier. Tiny and Medium are opt-in previews with
+the same API, types, result schema, and error model:
+
+| Tier | Install | Model payload | Status |
+| --- | --- | ---: | --- |
+| Small | `npm install @arcships/light-ocr` | about 30 MB | stable default |
+| Tiny | `npm install @arcships/light-ocr-tiny@next` | about 6.3 MB | preview; 49 languages, no Japanese |
+| Medium | `npm install @arcships/light-ocr-medium@next` | about 139 MB | preview; quality-first |
+
+Each facade installs only its selected model.
+
+## Errors and diagnostics
+
+Expected failures reject with `OcrError` and a stable `code`, including
+`invalid_argument`, `invalid_image`, `resource_limit_exceeded`,
+`package_load_failed`, and `inference_failed`.
+
+For environment reports:
 
 ```bash
-npm install @arcships/light-ocr-document@next
-light-ocr-document report.pdf --format jsonl
+light-ocr doctor --json
 ```
 
-The Document package is preview software and runs its pinned PDF renderer's
-prebuild installer. Keeping that dependency explicit prevents PDF tooling from
-changing the stable image package's installation contract.
+For package/PDF capability checks:
+
+```js
+import { hasPdfSupport, modelProfile } from "@arcships/light-ocr";
+
+console.log(hasPdfSupport());
+console.log(modelProfile);
+```
+
+## Documentation
+
+- [Project overview](https://github.com/arcships/light-ocr)
+- [Node.js and CLI reference](https://github.com/arcships/light-ocr/blob/main/bindings/node/README.md)
+- [PDF 0.5.6 release notes](https://github.com/arcships/light-ocr/blob/main/docs/releases/npm-0.5.6.en.md)
+- [Agent Skill](https://github.com/arcships/light-ocr/blob/main/.agents/skills/local-ocr/SKILL.md)
+- [Changelog](https://github.com/arcships/light-ocr/blob/main/CHANGELOG.md)
+- [Issues](https://github.com/arcships/light-ocr/issues)
+
+## License
+
+Apache-2.0. The package also carries the applicable licenses and notices for
+the bundled PP-OCRv6 model, native runtimes, PDFium, and Noto Sans SC font.

package/package.json

@@ -7,9 +7,9 @@
   },
   "dependencies": {
     "@arcships/light-ocr-model-ppocrv6-small": "0.3.4",
-    "@arcships/light-ocr-runtime": "0.1.4"
+    "@arcships/light-ocr-runtime": "0.1.6"
   },
-  "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/",
@@ -41,5 +42,5 @@
   },
   "type": "commonjs",
   "types": "./src/index.d.ts",
-  "version": "0.5.4"
+  "version": "0.5.6"
 }

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,8 +1,9 @@
 'use strict';
 
 const { createModelFacade } = require('@arcships/light-ocr-runtime/facade');
+const { createDocumentApi } = require('./document.cjs');
 
-module.exports = createModelFacade({
+const facade = createModelFacade({
   model: 'ppocrv6-small',
   modelPackage: '@arcships/light-ocr-model-ppocrv6-small',
   compatibleBundleIds: [
@@ -25,3 +26,8 @@ module.exports = createModelFacade({
     maturity: 'stable',
   },
 });
+
+module.exports = Object.freeze({
+  ...facade,
+  ...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;