macos-vision 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.2.0](https://github.com/woladi/macos-vision/compare/v1.1.0...v1.2.0) (2026-04-09)
+
+### Features
+
+* replace sips with PDFKit-based pdf-helper binary for PDF rasterization ([4a223e2](https://github.com/woladi/macos-vision/commit/4a223e2de79571794d866452fd5e87b84590ff0d))
+
 ## [1.1.0](https://github.com/woladi/macos-vision/compare/v1.0.3...v1.1.0) (2026-04-09)
 
 ### Features

package/dist/index.d.ts

@@ -1,3 +1,24 @@
+export interface PdfPage {
+    /** 0-based page index */
+    page: number;
+    /** Absolute path to the rasterized PNG file */
+    path: string;
+}
+export interface PdfRasterizeResult {
+    /** Pages in document order */
+    pages: PdfPage[];
+    /** Directory containing all rasterized PNGs */
+    cacheDir: string;
+}
+/**
+ * Rasterizes a PDF to 300 DPI PNG files using the native `pdf-helper` binary
+ * (PDFKit-based). Files are saved persistently to `~/.cache/macos-vision/`
+ * so they can be reused by downstream tools — **caller is responsible for cleanup**.
+ *
+ * @param pdfPath - Absolute or relative path to the PDF file.
+ * @returns An object with `pages` (sorted array of `{page, path}`) and `cacheDir`.
+ */
+export declare function rasterizePdf(pdfPath: string): Promise<PdfRasterizeResult>;
 export interface VisionBlock {
     /** Recognized text */
     text: string;

package/dist/index.js

@@ -1,14 +1,14 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { resolve, dirname, extname, join } from 'path';
+import { resolve, dirname, extname, dirname as pathDirname } from 'path';
 import { fileURLToPath } from 'url';
-import { tmpdir } from 'os';
-import { open, mkdir, readdir, rm } from 'fs/promises';
+import { open } from 'fs/promises';
 const execFileAsync = promisify(execFile);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const BIN_PATH = resolve(__dirname, '../bin/vision-helper');
+const PDF_BIN_PATH = resolve(__dirname, '../bin/pdf-helper');
 const BINARY_TIMEOUT_MS = 30_000;
-const SIPS_TIMEOUT_MS = 60_000;
+const PDF_RASTERIZE_TIMEOUT_MS = 120_000;
 async function run(flag, imagePath) {
     const { stdout } = await execFileAsync(BIN_PATH, [flag, resolve(imagePath)], {
         timeout: BINARY_TIMEOUT_MS,
@@ -36,49 +36,41 @@ async function isPdf(filePath) {
     }
 }
 /**
- * Rasterizes a PDF to PNG files in `outDir` using macOS `sips`.
- * Returns sorted list of absolute PNG paths (order = page order).
+ * Rasterizes a PDF to 300 DPI PNG files using the native `pdf-helper` binary
+ * (PDFKit-based). Files are saved persistently to `~/.cache/macos-vision/`
+ * so they can be reused by downstream tools — **caller is responsible for cleanup**.
  *
- * sips names single-page output `{basename}.png` and multi-page output
- * `{basename}-1.png`, `{basename}-2.png`, etc. The numeric sort handles both.
+ * @param pdfPath - Absolute or relative path to the PDF file.
+ * @returns An object with `pages` (sorted array of `{page, path}`) and `cacheDir`.
  */
-async function rasterizePdf(pdfPath, outDir) {
-    await execFileAsync('sips', ['-s', 'format', 'png', '--resampleHeight', '2000', pdfPath, '--out', outDir], { timeout: SIPS_TIMEOUT_MS });
-    const entries = await readdir(outDir);
-    const pngs = entries.filter((n) => n.toLowerCase().endsWith('.png'));
-    pngs.sort((a, b) => {
-        const numA = parseInt(a.match(/-(\d+)\.png$/i)?.[1] ?? '0', 10);
-        const numB = parseInt(b.match(/-(\d+)\.png$/i)?.[1] ?? '0', 10);
-        return numA - numB;
+export async function rasterizePdf(pdfPath) {
+    const absPath = resolve(pdfPath);
+    const { stdout } = await execFileAsync(PDF_BIN_PATH, [absPath], {
+        timeout: PDF_RASTERIZE_TIMEOUT_MS,
     });
-    return pngs.map((n) => join(outDir, n));
+    const pages = JSON.parse(stdout);
+    const cacheDir = pages.length > 0 ? pathDirname(pages[0].path) : '';
+    return { pages, cacheDir };
 }
 /**
- * Full PDF OCR pipeline: rasterize → per-page OCR → merge results.
- * Temporary PNG files are always cleaned up in the `finally` block.
+ * Internal PDF OCR pipeline: rasterize via pdf-helper → OCR each page → merge.
+ * PNG files are NOT cleaned up — they persist in ~/.cache/macos-vision/.
  */
 async function ocrPdf(pdfPath, format) {
-    const outDir = join(tmpdir(), `macos-vision-${globalThis.crypto.randomUUID()}`);
-    await mkdir(outDir, { recursive: true });
-    try {
-        const pages = await rasterizePdf(pdfPath, outDir);
-        if (format === 'blocks') {
-            const all = [];
-            for (let i = 0; i < pages.length; i++) {
-                const blocks = (await ocr(pages[i], { format: 'blocks' }));
-                all.push(...blocks.map((b) => ({ ...b, page: i })));
-            }
-            return all;
-        }
-        const texts = [];
-        for (let i = 0; i < pages.length; i++) {
-            texts.push((await ocr(pages[i])));
+    const { pages } = await rasterizePdf(pdfPath);
+    if (format === 'blocks') {
+        const all = [];
+        for (const { page, path: pagePath } of pages) {
+            const blocks = (await ocr(pagePath, { format: 'blocks' }));
+            all.push(...blocks.map((b) => ({ ...b, page })));
         }
-        return texts.join('\n\n--- Page Break ---\n\n');
+        return all;
     }
-    finally {
-        await rm(outDir, { recursive: true, force: true });
+    const texts = [];
+    for (const { path: pagePath } of pages) {
+        texts.push((await ocr(pagePath)));
     }
+    return texts.join('\n\n--- Page Break ---\n\n');
 }
 export async function ocr(imagePath, options = {}) {
     const absPath = resolve(imagePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macos-vision",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Apple Vision OCR & image analysis for Node.js — native, fast, offline, no API keys",
   "author": "Adrian Wolczuk",
   "license": "MIT",

package/scripts/build-native.js

@@ -6,21 +6,36 @@ import path from 'path';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 const binDir = path.join(root, 'bin');
-const binPath = path.join(binDir, 'vision-helper');
-const swiftSrc = path.join(root, 'src', 'native', 'vision-helper.swift');
 
-if (existsSync(binPath)) {
+const binaries = [
+  {
+    src: path.join(root, 'src', 'native', 'vision-helper.swift'),
+    out: path.join(binDir, 'vision-helper'),
+    name: 'vision-helper',
+  },
+  {
+    src: path.join(root, 'src', 'native', 'pdf-helper.swift'),
+    out: path.join(binDir, 'pdf-helper'),
+    name: 'pdf-helper',
+  },
+];
+
+const allExist = binaries.every(({ out }) => existsSync(out));
+if (allExist) {
   process.exit(0);
 }
 
 mkdirSync(binDir, { recursive: true });
 
-try {
-  execSync(`swiftc -O "${swiftSrc}" -o "${binPath}"`, { stdio: 'inherit' });
-  console.log('✅ macos-vision: native binary compiled successfully');
-} catch {
-  console.error('❌ macos-vision: Swift compilation failed.');
-  console.error('   Make sure Xcode Command Line Tools are installed:');
-  console.error('   xcode-select --install');
-  process.exit(1);
+for (const { src, out, name } of binaries) {
+  if (existsSync(out)) continue;
+  try {
+    execSync(`swiftc -O "${src}" -o "${out}"`, { stdio: 'inherit' });
+    console.log(`✅ macos-vision: ${name} compiled successfully`);
+  } catch {
+    console.error(`❌ macos-vision: ${name} compilation failed.`);
+    console.error('   Make sure Xcode Command Line Tools are installed:');
+    console.error('   xcode-select --install');
+    process.exit(1);
+  }
 }