Skip to content

A fast, helpful, and open-source document parser

fix(wasm): run browser OCR without Tokio

Choudhry Abdullahdf41d4479ee2
diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rs
index ba6adcb..2237c80 100644
--- a/crates/liteparse/src/ocr_merge.rs
+++ b/crates/liteparse/src/ocr_merge.rs
@@ -544,6 +544,31 @@ pub(crate) async fn ocr_and_merge_rendered(
num_workers: usize,
ocr_failure_fatal: bool,
) -> Result<(), LiteParseError> {
+ type OcrTaskResult = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>;
+
+ // Browser WASM uses the JavaScript event loop. It has no Tokio runtime or
+ // blocking thread pool. Run each JavaScript OCR callback directly so the
+ // returned Promise can make progress on the browser event loop.
+ #[cfg(target_arch = "wasm32")]
+ let task_results: Vec<(usize, usize, f32, OcrTaskResult)> = {
+ let _ = num_workers;
+ let mut results = Vec::with_capacity(rendered.len());
+ for r in rendered {
+ let idx = r.idx;
+ let page_number = pages[idx].page_number;
+ let page_dpi = r.dpi;
+ let options = OcrOptions {
+ language: ocr_language.to_string(),
+ dpi: page_dpi,
+ };
+ let result = ocr_engine
+ .recognize(&r.pixels, r.width, r.height, &options)
+ .await;
+ results.push((idx, page_number, page_dpi, result));
+ }
+ results
+ };
+
// Phase 1: spawn one async task per page. A semaphore limits how many run
// `recognize` concurrently to `num_workers`.
//
@@ -557,48 +582,63 @@ pub(crate) async fn ocr_and_merge_rendered(
// request never goes out, the permit is never released, and the whole OCR
// pass deadlocks. Acquiring the permit asynchronously parks the lightweight
// task instead, so only `num_workers` blocking threads are ever consumed.
- let num_workers = num_workers.max(1);
- let semaphore = Arc::new(tokio::sync::Semaphore::new(num_workers));
- let mut handles = Vec::with_capacity(rendered.len());
-
- let handle = tokio::runtime::Handle::current();
-
- for r in rendered {
- let engine = ocr_engine.clone();
- let sem = semaphore.clone();
- let language = ocr_language.to_string();
- let page_number = pages[r.idx].page_number;
- let rt_handle = handle.clone();
-
- handles.push((
- r.idx,
- page_number,
- r.dpi,
- tokio::spawn(async move {
- // Park the task (not an OS thread) until a permit is available.
- let _permit = sem.acquire_owned().await.expect("semaphore closed");
- let options = OcrOptions {
- language,
- dpi: r.dpi,
- };
- // Offload the (possibly CPU-blocking, e.g. Tesseract) recognize
- // onto a blocking thread. Because the permit is already held,
- // at most `num_workers` blocking threads are in use at once,
- // leaving the rest of the pool free for the HTTP client's
- // internal DNS resolution.
- match tokio::task::spawn_blocking(move || {
- rt_handle.block_on(engine.recognize(&r.pixels, r.width, r.height, &options))
- })
- .await
- {
- Ok(result) => result,
- Err(join_err) => {
- Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)
+ #[cfg(not(target_arch = "wasm32"))]
+ let task_results: Vec<(usize, usize, f32, OcrTaskResult)> = {
+ let num_workers = num_workers.max(1);
+ let semaphore = Arc::new(tokio::sync::Semaphore::new(num_workers));
+ let mut handles = Vec::with_capacity(rendered.len());
+
+ let handle = tokio::runtime::Handle::current();
+
+ for r in rendered {
+ let engine = ocr_engine.clone();
+ let sem = semaphore.clone();
+ let language = ocr_language.to_string();
+ let page_number = pages[r.idx].page_number;
+ let rt_handle = handle.clone();
+
+ handles.push((
+ r.idx,
+ page_number,
+ r.dpi,
+ tokio::spawn(async move {
+ // Park the task (not an OS thread) until a permit is available.
+ let _permit = sem.acquire_owned().await.expect("semaphore closed");
+ let options = OcrOptions {
+ language,
+ dpi: r.dpi,
+ };
+ // Offload the (possibly CPU-blocking, e.g. Tesseract) recognize
+ // onto a blocking thread. Because the permit is already held,
+ // at most `num_workers` blocking threads are in use at once,
+ // leaving the rest of the pool free for the HTTP client's
+ // internal DNS resolution.
+ match tokio::task::spawn_blocking(move || {
+ rt_handle.block_on(engine.recognize(&r.pixels, r.width, r.height, &options))
+ })
+ .await
+ {
+ Ok(result) => result,
+ Err(join_err) => {
+ Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)
+ }
}
+ }),
+ ));
+ }
+
+ let mut results = Vec::with_capacity(handles.len());
+ for (idx, page_number, page_dpi, handle) in handles {
+ let result = match handle.await {
+ Ok(result) => result,
+ Err(join_err) => {
+ Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)
}
- }),
- ));
- }
+ };
+ results.push((idx, page_number, page_dpi, result));
+ }
+ results
+ };
// Phase 3: collect results and merge into pages.
@@ -614,32 +654,20 @@ pub(crate) async fn ocr_and_merge_rendered(
// enrichment but already has all its text. We must only fail loud when OCR
// failure destroyed a sparse page's likely primary text source — otherwise
// a broken OCR setup would abort perfectly good native-text documents.
- let total_tasks = handles.len();
+ let total_tasks = task_results.len();
let mut failed_tasks = 0usize;
let mut failed_sparse_text_page = false;
let mut first_error: Option<String> = None;
- for (idx, page_number, page_dpi, handle) in handles {
- let ocr_results: Vec<OcrResult> = match handle.await {
- Ok(Ok(results)) => results,
- Ok(Err(e)) => {
- failed_tasks += 1;
- failed_sparse_text_page |= page_has_sparse_native_text(&pages[idx]);
- // Only log the first failure to avoid flooding stderr with an
- // identical message for every page.
- if first_error.is_none() {
- let msg = e.to_string();
- eprintln!("[ocr] failed for page {}: {}", page_number, msg);
- first_error = Some(msg);
- }
- continue;
- }
+ for (idx, page_number, page_dpi, result) in task_results {
+ let ocr_results: Vec<OcrResult> = match result {
+ Ok(results) => results,
Err(e) => {
failed_tasks += 1;
failed_sparse_text_page |= page_has_sparse_native_text(&pages[idx]);
if first_error.is_none() {
let msg = e.to_string();
- eprintln!("[ocr] task panicked for page {}: {}", page_number, msg);
+ eprintln!("[ocr] failed for page {}: {}", page_number, msg);
first_error = Some(msg);
}
continue;
diff --git a/scripts/browser-compat/wasm-test.html b/scripts/browser-compat/wasm-test.html
index 88445f5..e16137d 100644
--- a/scripts/browser-compat/wasm-test.html
+++ b/scripts/browser-compat/wasm-test.html
@@ -3,6 +3,7 @@
<head>
<meta charset="UTF-8" />
<title>LiteParse WASM Browser Test</title>
+ <link rel="icon" href="data:," />
</head>
<body>
<div id="status">loading</div>
@@ -14,6 +15,32 @@
const resultEl = document.getElementById("result");
const errorEl = document.getElementById("error");
+ function buildBlankPdf() {
+ const objects = [
+ "<< /Type /Catalog /Pages 2 0 R >>",
+ "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+ "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 72 72] /Resources << >> /Contents 4 0 R >>",
+ "<< /Length 0 >>\nstream\n\nendstream",
+ ];
+
+ let pdf = "%PDF-1.4\n%1234\n";
+ const offsets = [0];
+ for (let index = 0; index < objects.length; index += 1) {
+ offsets.push(pdf.length);
+ pdf += `${index + 1} 0 obj\n${objects[index]}\nendobj\n`;
+ }
+
+ const xrefOffset = pdf.length;
+ pdf += `xref\n0 ${objects.length + 1}\n`;
+ pdf += "0000000000 65535 f \n";
+ for (const offset of offsets.slice(1)) {
+ pdf += `${String(offset).padStart(10, "0")} 00000 n \n`;
+ }
+ pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\n`;
+ pdf += `startxref\n${xrefOffset}\n%%EOF\n`;
+ return new TextEncoder().encode(pdf);
+ }
+
try {
status.textContent = "loading wasm";
const { default: init, LiteParse } = await import("/packages/wasm/pkg/liteparse_wasm.js");
@@ -37,11 +64,56 @@
if (pageCount === 0) throw new Error("No pages parsed");
if (!hasText) throw new Error(`Text too short: ${textLength} chars`);
+ status.textContent = "testing OCR callback";
+ let ocrCallbackCalls = 0;
+ let ocrByteLength = 0;
+ const ocrParser = new LiteParse({
+ ocrEnabled: true,
+ ocrLanguage: "eng",
+ outputFormat: "text",
+ dpi: 72,
+ quiet: true,
+ ocrEngine: {
+ async recognize(imageData, width, height, language) {
+ ocrCallbackCalls += 1;
+ if (!(imageData instanceof Uint8Array)) {
+ throw new Error("OCR input is not a Uint8Array");
+ }
+ if (imageData.length === 0) {
+ throw new Error("OCR input is empty");
+ }
+ if (width <= 0 || height <= 0) {
+ throw new Error(`Invalid OCR dimensions: ${width}x${height}`);
+ }
+ if (language !== "eng") {
+ throw new Error(`Unexpected OCR language: ${language}`);
+ }
+
+ ocrByteLength = imageData.length;
+ return [{
+ text: "WASM_OCR_CALLBACK_OK",
+ bbox: [4, 4, Math.max(8, width - 4), Math.min(24, height - 4)],
+ confidence: 0.99,
+ }];
+ },
+ },
+ });
+ const ocrResult = await ocrParser.parse(buildBlankPdf());
+
+ if (ocrCallbackCalls !== 1) {
+ throw new Error(`Expected one OCR callback, received ${ocrCallbackCalls}`);
+ }
+ if (!ocrResult.text.includes("WASM_OCR_CALLBACK_OK")) {
+ throw new Error("OCR callback text was not merged into the parse result");
+ }
+
status.textContent = "done";
resultEl.style.display = "block";
resultEl.setAttribute("data-pages", pageCount);
resultEl.setAttribute("data-text-length", textLength);
- resultEl.textContent = `OK: ${pageCount} pages, ${textLength} chars`;
+ resultEl.setAttribute("data-ocr-callbacks", ocrCallbackCalls);
+ resultEl.setAttribute("data-ocr-bytes", ocrByteLength);
+ resultEl.textContent = `OK: ${pageCount} pages, ${textLength} chars, OCR callback passed`;
} catch (err) {
status.textContent = "error";
errorEl.style.display = "block";
diff --git a/scripts/browser-compat/wasm-test.mjs b/scripts/browser-compat/wasm-test.mjs
index 01128df..e66c821 100644
--- a/scripts/browser-compat/wasm-test.mjs
+++ b/scripts/browser-compat/wasm-test.mjs
@@ -7,6 +7,7 @@
* Requires: playwright (npx playwright install chromium)
* Expects: packages/wasm/pkg/ to contain the built WASM files
* demo/docs/apple-10k-2024.pdf to exist
+ * Set PLAYWRIGHT_CHROMIUM_EXECUTABLE to use an existing browser executable.
*/
import { createServer } from "node:http";
@@ -67,35 +68,54 @@ async function main() {
let browser;
try {
- browser = await chromium.launch();
+ browser = await chromium.launch({
+ executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE,
+ });
const page = await browser.newPage();
- // Collect console errors
const errors = [];
- page.on("pageerror", (err) => errors.push(err.message));
+ let reportBrowserFailure;
+ const browserFailure = new Promise((resolvePromise) => {
+ reportBrowserFailure = resolvePromise;
+ });
+ page.on("pageerror", (error) => {
+ errors.push(error.message);
+ reportBrowserFailure(error);
+ });
+ page.on("console", (message) => {
+ if (message.type() === "error") {
+ const error = new Error(message.text());
+ errors.push(error.message);
+ reportBrowserFailure(error);
+ }
+ });
console.log("Navigating to test page...");
await page.goto(`${baseUrl}/scripts/browser-compat/wasm-test.html`);
- // Wait for either #result or #error to appear (up to 120s for large PDFs)
- await page.waitForSelector("#result[style*='block'], #error[style*='block']", {
- timeout: 120_000,
- });
+ const completion = page
+ .waitForSelector("#result[style*='block'], #error[style*='block']", { timeout: 120_000 })
+ .then(() => null)
+ .catch((error) => error);
+ const failure = await Promise.race([completion, browserFailure]);
+ if (failure) throw failure;
const errorText = await page.locator("#error").textContent();
if (errorText) {
- console.error(`FAIL: ${errorText}`);
- if (errors.length) console.error("Console errors:", errors);
- process.exit(1);
+ throw new Error(`${errorText}${errors.length ? `\nPage errors: ${errors.join("\n")}` : ""}`);
}
const resultText = await page.locator("#result").textContent();
const pages = await page.locator("#result").getAttribute("data-pages");
const textLength = await page.locator("#result").getAttribute("data-text-length");
+ const ocrCallbacks = await page.locator("#result").getAttribute("data-ocr-callbacks");
+ const ocrBytes = await page.locator("#result").getAttribute("data-ocr-bytes");
console.log(`PASS: ${resultText}`);
console.log(` Pages: ${pages}`);
console.log(` Text length: ${textLength}`);
+ console.log(` OCR callback calls: ${ocrCallbacks}`);
+ console.log(` OCR input bytes: ${ocrBytes}`);
if (errors.length) {
console.warn("Browser console errors (non-fatal):", errors);
@@ -106,7 +126,7 @@ async function main() {
}
}
-main().catch((err) => {
- console.error("Test runner failed:", err);
+main().catch((error) => {
+ console.error("Test runner failed:", error);
process.exit(1);
});