@arcships/light-ocr 0.3.4 → 0.5.1

package/README.md

@@ -1,14 +1,10 @@
 # @arcships/light-ocr
 
-Offline OCR for Node.js applications, powered by PP-OCRv6 Small.
+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.
 
 ```bash
 npm install @arcships/light-ocr
+light-ocr info --version
 ```
 
-The default PP-OCRv6 Small model is included as a required dependency; no
-runtime model download or postinstall compilation is used.
-
-Documentation: https://github.com/arcships/light-ocr
-
-License: Apache-2.0
+`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.

package/package.json

@@ -1,51 +1,38 @@
 {
   "bin": {
-    "light-ocr": "./bin/light-ocr.cjs"
+    "light-ocr": "./src/cli.cjs"
   },
   "bugs": {
     "url": "https://github.com/arcships/light-ocr/issues"
   },
   "dependencies": {
-    "@arcships/light-ocr-model-ppocrv6-small": "0.3.4"
+    "@arcships/light-ocr-model-ppocrv6-small": "0.3.4",
+    "@arcships/light-ocr-runtime": "0.1.1"
   },
-  "description": "Offline PP-OCRv6 OCR for Node.js, powered by an embeddable C++ core",
+  "description": "Offline PP-OCRv6 Small OCR for Node.js — the stable default tier",
   "engines": {
     "node": "^22.0.0 || ^24.0.0"
   },
   "exports": {
     ".": {
-      "import": "./js/index.mjs",
-      "require": "./js/index.cjs",
-      "types": "./js/index.d.ts"
+      "import": "./src/index.mjs",
+      "require": "./src/index.cjs",
+      "types": "./src/index.d.ts"
     }
   },
   "files": [
-    "js/",
-    "bin/",
+    "src/",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
   "homepage": "https://github.com/arcships/light-ocr#readme",
-  "keywords": [
-    "ocr",
-    "offline-ocr",
-    "pp-ocrv6",
-    "paddleocr",
-    "node-api",
-    "napi"
-  ],
   "license": "Apache-2.0",
-  "main": "./js/index.cjs",
-  "module": "./js/index.mjs",
+  "main": "./src/index.cjs",
+  "module": "./src/index.mjs",
   "name": "@arcships/light-ocr",
   "optionalDependencies": {
-    "@arcships/light-ocr-darwin-arm64": "0.3.4",
-    "@arcships/light-ocr-darwin-x64": "0.3.4",
-    "@arcships/light-ocr-linux-arm64-gnu": "0.3.4",
-    "@arcships/light-ocr-linux-x64-gnu": "0.3.4",
-    "@arcships/light-ocr-win32-arm64": "0.3.4",
-    "@arcships/light-ocr-win32-x64": "0.3.4"
+    "pdfium-native": "0.6.1"
   },
   "publishConfig": {
     "access": "public",
@@ -56,6 +43,6 @@
     "url": "git+https://github.com/arcships/light-ocr.git"
   },
   "type": "commonjs",
-  "types": "./js/index.d.ts",
-  "version": "0.3.4"
+  "types": "./src/index.d.ts",
+  "version": "0.5.1"
 }

package/src/cli.cjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+
+const facade = require('./index.cjs');
+
+// Try to use workspace dependencies, fallback to local paths
+let createCli, coreVersion, loadNative;
+try {
+  ({ createCli } = require('@arcships/light-ocr-runtime/cli'));
+  ({ coreVersion } = require('@arcships/light-ocr-runtime/metadata'));
+} catch {
+  // Fallback to local runtime
+  ({ createCli } = require(path.join(__dirname, '..', '..', 'runtime', 'src', 'cli.cjs')));
+  ({ coreVersion } = require(path.join(__dirname, '..', '..', 'runtime', 'src', 'metadata.cjs')));
+}
+try {
+  ({ loadNative } = require('@arcships/light-ocr-runtime'));
+} catch {
+  try {
+    ({ loadNative } = require(path.join(__dirname, '..', '..', 'runtime', 'src', 'load-native.cjs')));
+  } catch {
+    // loadNative unavailable — doctor will report native as unavailable
+  }
+}
+
+const packageMetadata = require('../package.json');
+
+const cli = createCli({
+  ...facade,
+  commandName: 'light-ocr',
+  packageVersion: packageMetadata.version,
+  coreVersion,
+  loadNative,
+});
+
+if (require.main === module) {
+  cli.main(process.argv.slice(2)).then((code) => {
+    if (code !== cli.EXIT.success) process.exitCode = code;
+  });
+}
+
+module.exports = cli;

package/src/index.cjs

@@ -0,0 +1,286 @@
+'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 facade = createModelFacade({
+  model: 'ppocrv6-small',
+  modelPackage: '@arcships/light-ocr-model-ppocrv6-small',
+  compatibleBundleIds: [
+    'ppocrv6-small-onnx-20260714.2',
+    'ppocrv6-small-apple-20260715.1',
+    'ppocrv6-small-webgpu-20260719.1',
+    'ppocrv6-small-native-20260719.1',
+  ],
+  appleBundleIds: [
+    'ppocrv6-small-apple-20260715.1',
+    'ppocrv6-small-native-20260719.1',
+  ],
+  profile: {
+    tier: 'small',
+    model: 'ppocrv6-small',
+    bundleId: 'ppocrv6-small-native-20260719.1',
+    languages: 50,
+    excludedLanguages: [],
+    dictionaryEntries: 18709,
+    maturity: 'stable',
+  },
+});
+
+// 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 = {
+  ...facade,
+  hasPdfSupport,
+  recognizeDocument
+};

package/src/index.d.ts

@@ -0,0 +1,21 @@
+export * from '@arcships/light-ocr-runtime';
+
+import type {
+  CreateEngineOptions as RuntimeCreateEngineOptions,
+  ModelProfile,
+  OcrEngine,
+} from '@arcships/light-ocr-runtime';
+
+export type BuiltInModel = 'ppocrv6-small';
+
+export type CreateEngineOptions = Omit<RuntimeCreateEngineOptions, 'bundlePath'> & {
+  readonly model?: BuiltInModel;
+  readonly bundlePath?: string;
+};
+
+export function createEngine(options?: CreateEngineOptions): Promise<OcrEngine>;
+export const modelProfile: ModelProfile & {
+  readonly tier: 'small';
+  readonly model: BuiltInModel;
+  readonly maturity: 'stable';
+};

package/{js → src}/index.mjs

@@ -2,3 +2,4 @@ import cjs from './index.cjs';
 
 export const createEngine = cjs.createEngine;
 export const OcrError = cjs.OcrError;
+export const modelProfile = cjs.modelProfile;