macos-vision 1.0.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+* add PDF support via sips rasterization ([a48bf17](https://github.com/woladi/macos-vision/commit/a48bf17579a6df11aed6eadbde4fa5041ccaa981))
+
 ## [1.0.3](https://github.com/woladi/macos-vision/compare/v1.0.2...v1.0.3) (2026-04-08)
 
 ### Reverts

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;
@@ -11,6 +32,8 @@ export interface VisionBlock {
     height: number;
     /** OCR transcription confidence, 0–1 */
     confidence: number;
+    /** 0-based page index. Present only when the source was a PDF. Absent for images. */
+    page?: number;
 }
 export interface OcrOptions {
     /** Return plain text (default) or structured blocks with coordinates */

package/dist/index.js

@@ -1,20 +1,85 @@
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { resolve, dirname } from 'path';
+import { resolve, dirname, extname, dirname as pathDirname } from 'path';
 import { fileURLToPath } from 'url';
+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 PDF_RASTERIZE_TIMEOUT_MS = 120_000;
 async function run(flag, imagePath) {
     const { stdout } = await execFileAsync(BIN_PATH, [flag, resolve(imagePath)], {
         timeout: BINARY_TIMEOUT_MS,
     });
     return stdout;
 }
+// ─── PDF helpers ─────────────────────────────────────────────────────────────
+/**
+ * Returns true if the file at `filePath` is a PDF.
+ * Uses extension as a fast path; falls back to magic bytes (`%PDF`) for
+ * files whose extension does not match their actual content.
+ */
+async function isPdf(filePath) {
+    if (extname(filePath).toLowerCase() === '.pdf')
+        return true;
+    let fh;
+    try {
+        fh = await open(filePath, 'r');
+        const buf = Buffer.alloc(4);
+        await fh.read(buf, 0, 4, 0);
+        return buf[0] === 0x25 && buf[1] === 0x50 && buf[2] === 0x44 && buf[3] === 0x46;
+    }
+    finally {
+        await fh?.close();
+    }
+}
+/**
+ * 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 async function rasterizePdf(pdfPath) {
+    const absPath = resolve(pdfPath);
+    const { stdout } = await execFileAsync(PDF_BIN_PATH, [absPath], {
+        timeout: PDF_RASTERIZE_TIMEOUT_MS,
+    });
+    const pages = JSON.parse(stdout);
+    const cacheDir = pages.length > 0 ? pathDirname(pages[0].path) : '';
+    return { pages, cacheDir };
+}
+/**
+ * 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 { 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 all;
+    }
+    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);
     const { format = 'text' } = options;
+    // ── PDF fast-path: rasterize via sips, then OCR each page ────────────────
+    if (await isPdf(absPath)) {
+        return ocrPdf(absPath, format);
+    }
+    // ── Existing image path (unchanged) ──────────────────────────────────────
     if (format === 'blocks') {
         const { stdout } = await execFileAsync(BIN_PATH, ['--json', absPath], {
             timeout: BINARY_TIMEOUT_MS,

package/dist/layout.d.ts

@@ -85,6 +85,14 @@ export declare function sortBlocksByReadingOrder(blocks: LayoutBlock[]): LayoutB
  * (`paragraphId`) using simple bounding-box heuristics. All other block types
  * are placed into the sorted sequence by their top-left coordinate.
  *
+ * **Multi-page PDFs**: `VisionBlock` items from PDF OCR carry an optional `page` field (0-based).
+ * Because all coordinates are page-local (0–1 relative to each page), mixing blocks from
+ * different pages produces meaningless geometry. Pre-filter by page before calling inferLayout:
+ * ```ts
+ * const pageBlocks = pdfBlocks.filter(b => b.page === 0);
+ * const layout = inferLayout({ textBlocks: pageBlocks });
+ * ```
+ *
  * @example
  * ```ts
  * const blocks  = await ocr('page.png', { format: 'blocks' });

package/dist/layout.js

@@ -114,6 +114,14 @@ export function sortBlocksByReadingOrder(blocks) {
  * (`paragraphId`) using simple bounding-box heuristics. All other block types
  * are placed into the sorted sequence by their top-left coordinate.
  *
+ * **Multi-page PDFs**: `VisionBlock` items from PDF OCR carry an optional `page` field (0-based).
+ * Because all coordinates are page-local (0–1 relative to each page), mixing blocks from
+ * different pages produces meaningless geometry. Pre-filter by page before calling inferLayout:
+ * ```ts
+ * const pageBlocks = pdfBlocks.filter(b => b.page === 0);
+ * const layout = inferLayout({ textBlocks: pageBlocks });
+ * ```
+ *
  * @example
  * ```ts
  * const blocks  = await ocr('page.png', { format: 'blocks' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macos-vision",
-  "version": "1.0.3",
+  "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);
+  }
 }