Skip to content

A fast, helpful, and open-source document parser

feat(wasm): support concurrent OCR with rolling scheduling

Choudhry Abdullahf5b60b705fd2
diff --git a/.github/workflows/ci-wasm.yml b/.github/workflows/ci-wasm.yml
index 80ca125..ea3a7a4 100644
--- a/.github/workflows/ci-wasm.yml
+++ b/.github/workflows/ci-wasm.yml
@@ -52,6 +52,11 @@ jobs:
- name: Install wasm-pack
run: cargo install wasm-pack --locked
+ - name: Test WASM OCR stages
+ env:
+ NODE_PATH: ${{ github.workspace }}/scripts/browser-compat/stage-test-support
+ run: wasm-pack test --node crates/liteparse-wasm --test ocr_stages
+
- name: Build WASM package
working-directory: packages/wasm
run: npm run build
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 355a8ca..f3faafb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -113,6 +113,17 @@ npm run build:nodejs # Node.js target
PDFium is statically linked into the `.wasm` binary — the output in `packages/wasm/pkg/` is fully self-contained.
+Run the WASM OCR stage tests from the repository root:
+
+```bash
+NODE_PATH="$PWD/scripts/browser-compat/stage-test-support" \
+ wasm-pack test --node crates/liteparse-wasm --test ocr_stages
+```
+
+These tests run the WASM recognition stage in Node.js. They use a mock OCR
+engine and control job completion without timers. The test support module
+resolves linked WASI imports and fails if a test calls one of them.
+
## Development Workflow
### Testing Local Changes
diff --git a/Cargo.lock b/Cargo.lock
index daf687a..3ec4829 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -182,6 +182,17 @@ dependencies = [
"stable_deref_trait",
]
+[[package]]
+name = "async-trait"
+version = "0.1.92"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82f6aeea286b8eb4dd3431a1be1b59d290ace00f5bfd8e2a159bc2a05e2c1667"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.2",
+]
+
[[package]]
name = "atomic-waker"
version = "1.1.2"
@@ -427,6 +438,12 @@ dependencies = [
"pkg-config",
]
+[[package]]
+name = "cast"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
+
[[package]]
name = "castaway"
version = "0.2.4"
@@ -2024,6 +2041,7 @@ dependencies = [
"crc32fast",
"file-format",
"flate2",
+ "futures-util",
"image",
"liteparse-pdfium",
"liteparse-pdfium-sys",
@@ -2112,6 +2130,7 @@ dependencies = [
"tsify-next",
"wasm-bindgen",
"wasm-bindgen-futures",
+ "wasm-bindgen-test",
]
[[package]]
@@ -2285,6 +2304,16 @@ dependencies = [
"unicase",
]
+[[package]]
+name = "minicov"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3aa3aa12b448ac225b3102217d1ac5cc717908f02722926524b0599c933c7a0"
+dependencies = [
+ "cc",
+ "walkdir",
+]
+
[[package]]
name = "minimal-lexical"
version = "0.2.1"
@@ -2731,6 +2760,12 @@ dependencies = [
"pkg-config",
]
+[[package]]
+name = "oorandom"
+version = "11.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
+
[[package]]
name = "openssl"
version = "0.10.81"
@@ -4944,6 +4979,45 @@ dependencies = [
"unicode-ident",
]
+[[package]]
+name = "wasm-bindgen-test"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a0d555ca874445df8d314f94f5c948a4e74e5418f332c89f660a3d8310a96f4"
+dependencies = [
+ "async-trait",
+ "cast",
+ "js-sys",
+ "libm",
+ "minicov",
+ "nu-ansi-term",
+ "num-traits",
+ "oorandom",
+ "serde",
+ "serde_json",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "wasm-bindgen-test-macro",
+ "wasm-bindgen-test-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-test-macro"
+version = "0.3.76"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94eb68555b95bcea5e8cf4abe280b529049479fa995bfc23734af96a6aedc120"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "wasm-bindgen-test-shared"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c31d56021e873866c968588ed85ccdf56db5c426e44afdb4618c39895104b920"
+
[[package]]
name = "web-sys"
version = "0.3.103"
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rs
index 541a190..b4838cb 100644
--- a/crates/liteparse-napi/src/types.rs
+++ b/crates/liteparse-napi/src/types.rs
@@ -95,9 +95,12 @@ pub struct JsLiteParseConfig {
/// Draw AcroForm field appearances into rendered rasters (screenshots and
/// OCR inputs). Runs the document's open/JS actions. Default false.
pub render_form_fields: Option<bool>,
- /// Whether a systemic OCR failure aborts the whole parse (default true).
- /// Set false to keep already-recovered native text and return partial
- /// results when OCR is unavailable, instead of rejecting.
+ /// Whether an OCR failure on a page with insufficient native text
+ /// stops parsing. Default `true`: report the error instead of silently
+ /// returning a page with missing OCR text.
+ /// Set `false` to return partial results and keep the available native
+ /// text, for example when the application has its own OCR fallback.
+ /// Other parsing errors can still stop parsing.
pub ocr_failure_fatal: Option<bool>,
/// OCR request-hedging schedule (ms). Empty/unset = no hedging. Multiple
/// delays (e.g. `[0, 5000, 10000]`) fire duplicate requests per attempt and
diff --git a/crates/liteparse-wasm/Cargo.toml b/crates/liteparse-wasm/Cargo.toml
index 776be56..ef851b9 100644
--- a/crates/liteparse-wasm/Cargo.toml
+++ b/crates/liteparse-wasm/Cargo.toml
@@ -28,6 +28,9 @@ console_error_panic_hook = { version = "0.1", optional = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
pdfium-sys = { package = "liteparse-pdfium-sys", version = "1.11.0", path = "../pdfium-sys" }
+[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
+wasm-bindgen-test = "0.3"
+
[features]
default = ["panic_hook"]
panic_hook = ["dep:console_error_panic_hook"]
diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rs
index 172b002..eb200c4 100644
--- a/crates/liteparse-wasm/src/lib.rs
+++ b/crates/liteparse-wasm/src/lib.rs
@@ -86,6 +86,9 @@ pub struct LiteParseConfig {
preserve_very_small_text: Option<bool>,
password: Option<String>,
quiet: Option<bool>,
+ /// Maximum number of concurrent `ocrEngine.recognize` calls. Each call
+ /// also keeps one rendered page raster in memory. Default 1.
+ num_workers: Option<usize>,
emit_word_boxes: Option<bool>,
/// Restrict output to a page sub-region. Each field is the fraction of the
/// page cropped from that side; a text item survives only if it lies
@@ -277,7 +280,10 @@ impl LiteParseConfig {
if let Some(v) = self.extract_blocks {
cfg.extract_blocks = v;
}
- cfg.num_workers = 1;
+ // Default to one OCR call at a time. The caller can increase this
+ // limit when its engine supports concurrent jobs.
+ // Treat zero as one. Engine capacity is not detected automatically.
+ cfg.num_workers = self.num_workers.unwrap_or(1).max(1);
Ok(cfg)
}
@@ -322,6 +328,7 @@ impl LiteParseConfig {
preserve_very_small_text: Some(cfg.preserve_very_small_text),
password: cfg.password.clone(),
quiet: Some(cfg.quiet),
+ num_workers: Some(cfg.num_workers),
emit_word_boxes: Some(cfg.emit_word_boxes),
crop_box: cfg.crop_box.map(|c| CropBox {
top: c.top,
diff --git a/crates/liteparse-wasm/tests/ocr_stages.rs b/crates/liteparse-wasm/tests/ocr_stages.rs
new file mode 100644
index 0000000..3043bc5
--- /dev/null
+++ b/crates/liteparse-wasm/tests/ocr_stages.rs
@@ -0,0 +1,238 @@
+#![cfg(target_arch = "wasm32")]
+
+use std::collections::{HashMap, HashSet};
+use std::future::{Future, poll_fn};
+use std::pin::{Pin, pin};
+use std::sync::{Arc, Mutex};
+use std::task::{Context, Poll, Waker};
+
+use liteparse::ocr::{OcrEngine, OcrOptions, OcrResult};
+use liteparse::stages::{self, OcrRaster};
+use wasm_bindgen_test::wasm_bindgen_test;
+
+#[derive(Default)]
+struct State {
+ started: Vec<u32>,
+ completed: Vec<u32>,
+ released: HashSet<u32>,
+ wakers: HashMap<u32, Waker>,
+ active: usize,
+ peak: usize,
+}
+
+#[derive(Default)]
+struct ControlledEngine {
+ state: Mutex<State>,
+}
+
+impl ControlledEngine {
+ fn release(&self, page: u32) {
+ let waker = {
+ let mut state = self.state.lock().unwrap();
+ state.released.insert(page);
+ state.wakers.remove(&page).expect("job must have started")
+ };
+ waker.wake();
+ }
+}
+
+impl OcrEngine for ControlledEngine {
+ fn name(&self) -> &str {
+ "controlled-stage-test"
+ }
+
+ fn recognize<'a, 'b: 'a, 'c: 'a>(
+ &'a self,
+ image_data: &'c [u8],
+ width: u32,
+ height: u32,
+ options: &'b OcrOptions,
+ ) -> Pin<
+ Box<
+ dyn Future<Output = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>>
+ + '_,
+ >,
+ > {
+ assert_eq!(image_data, vec![width as u8; width as usize]);
+ assert_eq!(height, 1);
+ assert_eq!(options.language, "eng");
+ assert_eq!(options.dpi, 150.0);
+ let mut started = false;
+ Box::pin(poll_fn(move |cx| {
+ let mut state = self.state.lock().unwrap();
+ if !started {
+ state.started.push(width);
+ state.active += 1;
+ state.peak = state.peak.max(state.active);
+ started = true;
+ }
+ if !state.released.contains(&width) {
+ state.wakers.insert(width, cx.waker().clone());
+ return Poll::Pending;
+ }
+ state.active -= 1;
+ state.completed.push(width);
+ Poll::Ready(Ok(vec![OcrResult {
+ text: format!("page-{width}"),
+ bbox: [0.0, 0.0, 1.0, 1.0],
+ confidence: 0.99,
+ polygon: None,
+ }]))
+ }))
+ }
+}
+
+fn check_recognition(num_workers: usize) {
+ // Use page numbers that differ from input order.
+ let page_numbers = [9, 3, 7];
+ let rasters = page_numbers
+ .iter()
+ .map(|&page_number| OcrRaster {
+ page_number,
+ pixels: vec![page_number as u8; page_number],
+ width: page_number as u32,
+ height: 1,
+ dpi: 150.0,
+ has_native_text: false,
+ image_rects: vec![],
+ })
+ .collect();
+ let engine = Arc::new(ControlledEngine::default());
+ let mut recognition = pin!(stages::recognize(
+ rasters,
+ engine.clone(),
+ "eng",
+ num_workers
+ ));
+ let mut cx = Context::from_waker(Waker::noop());
+ let limit = num_workers.clamp(1, page_numbers.len());
+
+ assert!(recognition.as_mut().poll(&mut cx).is_pending());
+ assert_eq!(engine.state.lock().unwrap().started.len(), limit);
+
+ for completed in 1..=page_numbers.len() {
+ // Finish the most recently started active job first.
+ // With multiple active jobs, keep earlier jobs pending while
+ // later jobs complete.
+ let page = {
+ let state = engine.state.lock().unwrap();
+ *state
+ .started
+ .iter()
+ .rev()
+ .find(|page| !state.completed.contains(page))
+ .unwrap()
+ };
+ engine.release(page);
+ let result = recognition.as_mut().poll(&mut cx);
+ let state = engine.state.lock().unwrap();
+ assert_eq!(state.completed.len(), completed);
+ assert_eq!(
+ state.started.len(),
+ (limit + completed).min(page_numbers.len())
+ );
+ assert_eq!(state.peak, limit);
+ if completed < page_numbers.len() {
+ assert!(
+ result.is_pending(),
+ "stage returned before all jobs finished"
+ );
+ assert_eq!(state.active, limit.min(page_numbers.len() - completed));
+ } else {
+ let Poll::Ready(outcomes) = result else {
+ panic!("stage did not return after all jobs finished");
+ };
+ assert_eq!(state.active, 0);
+ if limit > 1 {
+ assert_ne!(state.completed, vec![9, 3, 7]);
+ }
+ assert_eq!(outcomes.len(), page_numbers.len());
+ for (outcome, page_number) in outcomes.iter().zip(page_numbers) {
+ assert_eq!(outcome.page_number, page_number);
+ assert!(outcome.error.is_none());
+ assert_eq!(outcome.results.len(), 1);
+ assert_eq!(outcome.results[0].text, format!("page-{page_number}"));
+ }
+ }
+ }
+}
+
+#[wasm_bindgen_test]
+fn bounded_concurrency_refills_and_preserves_input_order() {
+ check_recognition(2);
+}
+
+#[wasm_bindgen_test]
+fn zero_workers_uses_one_slot() {
+ check_recognition(0);
+}
+
+#[wasm_bindgen_test]
+fn one_worker_is_sequential() {
+ check_recognition(1);
+}
+
+#[wasm_bindgen_test]
+fn worker_limit_can_exceed_raster_count() {
+ check_recognition(8);
+}
+
+#[wasm_bindgen_test]
+fn window_collects_ready_results_and_reuses_all_slots() {
+ let engine = Arc::new(ControlledEngine::default());
+ let mut window = stages::OcrWindow::new(engine.clone(), "eng", 2);
+ let mut cx = Context::from_waker(Waker::noop());
+ for page in [9, 3] {
+ let raster = OcrRaster {
+ page_number: page,
+ pixels: vec![page as u8; page],
+ width: page as u32,
+ height: 1,
+ dpi: 150.0,
+ has_native_text: false,
+ image_rects: vec![],
+ };
+ assert!(
+ pin!(window.submit(raster))
+ .as_mut()
+ .poll(&mut cx)
+ .is_ready()
+ );
+ }
+ window.complete_ready();
+ assert_eq!(window.available_capacity(), 0);
+ assert!(window.take_completed().is_empty());
+ engine.release(3);
+ engine.release(9);
+ window.complete_ready();
+ assert_eq!(window.available_capacity(), 2);
+ let outcomes = window.take_completed();
+ assert_eq!(
+ outcomes.iter().map(|o| o.page_number).collect::<Vec<_>>(),
+ vec![9, 3]
+ );
+ assert!(window.take_completed().is_empty());
+ let raster = OcrRaster {
+ page_number: 7,
+ pixels: vec![7; 7],
+ width: 7,
+ height: 1,
+ dpi: 150.0,
+ has_native_text: false,
+ image_rects: vec![],
+ };
+ assert!(
+ pin!(window.submit(raster))
+ .as_mut()
+ .poll(&mut cx)
+ .is_ready()
+ );
+ window.complete_ready();
+ engine.release(7);
+ let mut finish = pin!(window.finish());
+ let Poll::Ready(remaining) = finish.as_mut().poll(&mut cx) else {
+ panic!("released job must finish");
+ };
+ assert_eq!(remaining.len(), 1);
+ assert_eq!(remaining[0].page_number, 7);
+}
diff --git a/crates/liteparse/Cargo.toml b/crates/liteparse/Cargo.toml
index 03e4bd1..6a88d38 100644
--- a/crates/liteparse/Cargo.toml
+++ b/crates/liteparse/Cargo.toml
@@ -55,6 +55,9 @@ oar-ocr = { version = "0.8", optional = true }
rmp = "0.8"
tokio = { version = "1.52.3", features = ["rt-multi-thread", "fs", "process"] }
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+futures-util = { version = "0.3", default-features = false, features = ["std"] }
+
[dev-dependencies]
serial_test = "3"
crc32fast = "1"
diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rs
index 65ba55e..4dd92b6 100644
--- a/crates/liteparse/src/config.rs
+++ b/crates/liteparse/src/config.rs
@@ -113,13 +113,12 @@ pub struct LiteParseConfig {
/// scripts nor change raster bytes for form-bearing PDFs.
#[serde(default)]
pub render_form_fields: bool,
- /// Whether a systemic OCR failure (every OCR task failed *and* at least one
- /// was a text-sparse page whose primary text source was OCR) aborts the
- /// whole parse. Default `true`: surface the root cause instead of silently
- /// emitting blank pages. Set `false` to keep already-recovered native text
- /// and return partial results when OCR is unavailable — useful for callers
- /// that prefer a degraded document over a hard failure (e.g. when the host
- /// has its own OCR fallback or treats OCR as best-effort enrichment).
+ /// Whether an OCR failure on a page with insufficient native text
+ /// stops parsing. Default `true`: report the error instead of silently
+ /// returning a page with missing OCR text.
+ /// Set `false` to return partial results and keep the available native
+ /// text, for example when the application has its own OCR fallback.
+ /// Other parsing errors can still stop parsing.
pub ocr_failure_fatal: bool,
/// OCR request-hedging schedule (milliseconds) for the HTTP OCR engine.
/// Empty (default) = no hedging. With multiple delays (e.g.
diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rs
index 6346f7e..7a0d654 100644
--- a/crates/liteparse/src/ocr_merge.rs
+++ b/crates/liteparse/src/ocr_merge.rs
@@ -4,6 +4,11 @@ use std::sync::Arc;
use crate::error::LiteParseError;
use crate::ocr::{OcrEngine, OcrOptions, OcrResult};
use crate::types::{CutAxis, Page, ParsedPage, Rect, Region, RegionKind, TextItem, WordBox};
+#[cfg(target_arch = "wasm32")]
+use futures_util::{
+ FutureExt,
+ stream::{FuturesUnordered, StreamExt},
+};
use pdfium::{Document, ImageBounds};
use serde::{Deserialize, Serialize};
@@ -152,39 +157,52 @@ impl PageOcrOutcome {
}
}
+#[cfg(target_arch = "wasm32")]
+type OcrJob = std::pin::Pin<Box<dyn std::future::Future<Output = (usize, PageOcrOutcome)>>>;
+
/// At most `max_workers` recognitions in flight; a slot frees as soon as its
/// recognition finishes, so the caller can refill it without waiting on the
/// slowest request.
///
-/// Each recognition runs on a blocking thread (Tesseract is CPU-bound). A
-/// task is only spawned once a slot is free, so at most `max_workers`
+/// On native targets, recognition runs on a Tokio blocking thread
+/// because engines such as Tesseract perform CPU-intensive work.
+/// A task starts only when a slot is free, so at most `max_workers`
/// blocking threads are ever in use. That bound is load-bearing: the HTTP
/// engine's client resolves DNS through its own `spawn_blocking`, and if
/// every pool thread were parked waiting for a slot, that lookup could never
/// run and the whole OCR pass would deadlock.
///
-/// Dropping the pool aborts the async tasks, but a recognition already on a
-/// blocking thread runs to completion in the background and is discarded.
-#[cfg(not(target_arch = "wasm32"))]
+/// On WASM, `FuturesUnordered` polls recognition futures, which can
+/// await JavaScript promises.
+///
+/// Dropping the pool aborts native async tasks. Active blocking calls and
+/// JavaScript promises can continue after the pool is dropped.
pub(crate) struct OcrTaskPool {
max_workers: usize,
engine: Arc<dyn OcrEngine>,
language: String,
+ #[cfg(not(target_arch = "wasm32"))]
tasks: tokio::task::JoinSet<OcrTaskResult>,
- /// Submission index and pending outcome for each running task.
+ #[cfg(target_arch = "wasm32")]
+ tasks: FuturesUnordered<OcrJob>,
+ /// Submission index and pending outcome for each native task.
+ #[cfg(not(target_arch = "wasm32"))]
running: HashMap<tokio::task::Id, (usize, PageOcrOutcome)>,
completed: Vec<(usize, PageOcrOutcome)>,
submitted: usize,
}
-#[cfg(not(target_arch = "wasm32"))]
impl OcrTaskPool {
pub(crate) fn new(engine: Arc<dyn OcrEngine>, language: &str, num_workers: usize) -> Self {
Self {
max_workers: num_workers.max(1),
engine,
language: language.to_string(),
+ #[cfg(not(target_arch = "wasm32"))]
tasks: tokio::task::JoinSet::new(),
+ #[cfg(target_arch = "wasm32")]
+ tasks: FuturesUnordered::new(),
+ #[cfg(not(target_arch = "wasm32"))]
running: HashMap::new(),
completed: Vec::new(),
submitted: 0,
@@ -208,44 +226,76 @@ impl OcrTaskPool {
language: self.language.clone(),
dpi: raster.dpi,
};
- let runtime = tokio::runtime::Handle::current();
- let task = self.tasks.spawn(async move {
- match tokio::task::spawn_blocking(move || {
- runtime.block_on(engine.recognize(
- &raster.pixels,
- raster.width,
- raster.height,
- &options,
- ))
- })
- .await
- {
- Ok(result) => result,
- Err(join_err) => Err(Box::new(join_err) as _),
- }
- });
- self.running.insert(task.id(), (self.submitted, pending));
+ #[cfg(not(target_arch = "wasm32"))]
+ {
+ let runtime = tokio::runtime::Handle::current();
+ let task = self.tasks.spawn(async move {
+ match tokio::task::spawn_blocking(move || {
+ runtime.block_on(engine.recognize(
+ &raster.pixels,
+ raster.width,
+ raster.height,
+ &options,
+ ))
+ })
+ .await
+ {
+ Ok(result) => result,
+ Err(join_err) => Err(Box::new(join_err) as _),
+ }
+ });
+ self.running.insert(task.id(), (self.submitted, pending));
+ }
+ #[cfg(target_arch = "wasm32")]
+ {
+ let order = self.submitted;
+ self.tasks.push(Box::pin(async move {
+ let result = engine
+ .recognize(&raster.pixels, raster.width, raster.height, &options)
+ .await;
+ (order, pending.with_result(result))
+ }));
+ }
self.submitted += 1;
}
/// Wait for one running recognition to finish and record it. Returns
/// `false` (without waiting) when nothing is running.
pub(crate) async fn complete_one(&mut self) -> bool {
- match self.tasks.join_next_with_id().await {
- Some(joined) => {
- self.record_completion(joined);
- true
+ #[cfg(not(target_arch = "wasm32"))]
+ {
+ match self.tasks.join_next_with_id().await {
+ Some(joined) => {
+ self.record_completion(joined);
+ true
+ }
+ None => false,
+ }
+ }
+ #[cfg(target_arch = "wasm32")]
+ {
+ match self.tasks.next().await {
+ Some(outcome) => {
+ self.completed.push(outcome);
+ true
+ }
+ None => false,
}
- None => false,
}
}
pub(crate) fn complete_ready(&mut self) {
+ #[cfg(not(target_arch = "wasm32"))]
while let Some(joined) = self.tasks.try_join_next_with_id() {
self.record_completion(joined);
}
+ #[cfg(target_arch = "wasm32")]
+ while let Some(Some(outcome)) = self.tasks.next().now_or_never() {
+ self.completed.push(outcome);
+ }
}
+ #[cfg(not(target_arch = "wasm32"))]
fn record_completion(
&mut self,
joined: Result<(tokio::task::Id, OcrTaskResult), tokio::task::JoinError>,
@@ -266,8 +316,12 @@ impl OcrTaskPool {
/// merge reports first) does not depend on request timing.
pub(crate) async fn finish(mut self) -> Vec<PageOcrOutcome> {
while self.complete_one().await {}
+ self.take_completed()
+ }
+
+ pub(crate) fn take_completed(&mut self) -> Vec<PageOcrOutcome> {
self.completed.sort_by_key(|(order, _)| *order);
- self.completed
+ std::mem::take(&mut self.completed)
.into_iter()
.map(|(_, outcome)| outcome)
.collect()
@@ -1019,34 +1073,11 @@ pub async fn recognize_rasters(
ocr_language: &str,
num_workers: usize,
) -> Vec<PageOcrOutcome> {
- // 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 _ = num_workers;
- let mut outcomes = Vec::with_capacity(rendered.len());
- for r in rendered {
- let options = OcrOptions {
- language: ocr_language.to_string(),
- dpi: r.dpi,
- };
- let result = ocr_engine
- .recognize(&r.pixels, r.width, r.height, &options)
- .await;
- outcomes.push(PageOcrOutcome::pending(&r).with_result(result));
- }
- outcomes
- }
-
- #[cfg(not(target_arch = "wasm32"))]
- {
- let mut pool = OcrTaskPool::new(ocr_engine, ocr_language, num_workers);
- for r in rendered {
- pool.submit(r).await;
- }
- pool.finish().await
+ let mut pool = OcrTaskPool::new(ocr_engine, ocr_language, num_workers);
+ for raster in rendered {
+ pool.submit(raster).await;
}
+ pool.finish().await
}
/// Merge recognition outcomes into `pages`, in place. Pure: needs neither the
diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rs
index c6a852c..f2f410b 100644
--- a/crates/liteparse/src/parser.rs
+++ b/crates/liteparse/src/parser.rs
@@ -353,7 +353,10 @@ impl LiteParse {
std::collections::HashSet::new()
};
stages::OcrRenderOptions {
- // One round per `num_workers` pages bounds raster memory.
+ // Limit direct `stages::render_for_ocr` calls to at most
+ // `num_workers.max(1)` rasters per call.
+ // `parse()` uses `OcrWindow::render_next`, which limits rendering
+ // by free slots and ignores this field.
max_rasters: self.config.num_workers.max(1),
dpi: self.config.dpi,
grayscale,
@@ -792,96 +795,55 @@ impl LiteParse {
let t1 = web_time::Instant::now();
if let Some(engine) = ocr_engine {
- // `ocr_render_options` already carries the re-flatten set and a
- // `max_rasters` cap of `num_workers`. Native parses ignore that
- // cap and render only as many pages as there are free workers,
- // so a finished request refills the window without waiting out
- // the rest of a batch.
let render_options = ocr_render_options;
let ocr_input = repaired_input.as_ref().unwrap_or(validated_input);
let mut scan_start = 0usize;
+ let page_indices: std::collections::HashMap<_, _> = pages
+ .iter()
+ .enumerate()
+ .map(|(index, page)| (page.page_number, index))
+ .collect();
+ let mut ocr_tasks =
+ stages::OcrWindow::new(engine, &self.config.ocr_language, self.config.num_workers);
+ loop {
+ ocr_tasks.complete_ready();
+ // Merge completed results before rendering more pages. If
+ // `ocr_failure_fatal` requires parsing to stop, return before
+ // starting more work. Otherwise, refill the available slots.
+ for outcome in ocr_tasks.take_completed() {
+ let index = *page_indices.get(&outcome.page_number).ok_or_else(|| {
+ LiteParseError::Other(format!(
+ "No page for OCR outcome {}",
+ outcome.page_number
+ ))
+ })?;
+ stages::merge_ocr(
+ std::slice::from_mut(&mut pages[index]),
+ vec![outcome],
+ self.config.ocr_failure_fatal,
+ self.config.effective_emit_word_boxes(),
+ )?;
+ }
- #[cfg(not(target_arch = "wasm32"))]
- {
- let mut ocr_tasks = stages::OcrWindow::new(
- engine.clone(),
- &self.config.ocr_language,
- self.config.num_workers,
- );
- loop {
- // Reap completions before deciding whether to render so every
- // available worker can be refilled immediately.
- ocr_tasks.complete_ready();
-
- if scan_start >= pages.len() {
+ if scan_start >= pages.len() || ocr_tasks.available_capacity() == 0 {
+ if !ocr_tasks.complete_one().await {
break;
}
-
- if ocr_tasks.available_capacity() == 0 {
- ocr_tasks.complete_one().await;
- continue;
- }
-
- // Each refill reopens the document, often for a single
- // page. That costs a few ms (measured 1-12 ms on large
- // PDFs), small next to one OCR request, and the PDFium
- // lock cannot be held across the awaits. A render error
- // returns here; dropping `ocr_tasks` abandons in-flight
- // recognitions.
- let (rendered, next_start) = {
- let lib = Library::init();
- let document = self.open_document(&lib, ocr_input, password)?;
- ocr_tasks.render_next(&document, &pages, scan_start, &render_options)?
- // `lib` drops here, releasing the PDFium lock before the
- // next await.
- };
- scan_start = next_start;
-
- for raster in rendered {
- ocr_tasks.submit(raster).await;
- }
+ continue;
}
- ocr_tasks
- .finish_and_merge(
- &mut pages,
- self.config.ocr_failure_fatal,
- self.config.effective_emit_word_boxes(),
- )
- .await?;
- }
-
- #[cfg(target_arch = "wasm32")]
- while scan_start < pages.len() {
+ // Open the document for one render round that fills the available
+ // slots. Drop the document and library before awaiting OCR.
+ // On native targets, this releases the process-wide PDFium lock.
let (rendered, next_start) = {
let lib = Library::init();
let document = self.open_document(&lib, ocr_input, password)?;
- stages::render_for_ocr(&document, &pages, scan_start, &render_options)?
- // `lib` drops here, releasing the PDFium lock before the
- // engine's async recognition below.
+ ocr_tasks.render_next(&document, &pages, scan_start, &render_options)?
};
scan_start = next_start;
- if rendered.is_empty() {
- // The scan reached the end without finding another page
- // that needs OCR.
- continue;
+ for raster in rendered {
+ ocr_tasks.submit(raster).await;
}
- // Browser callbacks run serially on the JavaScript event loop.
- // `OcrRaster::page_number` identifies the source page, so the
- // whole slice is passed regardless of where this round started.
- let outcomes = stages::recognize(
- rendered,
- engine.clone(),
- &self.config.ocr_language,
- self.config.num_workers,
- )
- .await;
- stages::merge_ocr(
- &mut pages,
- outcomes,
- self.config.ocr_failure_fatal,
- self.config.effective_emit_word_boxes(),
- )?;
}
}
let t_ocr = web_time::Instant::now();
diff --git a/crates/liteparse/src/stages.rs b/crates/liteparse/src/stages.rs
index a0472a8..dc59373 100644
--- a/crates/liteparse/src/stages.rs
+++ b/crates/liteparse/src/stages.rs
@@ -228,7 +228,8 @@ pub fn render_for_ocr(
}
/// Run an [`OcrEngine`] over rasters, at most `num_workers` at a time. Pure
-/// recognition; failures are per-outcome, not errors. A caller with its own
+/// recognition; failures are per-outcome, not errors.
+/// Results are returned in input order on every target. A caller with its own
/// OCR service can skip this and build [`PageOcrOutcome`]s directly from
/// the [`OcrRaster`] facts and its engine's word boxes (raster pixel space).
pub async fn recognize(
@@ -250,14 +251,12 @@ pub async fn recognize(
/// [`OcrWindow::render_next`], which renders no more pages than there are
/// free slots.
///
-/// Browser WASM has no blocking thread pool, so `parse` uses [`recognize`]
-/// there. This type exists only on native targets.
-#[cfg(not(target_arch = "wasm32"))]
+/// Native recognition runs on Tokio blocking threads.
+/// On WASM, recognition futures can await JavaScript promises.
pub struct OcrWindow {
inner: ocr_merge::OcrTaskPool,
}
-#[cfg(not(target_arch = "wasm32"))]
impl OcrWindow {
/// Start a window that will run at most `num_workers` recognitions at once.
pub fn new(engine: Arc<dyn OcrEngine>, language: &str, num_workers: usize) -> Self {
@@ -300,6 +299,12 @@ impl OcrWindow {
self.inner.complete_one().await
}
+ /// Remove completed outcomes in submission order. Later calls to `finish`
+ /// return only outcomes that have not been removed.
+ pub fn take_completed(&mut self) -> Vec<PageOcrOutcome> {
+ self.inner.take_completed()
+ }
+
/// Start recognition for one raster, first waiting for a free slot if the
/// window is full.
pub async fn submit(&mut self, raster: OcrRaster) {
diff --git a/crates/liteparse/tests/integration_test.rs b/crates/liteparse/tests/integration_test.rs
index 4212866..7afff97 100644
--- a/crates/liteparse/tests/integration_test.rs
+++ b/crates/liteparse/tests/integration_test.rs
@@ -1290,6 +1290,124 @@ async fn test_orientation_correction_rejects_non_cardinal_angle() {
}
}
+struct PartialFailureEngine {
+ first_started: tokio::sync::Notify,
+ failed: tokio::sync::Notify,
+ release_first: tokio::sync::Notify,
+ first_finished: tokio::sync::Notify,
+ calls: std::sync::Mutex<Vec<u32>>,
+}
+
+impl liteparse::ocr::OcrEngine for PartialFailureEngine {
+ fn name(&self) -> &str {
+ "partial-failure"
+ }
+ fn recognize<'a, 'b: 'a, 'c: 'a>(
+ &'a self,
+ _pixels: &'c [u8],
+ width: u32,
+ _height: u32,
+ _options: &'b liteparse::ocr::OcrOptions,
+ ) -> std::pin::Pin<
+ Box<
+ dyn Future<
+ Output = Result<
+ Vec<liteparse::ocr::OcrResult>,
+ Box<dyn std::error::Error + Send + Sync>,
+ >,
+ > + Send
+ + '_,
+ >,
+ > {
+ Box::pin(async move {
+ self.calls.lock().unwrap().push(width);
+ if width == 200 {
+ self.first_started.notify_one();
+ self.release_first.notified().await;
+ self.first_finished.notify_one();
+ } else if width == 201 {
+ self.first_started.notified().await;
+ self.failed.notify_one();
+ return Err("EXPECTED_PARTIAL_OCR_FAILURE".into());
+ }
+ Ok(vec![liteparse::ocr::OcrResult {
+ text: format!("SUCCESS_{width}"),
+ bbox: [4.0, 4.0, 100.0, 24.0],
+ confidence: 0.99,
+ polygon: None,
+ }])
+ })
+ }
+}
+
+#[tokio::test]
+#[serial]
+async fn test_ocr_partial_failure_policy_with_active_job() {
+ use std::{sync::Arc, time::Duration};
+ for fatal in [true, false] {
+ let engine = Arc::new(PartialFailureEngine {
+ first_started: tokio::sync::Notify::new(),
+ failed: tokio::sync::Notify::new(),
+ release_first: tokio::sync::Notify::new(),
+ first_finished: tokio::sync::Notify::new(),
+ calls: std::sync::Mutex::new(Vec::new()),
+ });
+ let parser = LiteParse::new(LiteParseConfig {
+ ocr_enabled: true,
+ num_workers: 2,
+ dpi: 72.0,
+ quiet: true,
+ ocr_failure_fatal: fatal,
+ ..Default::default()
+ })
+ .with_ocr_engine(engine.clone());
+ let parse = tokio::spawn(async move {
+ parser
+ .parse_input(PdfInput::Bytes(blank_pdf(&[
+ (200, 200),
+ (201, 200),
+ (202, 200),
+ ])))
+ .await
+ });
+ tokio::time::timeout(Duration::from_secs(5), engine.failed.notified())
+ .await
+ .unwrap();
+ if !fatal {
+ engine.release_first.notify_one();
+ }
+ let result = tokio::time::timeout(Duration::from_secs(5), parse).await;
+ // Release the blocking job even if the assertion below fails.
+ engine.release_first.notify_one();
+ tokio::time::timeout(Duration::from_secs(5), engine.first_finished.notified())
+ .await
+ .unwrap();
+ let result = result
+ .expect(if fatal {
+ "fatal OCR failure must return before the blocked job is released"
+ } else {
+ "nonfatal parsing must finish after the blocked job is released"
+ })
+ .unwrap();
+ if fatal {
+ assert!(
+ result
+ .err()
+ .expect("parse must fail")
+ .to_string()
+ .contains("EXPECTED_PARTIAL_OCR_FAILURE")
+ );
+ assert!(!engine.calls.lock().unwrap().contains(&202));
+ } else {
+ let result = result.unwrap();
+ assert_eq!(result.pages.len(), 3);
+ assert!(result.pages[0].text.contains("SUCCESS_200"));
+ assert!(result.pages[1].text.trim().is_empty());
+ assert!(result.pages[2].text.contains("SUCCESS_202"));
+ }
+ }
+}
+
async fn diagonal_column_count(config: LiteParseConfig) -> usize {
let stats = LiteParse::new(LiteParseConfig {
quiet: true,
diff --git a/docs/src/content/docs/liteparse/guides/browser-usage.md b/docs/src/content/docs/liteparse/guides/browser-usage.md
index 8cf5815..4e34e80 100644
--- a/docs/src/content/docs/liteparse/guides/browser-usage.md
+++ b/docs/src/content/docs/liteparse/guides/browser-usage.md
@@ -48,7 +48,6 @@ console.log(result.pages[0]);
- **DOCX/XLSX/PPTX conversion** — requires LibreOffice, which isn't available in the browser
- **Built-in Tesseract or HTTP OCR** — use the custom `ocrEngine` interface instead
- **Screenshots** — not available in the WASM build
-- **`numWorkers`** — parsing is single-threaded in WASM; the option is not exposed
- **`imageOutputDir`** — there is no filesystem to write to. Use `extractImages` and read the bytes from the result instead
## OCR in the browser
@@ -59,6 +58,8 @@ The native Tesseract and HTTP OCR backends are not available in WASM. To use OCR
const parser = new LiteParse({
ocrEnabled: true,
ocrLanguage: "eng",
+ // Use more than 1 only if the engine supports concurrent jobs.
+ numWorkers: 2,
ocrEngine: {
/**
* @param imageData PNG-encoded image bytes
@@ -79,6 +80,18 @@ const parser = new LiteParse({
This lets you plug in any OCR implementation — a Web Worker running tesseract.js, a cloud OCR API, or anything else that returns text with bounding boxes.
+LiteParse keeps at most `numWorkers` calls to `recognize` active. When one call
+finishes, LiteParse prepares and starts the next page without waiting for the
+other calls. An OCR engine can send the calls to a Web Worker pool or to
+concurrent HTTP requests. Results stay assigned to their source pages when
+jobs finish out of order. Active calls can keep up to `numWorkers` rendered
+page rasters in memory, so use a small value for high-DPI documents.
+
+PDF parsing and rendering remain single-threaded in WASM. `numWorkers`
+defaults to `1` and limits concurrent OCR calls. LiteParse does not create
+Web Workers. To process OCR jobs in parallel, supply an engine that supports
+concurrent jobs.
+
## Config options
All optional, camelCase:
@@ -88,6 +101,7 @@ All optional, camelCase:
| `ocrLanguage` | `string` | `"eng"` | Language code passed to the OCR engine |
| `ocrEnabled` | `boolean` | `false` | Run OCR on text-sparse pages. Off by default in WASM — there is no built-in engine, so this does nothing without `ocrEngine` |
| `ocrEngine` | `object` | — | Custom JS-side OCR engine (see above) |
+| `numWorkers` | `number` | `1` | Maximum concurrent OCR calls |
| `ocrFailureFatal` | `boolean` | `true` | When `false`, OCR failures return partial results instead of throwing |
| `ocrHedgeDelaysMs` | `number[]` | `[]` | Request-hedging schedule for a remote `ocrEngine` |
| `maxPages` | `number` | `1000` | Stop after this many pages |
diff --git a/packages/node/native.d.ts b/packages/node/native.d.ts
index f129b6f..7bb16ba 100644
--- a/packages/node/native.d.ts
+++ b/packages/node/native.d.ts
@@ -105,9 +105,12 @@ export interface JsLiteParseConfig {
*/
renderFormFields?: boolean
/**
- * Whether a systemic OCR failure aborts the whole parse (default true).
- * Set false to keep already-recovered native text and return partial
- * results when OCR is unavailable, instead of rejecting.
+ * Whether an OCR failure on a page with insufficient native text
+ * stops parsing. Default `true`: report the error instead of silently
+ * returning a page with missing OCR text.
+ * Set `false` to return partial results and keep the available native
+ * text, for example when the application has its own OCR fallback.
+ * Other parsing errors can still stop parsing.
*/
ocrFailureFatal?: boolean
/**
diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.ts
index 5767161..8d83978 100644
--- a/packages/node/src/lib.ts
+++ b/packages/node/src/lib.ts
@@ -95,10 +95,12 @@ export interface LiteParseConfig {
quiet: boolean;
numWorkers: number;
/**
- * Whether a systemic OCR failure (every OCR task failed and at least one was
- * a text-sparse page) aborts the whole parse (default: true). Set false to
- * keep already-recovered native text and return partial results instead of
- * rejecting — for callers that prefer a degraded document over a hard failure.
+ * Whether an OCR failure on a page with insufficient native text
+ * stops parsing. Default `true`: report the error instead of silently
+ * returning a page with missing OCR text.
+ * Set `false` to return partial results and keep the available native
+ * text, for example when the application has its own OCR fallback.
+ * Other parsing errors can still stop parsing.
*/
ocrFailureFatal: boolean;
/**
diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.py
index 256afbc..f26a341 100644
--- a/packages/python/liteparse/parser.py
+++ b/packages/python/liteparse/parser.py
@@ -550,11 +550,12 @@ class LiteParse:
the rendered Markdown.
extract_structure_tree: Include the tagged-PDF logical structure
tree as page-scoped structured data (default: False).
- ocr_failure_fatal: Whether a systemic OCR failure (every OCR task
- failed and at least one was a text-sparse page) aborts the whole
- parse (default: True). Set False to keep already-recovered native
- text and return partial results instead of raising — for callers
- that prefer a degraded document over a hard failure.
+ ocr_failure_fatal: Whether an OCR failure on a page with insufficient
+ native text stops parsing. Default True: report the error instead
+ of silently returning a page with missing OCR text.
+ Set False to return partial results and keep the available native
+ text, for example when the application has its own OCR fallback.
+ Other parsing errors can still stop parsing.
ocr_hedge_delays_ms: Request-hedging schedule for HTTP OCR, in
milliseconds. Empty or single-element means no hedging (one
request per attempt — the default). With multiple delays (e.g.
diff --git a/packages/wasm/README.md b/packages/wasm/README.md
index 5762454..44df39c 100644
--- a/packages/wasm/README.md
+++ b/packages/wasm/README.md
@@ -75,6 +75,7 @@ All optional, camelCase:
| `preserveVerySmallText` | `boolean` | `false` | Keep tiny text that's normally filtered |
| `password` | `string` | — | Password for protected PDFs |
| `quiet` | `boolean` | `false` | Suppress progress logging |
+| `numWorkers` | `number` | `1` | Maximum concurrent OCR calls |
| `ocrEngine` | `object` | — | JS-side OCR engine (see below) |
## OCR in the browser
@@ -85,6 +86,8 @@ The native HTTP-OCR and Tesseract backends are not available in the browser. To
const parser = new LiteParse({
ocrEnabled: true,
ocrLanguage: "eng",
+ // Use more than 1 only if the engine supports concurrent jobs.
+ numWorkers: 2,
ocrEngine: {
/**
* @param imageData PNG-encoded image bytes
@@ -103,6 +106,18 @@ const parser = new LiteParse({
});
```
+LiteParse keeps at most `numWorkers` calls to `recognize` active. When one call
+finishes, LiteParse prepares and starts the next page without waiting for the
+other calls. An OCR engine can send the calls to a Web Worker pool or to
+concurrent HTTP requests. Results stay assigned to their source pages when
+jobs finish out of order. Active calls can keep up to `numWorkers` rendered
+page rasters in memory, so use a small value for high-DPI documents.
+
+With `ocrFailureFatal: true` (the default), an OCR failure on a page with
+insufficient native text rejects `parse()`, even if other pages succeed.
+With `ocrFailureFatal: false`, parsing continues with the available text.
+If parsing fails, OCR calls that have already started can continue.
+
## Building from source
Requires Rust + [`wasm-pack`](https://rustwasm.github.io/wasm-pack/):
diff --git a/scripts/browser-compat/stage-test-support/wasi_snapshot_preview1.js b/scripts/browser-compat/stage-test-support/wasi_snapshot_preview1.js
new file mode 100644
index 0000000..f1836dd
--- /dev/null
+++ b/scripts/browser-compat/stage-test-support/wasi_snapshot_preview1.js
@@ -0,0 +1,15 @@
+// The linked WASM binary has WASI imports. The OCR stage tests do not use
+// these functions. Fail if a test starts to depend on WASI access.
+for (const name of [
+ "fd_close",
+ "fd_fdstat_get",
+ "fd_prestat_get",
+ "fd_prestat_dir_name",
+ "fd_seek",
+ "fd_write",
+ "proc_exit",
+]) {
+ exports[name] = () => {
+ throw new Error(`OCR stage test called WASI function ${name}`);
+ };
+}
diff --git a/scripts/browser-compat/wasm-test.html b/scripts/browser-compat/wasm-test.html
index 2d286fd..fce6be3 100644
--- a/scripts/browser-compat/wasm-test.html
+++ b/scripts/browser-compat/wasm-test.html
@@ -15,14 +15,55 @@
const resultEl = document.getElementById("result");
const errorEl = document.getElementById("error");
- function buildBlankPdf() {
+ function deferred() {
+ let resolve;
+ const promise = new Promise((done) => { resolve = done; });
+ return { promise, resolve };
+ }
+ async function withDeadline(promise, message) {
+ let timer;
+ try {
+ return await Promise.race([
+ promise,
+ new Promise((_, reject) => {
+ timer = setTimeout(() => reject(new Error(message)), 5000);
+ }),
+ ]);
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+
+ function buildTestPdf(pageCount = 1, nativeTextPage = null) {
+ const kids = Array.from(
+ { length: pageCount },
+ (_, index) => `${3 + index * 2} 0 R`,
+ ).join(" ");
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",
+ `<< /Type /Pages /Kids [${kids}] /Count ${pageCount} >>`,
];
+ const fontId = 3 + pageCount * 2;
+ for (let index = 0; index < pageCount; index += 1) {
+ const contentId = 4 + index * 2;
+ const pageWidth = 72 + index;
+ const hasText = index + 1 === nativeTextPage;
+ const resources = hasText ? `<< /Font << /F1 ${fontId} 0 R >> >>` : "<< >>";
+ // Use enough text and page coverage to avoid OCR on the text page.
+ const content = hasText
+ ? "BT /F1 9 Tf 4 60 Td 11 TL\n" +
+ Array.from({ length: 5 }, () => "(NATIVE TEXT) Tj T*\n").join("") + "ET\n"
+ : "";
+ objects.push(
+ `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${pageWidth} 72] /Resources ${resources} /Contents ${contentId} 0 R >>`,
+ `<< /Length ${content.length} >>\nstream\n${content}\nendstream`,
+ );
+ }
+ if (nativeTextPage !== null) {
+ objects.push("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>");
+ }
+
let pdf = "%PDF-1.4\n%1234\n";
const offsets = [0];
for (let index = 0; index < objects.length; index += 1) {
@@ -49,20 +90,26 @@
status.textContent = "creating parser";
const parser = new LiteParse({ ocrEnabled: false, outputFormat: "text", quiet: true });
- status.textContent = "fetching pdf";
- const resp = await fetch("/demo/docs/apple-10k-2024.pdf");
- if (!resp.ok) throw new Error(`Failed to fetch PDF: ${resp.status}`);
- const bytes = new Uint8Array(await resp.arrayBuffer());
+ let pageCount;
+ let textLength;
+ try {
+ status.textContent = "fetching pdf";
+ const resp = await fetch("/demo/docs/apple-10k-2024.pdf");
+ if (!resp.ok) throw new Error(`Failed to fetch PDF: ${resp.status}`);
+ const bytes = new Uint8Array(await resp.arrayBuffer());
- status.textContent = "parsing";
- const result = await parser.parse(bytes);
+ status.textContent = "parsing";
+ const result = await parser.parse(bytes);
- const pageCount = result.pages.length;
- const textLength = result.text.length;
- const hasText = textLength > 100;
+ pageCount = result.pages.length;
+ textLength = result.text.length;
+ const hasText = textLength > 100;
- if (pageCount === 0) throw new Error("No pages parsed");
- if (!hasText) throw new Error(`Text too short: ${textLength} chars`);
+ if (pageCount === 0) throw new Error("No pages parsed");
+ if (!hasText) throw new Error(`Text too short: ${textLength} chars`);
+ } finally {
+ parser.free();
+ }
status.textContent = "testing OCR callback";
let ocrCallbackCalls = 0;
@@ -102,13 +149,326 @@
},
},
});
- const ocrResult = await ocrParser.parse(buildBlankPdf());
+ try {
+ const ocrResult = await ocrParser.parse(buildTestPdf());
+
+ if (ocrParser.config.numWorkers !== 1) {
+ throw new Error(`Expected default OCR concurrency 1, received ${ocrParser.config.numWorkers}`);
+ }
+ 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");
+ }
+ if (ocrParser.config.ocrFailureFatal !== true) {
+ throw new Error("Expected OCR failures to be fatal by default");
+ }
+ } finally {
+ ocrParser.free();
+ }
+
+ status.textContent = "testing concurrent OCR callbacks";
+ let activeOcrCalls = 0;
+ let maxActiveOcrCalls = 0;
+ let concurrentOcrCalls = 0;
+ const completionOrder = [];
+ const releaseFirstPage = deferred();
+ let firstOcrCallActive = false;
+ let queuedCallStartedBeforeFirstFinished = false;
+ const concurrentOcrParser = new LiteParse({
+ ocrEnabled: true,
+ ocrLanguage: "eng",
+ outputFormat: "text",
+ dpi: 72,
+ quiet: true,
+ numWorkers: 2,
+ ocrEngine: {
+ async recognize(_imageData, width, height) {
+ concurrentOcrCalls += 1;
+ activeOcrCalls += 1;
+ maxActiveOcrCalls = Math.max(maxActiveOcrCalls, activeOcrCalls);
+ try {
+ if (width === 72) {
+ firstOcrCallActive = true;
+ // Keep page 1 pending until page 3 finishes. This check fails if
+ // the scheduler waits for all active calls before starting page 3.
+ await withDeadline(
+ releaseFirstPage.promise,
+ "Page 3 did not start while page 1 was active",
+ );
+ } else if (width === 74) {
+ queuedCallStartedBeforeFirstFinished = firstOcrCallActive;
+ }
+ completionOrder.push(width);
+ return [{
+ text: `WASM_CONCURRENT_OCR_WIDTH_${width}`,
+ bbox: [4, 4, Math.max(8, width - 4), Math.min(24, height - 4)],
+ confidence: 0.99,
+ }];
+ } finally {
+ activeOcrCalls -= 1;
+ if (width === 72) firstOcrCallActive = false;
+ if (width === 74) releaseFirstPage.resolve();
+ }
+ },
+ },
+ });
+ try {
+ if (concurrentOcrParser.config.numWorkers !== 2) {
+ throw new Error("Expected configured OCR concurrency 2");
+ }
+ const concurrentResult = await concurrentOcrParser.parse(buildTestPdf(3));
+
+ if (concurrentOcrCalls !== 3) {
+ throw new Error(`Expected three OCR callbacks, received ${concurrentOcrCalls}`);
+ }
+ if (maxActiveOcrCalls !== 2) {
+ throw new Error(`Expected two concurrent OCR callbacks, observed ${maxActiveOcrCalls}`);
+ }
+ if (completionOrder.join(",") !== "73,74,72") {
+ throw new Error(`OCR callbacks did not finish out of order: ${completionOrder}`);
+ }
+ if (!queuedCallStartedBeforeFirstFinished) {
+ throw new Error("The queued OCR call waited for the slowest active call");
+ }
+ if (concurrentResult.pages.length !== 3) {
+ throw new Error("Concurrent OCR did not return all three pages");
+ }
+ const pageTexts = concurrentResult.pages.map((page) => page.text);
+ for (let index = 0; index < pageTexts.length; index += 1) {
+ const expected = `WASM_CONCURRENT_OCR_WIDTH_${72 + index}`;
+ if (!pageTexts[index].includes(expected)) {
+ throw new Error(`Page ${index + 1} did not keep its OCR result: ${pageTexts[index]}`);
+ }
+ }
+ } finally {
+ releaseFirstPage.resolve();
+ concurrentOcrParser.free();
+ }
+
+ status.textContent = "testing several completed OCR calls";
+ const completionGroups = [deferred(), deferred()];
+ let groupedCalls = 0;
+ let groupedActive = 0;
+ let groupedPeak = 0;
+ const groupedParser = new LiteParse({
+ ocrEnabled: true, dpi: 72, quiet: true, outputFormat: "text", numWorkers: 4,
+ ocrEngine: {
+ async recognize(_imageData, width) {
+ const group = Math.floor(groupedCalls / 4);
+ groupedCalls += 1;
+ groupedActive += 1;
+ groupedPeak = Math.max(groupedPeak, groupedActive);
+ if (groupedCalls % 4 === 0) completionGroups[group].resolve();
+ try {
+ // Release four calls together to leave several results ready.
+ await withDeadline(completionGroups[group].promise, "Four OCR slots did not fill");
+ return [{
+ text: `GROUPED_${width}`,
+ bbox: [4, 4, width - 4, 24], confidence: 0.99,
+ }];
+ } finally {
+ groupedActive -= 1;
+ }
+ },
+ },
+ });
+ try {
+ const groupedResult = await groupedParser.parse(buildTestPdf(8));
+ if (groupedCalls !== 8 || groupedPeak !== 4 || groupedActive !== 0) {
+ throw new Error(`Expected eight OCR calls with peak four, got ${groupedCalls} and ${groupedPeak}`);
+ }
+ if (groupedResult.pages.length !== 8 || groupedResult.pages.some(
+ (page, index) => !page.text.includes(`GROUPED_${72 + index}`),
+ )) {
+ throw new Error("Several completed calls did not keep their source pages");
+ }
+ } finally {
+ completionGroups.forEach((group) => group.resolve());
+ groupedParser.free();
+ }
+
+ status.textContent = "testing a ready failure before refill";
+ const releaseReadyPair = deferred();
+ let readyPairCalls = 0;
+ const readyFailureParser = new LiteParse({
+ ocrEnabled: true, dpi: 72, quiet: true, numWorkers: 2, ocrFailureFatal: true,
+ ocrEngine: {
+ async recognize(_imageData, width) {
+ readyPairCalls += 1;
+ if (readyPairCalls === 2) releaseReadyPair.resolve();
+ await withDeadline(releaseReadyPair.promise, "The first two OCR pages did not start");
+ if (width === 73) throw new Error("READY_OCR_FAILURE");
+ return [{text: `READY_${width}`, bbox: [4, 4, width - 4, 24], confidence: 0.99}];
+ },
+ },
+ });
+ try {
+ let failure;
+ try {
+ await readyFailureParser.parse(buildTestPdf(4));
+ } catch (error) {
+ failure = String(error);
+ }
+ if (!failure?.includes("READY_OCR_FAILURE") || readyPairCalls !== 2) {
+ throw new Error(`A ready failure must stop refill: calls=${readyPairCalls}, error=${failure}`);
+ }
+ } finally {
+ releaseReadyPair.resolve();
+ readyFailureParser.free();
+ }
+
+ status.textContent = "testing more workers than pages";
+ const allPagesStarted = deferred();
+ let largePoolCalls = 0;
+ let largePoolActive = 0;
+ let largePoolPeak = 0;
+ const largePoolParser = new LiteParse({
+ ocrEnabled: true, dpi: 72, quiet: true, outputFormat: "text", numWorkers: 8,
+ ocrEngine: {
+ async recognize(_imageData, width) {
+ largePoolCalls += 1;
+ largePoolActive += 1;
+ largePoolPeak = Math.max(largePoolPeak, largePoolActive);
+ if (largePoolCalls === 3) allPagesStarted.resolve();
+ try {
+ await withDeadline(allPagesStarted.promise, "Not all three OCR pages started");
+ return [{
+ text: `LARGE_POOL_${width}`,
+ bbox: [4, 4, width - 4, 24], confidence: 0.99,
+ }];
+ } finally {
+ largePoolActive -= 1;
+ }
+ },
+ },
+ });
+ try {
+ const largePoolResult = await largePoolParser.parse(buildTestPdf(3));
+ if (largePoolCalls !== 3 || largePoolPeak !== 3 || largePoolActive !== 0) {
+ throw new Error(`Expected three concurrent OCR calls with eight workers, got ${largePoolCalls} calls and peak ${largePoolPeak}`);
+ }
+ if (largePoolResult.pages.length !== 3 || largePoolResult.pages.some(
+ (page, index) => !page.text.includes(`LARGE_POOL_${72 + index}`),
+ )) {
+ throw new Error("The larger worker limit did not preserve each page's OCR text");
+ }
+ } finally {
+ allPagesStarted.resolve();
+ largePoolParser.free();
+ }
- if (ocrCallbackCalls !== 1) {
- throw new Error(`Expected one OCR callback, received ${ocrCallbackCalls}`);
+ status.textContent = "testing refill past a native text page";
+ const refillCalls = [];
+ const refillParser = new LiteParse({
+ ocrEnabled: true, dpi: 72, quiet: true, outputFormat: "text", numWorkers: 1,
+ ocrEngine: {
+ async recognize(_imageData, width) {
+ refillCalls.push(width);
+ return [{
+ text: `REFILL_${width}`,
+ bbox: [4, 4, width - 4, 24], confidence: 0.99,
+ }];
+ },
+ },
+ });
+ try {
+ // One slot forces the refill scan to skip the middle page.
+ const refillResult = await refillParser.parse(buildTestPdf(3, 2));
+ if (refillCalls.join(",") !== "72,74") {
+ throw new Error(`Expected OCR only on pages 1 and 3, got widths ${refillCalls}`);
+ }
+ if (refillResult.pages.length !== 3 ||
+ !refillResult.pages[0].text.includes("REFILL_72") ||
+ !refillResult.pages[1].text.includes("NATIVE TEXT") ||
+ !refillResult.pages[2].text.includes("REFILL_74")) {
+ throw new Error("Refill did not preserve OCR and native text on their source pages");
+ }
+ } finally {
+ refillParser.free();
}
- if (!ocrResult.text.includes("WASM_OCR_CALLBACK_OK")) {
- throw new Error("OCR callback text was not merged into the parse result");
+
+ status.textContent = "testing OCR failure policy";
+ let failureCases = 0;
+ for (const numWorkers of [1, 2]) {
+ for (const fatal of [true, false]) {
+ const secondStarted = deferred();
+ const thirdStarted = deferred();
+ const failed = deferred();
+ const releaseThird = deferred();
+ const thirdFinished = deferred();
+ const calls = [];
+ let thirdActive = false;
+ const failureParser = new LiteParse({
+ ocrEnabled: true, dpi: 72, quiet: true, outputFormat: "text",
+ numWorkers, ocrFailureFatal: fatal,
+ ocrEngine: {
+ async recognize(_imageData, width) {
+ calls.push(width);
+ if (width === 72 && numWorkers === 2) {
+ await secondStarted.promise;
+ }
+ if (width === 73) {
+ secondStarted.resolve();
+ if (numWorkers === 2) await thirdStarted.promise;
+ failed.resolve();
+ throw new Error("EXPECTED_OCR_PAGE_FAILURE");
+ }
+ if (width === 74) {
+ thirdActive = true;
+ thirdStarted.resolve();
+ try {
+ await releaseThird.promise;
+ } finally {
+ thirdActive = false;
+ thirdFinished.resolve();
+ }
+ }
+ return [{
+ text: `OCR_SUCCESS_${width}`,
+ bbox: [4, 4, width - 4, 24], confidence: 0.99,
+ }];
+ },
+ },
+ });
+ const settled = failureParser.parse(buildTestPdf(3)).then(
+ (result) => ({ result }), (error) => ({ error }),
+ );
+ try {
+ await withDeadline(failed.promise, "The failing OCR page did not start");
+ if (!fatal) releaseThird.resolve();
+ const outcome = await withDeadline(settled, "OCR failure policy did not settle parse()");
+ if (fatal) {
+ if (!String(outcome.error).includes("EXPECTED_OCR_PAGE_FAILURE")) {
+ throw new Error(`Expected a fatal OCR error with ${numWorkers} worker(s)`);
+ }
+ if (numWorkers === 1 && calls.join(",") !== "72,73") {
+ throw new Error("Serial OCR started another page after a fatal error");
+ }
+ if (numWorkers === 2 && !thirdActive) {
+ throw new Error("Fatal OCR did not reject while another call was active");
+ }
+ } else {
+ if (outcome.error) throw outcome.error;
+ const pages = outcome.result.pages;
+ if (pages.length !== 3 || !pages[0].text.includes("OCR_SUCCESS_72") ||
+ pages[1].text.trim() !== "" || !pages[2].text.includes("OCR_SUCCESS_74")) {
+ throw new Error("Nonfatal OCR did not preserve successful pages");
+ }
+ }
+ } finally {
+ secondStarted.resolve();
+ thirdStarted.resolve();
+ releaseThird.resolve();
+ await withDeadline(settled, "OCR cleanup did not settle parse()");
+ if (calls.includes(74)) {
+ await withDeadline(thirdFinished.promise, "The active OCR call did not finish");
+ }
+ failureParser.free();
+ }
+ failureCases += 1;
+ }
}
status.textContent = "done";
@@ -117,7 +477,9 @@
resultEl.setAttribute("data-text-length", textLength);
resultEl.setAttribute("data-ocr-callbacks", ocrCallbackCalls);
resultEl.setAttribute("data-ocr-bytes", ocrByteLength);
- resultEl.textContent = `OK: ${pageCount} pages, ${textLength} chars, OCR callback passed`;
+ resultEl.setAttribute("data-ocr-max-concurrency", maxActiveOcrCalls);
+ resultEl.setAttribute("data-ocr-failure-cases", failureCases);
+ resultEl.textContent = `OK: ${pageCount} pages, ${textLength} chars, OCR callback, concurrency, worker limits, grouped completion, ready failure, native text refill, and ${failureCases} failure cases 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 e66c821..5ba5836 100644
--- a/scripts/browser-compat/wasm-test.mjs
+++ b/scripts/browser-compat/wasm-test.mjs
@@ -110,12 +110,16 @@ async function main() {
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");
+ const ocrMaxConcurrency = await page.locator("#result").getAttribute("data-ocr-max-concurrency");
+ const ocrFailureCases = await page.locator("#result").getAttribute("data-ocr-failure-cases");
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}`);
+ console.log(` OCR maximum concurrency: ${ocrMaxConcurrency}`);
+ console.log(` OCR failure cases: ${ocrFailureCases}`);
if (errors.length) {
console.warn("Browser console errors (non-fatal):", errors);