A fast, helpful, and open-source document parser
feat: add word-level bbox output (opt-in)
Logan Markewich99aa90bc71fb
diff --git a/crates/liteparse-napi/src/types.rs b/crates/liteparse-napi/src/types.rsindex d4a8cad..6dbde2f 100644--- a/crates/liteparse-napi/src/types.rs+++ b/crates/liteparse-napi/src/types.rs@@ -4,7 +4,7 @@ use napi_derive::napi;use liteparse::config::{ImageMode, LiteParseConfig, OutputFormat};use liteparse::parser::ParseResult;-use liteparse::types::{GraphicPrimitive, Page, ParsedPage, Rect, TextItem};+use liteparse::types::{GraphicPrimitive, Page, ParsedPage, Rect, TextItem, WordBox};// ---------------------------------------------------------------------------// Config@@ -55,6 +55,10 @@ pub struct JsLiteParseConfig {/// delays (e.g. `[0, 5000, 10000]`) fire duplicate requests per attempt and/// take the first success — lower tail latency at the cost of extra load.pub ocr_hedge_delays_ms: Option<Vec<u32>>,+ /// Emit per-word sub-boxes on each text item (`TextItem.words`). Default+ /// false. Word boxes roughly double the text-item payload, so enable only+ /// for word-level bbox attribution.+ pub emit_word_boxes: Option<bool>,}impl JsLiteParseConfig {@@ -119,6 +123,9 @@ impl JsLiteParseConfig {if let Some(v) = self.ocr_hedge_delays_ms {cfg.ocr_hedge_delays_ms = v.into_iter().map(u64::from).collect();}+ if let Some(v) = self.emit_word_boxes {+ cfg.emit_word_boxes = v;+ }cfg}@@ -158,6 +165,7 @@ impl JsLiteParseConfig {.map(|&v| u32::try_from(v).unwrap_or(u32::MAX)).collect(),),+ emit_word_boxes: Some(cfg.emit_word_boxes),}}}@@ -166,6 +174,29 @@ impl JsLiteParseConfig {// TextItem// ---------------------------------------------------------------------------+/// One word's sub-box within a `JsTextItem`, in the same viewport space.+#[napi(object)]+#[derive(Clone)]+pub struct JsWordBox {+ pub text: String,+ pub x: f64,+ pub y: f64,+ pub width: f64,+ pub height: f64,+}++impl JsWordBox {+ pub fn from_rust(word: &WordBox) -> Self {+ Self {+ text: word.text.clone(),+ x: word.x as f64,+ y: word.y as f64,+ width: word.width as f64,+ height: word.height as f64,+ }+ }+}+#[napi(object)]#[derive(Clone)]pub struct JsTextItem {@@ -179,6 +210,9 @@ pub struct JsTextItem {pub confidence: Option<f64>,/// Rotation in degrees (viewport space). Defaults to 0 when omitted.pub rotation: Option<f64>,+ /// Per-word sub-boxes for attribution. Empty for items with no word split+ /// (e.g. OCR-sourced or single-token items).+ pub words: Vec<JsWordBox>,}impl JsTextItem {@@ -208,6 +242,7 @@ impl JsTextItem {font_name: item.font_name.clone(),font_size: item.font_size.map(|v| v as f64),confidence: item.confidence.map(|v| v as f64).or(Some(1.0)),+ words: item.words.iter().map(JsWordBox::from_rust).collect(),}}}diff --git a/crates/liteparse-python/src/lib.rs b/crates/liteparse-python/src/lib.rsindex 11d11b5..90b4e26 100644--- a/crates/liteparse-python/src/lib.rs+++ b/crates/liteparse-python/src/lib.rs@@ -12,6 +12,43 @@ mod cli;// Python type wrappers// ---------------------------------------------------------------------------+#[pyclass(frozen, from_py_object)]+#[derive(Clone)]+struct PyWordBox {+ #[pyo3(get)]+ text: String,+ #[pyo3(get)]+ x: f64,+ #[pyo3(get)]+ y: f64,+ #[pyo3(get)]+ width: f64,+ #[pyo3(get)]+ height: f64,+}++#[pymethods]+impl PyWordBox {+ fn __repr__(&self) -> String {+ format!(+ "WordBox(text={:?}, x={}, y={}, width={}, height={})",+ self.text, self.x, self.y, self.width, self.height+ )+ }+}++impl PyWordBox {+ fn from_rust(word: liteparse::types::WordBox) -> Self {+ Self {+ text: word.text,+ x: word.x as f64,+ y: word.y as f64,+ width: word.width as f64,+ height: word.height as f64,+ }+ }+}+#[pyclass(frozen, from_py_object)]#[derive(Clone)]struct PyTextItem {@@ -31,6 +68,13 @@ struct PyTextItem {font_size: Option<f64>,#[pyo3(get)]confidence: Option<f64>,+ /// Rotation in degrees (viewport space). Defaults to 0.+ #[pyo3(get)]+ rotation: f64,+ /// Per-word sub-boxes for attribution. Empty unless the parse was+ /// configured with `emit_word_boxes=True`.+ #[pyo3(get)]+ words: Vec<PyWordBox>,}#[pymethods]@@ -51,6 +95,7 @@ impl PyTextItem {y: self.y as f32,width: self.width as f32,height: self.height as f32,+ rotation: self.rotation as f32,font_name: self.font_name.clone(),font_size: self.font_size.map(|v| v as f32),confidence: self.confidence.map(|v| v as f32),@@ -68,6 +113,8 @@ impl PyTextItem {font_name: item.font_name,font_size: item.font_size.map(|v| v as f64),confidence: item.confidence.map(|v| v as f64).or(Some(1.0)),+ rotation: item.rotation as f64,+ words: item.words.into_iter().map(PyWordBox::from_rust).collect(),}}}@@ -405,6 +452,7 @@ impl LiteParse {extract_links = None,ocr_failure_fatal = None,ocr_hedge_delays_ms = None,+ emit_word_boxes = None,))]fn new(ocr_language: Option<String>,@@ -424,6 +472,7 @@ impl LiteParse {extract_links: Option<bool>,ocr_failure_fatal: Option<bool>,ocr_hedge_delays_ms: Option<Vec<u64>>,+ emit_word_boxes: Option<bool>,) -> PyResult<Self> {let mut cfg = LiteParseConfig::default();if let Some(v) = ocr_language {@@ -485,6 +534,9 @@ impl LiteParse {if let Some(v) = ocr_hedge_delays_ms {cfg.ocr_hedge_delays_ms = v;}+ if let Some(v) = emit_word_boxes {+ cfg.emit_word_boxes = v;+ }let inner = liteparse::parser::LiteParse::new(cfg.clone());let runtime = tokio::runtime::Runtime::new()@@ -615,6 +667,7 @@ fn _liteparse(m: &Bound<'_, PyModule>) -> PyResult<()> {m.add_class::<PyExtractedImage>()?;m.add_class::<PyParsedPage>()?;m.add_class::<PyTextItem>()?;+ m.add_class::<PyWordBox>()?;m.add_class::<PyScreenshotResult>()?;m.add_class::<PyPageComplexityStats>()?;m.add_function(wrap_pyfunction!(run_cli, m)?)?;diff --git a/crates/liteparse-wasm/src/lib.rs b/crates/liteparse-wasm/src/lib.rsindex 9861738..04c68d2 100644--- a/crates/liteparse-wasm/src/lib.rs+++ b/crates/liteparse-wasm/src/lib.rs@@ -54,6 +54,7 @@ struct JsLiteParseConfig {preserve_very_small_text: Option<bool>,password: Option<String>,quiet: Option<bool>,+ emit_word_boxes: Option<bool>,}impl JsLiteParseConfig {@@ -121,6 +122,9 @@ impl JsLiteParseConfig {if let Some(v) = self.quiet {cfg.quiet = v;}+ if let Some(v) = self.emit_word_boxes {+ cfg.emit_word_boxes = v;+ }cfg.num_workers = 1;Ok(cfg)}@@ -155,6 +159,7 @@ impl JsLiteParseConfig {preserve_very_small_text: Some(cfg.preserve_very_small_text),password: cfg.password.clone(),quiet: Some(cfg.quiet),+ emit_word_boxes: Some(cfg.emit_word_boxes),}}}@@ -163,6 +168,16 @@ impl JsLiteParseConfig {// JS-facing parse result// ---------------------------------------------------------------------------+#[derive(Serialize)]+#[serde(rename_all = "camelCase")]+struct JsWordBox<'a> {+ text: &'a str,+ x: f32,+ y: f32,+ width: f32,+ height: f32,+}+#[derive(Serialize)]#[serde(rename_all = "camelCase")]struct JsTextItem<'a> {@@ -177,6 +192,12 @@ struct JsTextItem<'a> {font_size: Option<f32>,#[serde(skip_serializing_if = "Option::is_none")]confidence: Option<f32>,+ /// Rotation in degrees (viewport space).+ rotation: f32,+ /// Per-word sub-boxes for attribution. Omitted when empty (the default —+ /// only populated when parsing with `emitWordBoxes: true`).+ #[serde(skip_serializing_if = "Vec::is_empty")]+ words: Vec<JsWordBox<'a>>,}#[derive(Serialize)]@@ -381,6 +402,18 @@ impl LiteParse {font_name: i.font_name.as_deref(),font_size: i.font_size,confidence: i.confidence,+ rotation: i.rotation,+ words: i+ .words+ .iter()+ .map(|w| JsWordBox {+ text: &w.text,+ x: w.x,+ y: w.y,+ width: w.width,+ height: w.height,+ })+ .collect(),}).collect(),})@@ -543,6 +576,18 @@ pub fn search_items(items: JsValue, options: JsValue) -> Result<JsValue, JsErrorfont_name: i.font_name.as_deref(),font_size: i.font_size,confidence: i.confidence,+ rotation: i.rotation,+ words: i+ .words+ .iter()+ .map(|w| JsWordBox {+ text: &w.text,+ x: w.x,+ y: w.y,+ width: w.width,+ height: w.height,+ })+ .collect(),}).collect();diff --git a/crates/liteparse/src/config.rs b/crates/liteparse/src/config.rsindex 88c6333..517286a 100644--- a/crates/liteparse/src/config.rs+++ b/crates/liteparse/src/config.rs@@ -53,6 +53,13 @@ pub struct LiteParseConfig {/// OCR-server load for lower tail latency on a slow/stuck pod. No effect on/// the Tesseract engine.pub ocr_hedge_delays_ms: Vec<u64>,+ /// Emit per-word sub-boxes on each `TextItem` (`TextItem.words`). Default+ /// `false`: a text item already carries its own box, and word boxes roughly+ /// double the text-item payload (size + napi marshalling), so they are only+ /// worth computing for callers doing word-level bbox attribution. When+ /// `false`, `TextItem.words` is always empty and the per-word tracking is+ /// skipped entirely (zero allocation).+ pub emit_word_boxes: bool,}/// Image handling for the markdown emitter.@@ -113,6 +120,7 @@ impl Default for LiteParseConfig {extract_links: true,ocr_failure_fatal: true,ocr_hedge_delays_ms: Vec::new(),+ emit_word_boxes: false,}}}diff --git a/crates/liteparse/src/extract.rs b/crates/liteparse/src/extract.rsindex 797eecd..13a8dc3 100644--- a/crates/liteparse/src/extract.rs+++ b/crates/liteparse/src/extract.rs@@ -2,7 +2,7 @@ use crate::error::LiteParseError;use crate::glyph_names::resolve_glyph_name;use crate::types::{ExtractedImage, GraphicPrimitive, ImageRef, OutlineTarget, Page as LitePage, PdfInput, Rect,- StructNode, TextItem,+ StructNode, TextItem, WordBox,};use image::ImageEncoder;use pdfium::{@@ -49,7 +49,7 @@ pub(crate) fn extract_pages_from_document(target_pages: Option<&[u32]>,max_pages: usize,) -> Result<Vec<LitePage>, LiteParseError> {- Ok(extract_pages_and_images(document, target_pages, max_pages, false, false, None)?.0)+ Ok(extract_pages_and_images(document, target_pages, max_pages, false, false, None, false)?.0)}/// Same as `extract_pages_from_document` but optionally also renders every@@ -64,6 +64,7 @@ pub(crate) fn extract_pages_and_images(render_images: bool,extract_links: bool,glyph_resolver: Option<&dyn crate::GlyphResolver>,+ emit_word_boxes: bool,) -> Result<(Vec<LitePage>, Vec<ExtractedImage>), LiteParseError> {let page_count = document.page_count();let mut pages = Vec::new();@@ -90,7 +91,13 @@ pub(crate) fn extract_pages_and_images(right: page.width(),bottom: 0.0,});- let mut text_items = extract_page_text_items(&page, &text_page, &view_box, glyph_resolver)?;+ let mut text_items = extract_page_text_items(+ &page,+ &text_page,+ &view_box,+ glyph_resolver,+ emit_word_boxes,+ )?;if extract_links {assign_links(&mut text_items, &page.links(&view_box));}@@ -524,6 +531,7 @@ fn extract_page_text_items(text_page: &TextPage,view_box: &RectF,glyph_resolver: Option<&dyn crate::GlyphResolver>,+ emit_word_boxes: bool,) -> Result<Vec<TextItem>, LiteParseError> {let char_count = text_page.char_count();if char_count <= 0 {@@ -554,7 +562,7 @@ fn extract_page_text_items(let page_rotation = page.rotation();let vp_xform = page.viewport_transform(view_box);let mut items: Vec<TextItem> = Vec::new();- let mut seg = SegmentBuilder::new();+ let mut seg = SegmentBuilder::new(emit_word_boxes);let garbage_fonts = detect_garbage_unicode_fonts(text_page, char_count);let mut glyph_decoder = GlyphDecoder::new(std::env::var("LITEPARSE_DEBUG_GLYPH").is_ok(),@@ -829,6 +837,7 @@ fn extract_page_text_items(};if both_alnum && thresh > 0.0 && loose_gap > thresh {seg.text.push(' ');+ seg.break_word();}seg.push_char(c, &vp_loose, &vp_strict, &ch);seg.append_ligature_tail(ligature_tail);@@ -1408,10 +1417,22 @@ struct SegmentBuilder {stroke_color: Option<String>,has_content: bool,pending_space: bool,+ // Per-word sub-boxes, finalized at each inter-word space break. The+ // currently-open word is accumulated in the `word_*` fields below and+ // flushed into `words` by `break_word`.+ words: Vec<WordBox>,+ cur_word: String,+ word_left: f32,+ word_right: f32,+ word_top: f32,+ word_bottom: f32,+ word_has: bool,+ // When false, per-word tracking is skipped entirely and `words` stays empty.+ emit_words: bool,}impl SegmentBuilder {- fn new() -> Self {+ fn new(emit_words: bool) -> Self {Self {text: String::new(),vp_left: f32::MAX,@@ -1440,9 +1461,59 @@ impl SegmentBuilder {stroke_color: None,has_content: false,pending_space: false,+ words: Vec::new(),+ cur_word: String::new(),+ word_left: f32::MAX,+ word_right: f32::MIN,+ word_top: f32::MAX,+ word_bottom: f32::MIN,+ word_has: false,+ emit_words,}}+ /// Extend the currently-open word with a character's loose box, opening a+ /// fresh word if none is active. No-op unless word emission is enabled.+ fn add_word_char(&mut self, c: char, vp_loose: &RectF) {+ if !self.emit_words {+ return;+ }+ if self.word_has {+ self.word_left = self.word_left.min(vp_loose.left);+ self.word_right = self.word_right.max(vp_loose.right);+ self.word_top = self.word_top.min(vp_loose.top);+ self.word_bottom = self.word_bottom.max(vp_loose.bottom);+ } else {+ self.cur_word.clear();+ self.word_left = vp_loose.left;+ self.word_right = vp_loose.right;+ self.word_top = vp_loose.top;+ self.word_bottom = vp_loose.bottom;+ self.word_has = true;+ }+ self.cur_word.push(c);+ }++ /// Finalize the open word (if any) into `words` and reset the accumulator.+ /// Called at each inter-word space and at segment flush.+ fn break_word(&mut self) {+ if !self.word_has {+ return;+ }+ let trimmed = self.cur_word.trim();+ if !trimmed.is_empty() {+ self.words.push(WordBox {+ text: trimmed.to_string(),+ x: self.word_left,+ y: self.word_top,+ width: self.word_right - self.word_left,+ height: self.word_bottom - self.word_top,+ });+ }+ self.cur_word.clear();+ self.word_has = false;+ }+/// Average width of non-space characters in the current segment./// Prefers actual glyph widths (text_width) over bbox width, since bbox/// includes inter-character gaps that inflate the average and cause@@ -1480,6 +1551,9 @@ impl SegmentBuilder {self.unmapped_char_count = if ch.has_unicode_map_error() { 1 } else { 0 };self.has_content = true;self.pending_space = false;+ self.words.clear();+ self.word_has = false;+ self.add_word_char(c, vp_loose);self.text_width = 0.0;self.font_is_buggy = false;self.font_is_embedded = false;@@ -1564,6 +1638,7 @@ impl SegmentBuilder {/// Add a visible character to the current segment.fn push_char(&mut self, c: char, vp_loose: &RectF, vp_strict: &RectF, ch: &pdfium::TextChar) {self.text.push(c);+ self.add_word_char(c, vp_loose);self.vp_left = self.vp_left.min(vp_loose.left);self.vp_right = self.vp_right.max(vp_loose.right);self.vp_top = self.vp_top.min(vp_loose.top);@@ -1601,6 +1676,9 @@ impl SegmentBuilder {/// Does not update bounding boxes or char count.fn append_ligature_tail(&mut self, tail: &str) {self.text.push_str(tail);+ if self.word_has {+ self.cur_word.push_str(tail);+ }}/// Returns true if the segment contains any characters that aren't dots or spaces.@@ -1620,6 +1698,7 @@ impl SegmentBuilder {/// Commit a pending space into the segment text.fn commit_pending_space(&mut self) {if self.pending_space {+ self.break_word();self.text.push(' ');self.pending_space = false;}@@ -1631,6 +1710,7 @@ impl SegmentBuilder {return;}+ self.break_word();let trimmed = self.text.trim();if !trimmed.is_empty() {let width = self.vp_right - self.vp_left;@@ -1669,10 +1749,11 @@ impl SegmentBuilder {confidence: None,link: None,strike: false,+ words: std::mem::take(&mut self.words),});}- *self = Self::new();+ *self = Self::new(self.emit_words);}}diff --git a/crates/liteparse/src/lib.rs b/crates/liteparse/src/lib.rsindex 0efa0ec..688b23b 100644--- a/crates/liteparse/src/lib.rs+++ b/crates/liteparse/src/lib.rs@@ -12,7 +12,7 @@ pub use font_db_resolver::FontDbResolver;pub use glyph_resolver::{GLYPH_RESOLVER_FONT_SIZE, GlyphResolver};pub use parser::{LiteParse, ParseResult, ScreenshotResult};pub use search::{SearchOptions, search_items};-pub use types::{ParsedPage, TextItem};+pub use types::{ParsedPage, TextItem, WordBox};// ── Modules with user-facing types (visible in docs) ───────────────────pub mod config;diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rsindex e8bfac6..183100f 100644--- a/crates/liteparse/src/parser.rs+++ b/crates/liteparse/src/parser.rs@@ -171,6 +171,7 @@ impl LiteParse {false, // render_images: image rasters not needed for complexityfalse, // extract_links: irrelevant for complexity statsself.glyph_resolver.as_deref(),+ false, // emit_word_boxes: word boxes not needed for complexity stats)?;let t_extract = web_time::Instant::now();log(&format!(@@ -296,6 +297,7 @@ impl LiteParse {self.config.extract_links&& self.config.output_format == crate::config::OutputFormat::Markdown,self.glyph_resolver.as_deref(),+ self.config.emit_word_boxes,)?;let t_extract = web_time::Instant::now();log(&format!(diff --git a/crates/liteparse/src/types.rs b/crates/liteparse/src/types.rsindex 5717189..5ddf9f5 100644--- a/crates/liteparse/src/types.rs+++ b/crates/liteparse/src/types.rs@@ -67,6 +67,27 @@ pub struct TextItem {/// markdown emitter to wrap the text in `~~…~~`.#[serde(skip_serializing_if = "std::ops::Not::not")]pub strike: bool,+ /// Per-word sub-boxes within this item, split on the inter-word spaces seen+ /// during segment building. A segment groups several words together (it only+ /// breaks at line/column boundaries), so this exposes the finer word-level+ /// geometry needed for bbox attribution. Empty for items that produced no+ /// word split (e.g. OCR-sourced or single-token items). Internal/attribution+ /// use only — `#[serde(skip)]` keeps it out of the JSON output but it is+ /// marshalled across the napi boundary.+ #[serde(skip)]+ pub words: Vec<WordBox>,+}++/// One word's bounding box within a `TextItem`, in the same viewport space+/// (top-left origin, 72 DPI) as the parent item. `text` is the word's content+/// with inter-word spaces excluded.+#[derive(Debug, Clone, Default, Serialize)]+pub struct WordBox {+ pub text: String,+ pub x: f32,+ pub y: f32,+ pub width: f32,+ pub height: f32,}#[doc(hidden)]diff --git a/packages/node/native.d.ts b/packages/node/native.d.tsindex d428c16..f9fe03b 100644--- a/packages/node/native.d.ts+++ b/packages/node/native.d.ts@@ -56,6 +56,20 @@ export interface JsLiteParseConfig {* take the first success — lower tail latency at the cost of extra load.*/ocrHedgeDelaysMs?: Array<number>+ /**+ * Emit per-word sub-boxes on each text item (`TextItem.words`). Default+ * false. Word boxes roughly double the text-item payload, so enable only+ * for word-level bbox attribution.+ */+ emitWordBoxes?: boolean+}+/** One word's sub-box within a `JsTextItem`, in the same viewport space. */+export interface JsWordBox {+ text: string+ x: number+ y: number+ width: number+ height: number}export interface JsTextItem {text: string@@ -68,6 +82,11 @@ export interface JsTextItem {confidence?: number/** Rotation in degrees (viewport space). Defaults to 0 when omitted. */rotation?: number+ /**+ * Per-word sub-boxes for attribution. Empty for items with no word split+ * (e.g. OCR-sourced or single-token items).+ */+ words: Array<JsWordBox>}/*** A vector-graphic primitive supplied by an external extractor. `kind` selects@@ -136,6 +155,21 @@ export interface JsScreenshotResult {height: numberimageBuffer: Buffer}+export interface JsPageComplexityStats {+ pageNumber: number+ textLength: number+ textCoverage: number+ hasSubstantialImages: boolean+ imageBlockCount: number+ imageCoverage: number+ largestImageCoverage: number+ fullPageImage: boolean+ uncoveredVectorArea?: number+ isGarbled: boolean+ pageArea: number+ needsOcr: boolean+ reasons: Array<string>+}/** Search text items for phrase matches, returning merged items with combined bounding boxes. */export declare function searchItems(items: Array<JsTextItem>, phrase: string, caseSensitive?: boolean | undefined | null): Array<JsTextItem>/** Main LiteParse parser class. */@@ -157,6 +191,13 @@ export declare class LiteParse {* font-recovery pipeline).*/parsePages(pages: Array<JsPageInput>): JsParseResult+ /**+ * Determine per-page complexity. Returns one entry per parsed page with+ * signals (text coverage, images, garbled text, vector area) and a+ * `needsOcr` verdict — a cheap pre-OCR check to decide whether a document+ * needs advanced parsing. Accepts a file path (string) or raw PDF bytes.+ */+ isComplex(input: string | Buffer): Promise<Array<JsPageComplexityStats>>/*** Take screenshots of document pages. Returns PNG image buffers.*diff --git a/packages/node/src/lib.ts b/packages/node/src/lib.tsindex b713c9c..9b0206c 100644--- a/packages/node/src/lib.ts+++ b/packages/node/src/lib.ts@@ -51,6 +51,24 @@ export interface LiteParseConfig {* OCR pod, at the cost of extra OCR-server load. HTTP OCR engine only.*/ocrHedgeDelaysMs: number[];+ /**+ * Emit per-word sub-boxes on each text item ({@link TextItem.words}).+ * Default false. Word boxes roughly double the text-item payload (size + napi+ * marshalling), so enable only when doing word-level bbox attribution.+ */+ emitWordBoxes: boolean;+}++/**+ * One word's bounding box within a {@link TextItem}, in the same viewport space+ * (top-left origin, 72 DPI). `text` excludes inter-word spaces.+ */+export interface WordBox {+ text: string;+ x: number;+ y: number;+ width: number;+ height: number;}export interface TextItem {@@ -64,6 +82,13 @@ export interface TextItem {confidence?: number;/** Rotation in degrees (viewport space). Defaults to 0 when omitted. */rotation?: number;+ /**+ * Per-word sub-boxes within this item. A text item groups several words+ * together (breaking only at line/column boundaries), so this carries the+ * finer word-level geometry for bbox attribution. Empty/undefined for items+ * with no word split (e.g. OCR-sourced or single-token items).+ */+ words?: WordBox[];}/**@@ -199,6 +224,7 @@ export class LiteParse {numWorkers: userConfig.numWorkers,ocrFailureFatal: userConfig.ocrFailureFatal,ocrHedgeDelaysMs: userConfig.ocrHedgeDelaysMs,+ emitWordBoxes: userConfig.emitWordBoxes,};this._native = new native.LiteParse(nativeConfig);@@ -223,6 +249,7 @@ export class LiteParse {numWorkers: resolved.numWorkers ?? 1,ocrFailureFatal: resolved.ocrFailureFatal ?? true,ocrHedgeDelaysMs: resolved.ocrHedgeDelaysMs ?? [],+ emitWordBoxes: resolved.emitWordBoxes ?? false,};}@@ -339,6 +366,8 @@ function toTextItem(item: NativeTextItem): TextItem {fontName: item.fontName,fontSize: item.fontSize,confidence: item.confidence,+ rotation: item.rotation,+ words: item.words,};}diff --git a/packages/node/src/native.ts b/packages/node/src/native.tsindex c313491..dd16ded 100644--- a/packages/node/src/native.ts+++ b/packages/node/src/native.ts@@ -37,6 +37,15 @@ export interface LiteParseNativeConfig {numWorkers?: number;ocrFailureFatal?: boolean;ocrHedgeDelaysMs?: number[];+ emitWordBoxes?: boolean;+}++export interface NativeWordBox {+ text: string;+ x: number;+ y: number;+ width: number;+ height: number;}export interface NativeTextItem {@@ -49,6 +58,7 @@ export interface NativeTextItem {fontSize?: number;confidence?: number;rotation?: number;+ words?: NativeWordBox[];}export interface NativeGraphic {diff --git a/packages/python/liteparse/__init__.py b/packages/python/liteparse/__init__.pyindex eee674a..3ccef61 100644--- a/packages/python/liteparse/__init__.py+++ b/packages/python/liteparse/__init__.py@@ -6,6 +6,7 @@ from .types import (ParseResult,ParsedPage,TextItem,+ WordBox,ScreenshotResult,ParseError,)@@ -17,6 +18,7 @@ __all__ = ["ParseResult","ParsedPage","TextItem",+ "WordBox","ScreenshotResult","PageComplexityStats","ExtractedImage",diff --git a/packages/python/liteparse/parser.py b/packages/python/liteparse/parser.pyindex 68b47e6..823a9a8 100644--- a/packages/python/liteparse/parser.py+++ b/packages/python/liteparse/parser.py@@ -15,6 +15,7 @@ from .types import (ParseResult,ScreenshotResult,TextItem,+ WordBox,)@@ -32,6 +33,17 @@ def _convert_native_result(native_result: Any) -> ParseResult:font_name=item.font_name,font_size=item.font_size,confidence=item.confidence,+ rotation=getattr(item, "rotation", 0.0),+ words=[+ WordBox(+ text=w.text,+ x=w.x,+ y=w.y,+ width=w.width,+ height=w.height,+ )+ for w in getattr(item, "words", [])+ ],)for item in native_page.text_items]@@ -93,6 +105,7 @@ class LiteParse:extract_links: Optional[bool] = None,ocr_failure_fatal: Optional[bool] = None,ocr_hedge_delays_ms: Optional[List[int]] = None,+ emit_word_boxes: Optional[bool] = None,):"""Initialize LiteParse parser.@@ -125,6 +138,10 @@ class LiteParse:``[0, 5000, 10000]``) each attempt fires a duplicate request atevery delay and takes the first to succeed, cancelling the rest— trades extra OCR-server load for lower tail latency.+ emit_word_boxes: Emit per-word sub-boxes on each text item+ (``TextItem.words``). Default False. Word boxes roughly double+ the text-item payload, so enable only for word-level bbox+ attribution."""kwargs = {}if ocr_enabled is not None:@@ -161,6 +178,8 @@ class LiteParse:kwargs["ocr_failure_fatal"] = ocr_failure_fatalif ocr_hedge_delays_ms is not None:kwargs["ocr_hedge_delays_ms"] = ocr_hedge_delays_ms+ if emit_word_boxes is not None:+ kwargs["emit_word_boxes"] = emit_word_boxesself._native = _NativeLiteParse(**kwargs)diff --git a/packages/python/liteparse/types.py b/packages/python/liteparse/types.pyindex 57e8215..d85e8e9 100644--- a/packages/python/liteparse/types.py+++ b/packages/python/liteparse/types.py@@ -6,6 +6,17 @@ from dataclasses import dataclass, fieldfrom typing import Dict, Iterator, List, Optional+@dataclass+class WordBox:+ """One word's bounding box within a :class:`TextItem`, in the same viewport+ space (top-left origin, 72 DPI). ``text`` excludes inter-word spaces."""+ text: str+ x: float+ y: float+ width: float+ height: float++@dataclassclass TextItem:"""Individual text item extracted from a document."""@@ -17,6 +28,10 @@ class TextItem:font_name: Optional[str] = Nonefont_size: Optional[float] = Noneconfidence: Optional[float] = None+ rotation: float = 0.0+ #: Per-word sub-boxes. Empty unless the parser was configured with+ #: ``emit_word_boxes=True``.+ words: List[WordBox] = field(default_factory=list)@dataclass