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.ymlindex 80ca125..ea3a7a4 100644--- a/.github/workflows/ci-wasm.yml+++ b/.github/workflows/ci-wasm.yml@@ -52,6 +52,11 @@ jobs:- name: Install wasm-packrun: 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 packageworking-directory: packages/wasmrun: npm run builddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 355a8ca..f3faafb 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -113,6 +113,17 @@ npm run build:nodejs # Node.js targetPDFium 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 Changesdiff --git a/Cargo.lock b/Cargo.lockindex 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.rsindex 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 anddiff --git a/crates/liteparse-wasm/Cargo.toml b/crates/liteparse-wasm/Cargo.tomlindex 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.rsindex 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.rsnew file mode 100644index 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.tomlindex 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.rsindex 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.rsindex 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 thediff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex 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.rsindex 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.rsindex 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.mdindex 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 OCRconst 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 optionsAll 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.tsindex 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.tsindex 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.pyindex 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 structuretree 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, inmilliseconds. Empty or single-element means no hedging (onerequest per attempt — the default). With multiple delays (e.g.diff --git a/packages/wasm/README.md b/packages/wasm/README.mdindex 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. Toconst 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 sourceRequires 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.jsnew file mode 100644index 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.htmlindex 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.mjsindex 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);