v0.5.0 — OCR + render-backend pipeline (100% on insurance corpus)

[rrader26]

Summary

Pages with no extractable text — scanner output, "Microsoft Print To PDF" exports, image-only PDFs — can now be rasterized + OCR'd transparently. Two render backends + two OCR backends ship; the interfaces let callers plug in any provider.

Stacked on top of #3 (M2). Merge #2 → #3 → this PR in order.

Real-world impact

12-doc insurance corpus (the same one used to drive M2 design):

Mode	🟢 ≥70	🟡 30-69	🔴 <30
Without OCR (v0.4)	6 (50%)	6 (50%)	0
With OCR (Poppler+Tesseract)	12 (100%)	0	0

Failing categories before — all now resolved by OCR:

• "Microsoft Print To PDF" vector-glyph PDFs (4 docs)
• Scanner output (2 docs)

Sample output from an Erie Auto Quote PDF (was: 0 text items extracted; now: a full structured snapshot):

HAMMETT INSURANCE AGENCY INC 05/26/2026 ...
TRACEY LYNN RADER ...
[PAGE:p_2]
Total Annual Policy Premium Quoted: $2,107.16
[PAGE:p_3]
### Payment Plan Options
- Annual (Plan A) ...
- Monthly Auto-Pay (Plan G) ...
[PAGE:p_4]
### PA0021 02/26 Page 5 of §
- Diminishing deductible — your deductible is reduced for each consecutive claims-free year ...

Architecture

```
PDF page ──[RenderBackend]──► PNG/JPEG bytes ──[OcrBackend]──► Text + positions
```

• `OcrBackend` — `extractPage(image, opts)` → text + confidence + optional positioned items
• `RenderBackend` — `renderPage(pdfData, opts)` → image bytes
• `convertPdf({ ocr: { render, ocr, mode } })` — opt-in pipeline:
  • `'auto'` (default): OCR only pages with no extractable text — mixed PDFs get cheap partial OCR
  • `'always'`: OCR every page (overrides extracted text)
  • `'never'`: disable OCR
• `document.ocr_used` flag set to `true` when OCR was applied

Bundled backends

Render:

Backend	Install	When
`PopplerRenderBackend`	`brew install poppler` / `apt install poppler-utils`	Lightest — no native modules
`PdfjsRenderBackend`	`npm install canvas`	Pure-Node, no system deps

OCR:

Backend	Install	Cost	Quality
`TesseractOcrBackend`	`npm install tesseract.js@^5`	Free	Decent on clean text
`MistralOcrBackend`	(none — uses fetch)	~$1/1k pages	Excellent, layout-aware

Bring-your-own (AWS Textract, Google Document AI, Apple Vision) all fit the same interface.

Tests

• 8 new OCR pipeline unit tests with mocked backends (deterministic, fast)
• All 176 unit + 10 real-Chromium tests still passing

Test plan

• Merge v0.3.0 — production-ready SDK surface + action executor #2, v0.4.0 — PDF support + spec v0.2 (kind: document) #3 first (in order)
• `npm install && npm test` — all 176 unit tests pass
• Smoke-test OCR end-to-end: `npx tsx examples/ocr-pdf.ts `
• Diagnostic with OCR: `npx tsx examples/diagnose-pdf.ts --ocr --out report.md`
• Verify backwards compat: PDFs without `ocr` option behave identically to v0.4
• Verify cleanup: Tesseract worker terminates after each run (no zombie processes)
• CHANGELOG.md and README.md read sensibly

🤖 Generated with Claude Code