Skip to main content

docling_core/
json.rs

1//! Export a [`DoclingDocument`] to docling-core's native JSON wire format
2//! (`DoclingDocument` schema v1.10.0) — the same shape `export_to_dict()` /
3//! `save_as_json()` produce in Python docling, and the inverse of the
4//! JSON-docling reader.
5//!
6//! The crate's [`Node`] model bakes Markdown escaping (and inline markers) into
7//! its text, whereas docling stores raw text and escapes at render time. We
8//! therefore *un-escape* on the way out so a docling-core round-trip
9//! (`load_from_json().export_to_markdown()`) reproduces the same Markdown.
10
11use serde_json::{json, Map, Value};
12
13use crate::document::{CaptionParent, ContentLayer, DoclingDocument, Node, Table};
14
15const SCHEMA_VERSION: &str = "1.10.0";
16
17/// docling-core's `CodeLanguageLabel` values (anything else serializes as
18/// `unknown`, which the model requires for code items).
19const CODE_LANGUAGES: &[&str] = &[
20    "Ada",
21    "Awk",
22    "Bash",
23    "bc",
24    "C",
25    "C#",
26    "C++",
27    "CMake",
28    "COBOL",
29    "CSS",
30    "Ceylon",
31    "Clojure",
32    "Crystal",
33    "Cuda",
34    "Cython",
35    "D",
36    "Dart",
37    "dc",
38    "Dockerfile",
39    "DocLang",
40    "Elixir",
41    "Erlang",
42    "FORTRAN",
43    "Forth",
44    "Go",
45    "HTML",
46    "Haskell",
47    "Haxe",
48    "Java",
49    "JavaScript",
50    "JSON",
51    "Julia",
52    "Kotlin",
53    "Latex",
54    "Lisp",
55    "Lua",
56    "Matlab",
57    "MoonScript",
58    "Nim",
59    "OCaml",
60    "ObjectiveC",
61    "Octave",
62    "PHP",
63    "Pascal",
64    "Perl",
65    "Prolog",
66    "Python",
67    "Racket",
68    "Ruby",
69    "Rust",
70    "SML",
71    "SQL",
72    "Scala",
73    "Scheme",
74    "Swift",
75    "Tikz",
76    "TypeScript",
77    "VisualBasic",
78    "XML",
79    "YAML",
80];
81
82/// Map a fence language to docling's `CodeLanguageLabel` (case-insensitive), else
83/// `unknown`.
84/// docling's `CodeLanguageLabel` for a language name (`unknown` when it is
85/// not one docling knows) — the mapping the JSON `code_language` field uses,
86/// for a backend that wants to test a hint before storing it.
87pub fn code_language_label(lang: &str) -> &'static str {
88    code_language(Some(lang))
89}
90
91pub(crate) fn code_language(lang: Option<&str>) -> &'static str {
92    match lang {
93        Some(l) => CODE_LANGUAGES
94            .iter()
95            .find(|c| c.eq_ignore_ascii_case(l))
96            .copied()
97            .unwrap_or("unknown"),
98        None => "unknown",
99    }
100}
101
102/// An item's exact provenance, written verbatim (see [`Builder::prov_json`]):
103/// a [`Node::Prov`] wrapper's top-left page box, or a tree item's
104/// [`TreeProv`](crate::tree::TreeProv).
105#[derive(Clone, Copy)]
106struct ExactProv {
107    page_no: usize,
108    bbox: [f64; 4],
109    bottom_left: bool,
110    charspan: [usize; 2],
111}
112
113impl From<&crate::tree::TreeProv> for ExactProv {
114    fn from(p: &crate::tree::TreeProv) -> Self {
115        ExactProv {
116            page_no: p.page_no,
117            bbox: p.bbox,
118            bottom_left: p.bottom_left,
119            charspan: p.charspan,
120        }
121    }
122}
123
124/// Page sizes by page number; the first entry per page wins.
125type PageSizes = std::collections::HashMap<usize, (f64, f64)>;
126
127fn page_sizes(pages: &[(usize, f64, f64)]) -> PageSizes {
128    let mut sizes = PageSizes::with_capacity(pages.len());
129    for &(p, w, h) in pages {
130        sizes.entry(p).or_insert((w, h));
131    }
132    sizes
133}
134
135/// docling-core's `_clamp_provenance_bboxes_to_pages`: each `prov` box of
136/// every item on a known page is clamped to `[0, width] × [0, height]`
137/// (whatever its `coord_origin` — docling clamps the stored numbers), and a
138/// table whose provenance sits on one page has its cell boxes clamped too.
139/// Runs over the finished `texts`, `pictures`, `tables` and
140/// `key_value_items` (the form-field buckets are left as built).
141fn clamp_boxes_to_pages(b: &mut Builder) {
142    if b.pages.is_empty() {
143        return;
144    }
145    // A map, not a scan per box: that was items × pages on long documents.
146    let sizes = page_sizes(&b.pages);
147    for item in &mut b.texts {
148        match item {
149            Item::Text(t) => t.prov.clamp(&sizes),
150            Item::Json(v) => {
151                clamp_item(v, &sizes);
152            }
153        }
154    }
155    for item in b.pictures.iter_mut().chain(b.key_value_items.iter_mut()) {
156        clamp_item(item, &sizes);
157    }
158    for t in &mut b.tables {
159        if let Some(size) = clamp_item(&mut t.item, &sizes) {
160            t.data.clamp(size);
161        }
162    }
163}
164
165/// Clamp `item`'s `prov` boxes; returns the size of the page when the item
166/// sits on exactly one known page — a table's cells are clamped to it.
167fn clamp_item(item: &mut Value, sizes: &PageSizes) -> Option<(f64, f64)> {
168    let size = |page_no: &Value| -> Option<(f64, f64)> {
169        let n = page_no.as_u64()? as usize;
170        sizes.get(&n).copied()
171    };
172    let clamp_bbox = |bbox: &mut Value, (w, h): (f64, f64)| {
173        for (key, hi) in [("l", w), ("r", w), ("t", h), ("b", h)] {
174            if let Some(v) = bbox.get(key).and_then(Value::as_f64) {
175                bbox[key] = json!(round2(v.clamp(0.0, hi.max(0.0))));
176            }
177        }
178    };
179    let mut table_page: Option<Option<(f64, f64)>> = None;
180    if let Some(provs) = item.get_mut("prov").and_then(Value::as_array_mut) {
181        let mut page_nos: Vec<u64> = Vec::new();
182        for prov in provs.iter_mut() {
183            if let Some(n) = prov.get("page_no").and_then(Value::as_u64) {
184                page_nos.push(n);
185            }
186            let Some(sz) = prov.get("page_no").and_then(size) else {
187                continue;
188            };
189            if let Some(bbox) = prov.get_mut("bbox") {
190                clamp_bbox(bbox, sz);
191            }
192        }
193        page_nos.sort_unstable();
194        page_nos.dedup();
195        if let [only] = page_nos[..] {
196            table_page = Some(size(&json!(only)));
197        }
198    }
199    table_page.flatten()
200}
201
202/// docling-core's `Formatting` model, every field written.
203fn formatting_json(f: &crate::tree::Formatting) -> Value {
204    json!({
205        "bold": f.bold,
206        "italic": f.italic,
207        "underline": f.underline,
208        "strikethrough": f.strikethrough,
209        "script": match f.script {
210            crate::Script::Baseline => "baseline",
211            crate::Script::Sub => "sub",
212            crate::Script::Super => "super",
213        },
214    })
215}
216
217/// docling's `TrackSource` entry: `kind`, the two offsets, then the optional
218/// `identifier` / `voice` (dropped when `None`, as `exclude_none` does).
219fn track_json(t: &crate::tree::TreeTrack) -> Value {
220    let mut m = serde_json::Map::new();
221    m.insert("kind".into(), json!("track"));
222    m.insert("start_time".into(), json!(t.start_time));
223    m.insert("end_time".into(), json!(t.end_time));
224    if let Some(id) = &t.identifier {
225        m.insert("identifier".into(), json!(id));
226    }
227    if let Some(v) = &t.voice {
228        m.insert("voice".into(), json!(v));
229    }
230    Value::Object(m)
231}
232
233/// docling-core's `ImageRef` (pydantic field order: mimetype, dpi, size —
234/// as floats — uri), with the bytes inlined as a `data:` URI — a PNG, like
235/// `ImageRef.from_pil`'s (`pixel_digest::docling_data_uri`).
236fn image_ref_json(img: &crate::PictureImage) -> Value {
237    let (mimetype, uri) = crate::pixel_digest::docling_data_uri(img);
238    json!({
239        "mimetype": mimetype,
240        "dpi": img.dpi,
241        "size": { "width": img.width as f64, "height": img.height as f64 },
242        "uri": uri,
243    })
244}
245
246/// Build the docling-core JSON object for `doc`.
247pub fn to_json(doc: &DoclingDocument) -> Value {
248    build_parts(doc, false).into_value(None)
249}
250
251/// The key a table's `data` is replaced by in [`to_json_typed_tables`]'s
252/// `Value`: the index of its [`TableData`] beside it.
253pub(crate) const TYPED_TABLE: &str = "_typed_table";
254
255/// [`to_json`] for the serializers that walk the `Value` (HTML, Pandoc,
256/// WebVTT), with each table's `data` left typed (#875): the item carries
257/// `{"_typed_table": i}` and the cells are `tables[i]`, read through
258/// [`table_view`]. As a `Value` a table cost two maps of eleven owned keys
259/// per cell (its `table_cells` record and its `grid` copy) — 2.6 GB of an
260/// HTML export's peak on a 640,000-cell CSV. `note_keys` adds the Pandoc
261/// writer's keys ([`to_json_with_notes`]).
262pub(crate) fn to_json_typed_tables(
263    doc: &DoclingDocument,
264    note_keys: bool,
265) -> (Value, Vec<TableData>) {
266    let mut tables = Vec::new();
267    let value = build_parts(doc, note_keys).into_value(Some(&mut tables));
268    (value, tables)
269}
270
271/// [`to_json`] plus the note calls docling's model cannot express: a text
272/// item calling footnotes carries `"_notes": [[offset, text], …]`, a
273/// footnote item that is such a note's body `"_note_body": true` (#538),
274/// a text item that is a link destination `"_anchors": ["id", …]` (#849),
275/// a heading whose text opens with generated numbering `"_number": "1.2"`
276/// (#850), a run kept as a tracked change `"_revision": {"kind":
277/// "insertion" | "deletion", "author", "date"}` (#851),
278/// a picture's image its displayed size `"_display": [width, height]` in
279/// inches (#834), and the document's `metadata` whether or not the JSON
280/// export was asked for it (#836). The Pandoc writer reads these; nothing
281/// is ever exported with them. The tables stay typed, as in
282/// [`to_json_typed_tables`].
283pub(crate) fn to_json_with_notes(doc: &DoclingDocument) -> (Value, Vec<TableData>) {
284    to_json_typed_tables(doc, true)
285}
286
287fn build_parts(doc: &DoclingDocument, note_keys: bool) -> Parts {
288    let mut b = Builder {
289        note_keys,
290        ..Builder::default()
291    };
292    // A backend that built docling's item tree ([`crate::tree`]) has already
293    // decided every parent, child and creation index; serialize that. The
294    // flat nodes are for the other serializers.
295    let body = match &doc.tree {
296        Some(tree) => {
297            // The page map still comes from the flat stream's markers (a
298            // PPTX slide's EMU size): the tree holds items, not pages.
299            for n in &doc.nodes {
300                if let Node::PageInfo {
301                    page_no,
302                    width,
303                    height,
304                } = n
305                {
306                    if *page_no > 0 {
307                        b.pages.push((*page_no, *width as f64, *height as f64));
308                    }
309                }
310            }
311            // docling-core's `validate_misplaced_list_items` runs on every
312            // document it serializes; apply it the same way (keeping the
313            // items' children, which docling-core drops — #586).
314            let mut tree = tree.clone();
315            tree.wrap_misplaced_list_items();
316            b.write_tree(&tree).into_iter().map(Child::json).collect()
317        }
318        None => b.walk_into(&doc.nodes, "#/body"),
319    };
320    b.link_comments();
321
322    // docling-core's `validate_document` — a pydantic `model_validator` every
323    // `DoclingDocument` passes through when a `ConversionResult` (or a
324    // serializer) is built around it — clamps every provenance box, and a
325    // table's cell boxes, into its page's bounds in place
326    // (`_clamp_provenance_bboxes_to_pages`). The JSON docling writes therefore
327    // carries the clamped boxes: a spreadsheet region whose page was sized
328    // `right − left` × `bottom − top` loses its offset, a slide shape hanging
329    // off the slide edge is cut at it. Reproduce that on the finished items.
330    clamp_boxes_to_pages(&mut b);
331
332    let pages = b
333        .pages
334        .iter()
335        .map(|(n, w, h)| {
336            let r2 = |v: f64| (v * 100.0).round() / 100.0;
337            // docling-core's `PageItem` field order: size, image, page_no
338            // (#520 — the image only when page images were generated).
339            let mut page = serde_json::Map::new();
340            page.insert("size".into(), json!({ "width": r2(*w), "height": r2(*h) }));
341            if let Some(img) = doc.page_images.get(n) {
342                page.insert("image".into(), image_ref_json(img));
343            }
344            page.insert("page_no".into(), json!(n));
345            (n.to_string(), Value::Object(page))
346        })
347        .collect::<serde_json::Map<String, Value>>();
348    // docling only emits `field_regions` / `field_items` when a document has
349    // form fields, and places them just before `pages`.
350    let fields = (!b.field_regions.is_empty()).then_some((b.field_regions, b.field_items));
351    Parts {
352        name: doc.name.clone(),
353        // The Pandoc writer (`note_keys`) always gets the metadata, for
354        // its `meta` (#836); the JSON export only when asked.
355        metadata: (doc.metadata_output.in_json() || note_keys)
356            .then(|| doc.metadata.to_json())
357            .filter(|m| m.as_object().is_some_and(|o| !o.is_empty())),
358        origin: json!({
359            "mimetype": "text/plain",
360            "binary_hash": fnv1a(&doc.name),
361            "filename": doc.name,
362        }),
363        furniture: json!({
364            "self_ref": "#/furniture",
365            "children": [],
366            "content_layer": "furniture",
367            "name": "_root_",
368            "label": "unspecified",
369        }),
370        body,
371        groups: b.groups,
372        texts: b.texts,
373        pictures: b.pictures,
374        tables: b.tables,
375        key_value_items: b.key_value_items,
376        fields,
377        pages,
378    }
379}
380
381/// The finished document, before it is a `Value`: one representation
382/// behind both [`to_json`] (a `Value`) and [`write_json`] (bytes, with no
383/// `Value` ever built — the text items stay compact [`Item`]s throughout).
384/// Both produce the same keys in the same order.
385struct Parts {
386    name: String,
387    /// The document's metadata (#679), after `origin`, only when the
388    /// document's output mode asks for it and there is any.
389    metadata: Option<Value>,
390    origin: Value,
391    furniture: Value,
392    /// The body's `children`; the rest of the body object is fixed.
393    body: Vec<Child>,
394    groups: Vec<Value>,
395    texts: Vec<Item>,
396    pictures: Vec<Value>,
397    tables: Vec<TableItem>,
398    key_value_items: Vec<Value>,
399    /// `field_regions` and `field_items`, present only for a document with
400    /// form fields (non-form documents' JSON has neither key).
401    fields: Option<(Vec<Value>, Vec<Value>)>,
402    pages: serde_json::Map<String, Value>,
403}
404
405impl Parts {
406    /// The document `Value`; with `typed`, the tables' `data` goes there
407    /// instead (see [`to_json_typed_tables`]).
408    fn into_value(self, mut typed: Option<&mut Vec<TableData>>) -> Value {
409        // Moved in, never through `json!`, which would deep-copy each array.
410        let mut out = serde_json::Map::with_capacity(15);
411        out.insert("schema_name".into(), "DoclingDocument".into());
412        out.insert("version".into(), SCHEMA_VERSION.into());
413        out.insert("name".into(), Value::String(self.name));
414        out.insert("origin".into(), self.origin);
415        if let Some(m) = self.metadata {
416            out.insert("metadata".into(), m);
417        }
418        out.insert("furniture".into(), self.furniture);
419        out.insert(
420            "body".into(),
421            object([
422                ("self_ref", "#/body".into()),
423                (
424                    "children",
425                    Value::Array(self.body.into_iter().map(Child::into_value).collect()),
426                ),
427                ("content_layer", "body".into()),
428                ("name", "_root_".into()),
429                ("label", "unspecified".into()),
430            ]),
431        );
432        out.insert("groups".into(), Value::Array(self.groups));
433        out.insert(
434            "texts".into(),
435            Value::Array(
436                self.texts
437                    .into_iter()
438                    .enumerate()
439                    .map(|(i, item)| item.into_value(i))
440                    .collect(),
441            ),
442        );
443        out.insert("pictures".into(), Value::Array(self.pictures));
444        out.insert(
445            "tables".into(),
446            Value::Array(
447                self.tables
448                    .into_iter()
449                    .map(|t| match typed.as_deref_mut() {
450                        Some(store) => {
451                            let TableItem { mut item, data } = t;
452                            if let Some(slot) = item.get_mut("data") {
453                                *slot = object([(TYPED_TABLE, store.len().into())]);
454                            }
455                            store.push(data);
456                            item
457                        }
458                        None => t.into_value(),
459                    })
460                    .collect(),
461            ),
462        );
463        out.insert("key_value_items".into(), Value::Array(self.key_value_items));
464        out.insert("form_items".into(), Value::Array(Vec::new()));
465        if let Some((regions, items)) = self.fields {
466            out.insert("field_regions".into(), Value::Array(regions));
467            out.insert("field_items".into(), Value::Array(items));
468        }
469        out.insert("pages".into(), Value::Object(self.pages));
470        Value::Object(out)
471    }
472}
473
474/// [`Parts`] with `extras` — top-level keys a caller appends after
475/// `pages`, as inserting them into [`to_json`]'s `Value` would.
476struct PartsWith<'a>(&'a Parts, &'a [(&'a str, &'a Value)]);
477
478impl serde::Serialize for PartsWith<'_> {
479    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
480        use serde::ser::SerializeMap;
481        let PartsWith(parts, extras) = *self;
482        let mut m = s.serialize_map(Some(
483            13 + 2 * usize::from(parts.fields.is_some())
484                + usize::from(parts.metadata.is_some())
485                + extras.len(),
486        ))?;
487        m.serialize_entry("schema_name", "DoclingDocument")?;
488        m.serialize_entry("version", SCHEMA_VERSION)?;
489        m.serialize_entry("name", &parts.name)?;
490        m.serialize_entry("origin", &parts.origin)?;
491        if let Some(meta) = &parts.metadata {
492            m.serialize_entry("metadata", meta)?;
493        }
494        m.serialize_entry("furniture", &parts.furniture)?;
495        m.serialize_entry("body", &Body(&parts.body))?;
496        m.serialize_entry("groups", &parts.groups)?;
497        m.serialize_entry("texts", &Texts(&parts.texts))?;
498        m.serialize_entry("pictures", &parts.pictures)?;
499        m.serialize_entry("tables", &parts.tables)?;
500        m.serialize_entry("key_value_items", &parts.key_value_items)?;
501        m.serialize_entry("form_items", &[(); 0])?;
502        if let Some((regions, items)) = &parts.fields {
503            m.serialize_entry("field_regions", regions)?;
504            m.serialize_entry("field_items", items)?;
505        }
506        m.serialize_entry("pages", &parts.pages)?;
507        for (k, v) in extras {
508            m.serialize_entry(k, v)?;
509        }
510        m.end()
511    }
512}
513
514/// The body object: fixed keys around its `children`.
515struct Body<'a>(&'a [Child]);
516
517impl serde::Serialize for Body<'_> {
518    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
519        use serde::ser::SerializeMap;
520        let mut m = s.serialize_map(Some(5))?;
521        m.serialize_entry("self_ref", "#/body")?;
522        m.serialize_entry("children", self.0)?;
523        m.serialize_entry("content_layer", "body")?;
524        m.serialize_entry("name", "_root_")?;
525        m.serialize_entry("label", "unspecified")?;
526        m.end()
527    }
528}
529
530/// Write `doc`'s docling JSON to `w` — byte for byte what serializing
531/// [`to_json`]'s `Value` writes (compact, or `pretty` as
532/// `serde_json::to_writer_pretty` indents it), without building that
533/// `Value`. On a long PDF the `Value` is most of the export's memory: ~2.7 KB
534/// per text item (an owned-key map per JSON object) against a few hundred
535/// bytes here.
536pub fn write_json<W: std::io::Write>(
537    doc: &DoclingDocument,
538    w: W,
539    pretty: bool,
540) -> serde_json::Result<()> {
541    write_json_with(doc, w, pretty, &[])
542}
543
544/// [`write_json`] with `extras` appended after `pages` — byte for byte
545/// serializing [`to_json`]'s `Value` with each `value[k] = v` inserted (the
546/// keys must be new to it, as docling-serve's `confidence` is).
547pub fn write_json_with<W: std::io::Write>(
548    doc: &DoclingDocument,
549    w: W,
550    pretty: bool,
551    extras: &[(&str, &Value)],
552) -> serde_json::Result<()> {
553    use serde::Serialize;
554    let parts = build_parts(doc, false);
555    let parts = PartsWith(&parts, extras);
556    if pretty {
557        parts.serialize(&mut serde_json::Serializer::pretty(w))
558    } else {
559        parts.serialize(&mut serde_json::Serializer::new(w))
560    }
561}
562
563/// A DocumentPictureClassifier's predictions as the picture's `meta` — they
564/// land twice, exactly like docling 2.x writes them: the newer
565/// `meta.classification` field (pydantic field order: confidence, created_by,
566/// class_name) and the deprecated-but-still-emitted `classification`
567/// annotation, carried here under an `annotations` key that `add_picture`
568/// lifts onto the item.
569fn classification_meta(classes: &[crate::PictureClass]) -> Value {
570    json!({
571        "classification": {
572            "predictions": classes.iter().map(|c| json!({
573                "confidence": c.confidence as f64,
574                "created_by": "DocumentPictureClassifier",
575                "class_name": c.class_name,
576            })).collect::<Vec<_>>(),
577        },
578        "annotations": [{
579            "kind": "classification",
580            "provenance": "DocumentPictureClassifier",
581            "predicted_classes": classes.iter().map(|c| json!({
582                "class_name": c.class_name,
583                "confidence": c.confidence as f64,
584            })).collect::<Vec<_>>(),
585        }],
586    })
587}
588
589/// The picture-OCR enrichment's text (#645) as docling writes a picture
590/// description: `meta.description` — a `DescriptionMetaField`, pydantic
591/// field order `created_by` (the model, here the OCR engine) then `text` —
592/// plus the deprecated-but-still-emitted `PictureDescriptionData`
593/// annotation (`kind`, `text`, `provenance`), both exactly what
594/// `PictureDescriptionBaseModel` attaches. Carried like
595/// [`classification_meta`]'s: `annotations` is lifted onto the item.
596fn description_meta(desc: &crate::PictureDescription) -> Value {
597    json!({
598        "description": {
599            "created_by": desc.provenance,
600            "text": desc.text,
601        },
602        "annotations": [{
603            "kind": "description",
604            "text": desc.text,
605            "provenance": desc.provenance,
606        }],
607    })
608}
609
610/// A flat picture node's `meta`: the classifier's predictions and/or the
611/// OCR description, merged — `description` precedes `classification` in
612/// `PictureMeta`'s field order (it is inherited from the floating-item
613/// base), the annotations run in the order docling's enrichment pipeline
614/// appends them (classification, then description).
615fn picture_meta(
616    classes: Option<&[crate::PictureClass]>,
617    desc: Option<&crate::PictureDescription>,
618) -> Option<Value> {
619    let mut meta = Map::new();
620    let mut annotations = Vec::new();
621    if let Some(desc) = desc {
622        let mut m = description_meta(desc);
623        annotations.push(m["annotations"][0].take());
624        meta.insert("description".into(), m["description"].take());
625    }
626    if let Some(classes) = classes {
627        let mut m = classification_meta(classes);
628        annotations.insert(0, m["annotations"][0].take());
629        meta.insert("classification".into(), m["classification"].take());
630    }
631    if meta.is_empty() {
632        return None;
633    }
634    meta.insert("annotations".into(), Value::Array(annotations));
635    Some(Value::Object(meta))
636}
637
638/// One table cell of docling's `TableCell`, typed (#875): the table's cells
639/// stay these until the export writes them, rather than a `serde_json` map
640/// of eleven owned keys each — and a second copy of that map in every grid
641/// slot the cell covers. As maps a short numeric CSV cell cost ~7.5 KB of
642/// export peak; typed it is this struct plus its text.
643#[derive(Clone)]
644pub(crate) struct GridCell {
645    row_span: usize,
646    col_span: usize,
647    start_row: usize,
648    end_row: usize,
649    start_col: usize,
650    end_col: usize,
651    text: Box<str>,
652    column_header: bool,
653    row_header: bool,
654    row_section: bool,
655    /// `l t r b`, top-left origin — the backend's `f32` box widened to the
656    /// `f64` a `Value` would hold it as, so both paths print the same digits.
657    bbox: Option<[f64; 4]>,
658    /// A `RichTableCell`'s `ref` to the group holding its content — written
659    /// on `table_cells` only; the `grid` shows the plain cell.
660    cell_ref: Option<Box<Value>>,
661}
662
663impl GridCell {
664    /// docling's empty filler for a grid position no cell covers.
665    fn filler(r: usize, c: usize) -> Self {
666        GridCell {
667            row_span: 1,
668            col_span: 1,
669            start_row: r,
670            end_row: r + 1,
671            start_col: c,
672            end_col: c + 1,
673            text: "".into(),
674            column_header: false,
675            row_header: false,
676            row_section: false,
677            bbox: None,
678            cell_ref: None,
679        }
680    }
681
682    /// The cell as a `Value`: the eleven fields in pydantic order, `bbox`
683    /// appended when the cell carries one, then the rich cell's `ref`
684    /// (`with_ref`, the `table_cells` copy). Built straight into a `Map`
685    /// sized for its entries rather than through `json!`'s doubling map.
686    fn to_value(&self, with_ref: bool) -> Value {
687        let mut m = serde_json::Map::with_capacity(13);
688        m.insert("row_span".into(), self.row_span.into());
689        m.insert("col_span".into(), self.col_span.into());
690        m.insert("start_row_offset_idx".into(), self.start_row.into());
691        m.insert("end_row_offset_idx".into(), self.end_row.into());
692        m.insert("start_col_offset_idx".into(), self.start_col.into());
693        m.insert("end_col_offset_idx".into(), self.end_col.into());
694        m.insert("text".into(), Value::String(self.text.to_string()));
695        m.insert("column_header".into(), self.column_header.into());
696        m.insert("row_header".into(), self.row_header.into());
697        m.insert("row_section".into(), self.row_section.into());
698        m.insert("fillable".into(), false.into());
699        if let Some([l, t, r, b]) = self.bbox {
700            m.insert(
701                "bbox".into(),
702                object([
703                    ("l", l.into()),
704                    ("t", t.into()),
705                    ("r", r.into()),
706                    ("b", b.into()),
707                    ("coord_origin", "TOPLEFT".into()),
708                ]),
709            );
710        }
711        if let Some(r) = self.cell_ref.as_deref().filter(|_| with_ref) {
712            m.insert("ref".into(), r.clone());
713        }
714        Value::Object(m)
715    }
716}
717
718/// [`GridCell::to_value`] written in place: the same keys in the same order.
719struct CellOut<'a>(&'a GridCell, bool);
720
721impl serde::Serialize for CellOut<'_> {
722    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
723        use serde::ser::SerializeMap;
724        let CellOut(c, with_ref) = *self;
725        let cell_ref = c.cell_ref.as_deref().filter(|_| with_ref);
726        let mut m = s.serialize_map(Some(
727            11 + usize::from(c.bbox.is_some()) + usize::from(cell_ref.is_some()),
728        ))?;
729        m.serialize_entry("row_span", &c.row_span)?;
730        m.serialize_entry("col_span", &c.col_span)?;
731        m.serialize_entry("start_row_offset_idx", &c.start_row)?;
732        m.serialize_entry("end_row_offset_idx", &c.end_row)?;
733        m.serialize_entry("start_col_offset_idx", &c.start_col)?;
734        m.serialize_entry("end_col_offset_idx", &c.end_col)?;
735        m.serialize_entry("text", &c.text)?;
736        m.serialize_entry("column_header", &c.column_header)?;
737        m.serialize_entry("row_header", &c.row_header)?;
738        m.serialize_entry("row_section", &c.row_section)?;
739        m.serialize_entry("fillable", &false)?;
740        if let Some(b) = c.bbox {
741            struct Bbox([f64; 4]);
742            impl serde::Serialize for Bbox {
743                fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
744                    let mut m = s.serialize_map(Some(5))?;
745                    for (k, v) in ["l", "t", "r", "b"].iter().zip(self.0) {
746                        m.serialize_entry(k, &v)?;
747                    }
748                    m.serialize_entry("coord_origin", "TOPLEFT")?;
749                    m.end()
750                }
751            }
752            m.serialize_entry("bbox", &Bbox(b))?;
753        }
754        if let Some(r) = cell_ref {
755            m.serialize_entry("ref", r)?;
756        }
757        m.end()
758    }
759}
760
761/// What a `grid` position shows: the cell covering it (an index into
762/// [`TableData::cells`] — docling repeats the whole cell at every position
763/// it spans), docling's empty filler cell, or `null`.
764#[derive(Clone, Copy)]
765enum GridSlot {
766    Cell(usize),
767    Filler,
768    Null,
769}
770
771/// docling's `TableData` for a table: `table_cells`, `num_rows`/`num_cols`
772/// and the `grid` that repeats each cell at every position it covers —
773/// typed (#875), each cell stored once and the grid as slots pointing at
774/// it, so a table costs its cells rather than a map per cell and per slot.
775/// Shared by table items and a chart picture's `meta.tabular_chart.chart_data`.
776pub(crate) struct TableData {
777    cells: Vec<GridCell>,
778    num_rows: usize,
779    num_cols: usize,
780    /// Row-major, `num_rows × num_cols`.
781    grid: Vec<GridSlot>,
782}
783
784/// One position of docling's `TableData.grid`, as the DocLang tree
785/// serializer reads it (`doclang_tree.rs`): the covering cell's anchor,
786/// text and header roles — an empty filler where no cell covers the
787/// position, which is what docling's computed `grid` holds there.
788pub(crate) struct GridPos<'a> {
789    pub(crate) start_row: usize,
790    pub(crate) start_col: usize,
791    pub(crate) text: &'a str,
792    pub(crate) column_header: bool,
793    pub(crate) row_header: bool,
794    pub(crate) row_section: bool,
795}
796
797/// [`TableData`] of a backend-built tree's table (raw cell text).
798pub(crate) fn raw_table_data(t: &Table) -> TableData {
799    table_data_with(t, true)
800}
801
802impl TableData {
803    /// `(num_rows, num_cols)`.
804    pub(crate) fn dims(&self) -> (usize, usize) {
805        (self.num_rows, self.num_cols)
806    }
807
808    /// Whether `table_cells` holds any cell.
809    pub(crate) fn has_cells(&self) -> bool {
810        !self.cells.is_empty()
811    }
812
813    /// The grid position `(r, c)`.
814    pub(crate) fn at(&self, r: usize, c: usize) -> GridPos<'_> {
815        match self.grid[r * self.num_cols + c] {
816            GridSlot::Cell(i) => {
817                let cell = &self.cells[i];
818                GridPos {
819                    start_row: cell.start_row,
820                    start_col: cell.start_col,
821                    text: &cell.text,
822                    column_header: cell.column_header,
823                    row_header: cell.row_header,
824                    row_section: cell.row_section,
825                }
826            }
827            GridSlot::Filler | GridSlot::Null => GridPos {
828                start_row: r,
829                start_col: c,
830                text: "",
831                column_header: false,
832                row_header: false,
833                row_section: false,
834            },
835        }
836    }
837}
838
839impl TableData {
840    fn slot_cell(
841        &self,
842        slot: GridSlot,
843        r: usize,
844        c: usize,
845    ) -> Option<std::borrow::Cow<'_, GridCell>> {
846        match slot {
847            GridSlot::Cell(i) => Some(std::borrow::Cow::Borrowed(&self.cells[i])),
848            GridSlot::Filler => Some(std::borrow::Cow::Owned(GridCell::filler(r, c))),
849            GridSlot::Null => None,
850        }
851    }
852
853    fn into_value(self) -> Value {
854        let cells = Value::Array(self.cells.iter().map(|c| c.to_value(true)).collect());
855        let mut data = serde_json::Map::with_capacity(5);
856        data.insert("table_cells".into(), cells);
857        data.insert("num_rows".into(), self.num_rows.into());
858        data.insert("num_cols".into(), self.num_cols.into());
859        data.insert("orientation".into(), "rot_0".into());
860        let mut rows = Vec::with_capacity(self.num_rows);
861        for r in 0..self.num_rows {
862            let mut row = Vec::with_capacity(self.num_cols);
863            for c in 0..self.num_cols {
864                let slot = self.grid[r * self.num_cols + c];
865                row.push(match self.slot_cell(slot, r, c) {
866                    Some(cell) => cell.to_value(false),
867                    None => Value::Null,
868                });
869            }
870            rows.push(Value::Array(row));
871        }
872        data.insert("grid".into(), Value::Array(rows));
873        Value::Object(data)
874    }
875
876    /// docling's page clamp ([`clamp_boxes_to_pages`]) on every cell box —
877    /// once per cell: the grid's copies are the same cells.
878    fn clamp(&mut self, (w, h): (f64, f64)) {
879        for bbox in self.cells.iter_mut().filter_map(|c| c.bbox.as_mut()) {
880            for (v, hi) in bbox.iter_mut().zip([w, h, w, h]) {
881                // A non-finite coordinate is `null` in the JSON, which the
882                // clamp leaves alone.
883                if v.is_finite() {
884                    *v = round2(v.clamp(0.0, hi.max(0.0)));
885                }
886            }
887        }
888    }
889}
890
891impl serde::Serialize for TableData {
892    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
893        use serde::ser::{SerializeMap, SerializeSeq};
894        struct Cells<'a>(&'a [GridCell]);
895        impl serde::Serialize for Cells<'_> {
896            fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
897                let mut seq = s.serialize_seq(Some(self.0.len()))?;
898                for c in self.0 {
899                    seq.serialize_element(&CellOut(c, true))?;
900                }
901                seq.end()
902            }
903        }
904        struct Row<'a>(&'a TableData, usize);
905        impl serde::Serialize for Row<'_> {
906            fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
907                let Row(t, r) = *self;
908                let mut seq = s.serialize_seq(Some(t.num_cols))?;
909                for c in 0..t.num_cols {
910                    match t.slot_cell(t.grid[r * t.num_cols + c], r, c) {
911                        Some(cell) => seq.serialize_element(&CellOut(&cell, false))?,
912                        None => seq.serialize_element(&())?,
913                    }
914                }
915                seq.end()
916            }
917        }
918        struct Grid<'a>(&'a TableData);
919        impl serde::Serialize for Grid<'_> {
920            fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
921                let mut seq = s.serialize_seq(Some(self.0.num_rows))?;
922                for r in 0..self.0.num_rows {
923                    seq.serialize_element(&Row(self.0, r))?;
924                }
925                seq.end()
926            }
927        }
928        let mut m = s.serialize_map(Some(5))?;
929        m.serialize_entry("table_cells", &Cells(&self.cells))?;
930        m.serialize_entry("num_rows", &self.num_rows)?;
931        m.serialize_entry("num_cols", &self.num_cols)?;
932        m.serialize_entry("orientation", "rot_0")?;
933        m.serialize_entry("grid", &Grid(self))?;
934        m.end()
935    }
936}
937
938/// A table cell as the `Value`-walking serializers read it — from a typed
939/// [`GridCell`] or from a `table_cells` entry of docling JSON (a document
940/// Python docling wrote, read by [`crate::pandoc::from_docling_json`]): a
941/// missing field reads as `0` / `""` / `false`, like the `Value` getters
942/// those serializers used.
943pub(crate) struct CellView<'a> {
944    pub start_row: usize,
945    pub end_row: usize,
946    pub start_col: usize,
947    pub end_col: usize,
948    pub row_span: usize,
949    pub col_span: usize,
950    pub text: &'a str,
951    pub column_header: bool,
952    pub row_header: bool,
953    pub row_section: bool,
954    /// A rich cell's `ref.$ref`.
955    pub cell_ref: Option<&'a str>,
956}
957
958/// A table's `data` as [`CellView`]s: `num_rows`, `num_cols` and the
959/// `table_cells` (the derived `grid` is not read).
960pub(crate) struct TableView<'a> {
961    pub num_rows: usize,
962    pub num_cols: usize,
963    pub cells: Vec<CellView<'a>>,
964}
965
966/// The [`TableView`] of a table item's `data`: the typed table it names
967/// ([`TYPED_TABLE`], an index into `typed`), or the JSON's own fields.
968pub(crate) fn table_view<'a>(data: &'a Value, typed: &'a [TableData]) -> TableView<'a> {
969    let ref_of = |r: Option<&'a Value>| r.and_then(|r| r.get("$ref")).and_then(Value::as_str);
970    if let Some(t) = data
971        .get(TYPED_TABLE)
972        .and_then(Value::as_u64)
973        .and_then(|i| typed.get(i as usize))
974    {
975        return TableView {
976            num_rows: t.num_rows,
977            num_cols: t.num_cols,
978            cells: t
979                .cells
980                .iter()
981                .map(|c| CellView {
982                    start_row: c.start_row,
983                    end_row: c.end_row,
984                    start_col: c.start_col,
985                    end_col: c.end_col,
986                    row_span: c.row_span,
987                    col_span: c.col_span,
988                    text: &c.text,
989                    column_header: c.column_header,
990                    row_header: c.row_header,
991                    row_section: c.row_section,
992                    cell_ref: ref_of(c.cell_ref.as_deref()),
993                })
994                .collect(),
995        };
996    }
997    let num = |v: &Value, k: &str| v.get(k).and_then(Value::as_u64).unwrap_or(0) as usize;
998    let flag = |v: &Value, k: &str| v.get(k).and_then(Value::as_bool).unwrap_or(false);
999    TableView {
1000        num_rows: num(data, "num_rows"),
1001        num_cols: num(data, "num_cols"),
1002        cells: data
1003            .get("table_cells")
1004            .and_then(Value::as_array)
1005            .into_iter()
1006            .flatten()
1007            .map(|c| CellView {
1008                start_row: num(c, "start_row_offset_idx"),
1009                end_row: num(c, "end_row_offset_idx"),
1010                start_col: num(c, "start_col_offset_idx"),
1011                end_col: num(c, "end_col_offset_idx"),
1012                row_span: num(c, "row_span"),
1013                col_span: num(c, "col_span"),
1014                text: c.get("text").and_then(Value::as_str).unwrap_or(""),
1015                column_header: flag(c, "column_header"),
1016                row_header: flag(c, "row_header"),
1017                row_section: flag(c, "row_section"),
1018                cell_ref: ref_of(c.get("ref")),
1019            })
1020            .collect(),
1021    }
1022}
1023
1024/// A `tables` entry: the item's JSON with a `null` stand-in under `data`
1025/// — so every edit of the item (children, content layer, comment
1026/// back-refs) works on the `Value` as before and keeps its key order —
1027/// and the typed [`TableData`] that takes the stand-in's place when the
1028/// item is written or turned into a `Value`.
1029struct TableItem {
1030    item: Value,
1031    data: TableData,
1032}
1033
1034impl TableItem {
1035    fn into_value(self) -> Value {
1036        let TableItem { mut item, data } = self;
1037        if let Some(slot) = item.get_mut("data") {
1038            *slot = data.into_value();
1039        }
1040        item
1041    }
1042}
1043
1044impl serde::Serialize for TableItem {
1045    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1046        use serde::ser::SerializeMap;
1047        let Value::Object(obj) = &self.item else {
1048            return self.item.serialize(s);
1049        };
1050        let mut m = s.serialize_map(Some(obj.len()))?;
1051        for (k, v) in obj {
1052            if k == "data" {
1053                m.serialize_entry(k, &self.data)?;
1054            } else {
1055                m.serialize_entry(k, v)?;
1056            }
1057        }
1058        m.end()
1059    }
1060}
1061
1062/// `TableData` from a table whose cell text is Markdown-flavoured (the flat
1063/// nodes: escapes to undo, GFM hard-break markers to strip).
1064fn table_data(t: &Table) -> TableData {
1065    table_data_with(t, false)
1066}
1067
1068/// `TableData`; with `raw` the cell text is docling's own raw cell text (a
1069/// backend-built tree) and is written verbatim.
1070fn table_data_with(t: &Table, raw: bool) -> TableData {
1071    let cell_text = |s: &str| -> Box<str> {
1072        if raw {
1073            s.into()
1074        } else {
1075            unescape_text(&crate::markdown::strip_hard_breaks(s)).into()
1076        }
1077    };
1078    let widen = |b: [f32; 4]| b.map(f64::from);
1079    let mut num_rows = t.rows.len();
1080    let mut num_cols = t.rows.iter().map(Vec::len).max().unwrap_or(0);
1081    // Rectangular `rows` are the grid, and cells reaching past it are
1082    // clipped — docling's own `TableData.grid` on a USPTO table whose
1083    // replicated cells outrun `num_cols`, or an HTML rowspan past the last
1084    // row. Ragged rows are no grid at all: a backend that compacts them
1085    // (xlsx `skip_empty_cells`, #271) keeps the true offsets in first-class
1086    // cells, so there the grid spans every cell's extent and the omitted
1087    // positions come back as docling's empty filler cells.
1088    let ragged = t.rows.iter().any(|r| r.len() != num_cols);
1089    if let Some(first_class) = t.cells.as_ref().filter(|c| ragged && !c.is_empty()) {
1090        let (mut rows, mut cols) = (num_rows, num_cols);
1091        for c in first_class {
1092            rows = rows.max(c.start_row.saturating_add(c.row_span));
1093            cols = cols.max(c.start_col.saturating_add(c.col_span));
1094        }
1095        // A cell whose declared extent reaches past the cell budget (#861)
1096        // does not size the slot map; the grid stays the rows' own and the
1097        // cell is clipped to it, like any other cell reaching past the grid.
1098        if rows.saturating_mul(cols) <= crate::limits::max_table_cells() {
1099            num_rows = rows;
1100            num_cols = cols;
1101        }
1102    }
1103    let mut cells = Vec::new();
1104    // Grid slot → the cell covering it, row-major — no per-slot copy and
1105    // nothing hashed.
1106    let mut grid: Vec<GridSlot>;
1107    if let Some(first_class) = t.cells.as_ref().filter(|c| !c.is_empty()) {
1108        // A position no cell covers is docling's empty filler cell.
1109        grid = vec![GridSlot::Filler; num_rows * num_cols];
1110        cells.reserve(first_class.len());
1111        for c in first_class {
1112            let idx = cells.len();
1113            cells.push(GridCell {
1114                row_span: c.row_span,
1115                col_span: c.col_span,
1116                start_row: c.start_row,
1117                end_row: c.start_row + c.row_span,
1118                start_col: c.start_col,
1119                end_col: c.start_col + c.col_span,
1120                text: cell_text(&c.text),
1121                column_header: c.column_header,
1122                row_header: c.row_header,
1123                row_section: c.row_section,
1124                bbox: c.bbox.map(widen),
1125                cell_ref: None,
1126            });
1127            for r in c.start_row..(c.start_row + c.row_span).min(num_rows) {
1128                for k in c.start_col..(c.start_col + c.col_span).min(num_cols) {
1129                    grid[r * num_cols + k] = GridSlot::Cell(idx);
1130                }
1131            }
1132        }
1133    } else {
1134        grid = vec![GridSlot::Null; num_rows * num_cols];
1135        let s = t.structure.as_ref();
1136        let flag = |grid: Option<&Vec<Vec<bool>>>, r: usize, c: usize| -> bool {
1137            grid.and_then(|g| g.get(r))
1138                .and_then(|row| row.get(c))
1139                .copied()
1140                .unwrap_or(false)
1141        };
1142        let anchor_of = |r: usize, c: usize| -> (usize, usize) {
1143            let (mut r0, mut c0) = (r, c);
1144            while c0 > 0 && flag(s.map(|s| &s.col_continuation), r, c0) {
1145                c0 -= 1;
1146            }
1147            while r0 > 0 && flag(s.map(|s| &s.row_continuation), r0, c0) {
1148                r0 -= 1;
1149            }
1150            (r0, c0)
1151        };
1152        // Each slot's anchor, computed once; the anchor's extent is the
1153        // farthest slot that resolves to it.
1154        let anchors: Vec<(usize, usize)> = (0..num_rows)
1155            .flat_map(|r| (0..num_cols).map(move |c| (r, c)))
1156            .map(|(r, c)| anchor_of(r, c))
1157            .collect();
1158        let mut extent: Vec<(usize, usize)> = (0..num_rows)
1159            .flat_map(|r| (0..num_cols).map(move |c| (r, c)))
1160            .collect();
1161        for (i, &(ar, ac)) in anchors.iter().enumerate() {
1162            let (r, c) = (i / num_cols.max(1), i % num_cols.max(1));
1163            let e = &mut extent[ar * num_cols + ac];
1164            e.0 = e.0.max(r);
1165            e.1 = e.1.max(c);
1166        }
1167        // An anchor's cell, by slot, once it is created (anchors precede
1168        // the slots they cover in row-major order).
1169        let mut anchor_cell: Vec<Option<usize>> = vec![None; num_rows * num_cols];
1170        for (r, row) in t.rows.iter().enumerate() {
1171            for c in 0..num_cols {
1172                let (ar, ac) = anchors[r * num_cols + c];
1173                if (ar, ac) == (r, c) {
1174                    let (er, ec) = extent[r * num_cols + c];
1175                    let text = row.get(c).map(|s| cell_text(s)).unwrap_or_default();
1176                    let column_header = match s.filter(|s| !s.col_header.is_empty()) {
1177                        Some(s) => flag(Some(&s.col_header), r, c),
1178                        None => r == 0,
1179                    };
1180                    anchor_cell[r * num_cols + c] = Some(cells.len());
1181                    cells.push(GridCell {
1182                        row_span: er - r + 1,
1183                        col_span: ec - c + 1,
1184                        start_row: r,
1185                        end_row: er + 1,
1186                        start_col: c,
1187                        end_col: ec + 1,
1188                        text,
1189                        column_header,
1190                        row_header: flag(s.map(|s| &s.row_header), r, c),
1191                        row_section: false,
1192                        bbox: None,
1193                        cell_ref: None,
1194                    });
1195                }
1196                if let Some(i) = anchor_cell[ar * num_cols + ac] {
1197                    grid[r * num_cols + c] = GridSlot::Cell(i);
1198                }
1199            }
1200        }
1201    }
1202    TableData {
1203        cells,
1204        num_rows,
1205        num_cols,
1206        grid,
1207    }
1208}
1209
1210/// An item's `prov` array as the builder holds it: empty, or docling's one
1211/// `ProvenanceItem` — kept typed so a text item need not be a `Value` until
1212/// it is written (see [`Item`]).
1213#[derive(Clone, Copy)]
1214enum ProvSlot {
1215    None,
1216    One {
1217        page_no: usize,
1218        /// `l t r b`, already rounded to 2 decimals.
1219        bbox: [f64; 4],
1220        bottom_left: bool,
1221        charspan: [usize; 2],
1222    },
1223}
1224
1225impl ProvSlot {
1226    fn origin(bottom_left: bool) -> &'static str {
1227        if bottom_left {
1228            "BOTTOMLEFT"
1229        } else {
1230            "TOPLEFT"
1231        }
1232    }
1233
1234    /// The `prov` array: `page_no`, `bbox` (`l t r b` + `coord_origin`) and
1235    /// `charspan`, in pydantic field order.
1236    fn to_value(self) -> Value {
1237        let ProvSlot::One {
1238            page_no,
1239            bbox: [l, t, r, b],
1240            bottom_left,
1241            charspan,
1242        } = self
1243        else {
1244            return Value::Array(Vec::new());
1245        };
1246        let bbox = object([
1247            ("l", l.into()),
1248            ("t", t.into()),
1249            ("r", r.into()),
1250            ("b", b.into()),
1251            ("coord_origin", Self::origin(bottom_left).into()),
1252        ]);
1253        let span = Value::Array(vec![charspan[0].into(), charspan[1].into()]);
1254        Value::Array(vec![object([
1255            ("page_no", page_no.into()),
1256            ("bbox", bbox),
1257            ("charspan", span),
1258        ])])
1259    }
1260
1261    /// docling's page clamp ([`clamp_boxes_to_pages`]) on the typed box.
1262    fn clamp(&mut self, sizes: &PageSizes) {
1263        if let ProvSlot::One { page_no, bbox, .. } = self {
1264            if let Some(&(w, h)) = sizes.get(page_no) {
1265                for (v, hi) in bbox.iter_mut().zip([w, h, w, h]) {
1266                    // A non-finite coordinate is `null` in the JSON, which the
1267                    // clamp leaves alone.
1268                    if v.is_finite() {
1269                        *v = round2(v.clamp(0.0, hi.max(0.0)));
1270                    }
1271                }
1272            }
1273        }
1274    }
1275}
1276
1277impl serde::Serialize for ProvSlot {
1278    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1279        use serde::ser::{SerializeMap, SerializeSeq};
1280        let ProvSlot::One {
1281            page_no,
1282            bbox: [l, t, r, b],
1283            bottom_left,
1284            charspan,
1285        } = *self
1286        else {
1287            return s.serialize_seq(Some(0))?.end();
1288        };
1289        struct Bbox([f64; 4], &'static str);
1290        impl serde::Serialize for Bbox {
1291            fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1292                let mut m = s.serialize_map(Some(5))?;
1293                for (k, v) in ["l", "t", "r", "b"].iter().zip(self.0) {
1294                    m.serialize_entry(k, &v)?;
1295                }
1296                m.serialize_entry("coord_origin", self.1)?;
1297                m.end()
1298            }
1299        }
1300        struct Entry(usize, Bbox, [usize; 2]);
1301        impl serde::Serialize for Entry {
1302            fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1303                let mut m = s.serialize_map(Some(3))?;
1304                m.serialize_entry("page_no", &self.0)?;
1305                m.serialize_entry("bbox", &self.1)?;
1306                m.serialize_entry("charspan", &self.2)?;
1307                m.end()
1308            }
1309        }
1310        let mut seq = s.serialize_seq(Some(1))?;
1311        seq.serialize_element(&Entry(
1312            page_no,
1313            Bbox([l, t, r, b], Self::origin(bottom_left)),
1314            charspan,
1315        ))?;
1316        seq.end()
1317    }
1318}
1319
1320/// The plain text item — docling's `TextItem` with no children, on the body
1321/// layer, `orig` equal to `text` and no extra fields: what a PDF's text layer
1322/// is made of, millions of times over on a long document. As a `Value` each
1323/// cost ~2.7 KB (a map of owned keys per object); typed it is ~150 bytes, and
1324/// it serializes to exactly the same JSON. Its `self_ref` is its position
1325/// (`#/texts/{i}`), so it is not stored.
1326struct TextItem {
1327    parent: Box<str>,
1328    label: Box<str>,
1329    prov: ProvSlot,
1330    text: Box<str>,
1331}
1332
1333impl TextItem {
1334    fn into_value(self, index: usize) -> Value {
1335        let text = String::from(self.text);
1336        object([
1337            ("self_ref", Value::String(format!("#/texts/{index}"))),
1338            ("parent", ref_value(self.parent)),
1339            ("children", Value::Array(Vec::new())),
1340            ("content_layer", "body".into()),
1341            ("label", Value::String(self.label.into())),
1342            ("prov", self.prov.to_value()),
1343            ("orig", Value::String(text.clone())),
1344            ("text", Value::String(text)),
1345        ])
1346    }
1347}
1348
1349/// A `texts` entry: the compact [`TextItem`] until something needs to edit
1350/// it as JSON (a nested list's children, a content-layer move, a comment
1351/// back-ref), then the `Value` it stands for. Both boxed: a slot is 16 bytes.
1352enum Item {
1353    Text(Box<TextItem>),
1354    Json(Box<Value>),
1355}
1356
1357impl Item {
1358    fn json(v: Value) -> Self {
1359        Item::Json(Box::new(v))
1360    }
1361
1362    /// The item at `texts[index]` as an editable `Value`, converting a
1363    /// [`TextItem`] in place.
1364    fn value_mut(&mut self, index: usize) -> &mut Value {
1365        if let Item::Text(t) = self {
1366            let t = std::mem::replace(
1367                t,
1368                Box::new(TextItem {
1369                    parent: "".into(),
1370                    label: "".into(),
1371                    prov: ProvSlot::None,
1372                    text: "".into(),
1373                }),
1374            );
1375            *self = Item::json(t.into_value(index));
1376        }
1377        match self {
1378            Item::Json(v) => v,
1379            Item::Text(_) => unreachable!("converted above"),
1380        }
1381    }
1382
1383    fn into_value(self, index: usize) -> Value {
1384        match self {
1385            Item::Text(t) => t.into_value(index),
1386            Item::Json(v) => *v,
1387        }
1388    }
1389}
1390
1391/// The `texts` array, serialized in place.
1392struct Texts<'a>(&'a [Item]);
1393
1394impl serde::Serialize for Texts<'_> {
1395    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1396        use serde::ser::{SerializeMap, SerializeSeq};
1397        struct Text<'a>(usize, &'a TextItem);
1398        impl serde::Serialize for Text<'_> {
1399            fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1400                let Text(i, t) = *self;
1401                let mut m = s.serialize_map(Some(8))?;
1402                m.serialize_entry("self_ref", &format_args!("#/texts/{i}"))?;
1403                m.serialize_entry("parent", &Child::Ref(t.parent.clone()))?;
1404                m.serialize_entry("children", &[(); 0])?;
1405                m.serialize_entry("content_layer", "body")?;
1406                m.serialize_entry("label", &t.label)?;
1407                m.serialize_entry("prov", &t.prov)?;
1408                m.serialize_entry("orig", &t.text)?;
1409                m.serialize_entry("text", &t.text)?;
1410                m.end()
1411            }
1412        }
1413        let mut seq = s.serialize_seq(Some(self.0.len()))?;
1414        for (i, item) in self.0.iter().enumerate() {
1415            match item {
1416                Item::Text(t) => seq.serialize_element(&Text(i, t))?,
1417                Item::Json(v) => seq.serialize_element(v)?,
1418            }
1419        }
1420        seq.end()
1421    }
1422}
1423
1424/// An entry of a `children` list as the walk collects it: a `{"$ref": …}`
1425/// held as its target string (a body of millions of refs costs ~40 bytes
1426/// each, not a ~270-byte `Value` map), or any other JSON.
1427enum Child {
1428    Ref(Box<str>),
1429    Json(Box<Value>),
1430}
1431
1432impl Child {
1433    fn json(v: Value) -> Self {
1434        Child::Json(Box::new(v))
1435    }
1436
1437    fn into_value(self) -> Value {
1438        match self {
1439            Child::Ref(r) => ref_value(r),
1440            Child::Json(v) => *v,
1441        }
1442    }
1443}
1444
1445impl serde::Serialize for Child {
1446    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
1447        use serde::ser::SerializeMap;
1448        match self {
1449            Child::Ref(r) => {
1450                let mut m = s.serialize_map(Some(1))?;
1451                m.serialize_entry("$ref", r)?;
1452                m.end()
1453            }
1454            Child::Json(v) => v.serialize(s),
1455        }
1456    }
1457}
1458
1459fn round2(v: f64) -> f64 {
1460    (v * 100.0).round() / 100.0
1461}
1462
1463#[derive(Default)]
1464struct Builder {
1465    /// Write the internal `_notes` / `_note_body` keys of tree text items
1466    /// ([`crate::tree::TreeItem::notes`]) — for the Pandoc writer only
1467    /// ([`to_json_with_notes`]); docling's JSON has no such fields.
1468    note_keys: bool,
1469    texts: Vec<Item>,
1470    groups: Vec<Value>,
1471    tables: Vec<TableItem>,
1472    pictures: Vec<Value>,
1473    field_regions: Vec<Value>,
1474    field_items: Vec<Value>,
1475    key_value_items: Vec<Value>,
1476    /// Pages seen so far (`page_no`, width, height in points) — from the
1477    /// [`Node::PageInfo`] markers the PDF paths emit; empty for every other
1478    /// backend, which keeps their JSON byte-identical (`"pages": {}`, no prov).
1479    pages: Vec<(usize, f64, f64)>,
1480    /// The page the walk is currently on (0 before the first marker).
1481    cur_page: usize,
1482    cur_w: f64,
1483    cur_h: f64,
1484    /// The enclosing [`Node::Located`] wrapper's 0–511 grid box, waiting to be
1485    /// consumed as the next item's provenance.
1486    pending_loc: Option<[u16; 4]>,
1487    /// The enclosing [`Node::Prov`] wrapper's (or the tree item's) exact
1488    /// provenance, which takes precedence over the grid box.
1489    pending_exact: Option<ExactProv>,
1490    /// The enclosing [`Node::Track`]'s timing, for the text item it wraps
1491    /// (#614).
1492    pending_track: Option<(crate::tree::TreeTrack, String)>,
1493    /// [`Node::Anchor`]s met since the last text item (#852): that item's
1494    /// `_anchors` on the Pandoc path.
1495    pending_anchors: Vec<String>,
1496    /// `$ref`s an item wants placed in its parent's `children` *before* its
1497    /// own — a chart's caption item, which docling's office backends add to
1498    /// the container ahead of the picture that references it.
1499    pending_siblings: Vec<Value>,
1500    /// `$ref`s an item wants placed in its parent's `children` right *after*
1501    /// its own — an HTML `<figure>`-wrapped table's caption
1502    /// ([`CaptionParent::ContainerAfter`]).
1503    pending_after: Vec<Value>,
1504    /// Caption `$ref`s that hang off `#/body` while their item sits deeper
1505    /// ([`CaptionParent::Body`]): docling appends them to the body's children
1506    /// as they are created, so they follow the top-level item being walked.
1507    pending_body: Vec<Value>,
1508    /// What each [`Node::CommentSection`] is referenced by, in document order —
1509    /// its group `$ref`, or its note text's when the section says so. The index
1510    /// is what a [`Node::Commented`] annotation carries.
1511    comment_groups: Vec<String>,
1512    /// The last `comment_section` group emitted, as `(name, self_ref)`: a
1513    /// following section of the same name adds its note to that group rather
1514    /// than opening another — one `comment-{sheet}-{cell}` group holds every
1515    /// message of a threaded comment (docling#4353).
1516    last_comment_section: Option<(String, String)>,
1517    /// Annotated items awaiting their refs: comments are usually emitted
1518    /// *after* the body they annotate (docx appends them), so the link is
1519    /// patched in once the whole document has been walked.
1520    pending_comments: Vec<(String, Vec<usize>)>,
1521}
1522
1523impl Builder {
1524    /// Consume the pending location (if any) into a docling `prov` array: the
1525    /// 0-511 grid denormalized against the current page into BOTTOMLEFT
1526    /// points, rounded to 2 decimals like docling's own export. `char_len` is
1527    /// the item's text length in characters (0 for tables and pictures, whose
1528    /// charspan docling emits as `[0, 0]`).
1529    fn take_prov(&mut self, char_len: usize) -> Value {
1530        self.take_prov_slot(char_len).to_value()
1531    }
1532
1533    /// [`Self::take_prov`], typed.
1534    fn take_prov_slot(&mut self, char_len: usize) -> ProvSlot {
1535        let prov = self.prov_slot(char_len, false);
1536        self.pending_exact = None;
1537        self.pending_loc = None;
1538        prov
1539    }
1540
1541    /// The pending provenance without consuming it. An exact [`Node::Prov`]
1542    /// box wins over the grid; its own `charspan` is used unless
1543    /// `span_over_text` asks for `[0, char_len]` (a chart caption's span
1544    /// covers the caption text where the chart's is `[0, 0]`).
1545    fn prov_slot(&self, char_len: usize, span_over_text: bool) -> ProvSlot {
1546        let r2 = round2;
1547        if let Some(ExactProv {
1548            page_no,
1549            bbox: [l, t, r, b],
1550            bottom_left,
1551            charspan,
1552        }) = self.pending_exact
1553        {
1554            let charspan = if span_over_text {
1555                [0, char_len]
1556            } else {
1557                charspan
1558            };
1559            return ProvSlot::One {
1560                page_no,
1561                bbox: [r2(l), r2(t), r2(r), r2(b)],
1562                bottom_left,
1563                charspan,
1564            };
1565        }
1566        let Some([x0, y0, x1, y1]) = self.pending_loc else {
1567            return ProvSlot::None;
1568        };
1569        // An all-zero grid box is the sentinel for "this item has no geometry"
1570        // (a slide's speaker notes, say). docling writes a zero bbox for it,
1571        // not a box spanning the page, which is what denormalizing would give.
1572        if [x0, y0, x1, y1] == [0, 0, 0, 0] {
1573            return ProvSlot::One {
1574                page_no: self.cur_page,
1575                bbox: [0.0; 4],
1576                bottom_left: true,
1577                charspan: [0, char_len],
1578            };
1579        }
1580        ProvSlot::One {
1581            page_no: self.cur_page,
1582            bbox: [
1583                r2(x0 as f64 * self.cur_w / 512.0),
1584                r2(self.cur_h - y0 as f64 * self.cur_h / 512.0),
1585                r2(x1 as f64 * self.cur_w / 512.0),
1586                r2(self.cur_h - y1 as f64 * self.cur_h / 512.0),
1587            ],
1588            bottom_left: true,
1589            charspan: [0, char_len],
1590        }
1591    }
1592
1593    /// Adopt a node's own location field (tables, formulas, list items carry
1594    /// one instead of a [`Node::Located`] wrapper) when no wrapper is pending.
1595    fn adopt_loc(&mut self, loc: Option<[u16; 4]>) {
1596        if self.pending_loc.is_none() && self.cur_page > 0 {
1597            self.pending_loc = loc;
1598        }
1599    }
1600
1601    /// Resolve the [`Node::Commented`] annotations collected during the walk
1602    /// into docling's `comments: [{"$ref": "#/groups/N"}]` key on the annotated
1603    /// item. It has to run after the whole walk: docx appends its comment
1604    /// bodies, so the groups they live in are usually allocated *later* than
1605    /// the paragraphs pointing at them. docling emits the key between `prov`
1606    /// and `orig`, so insert it in place rather than appending (serde_json runs
1607    /// with `preserve_order`, i.e. key order is output order).
1608    fn link_comments(&mut self) {
1609        let refs: Vec<(String, Vec<Value>)> = std::mem::take(&mut self.pending_comments)
1610            .into_iter()
1611            .map(|(item, comments)| {
1612                let refs = comments
1613                    .iter()
1614                    .filter_map(|i| self.comment_groups.get(*i))
1615                    .map(ref_value)
1616                    .collect();
1617                (item, refs)
1618            })
1619            .collect();
1620        for (item, comment_refs) in refs {
1621            if comment_refs.is_empty() {
1622                continue;
1623            }
1624            let Some(target) = self.item_mut(&item) else {
1625                continue;
1626            };
1627            let Some(obj) = target.as_object_mut() else {
1628                continue;
1629            };
1630            let tail: Vec<(String, Value)> = obj
1631                .iter()
1632                .skip_while(|(k, _)| k.as_str() != "prov")
1633                .skip(1)
1634                .map(|(k, v)| (k.clone(), v.clone()))
1635                .collect();
1636            for (k, _) in &tail {
1637                obj.shift_remove(k);
1638            }
1639            obj.insert("comments".into(), Value::Array(comment_refs));
1640            for (k, v) in tail {
1641                obj.insert(k, v);
1642            }
1643        }
1644    }
1645
1646    /// The stored JSON object a `#/texts/N`-style self-ref points at.
1647    fn item_mut(&mut self, self_ref: &str) -> Option<&mut Value> {
1648        let idx = ref_index(self_ref)?;
1649        if self_ref.starts_with("#/texts/") {
1650            return self.texts.get_mut(idx).map(|item| item.value_mut(idx));
1651        }
1652        if self_ref.starts_with("#/tables/") {
1653            return self.tables.get_mut(idx).map(|t| &mut t.item);
1654        }
1655        let bucket = if self_ref.starts_with("#/pictures/") {
1656            &mut self.pictures
1657        } else if self_ref.starts_with("#/groups/") {
1658            &mut self.groups
1659        } else {
1660            return None;
1661        };
1662        bucket.get_mut(idx)
1663    }
1664
1665    /// Serialize a backend-built [`ItemTree`](crate::tree::ItemTree): every
1666    /// item in creation order into its bucket, with the parent / children /
1667    /// layer the tree recorded. Returns the body's `children` refs.
1668    fn write_tree(&mut self, tree: &crate::tree::ItemTree) -> Vec<Value> {
1669        use crate::tree::TreeKind;
1670        // Every item's `self_ref` first: children may be listed before they
1671        // are written (a rich cell's group is created after its content).
1672        let mut refs: Vec<String> = Vec::with_capacity(tree.items.len());
1673        let (mut nt, mut ng, mut ntb, mut np, mut nf, mut nk) = (0, 0, 0, 0, 0, 0);
1674        for item in &tree.items {
1675            if item.deleted {
1676                refs.push(String::new());
1677                continue;
1678            }
1679            let r = match &item.kind {
1680                TreeKind::Text { .. } | TreeKind::Code { .. } => {
1681                    nt += 1;
1682                    format!("#/texts/{}", nt - 1)
1683                }
1684                TreeKind::Group { .. } => {
1685                    ng += 1;
1686                    format!("#/groups/{}", ng - 1)
1687                }
1688                TreeKind::Table { .. } => {
1689                    ntb += 1;
1690                    format!("#/tables/{}", ntb - 1)
1691                }
1692                TreeKind::Picture { .. } => {
1693                    np += 1;
1694                    format!("#/pictures/{}", np - 1)
1695                }
1696                TreeKind::FieldRegion { items } => {
1697                    // A region's marker / key / value parts are text items
1698                    // too, numbered where docling creates them.
1699                    nt += items
1700                        .iter()
1701                        .map(|i| {
1702                            [&i.marker, &i.key, &i.value]
1703                                .iter()
1704                                .filter(|p| p.is_some())
1705                                .count()
1706                        })
1707                        .sum::<usize>();
1708                    nf += 1;
1709                    format!("#/field_regions/{}", nf - 1)
1710                }
1711                TreeKind::KeyValueGraph { .. } => {
1712                    nk += 1;
1713                    format!("#/key_value_items/{}", nk - 1)
1714                }
1715            };
1716            refs.push(r);
1717        }
1718        let ref_of = |id: usize| ref_value(refs[id].as_str());
1719        for (id, item) in tree.items.iter().enumerate() {
1720            if item.deleted {
1721                continue;
1722            }
1723            let parent = item.parent.map_or("#/body", |p| refs[p].as_str());
1724            // A deleted item has no ref; one still listed as a child (a stale
1725            // backend link) is left out rather than written as `"$ref": ""`,
1726            // which docling-core rejects on load (#527).
1727            let children: Vec<Value> = item
1728                .children
1729                .iter()
1730                .filter(|&&c| !tree.items[c].deleted)
1731                .map(|&c| ref_of(c))
1732                .collect();
1733            let layer = item.layer.map_or("body", |l| l.value());
1734            // The item's own provenance, consumed by the writer below
1735            // (`take_prov`); an item without one writes `prov: []`.
1736            self.pending_exact = item.prov.as_ref().map(ExactProv::from);
1737            let self_ref = match &item.kind {
1738                TreeKind::Text {
1739                    label,
1740                    text,
1741                    orig,
1742                    formatting,
1743                    hyperlink,
1744                    level,
1745                    list,
1746                } => {
1747                    // docling's field order: …, text, formatting, hyperlink,
1748                    // then the subclass fields (`level`; `enumerated`, `marker`).
1749                    let mut tail = serde_json::Map::new();
1750                    if let Some(f) = formatting {
1751                        tail.insert("formatting".into(), formatting_json(f));
1752                    }
1753                    if let Some(h) = hyperlink {
1754                        tail.insert("hyperlink".into(), json!(h));
1755                    }
1756                    if let Some(l) = level {
1757                        tail.insert("level".into(), json!(l));
1758                    }
1759                    if let Some(l) = list {
1760                        tail.insert("enumerated".into(), json!(l.enumerated));
1761                        tail.insert("marker".into(), json!(l.marker));
1762                    }
1763                    let r = format!("#/texts/{}", self.texts.len());
1764                    let prov = self.take_prov(text.chars().count());
1765                    let mut item_json = json!({
1766                        "self_ref": r,
1767                        "parent": { "$ref": parent },
1768                        "children": children,
1769                        "content_layer": layer,
1770                        "label": label,
1771                        "prov": prov,
1772                    });
1773                    // docling's `comments` back-refs sit between `prov` and
1774                    // `orig`, and are written only when set.
1775                    if !item.comments.is_empty() {
1776                        item_json["comments"] =
1777                            Value::Array(item.comments.iter().map(|&c| ref_of(c)).collect());
1778                    }
1779                    // `DocItem.source`, likewise only when set: a WebVTT
1780                    // cue's `TrackSource`, whose `None` fields are omitted.
1781                    if let Some(track) = &item.source {
1782                        item_json["source"] = json!([track_json(track)]);
1783                    }
1784                    merge(
1785                        &mut item_json,
1786                        json!({
1787                            "orig": orig.as_deref().unwrap_or(text),
1788                            "text": text,
1789                        }),
1790                    );
1791                    merge(&mut item_json, Value::Object(tail));
1792                    if self.note_keys {
1793                        if !item.notes.is_empty() {
1794                            item_json["_notes"] = Value::Array(
1795                                item.notes
1796                                    .iter()
1797                                    .map(|n| json!([n.offset, n.text]))
1798                                    .collect(),
1799                            );
1800                        }
1801                        if item.note_body {
1802                            item_json["_note_body"] = json!(true);
1803                        }
1804                        if !item.anchors.is_empty() {
1805                            item_json["_anchors"] = json!(item.anchors);
1806                        }
1807                        if let Some(number) = &item.number {
1808                            item_json["_number"] = json!(number);
1809                        }
1810                        if let Some(rev) = &item.revision {
1811                            let mut r = serde_json::Map::new();
1812                            r.insert("kind".into(), json!(rev.kind.as_str()));
1813                            if let Some(a) = &rev.author {
1814                                r.insert("author".into(), json!(a));
1815                            }
1816                            if let Some(d) = &rev.date {
1817                                r.insert("date".into(), json!(d));
1818                            }
1819                            item_json["_revision"] = Value::Object(r);
1820                        }
1821                    }
1822                    self.texts.push(Item::json(item_json));
1823                    r
1824                }
1825                TreeKind::Code {
1826                    text,
1827                    orig,
1828                    language,
1829                    formatting,
1830                    hyperlink,
1831                    captions,
1832                } => {
1833                    let r = format!("#/texts/{}", self.texts.len());
1834                    let prov = self.take_prov(text.chars().count());
1835                    let mut item_json = json!({
1836                        "self_ref": r,
1837                        "parent": { "$ref": parent },
1838                        "children": children,
1839                        "content_layer": layer,
1840                        "label": "code",
1841                        "prov": prov,
1842                    });
1843                    if !item.comments.is_empty() {
1844                        item_json["comments"] =
1845                            Value::Array(item.comments.iter().map(|&c| ref_of(c)).collect());
1846                    }
1847                    merge(
1848                        &mut item_json,
1849                        json!({
1850                            "orig": orig.as_deref().unwrap_or(text),
1851                            "text": text,
1852                        }),
1853                    );
1854                    if let Some(f) = formatting {
1855                        item_json["formatting"] = formatting_json(f);
1856                    }
1857                    if let Some(h) = hyperlink {
1858                        item_json["hyperlink"] = json!(h);
1859                    }
1860                    merge(
1861                        &mut item_json,
1862                        json!({
1863                            "captions": captions.iter().map(|&c| ref_of(c)).collect::<Vec<_>>(),
1864                            "references": [],
1865                            "footnotes": [],
1866                            "code_language": code_language(language.as_deref()),
1867                        }),
1868                    );
1869                    self.texts.push(Item::json(item_json));
1870                    r
1871                }
1872                TreeKind::Group { label, name } => {
1873                    self.pending_exact = None;
1874                    let r = format!("#/groups/{}", self.groups.len());
1875                    self.groups.push(json!({
1876                        "self_ref": r,
1877                        "parent": { "$ref": parent },
1878                        "children": children,
1879                        "content_layer": layer,
1880                        "name": name,
1881                        "label": label,
1882                    }));
1883                    r
1884                }
1885                TreeKind::Table {
1886                    table,
1887                    rich_cells,
1888                    captions,
1889                } => {
1890                    // docling's raw cell text: nothing to unescape or strip.
1891                    let r = self.add_table_with(table, parent, true);
1892                    let idx = ref_index(&r).expect("table ref");
1893                    let t = &mut self.tables[idx];
1894                    t.item["children"] = Value::Array(children);
1895                    t.item["content_layer"] = json!(layer);
1896                    t.item["captions"] =
1897                        Value::Array(captions.iter().map(|&c| ref_of(c)).collect());
1898                    // A `RichTableCell` is the plain cell plus a `ref` to the
1899                    // group holding its content — on `table_cells` only; the
1900                    // derived `grid` shows plain cells.
1901                    for &(row, col, group) in rich_cells {
1902                        let cell_ref = ref_of(group);
1903                        for c in t.data.cells.iter_mut() {
1904                            if c.start_row == row && c.start_col == col {
1905                                c.cell_ref = Some(Box::new(cell_ref.clone()));
1906                            }
1907                        }
1908                    }
1909                    r
1910                }
1911                TreeKind::Picture {
1912                    captions,
1913                    image,
1914                    classification,
1915                    extra_classes,
1916                    description,
1917                    confidence,
1918                    chart,
1919                    dpi,
1920                } => {
1921                    // A chart's meta: the kind as the one classification
1922                    // prediction (pydantic's field order puts `confidence`
1923                    // first when present), then the reconstructed data grid
1924                    // (#405).
1925                    let mut meta = classification.as_ref().map(|c| {
1926                        let mut pred = serde_json::Map::new();
1927                        if let Some(conf) = confidence {
1928                            pred.insert("confidence".into(), json!(conf));
1929                        }
1930                        pred.insert("class_name".into(), json!(c));
1931                        let mut preds = vec![Value::Object(pred)];
1932                        preds.extend(extra_classes.iter().map(|c| json!({ "class_name": c })));
1933                        json!({ "classification": { "predictions": preds } })
1934                    });
1935                    if let (Some(m), Some(t)) = (meta.as_mut(), chart) {
1936                        if !t.rows.is_empty() {
1937                            m["tabular_chart"] =
1938                                object([("chart_data", table_data(t).into_value())]);
1939                        }
1940                    }
1941                    // The OCR description (#645) goes first in the meta —
1942                    // `PictureMeta` field order — and as the annotation the
1943                    // flat node writes (see `description_meta`).
1944                    if let Some(desc) = description {
1945                        let mut d = description_meta(desc);
1946                        let mut merged = Map::new();
1947                        merged.insert("description".into(), d["description"].take());
1948                        if let Some(Value::Object(rest)) = meta {
1949                            merged.extend(rest);
1950                        }
1951                        merged.insert("annotations".into(), d["annotations"].take());
1952                        meta = Some(Value::Object(merged));
1953                    }
1954                    // The source of a picture no engine rendered (a LaTeX
1955                    // `tikzpicture`): `PictureMeta.code`.
1956                    if let Some((text, language)) = &item.code_meta {
1957                        let code = json!({ "text": text, "language": language });
1958                        match meta.as_mut() {
1959                            Some(Value::Object(m)) => {
1960                                m.insert("code".into(), code);
1961                            }
1962                            _ => meta = Some(json!({ "code": code })),
1963                        }
1964                    }
1965                    let prov = self.take_prov(0);
1966                    let r = self.push_picture(
1967                        prov,
1968                        captions.iter().map(|&c| ref_of(c)).collect(),
1969                        children,
1970                        image.as_ref(),
1971                        meta,
1972                        parent,
1973                    );
1974                    if let Some(idx) = ref_index(&r) {
1975                        self.pictures[idx]["content_layer"] = json!(layer);
1976                        // The image's dpi is the file's when the backend read
1977                        // it (python-pptx does); the default 72 otherwise.
1978                        if let (Some(dpi), Some(img)) = (dpi, self.pictures[idx].get_mut("image")) {
1979                            img["dpi"] = json!(dpi);
1980                        }
1981                    }
1982                    r
1983                }
1984                TreeKind::FieldRegion { items } => {
1985                    self.pending_exact = None;
1986                    let r = self.add_field_region(items, parent);
1987                    if let Some(region) = self.field_regions.last_mut() {
1988                        region["content_layer"] = json!(layer);
1989                    }
1990                    r
1991                }
1992                TreeKind::KeyValueGraph { cells, links } => {
1993                    self.pending_exact = None;
1994                    let r = self.add_key_value_graph(cells, links, parent);
1995                    if let Some(item) = self.key_value_items.last_mut() {
1996                        item["content_layer"] = json!(layer);
1997                    }
1998                    r
1999                }
2000            };
2001            debug_assert_eq!(self_ref, refs[id], "tree item {id} numbered out of order");
2002        }
2003        tree.body
2004            .iter()
2005            .filter(|&&c| !tree.items[c].deleted)
2006            .map(|&c| ref_of(c))
2007            .collect()
2008    }
2009
2010    fn add_node(&mut self, node: &Node, parent: &str) -> Option<String> {
2011        match node {
2012            Node::Heading { level: 1, text } => {
2013                Some(self.add_text("title", text, parent, json!({})))
2014            }
2015            Node::Heading { level, text } => Some(self.add_text(
2016                "section_header",
2017                text,
2018                parent,
2019                json!({ "level": level.saturating_sub(1) }),
2020            )),
2021            Node::Caption { text, href } => {
2022                let extra = match href {
2023                    Some(url) => json!({ "hyperlink": url }),
2024                    None => json!({}),
2025                };
2026                Some(self.add_text("caption", text, parent, extra))
2027            }
2028            // A PDF footnote: docling's own label, and its link as the item's
2029            // `hyperlink` rather than Markdown baked into the text.
2030            Node::LabeledText { label, text, href } => {
2031                let extra = match href {
2032                    Some(url) => json!({ "hyperlink": url }),
2033                    None => json!({}),
2034                };
2035                Some(self.add_text(label, text, parent, extra))
2036            }
2037            Node::Paragraph { text } | Node::ListText { text, .. } => {
2038                // A whole-paragraph display equation is a formula item (docling
2039                // wraps it in `$$…$$` and, unlike a text item, never escapes it).
2040                let t = text.trim();
2041                match t.strip_prefix("$$").and_then(|s| s.strip_suffix("$$")) {
2042                    Some(inner) if !inner.is_empty() => Some(self.add_formula(inner, parent)),
2043                    _ => Some(self.add_text("text", text, parent, json!({}))),
2044                }
2045            }
2046            Node::CheckboxItem { checked, text } => {
2047                // docling's checkbox item: the `checkbox_selected` /
2048                // `checkbox_unselected` label carries the state and the text
2049                // is the bare option label (right_to_left_03's `خير`,
2050                // docx_checkboxes' `Orange juice`). The `- [x]` task-list
2051                // marker is Markdown's rendering of it, not item text (#609).
2052                let label = if *checked {
2053                    "checkbox_selected"
2054                } else {
2055                    "checkbox_unselected"
2056                };
2057                Some(self.add_text(label, text, parent, json!({})))
2058            }
2059            Node::Code {
2060                language,
2061                text,
2062                orig,
2063                ..
2064            } => Some(self.add_code(text, language.as_deref(), orig.as_deref(), parent)),
2065            // A CodeFormula-decoded display formula: `text` carries the LaTeX,
2066            // `orig` the raw glyph extraction (docling's enriched shape).
2067            Node::Formula {
2068                latex,
2069                orig,
2070                location,
2071            } => {
2072                self.adopt_loc(*location);
2073                Some(self.add_formula_item(latex, orig, parent))
2074            }
2075            // docling's notes-layer `comment_section` group holding the
2076            // comment's text item. What the annotated items point at differs
2077            // upstream: the docx backend links the group (so a comment's
2078            // replies group together), everything going through
2079            // docling-core's `add_comment` links the note text itself.
2080            Node::CommentSection {
2081                name,
2082                text,
2083                refs_note_text,
2084                grouped,
2085            } => {
2086                if !*grouped {
2087                    // docling-core's bare `add_comment`: the note text sits
2088                    // directly under the parent and is what the back-refs
2089                    // point at.
2090                    let child =
2091                        self.add_text("text", text, parent, json!({ "content_layer": "notes" }));
2092                    self.comment_groups.push(child.clone());
2093                    return Some(child);
2094                }
2095                if let Some((_, self_ref)) = self
2096                    .last_comment_section
2097                    .as_ref()
2098                    .filter(|(n, _)| n == name)
2099                    .cloned()
2100                {
2101                    // Another message of the same thread: a further note in
2102                    // the group already open for this cell.
2103                    let child =
2104                        self.add_text("text", text, &self_ref, json!({ "content_layer": "notes" }));
2105                    if let Some(children) =
2106                        self.groups[group_index(&self_ref)]["children"].as_array_mut()
2107                    {
2108                        children.push(ref_value(child.as_str()));
2109                    }
2110                    self.comment_groups.push(if *refs_note_text {
2111                        child
2112                    } else {
2113                        self_ref.clone()
2114                    });
2115                    // The group is already its parent's child: listing it
2116                    // again put a thread's group in the body once per message.
2117                    return None;
2118                }
2119                let self_ref = format!("#/groups/{}", self.groups.len());
2120                self.groups.push(Value::Null);
2121                let child =
2122                    self.add_text("text", text, &self_ref, json!({ "content_layer": "notes" }));
2123                self.groups[group_index(&self_ref)] = json!({
2124                    "self_ref": self_ref,
2125                    "parent": { "$ref": parent },
2126                    "children": [{ "$ref": child }],
2127                    "content_layer": "notes",
2128                    "name": name,
2129                    "label": "comment_section",
2130                });
2131                self.last_comment_section = Some((name.clone(), self_ref.clone()));
2132                self.comment_groups.push(if *refs_note_text {
2133                    child
2134                } else {
2135                    self_ref.clone()
2136                });
2137                Some(self_ref)
2138            }
2139            // The annotation itself is a cross-reference: emit the item, then
2140            // remember it so the group refs can be filled in at the end.
2141            Node::Commented { comments, inner } => {
2142                let item = self.add_node(inner, parent)?;
2143                if !comments.is_empty() {
2144                    self.pending_comments.push((item.clone(), comments.clone()));
2145                }
2146                Some(item)
2147            }
2148            Node::Table(t) => Some(self.add_table(t, parent)),
2149            Node::Picture {
2150                caption,
2151                caption_href,
2152                image,
2153                classification,
2154                description,
2155                caption_parent,
2156                caption_location,
2157            } => Some(self.add_picture(
2158                caption.as_deref(),
2159                caption_href.as_deref(),
2160                image.as_ref(),
2161                picture_meta(classification.as_deref(), description.as_ref()),
2162                parent,
2163                (*caption_parent, *caption_location),
2164            )),
2165            // A chart is a picture item in the JSON with docling's chart
2166            // meta — `classification` (the chart kind, as the one prediction)
2167            // and `tabular_chart.chart_data`, the series reconstructed as a
2168            // `TableData` (#405) — and no image payload.
2169            Node::Chart {
2170                kind,
2171                table,
2172                caption,
2173                location,
2174            } => {
2175                self.adopt_loc(*location);
2176                let mut meta = json!({
2177                    "classification": { "predictions": [{ "class_name": kind }] },
2178                });
2179                if !table.rows.is_empty() {
2180                    meta["tabular_chart"] =
2181                        object([("chart_data", table_data(table).into_value())]);
2182                }
2183                // docling's office backends add the chart's title as a caption
2184                // item of the *container* (the sheet group, the slide), listed
2185                // before the picture that references it, with the chart's own
2186                // box and a charspan over the caption text — not as a child
2187                // of the picture, which is where a PDF caption lives.
2188                let mut captions = Vec::new();
2189                if let Some(cap) = caption.as_deref().filter(|c| !c.is_empty()) {
2190                    let prov = self.prov_slot(unescape_text(cap).chars().count(), true);
2191                    let cap_ref = self.add_text_with("caption", cap, parent, json!({}), prov);
2192                    self.pending_siblings.push(ref_value(cap_ref.as_str()));
2193                    captions.push(ref_value(cap_ref));
2194                }
2195                let prov = self.take_prov(0);
2196                Some(self.push_picture(prov, captions, Vec::new(), None, Some(meta), parent))
2197            }
2198            // A DocLang-only node is omitted from the JSON body.
2199            Node::DoclangOnly(_) => None,
2200            Node::Group {
2201                label,
2202                name,
2203                layer,
2204                children,
2205            } => Some(self.add_group(label, name.as_deref(), *layer, children, parent)),
2206            Node::FieldRegion { items } => Some(self.add_field_region(items, parent)),
2207            Node::KeyValueGraph { cells, links } => {
2208                Some(self.add_key_value_graph(cells, links, parent))
2209            }
2210            // A rich inline group is a text item over its Markdown text; the
2211            // structured runs are DocLang-only, so the JSON matches a paragraph.
2212            Node::InlineGroup { md_text, .. } => {
2213                Some(self.add_text("text", md_text, parent, json!({})))
2214            }
2215            // A plain-text backend dump is a single text item over the file body.
2216            Node::TextDump(text) => Some(self.add_text("text", text, parent, json!({}))),
2217            // Speaker notes are content a deck carries, and docling puts them
2218            // in the JSON on their own layer, so a consumer reading only JSON
2219            // can pick them (#402). Page furniture stays out of the flat
2220            // path; a backend that builds docling's item tree (HTML) puts its
2221            // furniture-layer items in the JSON through `write_tree`.
2222            Node::Furniture {
2223                layer: ContentLayer::Notes,
2224                inner,
2225            } => {
2226                let item = self.add_node(inner, parent)?;
2227                self.set_layer(&item, "notes");
2228                Some(item)
2229            }
2230            Node::Furniture { .. } => None,
2231            // PDF page headers and footers: docling writes them as body-parented
2232            // `page_header`/`page_footer` text items on the furniture layer, so a
2233            // JSON consumer can read running headers (printed page ids, dates).
2234            Node::PageFurniture {
2235                footer,
2236                location,
2237                text,
2238            } => {
2239                if self.cur_page > 0 {
2240                    self.pending_loc = Some(*location);
2241                }
2242                let label = if *footer {
2243                    "page_footer"
2244                } else {
2245                    "page_header"
2246                };
2247                let item = self.add_text(label, text, parent, json!({}));
2248                self.pending_loc = None;
2249                self.set_layer(&item, "furniture");
2250                Some(item)
2251            }
2252            // A labelled furniture paragraph (a `.doc` header / footer or
2253            // note body, #535): the item docling's office backends write.
2254            Node::FurnitureText { label, text } => {
2255                let item = self.add_text(label, text, parent, json!({}));
2256                self.set_layer(&item, "furniture");
2257                Some(item)
2258            }
2259            // A PDF picture's contained text (docling's `_add_child_elements`):
2260            // items parented to the picture just written, listed after its
2261            // caption in that picture's `children`.
2262            Node::PictureChildren(children) => {
2263                let pic = self.pictures.len().checked_sub(1)?;
2264                let pic_ref = format!("#/pictures/{pic}");
2265                let refs = self.walk_into(children, &pic_ref);
2266                if let Some(list) = self.pictures[pic]["children"].as_array_mut() {
2267                    list.extend(refs.into_iter().map(Child::into_value));
2268                }
2269                None
2270            }
2271            // A location wrapper turns into the wrapped item's `prov` entry —
2272            // but only on pages the PDF paths described with a PageInfo marker
2273            // (other geometry-bearing backends, e.g. PPTX shapes, keep their
2274            // pre-#171 provenance-less JSON until they emit markers too).
2275            Node::Located { location, inner } => {
2276                if self.cur_page > 0 {
2277                    self.pending_loc = Some(*location);
2278                }
2279                let r = self.add_node(inner, parent);
2280                self.pending_loc = None;
2281                r
2282            }
2283            Node::Anchor { id } => {
2284                self.pending_anchors.push(id.clone());
2285                None
2286            }
2287            Node::Track { track, cue, inner } => {
2288                self.pending_track = Some((track.clone(), cue.clone()));
2289                let r = self.add_node(inner, parent);
2290                self.pending_track = None;
2291                r
2292            }
2293            Node::Prov {
2294                page_no,
2295                bbox,
2296                charspan,
2297                bottom_left,
2298                inner,
2299                ..
2300            } => {
2301                self.pending_exact = Some(ExactProv {
2302                    page_no: *page_no,
2303                    bbox: bbox.map(f64::from),
2304                    bottom_left: *bottom_left,
2305                    charspan: *charspan,
2306                });
2307                let r = self.add_node(inner, parent);
2308                self.pending_exact = None;
2309                r
2310            }
2311            // Page breaks are DocLang-only; docling omits them from the JSON body.
2312            Node::PageBreak => None,
2313            // The page marker: record the page's number and size for the
2314            // `pages` map, and denormalize every following location against it.
2315            Node::PageInfo {
2316                page_no,
2317                width,
2318                height,
2319            } => {
2320                self.cur_page = *page_no;
2321                self.cur_w = *width as f64;
2322                self.cur_h = *height as f64;
2323                if *page_no > 0 {
2324                    self.pages.push((*page_no, self.cur_w, self.cur_h));
2325                }
2326                None
2327            }
2328            // Handled by `add_list` in `walk`.
2329            Node::ListItem { .. } => None,
2330        }
2331    }
2332
2333    /// A form key-value region: `field_regions/N` holds the region, each field is
2334    /// a `field_items/M` whose children are its `marker` / `field_key` /
2335    /// `field_value` texts (absent parts are simply omitted).
2336    fn add_field_region(&mut self, items: &[crate::FieldItem], parent: &str) -> String {
2337        let self_ref = format!("#/field_regions/{}", self.field_regions.len());
2338        self.field_regions.push(Value::Null);
2339        let region_index = self.field_regions.len() - 1;
2340        let mut item_refs = Vec::new();
2341        for item in items {
2342            item_refs.push(ref_value(self.add_field_item(item, &self_ref)));
2343        }
2344        self.field_regions[region_index] = json!({
2345            "self_ref": self_ref,
2346            "parent": { "$ref": parent },
2347            "children": item_refs,
2348            "content_layer": "body",
2349            "label": "field_region",
2350            "prov": [],
2351        });
2352        self_ref
2353    }
2354
2355    /// A `KeyValueItem`: docling's `GraphData` written cell for cell and link
2356    /// for link (`key_value_items/N`), the item itself childless and without
2357    /// provenance, the way the XBRL backend creates it.
2358    fn add_key_value_graph(
2359        &mut self,
2360        cells: &[crate::GraphCell],
2361        links: &[crate::GraphLink],
2362        parent: &str,
2363    ) -> String {
2364        let self_ref = format!("#/key_value_items/{}", self.key_value_items.len());
2365        let cells: Vec<Value> = cells
2366            .iter()
2367            .map(|c| {
2368                json!({
2369                    "label": c.label,
2370                    "cell_id": c.cell_id,
2371                    "text": c.text,
2372                    "orig": c.orig,
2373                })
2374            })
2375            .collect();
2376        let links: Vec<Value> = links
2377            .iter()
2378            .map(|l| {
2379                json!({
2380                    "label": l.label,
2381                    "source_cell_id": l.source_cell_id,
2382                    "target_cell_id": l.target_cell_id,
2383                })
2384            })
2385            .collect();
2386        self.key_value_items.push(json!({
2387            "self_ref": self_ref,
2388            "parent": { "$ref": parent },
2389            "children": [],
2390            "content_layer": "body",
2391            "label": "key_value_region",
2392            "prov": [],
2393            "captions": [],
2394            "references": [],
2395            "footnotes": [],
2396            "graph": { "cells": cells, "links": links },
2397        }));
2398        self_ref
2399    }
2400
2401    fn add_field_item(&mut self, item: &crate::FieldItem, parent: &str) -> String {
2402        let self_ref = format!("#/field_items/{}", self.field_items.len());
2403        self.field_items.push(Value::Null);
2404        let item_index = self.field_items.len() - 1;
2405        let mut child_refs = Vec::new();
2406        for (label, text) in [
2407            ("marker", &item.marker),
2408            ("field_key", &item.key),
2409            ("field_value", &item.value),
2410        ] {
2411            if let Some(text) = text {
2412                // A value's `kind` (docling's `read_only` / `fillable`)
2413                // follows its text.
2414                let extra = match (label, &item.value_kind) {
2415                    ("field_value", Some(kind)) => json!({ "kind": kind }),
2416                    _ => json!({}),
2417                };
2418                child_refs.push(ref_value(self.add_text(label, text, &self_ref, extra)));
2419            }
2420        }
2421        self.field_items[item_index] = json!({
2422            "self_ref": self_ref,
2423            "parent": { "$ref": parent },
2424            "children": child_refs,
2425            "content_layer": "body",
2426            "label": "field_item",
2427            "prov": [],
2428        });
2429        self_ref
2430    }
2431
2432    /// Move an already-emitted item onto a content layer. Notes are single
2433    /// text items today; a deeper notes subtree would need its children moved
2434    /// too, and no backend builds one.
2435    fn set_layer(&mut self, self_ref: &str, layer: &str) {
2436        if let Some(item) = self.item_mut(self_ref) {
2437            item["content_layer"] = json!(layer);
2438        }
2439    }
2440
2441    fn add_text(&mut self, label: &str, text: &str, parent: &str, extra: Value) -> String {
2442        let prov = self.take_prov_slot(unescape_text(text).chars().count());
2443        self.add_text_with(label, text, parent, extra, prov)
2444    }
2445
2446    /// [`Self::add_text`] with an explicit `prov` (a chart caption shares the
2447    /// chart's box without consuming it).
2448    fn add_text_with(
2449        &mut self,
2450        label: &str,
2451        text: &str,
2452        parent: &str,
2453        extra: Value,
2454        prov: ProvSlot,
2455    ) -> String {
2456        let index = self.texts.len();
2457        let self_ref = format!("#/texts/{index}");
2458        // A [`Node::Track`] item is docling's ASR text item (#614): the
2459        // segment's words as `text`, its timing as `source` — the `[time: …]`
2460        // prefix the wrapped paragraph shows is Markdown's alone. It carries a
2461        // field the compact [`TextItem`] doesn't, so it is built as JSON.
2462        let mut item = match self.pending_track.take() {
2463            None => Item::Text(Box::new(TextItem {
2464                parent: parent.into(),
2465                label: label.into(),
2466                prov,
2467                text: unescape_text(text).into(),
2468            })),
2469            Some((track, cue)) => {
2470                let mut m = serde_json::Map::with_capacity(9);
2471                m.insert("self_ref".into(), Value::String(self_ref.clone()));
2472                m.insert("parent".into(), ref_value(parent));
2473                m.insert("children".into(), Value::Array(Vec::new()));
2474                m.insert("content_layer".into(), "body".into());
2475                m.insert("label".into(), label.into());
2476                m.insert("prov".into(), prov.to_value());
2477                // `DocItem.source` follows `prov` (docling's field order).
2478                m.insert("source".into(), Value::Array(vec![track_json(&track)]));
2479                m.insert("orig".into(), Value::String(cue.clone()));
2480                m.insert("text".into(), Value::String(cue));
2481                Item::json(Value::Object(m))
2482            }
2483        };
2484        if extra.as_object().is_some_and(|e| !e.is_empty()) {
2485            merge(item.value_mut(index), extra);
2486        }
2487        // The link destinations met before this item (#852), on the Pandoc
2488        // path only — docling's model has no field for them.
2489        let anchors = std::mem::take(&mut self.pending_anchors);
2490        if self.note_keys && !anchors.is_empty() {
2491            merge(item.value_mut(index), json!({ "_anchors": anchors }));
2492        }
2493        self.texts.push(item);
2494        self_ref
2495    }
2496
2497    /// A display-math formula item. `latex` is the raw content (no `$$`); docling
2498    /// re-wraps it and never escapes it.
2499    fn add_formula(&mut self, latex: &str, parent: &str) -> String {
2500        let self_ref = format!("#/texts/{}", self.texts.len());
2501        let prov = self.take_prov(latex.chars().count());
2502        self.texts.push(Item::json(json!({
2503            "self_ref": self_ref,
2504            "parent": { "$ref": parent },
2505            "children": [],
2506            "content_layer": "body",
2507            "label": "formula",
2508            "prov": prov,
2509            "orig": latex,
2510            "text": latex,
2511        })));
2512        self_ref
2513    }
2514
2515    /// A CodeFormula-enriched display formula: `text` is the model's LaTeX
2516    /// while `orig` keeps the raw glyph extraction (docling's enriched shape;
2517    /// the plain [`Self::add_formula`] above sets both to the same string).
2518    fn add_formula_item(&mut self, latex: &str, orig: &str, parent: &str) -> String {
2519        let self_ref = format!("#/texts/{}", self.texts.len());
2520        let prov = self.take_prov(latex.chars().count());
2521        self.texts.push(Item::json(json!({
2522            "self_ref": self_ref,
2523            "parent": { "$ref": parent },
2524            "children": [],
2525            "content_layer": "body",
2526            "label": "formula",
2527            "prov": prov,
2528            "orig": orig,
2529            "text": latex,
2530        })));
2531        self_ref
2532    }
2533
2534    fn add_code(
2535        &mut self,
2536        text: &str,
2537        language: Option<&str>,
2538        orig: Option<&str>,
2539        parent: &str,
2540    ) -> String {
2541        let self_ref = format!("#/texts/{}", self.texts.len());
2542        let raw = unescape_text(text);
2543        let prov = self.take_prov(raw.chars().count());
2544        self.texts.push(Item::json(json!({
2545            "self_ref": self_ref,
2546            "parent": { "$ref": parent },
2547            "children": [],
2548            "content_layer": "body",
2549            "label": "code",
2550            "prov": prov,
2551            // With code enrichment, `text` is the model's rewrite while `orig`
2552            // keeps the raw extraction; otherwise both are the same string.
2553            "orig": orig.map(unescape_text).unwrap_or_else(|| raw.clone()),
2554            "text": raw,
2555            "captions": [],
2556            "references": [],
2557            "footnotes": [],
2558            "code_language": code_language(language),
2559        })));
2560        self_ref
2561    }
2562
2563    /// Build a list group from a run of (possibly multi-level) list items. A
2564    /// deeper level starts a nested list under the preceding item.
2565    fn add_list(&mut self, items: &[Node], parent: &str) -> String {
2566        let self_ref = format!("#/groups/{}", self.groups.len());
2567        // reserve the slot so nested groups get later indices
2568        self.groups.push(Value::Null);
2569        let base = level_of(&items[0]);
2570        let mut children = Vec::new();
2571        let mut i = 0;
2572        while i < items.len() {
2573            // Empty paragraphs absorbed into the run (blank lines between items)
2574            // are not list items — skip them.
2575            if !matches!(items[i], Node::ListItem { .. }) {
2576                i += 1;
2577                continue;
2578            }
2579            let lvl = level_of(&items[i]);
2580            if lvl > base {
2581                // shouldn't happen at the head; skip defensively
2582                i += 1;
2583                continue;
2584            }
2585            let item_ref = self.add_list_item(&items[i], &self_ref);
2586            // collect any deeper items that nest under this one
2587            let mut j = i + 1;
2588            while j < items.len() && level_of(&items[j]) > base {
2589                j += 1;
2590            }
2591            if j > i + 1 {
2592                let mut nested = Vec::new();
2593                self.add_sibling_lists(&items[i + 1..j], &item_ref, &mut nested);
2594                // the nested list group(s) are children of this item
2595                if let Some(idx) = ref_index(&item_ref) {
2596                    self.texts[idx].value_mut(idx)["children"]
2597                        .as_array_mut()
2598                        .unwrap()
2599                        .extend(nested);
2600                }
2601            }
2602            children.push(ref_value(item_ref));
2603            i = j;
2604        }
2605        self.groups[group_index(&self_ref)] = json!({
2606            "self_ref": self_ref,
2607            "parent": { "$ref": parent },
2608            "children": children,
2609            "content_layer": "body",
2610            "name": "list",
2611            "label": "list",
2612        });
2613        self_ref
2614    }
2615
2616    fn add_list_item(&mut self, node: &Node, parent: &str) -> String {
2617        let Node::ListItem {
2618            ordered,
2619            number,
2620            text,
2621            location,
2622            ..
2623        } = node
2624        else {
2625            unreachable!()
2626        };
2627        self.adopt_loc(*location);
2628        let self_ref = format!("#/texts/{}", self.texts.len());
2629        let raw = unescape_text(text);
2630        let prov = self.take_prov(raw.chars().count());
2631        let marker = if *ordered {
2632            format!("{number}.")
2633        } else {
2634            "-".to_string()
2635        };
2636        self.texts.push(Item::json(json!({
2637            "self_ref": self_ref,
2638            "parent": { "$ref": parent },
2639            "children": [],
2640            "content_layer": "body",
2641            "label": "list_item",
2642            "prov": prov,
2643            "orig": raw,
2644            "text": raw,
2645            "enumerated": ordered,
2646            "marker": marker,
2647        })));
2648        self_ref
2649    }
2650
2651    fn add_table(&mut self, t: &Table, parent: &str) -> String {
2652        self.add_table_with(t, parent, false)
2653    }
2654
2655    /// [`Self::add_table`]; `raw` cell text is written verbatim (see
2656    /// [`table_data_with`]).
2657    fn add_table_with(&mut self, t: &Table, parent: &str, raw: bool) -> String {
2658        let self_ref = format!("#/tables/{}", self.tables.len());
2659        self.adopt_loc(t.location);
2660        let prov = self.take_prov(0);
2661        // The caption is a separate text item the table references (docling's
2662        // `TableItem.captions`), added before the grid so its box isn't
2663        // inherited by a later item.
2664        let (captions, children) = match t.caption.as_deref().filter(|c| !c.is_empty()) {
2665            Some(cap) => self.add_caption(
2666                cap,
2667                json!({}),
2668                &self_ref,
2669                parent,
2670                (t.caption_parent, t.caption_location),
2671            ),
2672            None => (Vec::new(), Vec::new()),
2673        };
2674        let data = table_data_with(t, raw);
2675        let item = json!({
2676            "self_ref": self_ref,
2677            "parent": { "$ref": parent },
2678            "children": children,
2679            "content_layer": "body",
2680            "label": "table",
2681            "prov": prov,
2682            "captions": captions,
2683            "references": [],
2684            "footnotes": [],
2685            // The typed `data` takes this stand-in's place on output.
2686            "data": null,
2687            "annotations": [],
2688        });
2689        self.tables.push(TableItem { item, data });
2690        self_ref
2691    }
2692
2693    /// Add a picture's or table's caption text item where `choice` says it
2694    /// hangs (#390), returning the `captions` entry for the item and the
2695    /// item's own `children` (the caption, when it is the item's child).
2696    /// The caption never consumes the item's pending provenance — the item
2697    /// takes its box first. Its own box, when the backend kept one (the PDF
2698    /// pipeline's caption region, #609), becomes the caption's `prov` on the
2699    /// item's page, as docling's reading-order model gives every caption the
2700    /// cluster it came from; without one the caption has no `prov`.
2701    fn add_caption(
2702        &mut self,
2703        text: &str,
2704        extra: Value,
2705        self_ref: &str,
2706        parent: &str,
2707        (choice, location): (CaptionParent, Option<[u16; 4]>),
2708    ) -> (Vec<Value>, Vec<Value>) {
2709        // docling's PDF pipeline parents the caption to the item; every
2710        // declarative backend leaves `add_text`'s default — the body — even
2711        // for an item inside a group; the office backends and HTML's
2712        // `<figure>` hang it off the item's container.
2713        let cap_parent = match choice {
2714            CaptionParent::Item => self_ref,
2715            CaptionParent::Container | CaptionParent::ContainerAfter => parent,
2716            CaptionParent::Body => "#/body",
2717        };
2718        if self.cur_page > 0 && location.is_some() {
2719            self.pending_loc = location;
2720        }
2721        let cap_ref = ref_value(self.add_text("caption", text, cap_parent, extra));
2722        match choice {
2723            CaptionParent::Item => return (vec![cap_ref.clone()], vec![cap_ref]),
2724            // Created ahead of the item, so it precedes the item in the
2725            // container's children — and, on the body, in the body's.
2726            CaptionParent::Container => self.pending_siblings.push(cap_ref.clone()),
2727            CaptionParent::Body if parent == "#/body" => {
2728                self.pending_siblings.push(cap_ref.clone())
2729            }
2730            CaptionParent::ContainerAfter => self.pending_after.push(cap_ref.clone()),
2731            // The item sits deeper: the body's children get the caption after
2732            // the top-level item under walk, where docling appended it.
2733            CaptionParent::Body => self.pending_body.push(cap_ref.clone()),
2734        }
2735        (vec![cap_ref], Vec::new())
2736    }
2737
2738    /// `meta` is the picture's docling `PictureMeta` (a classifier's
2739    /// predictions, a chart's kind and data), `None` for a plain picture.
2740    fn add_picture(
2741        &mut self,
2742        caption: Option<&str>,
2743        caption_href: Option<&str>,
2744        image: Option<&crate::PictureImage>,
2745        meta: Option<Value>,
2746        parent: &str,
2747        caption_at: (CaptionParent, Option<[u16; 4]>),
2748    ) -> String {
2749        let self_ref = format!("#/pictures/{}", self.pictures.len());
2750        // Take the picture's own provenance before the caption text is added —
2751        // the caption is a separate item and must not inherit the crop's box.
2752        let prov = self.take_prov(0);
2753        let (captions, children) = match caption.filter(|c| !c.is_empty()) {
2754            Some(cap) => {
2755                // Emit the caption as a text item that the picture references. A
2756                // wrapping `<a href>`'s link rides as docling's `hyperlink` field
2757                // on the caption item (#328).
2758                let extra = match caption_href {
2759                    Some(href) => json!({ "hyperlink": href }),
2760                    None => json!({}),
2761                };
2762                self.add_caption(cap, extra, &self_ref, parent, caption_at)
2763            }
2764            None => (Vec::new(), Vec::new()),
2765        };
2766        self.push_picture(prov, captions, children, image, meta, parent)
2767    }
2768
2769    /// Append the picture item itself — `prov`, `captions` and `children`
2770    /// (a PDF caption is the picture's child) already settled.
2771    fn push_picture(
2772        &mut self,
2773        prov: Value,
2774        captions: Vec<Value>,
2775        children: Vec<Value>,
2776        image: Option<&crate::PictureImage>,
2777        meta: Option<Value>,
2778        parent: &str,
2779    ) -> String {
2780        let self_ref = format!("#/pictures/{}", self.pictures.len());
2781        // The legacy `classification` annotation rides along with a
2782        // classifier's `meta` (see `classification_meta`); a chart's meta has
2783        // none, like docling's.
2784        let annotations = meta
2785            .as_ref()
2786            .and_then(|m| m.get("annotations").cloned())
2787            .unwrap_or_else(|| json!([]));
2788        let meta = meta.map(|mut m| {
2789            if let Some(obj) = m.as_object_mut() {
2790                obj.remove("annotations");
2791            }
2792            m
2793        });
2794        // `meta` sits between `content_layer` and `label` in docling's field
2795        // order (and `preserve_order` keeps ours byte-compatible), so the item
2796        // is built in one shot per shape rather than patched afterwards.
2797        let mut item = match meta {
2798            Some(meta) => json!({
2799                "self_ref": self_ref,
2800                "parent": { "$ref": parent },
2801                "children": children,
2802                "content_layer": "body",
2803                "meta": meta,
2804                "label": "picture",
2805                "prov": prov,
2806                "captions": captions,
2807                "references": [],
2808                "footnotes": [],
2809                "annotations": annotations,
2810            }),
2811            None => json!({
2812                "self_ref": self_ref,
2813                "parent": { "$ref": parent },
2814                "children": children,
2815                "content_layer": "body",
2816                "label": "picture",
2817                "prov": prov,
2818                "captions": captions,
2819                "references": [],
2820                "footnotes": [],
2821                "annotations": annotations,
2822            }),
2823        };
2824        // docling stores the extracted image as an `ImageRef` (data URI + size,
2825        // the size as floats) between `footnotes` and `annotations` — pydantic
2826        // field order, which `preserve_order` lets us reproduce by rebuilding
2827        // the tail.
2828        if let Some(img) = image {
2829            let mut image = image_ref_json(img);
2830            // The displayed size, for the Pandoc writer only (#834):
2831            // docling's `ImageRef` has no field for it.
2832            if self.note_keys {
2833                if let Some([w, h]) = img.display_size {
2834                    image["_display"] = json!([w, h]);
2835                }
2836            }
2837            if let Some(obj) = item.as_object_mut() {
2838                let annotations = obj.remove("annotations").unwrap_or_else(|| json!([]));
2839                obj.insert("image".into(), image);
2840                obj.insert("annotations".into(), annotations);
2841            }
2842        }
2843        self.pictures.push(item);
2844        self_ref
2845    }
2846
2847    fn add_group(
2848        &mut self,
2849        label: &str,
2850        name: Option<&str>,
2851        layer: Option<ContentLayer>,
2852        nodes: &[Node],
2853        parent: &str,
2854    ) -> String {
2855        let self_ref = format!("#/groups/{}", self.groups.len());
2856        self.groups.push(Value::Null);
2857        // Everything the walk creates belongs to this group, so a non-body
2858        // layer (a hidden sheet) is stamped on the whole subtree afterwards —
2859        // docling puts the layer on the group *and* on every item under it.
2860        let mark = (
2861            self.texts.len(),
2862            self.tables.len(),
2863            self.pictures.len(),
2864            self.groups.len(),
2865        );
2866        let children: Vec<Value> = self
2867            .walk_into(nodes, &self_ref)
2868            .into_iter()
2869            .map(Child::into_value)
2870            .collect();
2871        let name = name.unwrap_or(if label == "inline" { "group" } else { label });
2872        let content_layer = layer.map_or("body", |l| l.value());
2873        self.groups[group_index(&self_ref)] = json!({
2874            "self_ref": self_ref,
2875            "parent": { "$ref": parent },
2876            "children": children,
2877            "content_layer": content_layer,
2878            "name": name,
2879            "label": label,
2880        });
2881        if layer.is_some() {
2882            let (t, tb, p, g) = mark;
2883            for item in self.texts[t..]
2884                .iter_mut()
2885                .enumerate()
2886                .map(|(k, item)| item.value_mut(t + k))
2887                .chain(self.tables[tb..].iter_mut().map(|t| &mut t.item))
2888                .chain(self.pictures[p..].iter_mut())
2889                .chain(self.groups[g..].iter_mut())
2890            {
2891                if let Some(obj) = item.as_object_mut() {
2892                    obj.insert("content_layer".into(), json!(content_layer));
2893                }
2894            }
2895        }
2896        self_ref
2897    }
2898
2899    /// Walk a slice of sibling nodes, returning each child's `$ref`; runs of
2900    /// list items are folded into list groups (one per sibling list).
2901    fn walk_into(&mut self, nodes: &[Node], parent: &str) -> Vec<Child> {
2902        // Siblings that all carry a creation rank (an XLSX sheet's items) are
2903        // *added* in that order — so `#/tables/N` and friends are numbered as
2904        // docling numbers them — while their refs keep the node order, which
2905        // is docling's position-sorted `children`.
2906        let seqs: Option<Vec<usize>> = nodes
2907            .iter()
2908            .map(|n| match n {
2909                Node::Prov { seq: Some(s), .. } => Some(*s),
2910                _ => None,
2911            })
2912            .collect();
2913        if let Some(seqs) = seqs.filter(|s| !s.is_empty()) {
2914            let mut order: Vec<usize> = (0..nodes.len()).collect();
2915            order.sort_by_key(|&i| seqs[i]);
2916            let mut slots: Vec<Vec<Child>> = (0..nodes.len()).map(|_| Vec::new()).collect();
2917            for i in order {
2918                if let Some(r) = self.add_node(&nodes[i], parent) {
2919                    slots[i].extend(self.pending_siblings.drain(..).map(Child::json));
2920                    slots[i].push(Child::Ref(r.into()));
2921                    slots[i].extend(self.pending_after.drain(..).map(Child::json));
2922                }
2923                if parent == "#/body" {
2924                    slots[i].extend(self.pending_body.drain(..).map(Child::json));
2925                }
2926            }
2927            return slots.into_iter().flatten().collect();
2928        }
2929        let mut children = Vec::new();
2930        let mut i = 0;
2931        while i < nodes.len() {
2932            if matches!(nodes[i], Node::ListItem { .. }) {
2933                let start = i;
2934                i += 1;
2935                loop {
2936                    match nodes.get(i) {
2937                        Some(Node::ListItem { .. }) => i += 1,
2938                        // Absorb an empty paragraph sitting between two list
2939                        // items (docling keeps the ListGroup contiguous).
2940                        Some(Node::Paragraph { text })
2941                            if text.is_empty()
2942                                && matches!(nodes.get(i + 1), Some(Node::ListItem { .. })) =>
2943                        {
2944                            i += 1
2945                        }
2946                        _ => break,
2947                    }
2948                }
2949                let mut lists = Vec::new();
2950                self.add_sibling_lists(&nodes[start..i], parent, &mut lists);
2951                children.extend(lists.into_iter().map(Child::json));
2952            } else {
2953                if let Some(r) = self.add_node(&nodes[i], parent) {
2954                    children.extend(self.pending_siblings.drain(..).map(Child::json));
2955                    children.push(Child::Ref(r.into()));
2956                    children.extend(self.pending_after.drain(..).map(Child::json));
2957                }
2958                i += 1;
2959            }
2960            // Body-parented captions of items deeper in the tree follow the
2961            // top-level item they were created under (#390).
2962            if parent == "#/body" {
2963                children.extend(self.pending_body.drain(..).map(Child::json));
2964            }
2965        }
2966        children
2967    }
2968
2969    /// A run of list items may hold several *sibling* lists; emit one list group
2970    /// per sibling. The boundary is the backend's `first_in_list` flag on a
2971    /// base-level item — the same rule as the Markdown serializer's blank line
2972    /// (#385; the kind-flip and number-gap guesses are gone).
2973    fn add_sibling_lists(&mut self, run: &[Node], parent: &str, out: &mut Vec<Value>) {
2974        let base = level_of(&run[0]);
2975        let mut seg = 0;
2976        for k in 0..run.len() {
2977            let Node::ListItem {
2978                first_in_list,
2979                level,
2980                ..
2981            } = &run[k]
2982            else {
2983                continue;
2984            };
2985            if *level != base {
2986                continue; // nested item — handled inside add_list
2987            }
2988            if k > seg && *first_in_list {
2989                out.push(ref_value(self.add_list(&run[seg..k], parent)));
2990                seg = k;
2991            }
2992        }
2993        out.push(ref_value(self.add_list(&run[seg..], parent)));
2994    }
2995}
2996
2997fn level_of(node: &Node) -> u8 {
2998    match node {
2999        Node::ListItem { level, .. } => *level,
3000        _ => 0,
3001    }
3002}
3003
3004fn group_index(self_ref: &str) -> usize {
3005    self_ref.rsplit('/').next().unwrap().parse().unwrap()
3006}
3007
3008fn ref_index(self_ref: &str) -> Option<usize> {
3009    self_ref.rsplit('/').next()?.parse().ok()
3010}
3011
3012/// Merge the key/values of `extra` (an object) into `target` (an object).
3013fn merge(target: &mut Value, extra: Value) {
3014    if let (Some(t), Value::Object(e)) = (target.as_object_mut(), extra) {
3015        t.extend(e);
3016    }
3017}
3018
3019/// A JSON object of exactly these entries, in this order. The hot per-item
3020/// constructors use this instead of `json!`: the macro grows its map by
3021/// doubling (an 8-key item kept 14 slots) and deep-copies every interpolated
3022/// `Value` through `to_value`. On a long text-heavy PDF those item objects
3023/// *are* the export's footprint (the same reasoning as [`cell_value`]).
3024fn object<const N: usize>(entries: [(&str, Value); N]) -> Value {
3025    let mut m = serde_json::Map::with_capacity(N);
3026    for (k, v) in entries {
3027        m.insert(k.to_owned(), v);
3028    }
3029    Value::Object(m)
3030}
3031
3032/// A `{"$ref": r}` reference object.
3033fn ref_value(r: impl Into<String>) -> Value {
3034    object([("$ref", Value::String(r.into()))])
3035}
3036
3037/// Reverse [`crate`]'s Markdown text escaping (HTML entities + `\_`).
3038fn unescape_text(s: &str) -> String {
3039    s.replace("&lt;", "<")
3040        .replace("&gt;", ">")
3041        .replace("&amp;", "&")
3042        .replace("\\_", "_")
3043}
3044
3045/// 64-bit FNV-1a, a stand-in for docling's `binary_hash` (we lack the source bytes
3046/// at export time; the value only needs to be a stable u64).
3047fn fnv1a(s: &str) -> u64 {
3048    let mut h: u64 = 0xcbf29ce484222325;
3049    for b in s.bytes() {
3050        h ^= b as u64;
3051        h = h.wrapping_mul(0x100000001b3);
3052    }
3053    h
3054}
3055
3056#[cfg(test)]
3057mod tests {
3058    use crate::{
3059        CaptionParent, ContentLayer, DoclingDocument, ImageMode, Node, PictureImage, Table,
3060    };
3061    use serde_json::Value;
3062
3063    fn cell_at(text: &str, row: usize, col: usize, col_span: usize) -> crate::TableCell {
3064        crate::TableCell {
3065            text: text.into(),
3066            bbox: None,
3067            start_row: row,
3068            start_col: col,
3069            row_span: 1,
3070            col_span,
3071            column_header: row == 0,
3072            row_header: false,
3073            row_section: false,
3074        }
3075    }
3076
3077    /// First-class cells past the rows: rectangular rows are the grid and
3078    /// clip them (docling's `TableData.grid` on USPTO's overrun replicas);
3079    /// ragged rows — an xlsx table compacted by `skip_empty_cells` (#271) —
3080    /// are no grid, so the cells' extent sizes it and the omitted positions
3081    /// come back as empty filler cells in `grid` only.
3082    #[test]
3083    fn ragged_rows_take_their_grid_from_first_class_cells() {
3084        let cells = vec![
3085            cell_at("h0", 0, 0, 1),
3086            cell_at("h2", 0, 2, 1),
3087            cell_at("wide", 1, 0, 3),
3088        ];
3089        let export = |rows: Vec<Vec<String>>| -> Value {
3090            let mut doc = DoclingDocument::new("t");
3091            doc.push(Node::Table(Table {
3092                rows,
3093                cells: Some(cells.clone()),
3094                ..Table::default()
3095            }));
3096            let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3097            v["tables"][0]["data"].clone()
3098        };
3099        // Compacted rows: 2 and 3 wide, the cells say the grid is 3 wide.
3100        let data = export(vec![
3101            vec!["h0".into(), "h2".into()],
3102            vec!["wide".into(), "wide".into(), "wide".into()],
3103        ]);
3104        assert_eq!(data["num_rows"], 2);
3105        assert_eq!(data["num_cols"], 3);
3106        assert_eq!(data["table_cells"].as_array().unwrap().len(), 3);
3107        let row0: Vec<&str> = data["grid"][0]
3108            .as_array()
3109            .unwrap()
3110            .iter()
3111            .map(|c| c["text"].as_str().unwrap())
3112            .collect();
3113        assert_eq!(row0, ["h0", "", "h2"]);
3114        assert_eq!(data["table_cells"][2]["col_span"], 3);
3115        // Rectangular rows narrower than the cells: the rows win, the cells
3116        // are clipped to them exactly as before.
3117        let data = export(vec![
3118            vec!["h0".into(), "h2".into()],
3119            vec!["wide".into(), "wide".into()],
3120        ]);
3121        assert_eq!(data["num_cols"], 2);
3122        assert_eq!(data["grid"][0].as_array().unwrap().len(), 2);
3123    }
3124
3125    fn doc_with_image() -> DoclingDocument {
3126        let mut doc = DoclingDocument::new("t");
3127        doc.push(Node::Picture {
3128            caption: Some("Fig 1".into()),
3129            caption_href: None,
3130            image: Some(PictureImage {
3131                dpi: crate::PictureImage::DEFAULT_DPI,
3132                mimetype: "image/png".into(),
3133                width: 4,
3134                height: 2,
3135                data: b"foobar".to_vec(),
3136                display_size: None,
3137            }),
3138            classification: None,
3139            description: None,
3140            caption_parent: Default::default(),
3141            caption_location: None,
3142        });
3143        doc
3144    }
3145
3146    /// #402: a deck's speaker notes are content, and docling puts them in the
3147    /// JSON on the `notes` layer so a consumer reading only JSON can pick them
3148    /// out. Markdown still serializes the body layer alone, and page furniture
3149    /// stays out of the JSON, where docling does keep it.
3150    #[test]
3151    fn notes_layer_items_reach_the_json_but_furniture_does_not() {
3152        let mut doc = DoclingDocument::new("t");
3153        doc.push(Node::Heading {
3154            level: 1,
3155            text: "Slide One".into(),
3156        });
3157        doc.push(Node::Furniture {
3158            layer: ContentLayer::Notes,
3159            inner: Box::new(Node::Located {
3160                location: [0, 0, 0, 0],
3161                inner: Box::new(Node::Paragraph {
3162                    text: "Speaker note for slide 1.".into(),
3163                }),
3164            }),
3165        });
3166        doc.push(Node::Furniture {
3167            layer: ContentLayer::Furniture,
3168            inner: Box::new(Node::Paragraph {
3169                text: "page header".into(),
3170            }),
3171        });
3172
3173        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3174        let texts = v["texts"].as_array().unwrap();
3175        assert_eq!(
3176            texts
3177                .iter()
3178                .map(|t| (
3179                    t["label"].as_str().unwrap(),
3180                    t["content_layer"].as_str().unwrap(),
3181                    t["text"].as_str().unwrap()
3182                ))
3183                .collect::<Vec<_>>(),
3184            vec![
3185                ("title", "body", "Slide One"),
3186                ("text", "notes", "Speaker note for slide 1."),
3187            ],
3188            "the note is carried on its own layer; the furniture is not carried"
3189        );
3190        // The body layer is what Markdown serializes, so it does not change.
3191        assert_eq!(doc.export_to_markdown(), "# Slide One\n");
3192    }
3193
3194    /// #410: a backend that describes merged ranges only as continuation
3195    /// flags (xlsx `<mergeCell>`, docx `gridSpan`/`vMerge`) gets docling's
3196    /// one-`TableCell`-per-range JSON: the anchor's offsets and spans, the
3197    /// entry repeated across the grid positions it covers — not a 1×1 cell
3198    /// per position with the text copied into each.
3199    #[test]
3200    fn continuation_flags_become_spanning_cells() {
3201        let mut doc = DoclingDocument::new("t");
3202        // A1:C2 merged ("merged"), then a plain row underneath.
3203        let rows = vec![
3204            vec!["merged".to_string(), "merged".into(), "merged".into()],
3205            vec!["merged".to_string(), "merged".into(), "merged".into()],
3206            vec!["a".to_string(), "b".into(), "c".into()],
3207        ];
3208        doc.push(Node::Table(crate::Table {
3209            rows,
3210            location: None,
3211            structure: Some(crate::TableStructure {
3212                header_row: vec![true, false, false],
3213                col_continuation: vec![
3214                    vec![false, true, true],
3215                    vec![false, true, true],
3216                    vec![false, false, false],
3217                ],
3218                row_continuation: vec![
3219                    vec![false, false, false],
3220                    vec![true, true, true],
3221                    vec![false, false, false],
3222                ],
3223                row_header: Vec::new(),
3224                col_header: Vec::new(),
3225            }),
3226            cell_blocks: None,
3227            cells: None,
3228            caption: None,
3229            caption_parent: Default::default(),
3230            caption_location: None,
3231        }));
3232        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3233        let data = &v["tables"][0]["data"];
3234        assert_eq!(data["num_rows"], 3);
3235        assert_eq!(data["num_cols"], 3);
3236        let cells = data["table_cells"].as_array().unwrap();
3237        assert_eq!(
3238            cells.len(),
3239            4,
3240            "one cell for the range, three for the plain row"
3241        );
3242        assert_eq!(
3243            cells[0],
3244            serde_json::json!({
3245                "row_span": 2, "col_span": 3,
3246                "start_row_offset_idx": 0, "end_row_offset_idx": 2,
3247                "start_col_offset_idx": 0, "end_col_offset_idx": 3,
3248                "text": "merged", "column_header": true, "row_header": false,
3249                "row_section": false, "fillable": false,
3250            })
3251        );
3252        assert_eq!(cells[1]["text"], "a");
3253        assert_eq!(cells[1]["row_span"], 1);
3254        assert_eq!(cells[1]["column_header"], false);
3255        // The grid repeats the range's entry at every position it covers.
3256        let grid = data["grid"].as_array().unwrap();
3257        assert_eq!(grid.len(), 3);
3258        for (r, row) in grid.iter().take(2).enumerate() {
3259            for (c, cell) in row.as_array().unwrap().iter().enumerate() {
3260                assert_eq!(*cell, cells[0], "grid[{r}][{c}]");
3261            }
3262        }
3263        assert_eq!(grid[2][2]["text"], "c");
3264    }
3265
3266    /// A [`Node::Prov`] wrapper is docling's provenance verbatim — the exact
3267    /// box in a top-left origin, the backend's charspan — and the page marker
3268    /// before it sizes the page; a chart's caption becomes a sibling of the
3269    /// picture in the container, listed first, sharing the chart's box with
3270    /// a charspan over its text. That is the JSON shape of an XLSX sheet.
3271    #[test]
3272    fn exact_provenance_pages_and_chart_captions_follow_docling() {
3273        let mut doc = DoclingDocument::new("t");
3274        doc.push(Node::PageInfo {
3275            page_no: 1,
3276            width: 3.0,
3277            height: 4.0,
3278        });
3279        let table = crate::Table {
3280            rows: vec![vec!["a".to_string(), "b".into()]],
3281            ..Default::default()
3282        };
3283        doc.push(Node::Group {
3284            label: "sheet".into(),
3285            name: Some("Data".into()),
3286            layer: None,
3287            children: vec![
3288                // Node order is the position-sorted one; creation order (the
3289                // `seq`) had the chart first — so the chart is `#/pictures/0`
3290                // *and* its caption `#/texts/0`, while the table stays the
3291                // group's first child.
3292                Node::Prov {
3293                    page_no: 1,
3294                    bbox: [0.0, 0.0, 3.0, 4.0],
3295                    charspan: [0, 0],
3296                    bottom_left: false,
3297                    seq: Some(1),
3298                    inner: Box::new(Node::Table(table.clone())),
3299                },
3300                Node::Prov {
3301                    page_no: 1,
3302                    bbox: [0.0, 1.0, 1.0, 1.0],
3303                    charspan: [0, 0],
3304                    bottom_left: false,
3305                    seq: Some(0),
3306                    inner: Box::new(Node::Chart {
3307                        kind: "bar_chart".into(),
3308                        table,
3309                        caption: Some("Sales".into()),
3310                        location: Some([0, 128, 170, 128]),
3311                    }),
3312                },
3313            ],
3314        });
3315        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3316        assert_eq!(
3317            v["pages"],
3318            serde_json::json!({"1": {"size": {"width": 3.0, "height": 4.0}, "page_no": 1}})
3319        );
3320        assert_eq!(
3321            v["tables"][0]["prov"],
3322            serde_json::json!([{
3323                "page_no": 1,
3324                "bbox": {"l": 0.0, "t": 0.0, "r": 3.0, "b": 4.0, "coord_origin": "TOPLEFT"},
3325                "charspan": [0, 0],
3326            }])
3327        );
3328        assert_eq!(v["tables"][0]["data"]["orientation"], "rot_0");
3329        // The caption is the group's child *before* the picture, parented to
3330        // the group, and referenced by the picture.
3331        let sheet = &v["groups"][0];
3332        assert_eq!(
3333            sheet["children"],
3334            serde_json::json!([
3335                {"$ref": "#/tables/0"}, {"$ref": "#/texts/0"}, {"$ref": "#/pictures/0"}
3336            ])
3337        );
3338        let cap = &v["texts"][0];
3339        assert_eq!(cap["label"], "caption");
3340        assert_eq!(cap["parent"], serde_json::json!({"$ref": "#/groups/0"}));
3341        assert_eq!(cap["prov"][0]["charspan"], serde_json::json!([0, 5]));
3342        assert_eq!(cap["prov"][0]["bbox"]["b"], 1.0);
3343        let pic = &v["pictures"][0];
3344        assert_eq!(pic["captions"], serde_json::json!([{"$ref": "#/texts/0"}]));
3345        assert_eq!(pic["prov"][0]["charspan"], serde_json::json!([0, 0]));
3346        assert_eq!(pic["prov"][0]["bbox"]["coord_origin"], "TOPLEFT");
3347        assert_eq!(
3348            pic["meta"]["classification"]["predictions"][0]["class_name"],
3349            "bar_chart"
3350        );
3351        assert_eq!(pic["meta"]["tabular_chart"]["chart_data"]["num_cols"], 2);
3352    }
3353
3354    /// An all-zero location is the "no geometry" sentinel — a slide's speaker
3355    /// notes carry one — and docling writes it as a zero bbox, not as a box
3356    /// spanning the whole page, which is what denormalizing the grid gives.
3357    #[test]
3358    fn a_zero_location_is_a_zero_bbox_not_the_whole_page() {
3359        let mut doc = DoclingDocument::new("t");
3360        doc.push(Node::PageInfo {
3361            page_no: 1,
3362            width: 12192000.0,
3363            height: 6858000.0,
3364        });
3365        doc.push(Node::Furniture {
3366            layer: ContentLayer::Notes,
3367            inner: Box::new(Node::Located {
3368                location: [0, 0, 0, 0],
3369                inner: Box::new(Node::Paragraph {
3370                    text: "a note".into(),
3371                }),
3372            }),
3373        });
3374        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3375        let prov = &v["texts"][0]["prov"][0];
3376        assert_eq!(prov["page_no"], 1);
3377        assert_eq!(prov["charspan"], serde_json::json!([0, 6]));
3378        assert_eq!(
3379            prov["bbox"],
3380            serde_json::json!({"l": 0.0, "t": 0.0, "r": 0.0, "b": 0.0, "coord_origin": "BOTTOMLEFT"})
3381        );
3382        // The page itself is recorded at its true size.
3383        assert_eq!(
3384            v["pages"]["1"]["size"],
3385            serde_json::json!({"width": 12192000.0, "height": 6858000.0})
3386        );
3387    }
3388
3389    /// #171: PageInfo markers become the `pages` map, and `Located` wrappers /
3390    /// node-level locations become per-item `prov` — the 0–511 grid
3391    /// denormalized against the page into BOTTOMLEFT points. Without markers
3392    /// (every declarative backend) the JSON stays exactly as before: empty
3393    /// `pages`, `prov: []` even for located nodes.
3394    /// #609: a PDF caption and a checkbox item carry their own page and box.
3395    /// docling's reading-order model gives every caption the cluster it came
3396    /// from (`_add_caption_or_footnote`), not its picture's or table's, and
3397    /// a checkbox is a text item like any other.
3398    #[test]
3399    fn captions_and_checkboxes_carry_their_own_prov() {
3400        let mut doc = DoclingDocument::new("t");
3401        doc.push(Node::PageInfo {
3402            page_no: 1,
3403            width: 512.0,
3404            height: 512.0,
3405        });
3406        doc.push(Node::Located {
3407            location: [64, 64, 448, 256],
3408            inner: Box::new(Node::Picture {
3409                caption: Some("Figure 1".into()),
3410                caption_href: None,
3411                image: None,
3412                classification: None,
3413                description: None,
3414                caption_parent: CaptionParent::Item,
3415                caption_location: Some([64, 264, 448, 280]),
3416            }),
3417        });
3418        doc.push(Node::PageInfo {
3419            page_no: 2,
3420            width: 512.0,
3421            height: 512.0,
3422        });
3423        doc.push(Node::Located {
3424            location: [64, 120, 448, 300],
3425            inner: Box::new(Node::Table(Table {
3426                rows: vec![vec!["a".into()]],
3427                caption: Some("Table 1".into()),
3428                caption_parent: CaptionParent::Item,
3429                caption_location: Some([64, 100, 300, 112]),
3430                ..Table::default()
3431            })),
3432        });
3433        doc.push(Node::Located {
3434            location: [64, 320, 200, 332],
3435            inner: Box::new(Node::CheckboxItem {
3436                checked: false,
3437                text: "First option".into(),
3438            }),
3439        });
3440        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3441        let texts = v["texts"].as_array().unwrap();
3442        let by_text = |t: &str| texts.iter().find(|x| x["text"] == t).expect(t).clone();
3443        let bbox = |p: &Value| {
3444            let b = &p["prov"][0]["bbox"];
3445            [&b["l"], &b["t"], &b["r"], &b["b"]].map(|x| x.as_f64().unwrap())
3446        };
3447        // Figure 1: its own box (grid == points on a 512 page, flipped to
3448        // BOTTOMLEFT), not the picture's.
3449        let fig = by_text("Figure 1");
3450        assert_eq!(fig["prov"][0]["page_no"], 1);
3451        assert_eq!(bbox(&fig), [64.0, 248.0, 448.0, 232.0]);
3452        assert_eq!(fig["prov"][0]["charspan"], serde_json::json!([0, 8]));
3453        assert_eq!(fig["parent"]["$ref"], "#/pictures/0");
3454        assert_eq!(v["pictures"][0]["prov"][0]["bbox"]["t"], 448.0);
3455        // Table 1 on page 2, its own box; the table keeps its own.
3456        let tab = by_text("Table 1");
3457        assert_eq!(tab["prov"][0]["page_no"], 2);
3458        assert_eq!(bbox(&tab), [64.0, 412.0, 300.0, 400.0]);
3459        assert_eq!(v["tables"][0]["prov"][0]["bbox"]["t"], 392.0);
3460        // The checkbox item.
3461        let cb = by_text("First option");
3462        assert_eq!(cb["label"], "checkbox_unselected");
3463        assert_eq!(cb["prov"][0]["page_no"], 2);
3464        assert_eq!(bbox(&cb), [64.0, 192.0, 200.0, 180.0]);
3465        assert!(texts
3466            .iter()
3467            .all(|t| !t["prov"].as_array().unwrap().is_empty()));
3468
3469        // Without a caption box (every declarative backend) the caption
3470        // still has no prov, and nothing else moves.
3471        let mut plain = DoclingDocument::new("t");
3472        plain.push(Node::PageInfo {
3473            page_no: 1,
3474            width: 512.0,
3475            height: 512.0,
3476        });
3477        plain.push(Node::Located {
3478            location: [64, 64, 448, 256],
3479            inner: Box::new(Node::Picture {
3480                caption: Some("Figure 1".into()),
3481                caption_href: None,
3482                image: None,
3483                classification: None,
3484                description: None,
3485                caption_parent: CaptionParent::Item,
3486                caption_location: None,
3487            }),
3488        });
3489        let v: Value = serde_json::from_str(&plain.export_to_json()).unwrap();
3490        assert_eq!(v["texts"][0]["prov"], serde_json::json!([]));
3491        assert_eq!(v["pictures"][0]["prov"][0]["bbox"]["t"], 448.0);
3492    }
3493
3494    #[test]
3495    fn page_markers_produce_pages_and_prov() {
3496        let mut doc = DoclingDocument::new("t");
3497        doc.push(Node::PageInfo {
3498            page_no: 1,
3499            width: 512.0,
3500            height: 1024.0,
3501        });
3502        doc.push(Node::Located {
3503            location: [128, 64, 256, 128], // quarter/eighth points of the grid
3504            inner: Box::new(Node::Paragraph {
3505                text: "hello".into(),
3506            }),
3507        });
3508        doc.push(Node::Table(Table {
3509            rows: vec![vec!["a".into()]],
3510            location: Some([0, 0, 512, 512]),
3511            ..Table::default()
3512        }));
3513        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3514        assert_eq!(v["pages"]["1"]["page_no"], 1);
3515        assert_eq!(v["pages"]["1"]["size"]["width"], 512.0);
3516        assert_eq!(v["pages"]["1"]["size"]["height"], 1024.0);
3517        // 512-wide page: grid x scales 1:1; 1024-high: grid y doubles, then
3518        // flips to the BOTTOMLEFT origin (t from grid-top 64 → 1024-128=896).
3519        let prov = &v["texts"][0]["prov"][0];
3520        assert_eq!(prov["page_no"], 1);
3521        assert_eq!(prov["bbox"]["l"], 128.0);
3522        assert_eq!(prov["bbox"]["t"], 896.0);
3523        assert_eq!(prov["bbox"]["r"], 256.0);
3524        assert_eq!(prov["bbox"]["b"], 768.0);
3525        assert_eq!(prov["bbox"]["coord_origin"], "BOTTOMLEFT");
3526        assert_eq!(prov["charspan"][1], 5);
3527        // The table adopts its own location field; charspan is [0, 0].
3528        let tprov = &v["tables"][0]["prov"][0];
3529        assert_eq!(tprov["bbox"]["t"], 1024.0);
3530        assert_eq!(tprov["bbox"]["b"], 0.0);
3531        assert_eq!(tprov["charspan"][1], 0);
3532
3533        // No markers → the pre-#171 shape, byte for byte.
3534        let mut plain = DoclingDocument::new("t");
3535        plain.push(Node::Located {
3536            location: [1, 2, 3, 4],
3537            inner: Box::new(Node::Paragraph { text: "x".into() }),
3538        });
3539        let v: Value = serde_json::from_str(&plain.export_to_json()).unwrap();
3540        assert_eq!(v["pages"], serde_json::json!({}));
3541        assert_eq!(v["texts"][0]["prov"], serde_json::json!([]));
3542    }
3543
3544    /// PDF page headers/footers reach the JSON as docling writes them:
3545    /// body-parented text items on the furniture layer, with their box.
3546    #[test]
3547    fn page_furniture_becomes_furniture_layer_text() {
3548        let mut doc = DoclingDocument::new("t");
3549        doc.push(Node::PageInfo {
3550            page_no: 1,
3551            width: 512.0,
3552            height: 512.0,
3553        });
3554        doc.push(Node::PageFurniture {
3555            footer: false,
3556            location: [10, 0, 100, 20],
3557            text: "Chapter 1".into(),
3558        });
3559        doc.push(Node::Paragraph {
3560            text: "body".into(),
3561        });
3562        doc.push(Node::PageFurniture {
3563            footer: true,
3564            location: [400, 490, 500, 512],
3565            text: "1.10.2".into(),
3566        });
3567        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3568        let texts = v["texts"].as_array().unwrap();
3569        assert_eq!(texts.len(), 3);
3570        assert_eq!(texts[0]["label"], "page_header");
3571        assert_eq!(texts[0]["content_layer"], "furniture");
3572        assert_eq!(texts[0]["parent"]["$ref"], "#/body");
3573        assert_eq!(texts[0]["prov"][0]["bbox"]["l"], 10.0);
3574        assert_eq!(texts[1]["content_layer"], "body");
3575        assert_eq!(texts[1]["prov"], serde_json::json!([]));
3576        assert_eq!(texts[2]["label"], "page_footer");
3577        assert_eq!(texts[2]["text"], "1.10.2");
3578        assert_eq!(texts[2]["content_layer"], "furniture");
3579    }
3580
3581    #[test]
3582    fn picture_image_in_markdown_modes_and_json() {
3583        let doc = doc_with_image();
3584        // placeholder (default) ignores the image
3585        assert!(doc.export_to_markdown().contains("<!-- image -->"));
3586        // embedded → base64 data URI (b"foobar" → "Zm9vYmFy")
3587        let (md, files) = doc.export_to_markdown_with_images(ImageMode::Embedded, "artifacts");
3588        assert!(
3589            md.contains("![Image](data:image/png;base64,Zm9vYmFy)"),
3590            "got:\n{md}"
3591        );
3592        assert!(files.is_empty());
3593        // referenced → file link + collected bytes
3594        let (md, files) = doc.export_to_markdown_with_images(ImageMode::Referenced, "artifacts");
3595        assert!(
3596            md.contains("![Image](artifacts/image_000000.png)"),
3597            "got:\n{md}"
3598        );
3599        assert_eq!(
3600            files,
3601            vec![("artifacts/image_000000.png".to_string(), b"foobar".to_vec())]
3602        );
3603        // JSON carries the ImageRef (data URI + size — floats, as docling's
3604        // `Size` is — placed before `annotations`).
3605        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3606        assert_eq!(v["pictures"][0]["image"]["mimetype"], "image/png");
3607        assert_eq!(v["pictures"][0]["image"]["size"]["width"], 4.0);
3608        let keys: Vec<&str> = v["pictures"][0]
3609            .as_object()
3610            .unwrap()
3611            .keys()
3612            .map(String::as_str)
3613            .collect();
3614        assert_eq!(&keys[keys.len() - 2..], ["image", "annotations"]);
3615        assert_eq!(
3616            v["pictures"][0]["image"]["uri"],
3617            "data:image/png;base64,Zm9vYmFy"
3618        );
3619    }
3620
3621    #[test]
3622    fn exports_docling_schema() {
3623        let mut doc = DoclingDocument::new("t");
3624        doc.push(Node::Heading {
3625            level: 1,
3626            text: "Title".into(),
3627        });
3628        doc.push(Node::Heading {
3629            level: 2,
3630            text: "Sec".into(),
3631        });
3632        doc.push(Node::Paragraph {
3633            text: "Body &amp; more".into(),
3634        }); // markdown-escaped
3635        doc.push(Node::ListItem {
3636            ordered: false,
3637            number: 0,
3638            first_in_list: true,
3639            text: "one".into(),
3640            level: 0,
3641            marker: None,
3642            location: None,
3643            dclx: None,
3644            href: None,
3645            layer: None,
3646        });
3647        doc.push(Node::ListItem {
3648            ordered: false,
3649            number: 0,
3650            first_in_list: false,
3651            text: "two".into(),
3652            level: 0,
3653            marker: None,
3654            location: None,
3655            dclx: None,
3656            href: None,
3657            layer: None,
3658        });
3659        doc.push(Node::Table(Table {
3660            rows: vec![vec!["A".into(), "B".into()]],
3661            location: None,
3662            structure: None,
3663            cell_blocks: None,
3664            cells: None,
3665            caption: None,
3666            caption_parent: Default::default(),
3667            caption_location: None,
3668        }));
3669
3670        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3671        assert_eq!(v["schema_name"], "DoclingDocument");
3672        assert_eq!(v["version"], "1.10.0");
3673        assert_eq!(v["texts"][0]["label"], "title");
3674        assert_eq!(v["texts"][1]["label"], "section_header");
3675        assert_eq!(v["texts"][1]["level"], 1); // heading level 2 → docling level 1
3676        assert_eq!(v["texts"][2]["text"], "Body & more"); // un-escaped for the wire format
3677                                                          // consecutive list items fold into one list group, parented to it
3678        assert_eq!(v["groups"][0]["label"], "list");
3679        assert_eq!(v["groups"][0]["children"].as_array().unwrap().len(), 2);
3680        assert_eq!(v["texts"][3]["parent"]["$ref"], "#/groups/0");
3681        assert_eq!(v["texts"][3]["marker"], "-");
3682        // table grid + header flag
3683        assert_eq!(v["tables"][0]["data"]["num_cols"], 2);
3684        assert_eq!(v["tables"][0]["data"]["grid"][0][0]["column_header"], true);
3685    }
3686    /// A named group on a non-body layer — docling's hidden spreadsheet sheet:
3687    /// the group carries the sheet's name and the `invisible` layer, and every
3688    /// item inside it carries the layer too.
3689    #[test]
3690    fn a_layered_group_stamps_its_whole_subtree() {
3691        let doc = DoclingDocument {
3692            name: "s".into(),
3693            nodes: vec![
3694                Node::Group {
3695                    label: "sheet".into(),
3696                    name: Some("Sheet1".into()),
3697                    layer: None,
3698                    children: vec![Node::Paragraph {
3699                        text: "visible".into(),
3700                    }],
3701                },
3702                Node::Group {
3703                    label: "sheet".into(),
3704                    name: Some("Sheet2".into()),
3705                    layer: Some(ContentLayer::Invisible),
3706                    children: vec![Node::Paragraph {
3707                        text: "hidden".into(),
3708                    }],
3709                },
3710            ],
3711            ..DoclingDocument::new("s")
3712        };
3713        let v = crate::json::to_json(&doc);
3714        assert_eq!(v["groups"][0]["label"], "sheet");
3715        assert_eq!(v["groups"][0]["name"], "Sheet1");
3716        assert_eq!(v["groups"][0]["content_layer"], "body");
3717        assert_eq!(v["texts"][0]["content_layer"], "body");
3718        assert_eq!(v["groups"][1]["name"], "Sheet2");
3719        assert_eq!(v["groups"][1]["content_layer"], "invisible");
3720        assert_eq!(v["texts"][1]["content_layer"], "invisible");
3721        // The group's children are the items, and the body holds the groups.
3722        assert_eq!(v["groups"][1]["children"][0]["$ref"], "#/texts/1");
3723        assert_eq!(v["body"]["children"][1]["$ref"], "#/groups/1");
3724    }
3725
3726    /// A backend-built item tree is serialized as it is: items numbered in
3727    /// creation order per bucket (a field region's part texts included), the
3728    /// tree's parents / children / layers, docling's field order for
3729    /// `formatting`, `hyperlink`, `level`, `enumerated`/`marker`, a rich
3730    /// cell's `ref` on `table_cells` only, raw cell text.
3731    /// The DOCX tree's extras: an item `delete`d (docling's `delete_items`,
3732    /// the spacer between two items of a resumed list) is neither written nor
3733    /// numbered, `comments` back-refs sit between `prov` and `orig`, and a
3734    /// chart picture carries `classification` plus `tabular_chart`.
3735    #[test]
3736    fn deleted_items_comment_refs_and_chart_meta_in_the_tree() {
3737        use crate::tree::{ItemTree, TreeKind};
3738        let mut t = ItemTree::default();
3739        let text = |txt: &str| TreeKind::Text {
3740            label: "text".into(),
3741            text: txt.into(),
3742            orig: None,
3743            formatting: None,
3744            hyperlink: None,
3745            level: None,
3746            list: None,
3747        };
3748        let a = t.add(None, None, text("a"));
3749        let blank = t.add(None, None, text(""));
3750        let b = t.add(None, None, text("b"));
3751        t.delete(blank);
3752        let group = t.add(
3753            None,
3754            Some(ContentLayer::Notes),
3755            TreeKind::Group {
3756                label: "comment_section".into(),
3757                name: "comment-0".into(),
3758            },
3759        );
3760        t.add(Some(group), Some(ContentLayer::Notes), text("note"));
3761        t.items[a].comments.push(group);
3762        t.add(
3763            None,
3764            None,
3765            TreeKind::Picture {
3766                captions: Vec::new(),
3767                image: None,
3768                extra_classes: Vec::new(),
3769                classification: Some("bar_chart".into()),
3770                description: None,
3771                confidence: None,
3772                chart: Some(Table {
3773                    rows: vec![vec!["".into(), "s".into()], vec!["c".into(), "1".into()]],
3774                    ..Table::default()
3775                }),
3776                dpi: None,
3777            },
3778        );
3779        assert_eq!(t.last_text(), Some(4), "the note; the blank is skipped");
3780        assert_eq!(t.bucket_index(b), 1, "numbered past the deleted item");
3781        let mut doc = DoclingDocument::new("t");
3782        doc.tree = Some(t);
3783        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3784        let texts = v["texts"].as_array().unwrap();
3785        assert_eq!(texts.len(), 3);
3786        assert_eq!(texts[1]["text"], "b");
3787        assert_eq!(texts[1]["self_ref"], "#/texts/1");
3788        assert_eq!(
3789            v["body"]["children"],
3790            serde_json::json!([{"$ref": "#/texts/0"}, {"$ref": "#/texts/1"}, {"$ref": "#/groups/0"}, {"$ref": "#/pictures/0"}])
3791        );
3792        let keys: Vec<&str> = texts[0]
3793            .as_object()
3794            .unwrap()
3795            .keys()
3796            .map(String::as_str)
3797            .collect();
3798        assert_eq!(
3799            keys,
3800            vec![
3801                "self_ref",
3802                "parent",
3803                "children",
3804                "content_layer",
3805                "label",
3806                "prov",
3807                "comments",
3808                "orig",
3809                "text"
3810            ]
3811        );
3812        assert_eq!(
3813            texts[0]["comments"],
3814            serde_json::json!([{"$ref": "#/groups/0"}])
3815        );
3816        assert!(texts[1].get("comments").is_none());
3817        let meta = &v["pictures"][0]["meta"];
3818        assert_eq!(
3819            meta["classification"]["predictions"][0]["class_name"],
3820            "bar_chart"
3821        );
3822        assert_eq!(meta["tabular_chart"]["chart_data"]["num_rows"], 2);
3823    }
3824
3825    /// A tree item's `TreeProv` is written verbatim — a raw EMU box with
3826    /// whatever origin tag the backend set (`BOTTOMLEFT` here) and a per-item
3827    /// charspan, a note's zero `TOPLEFT` box — a picture's `image.dpi` is the file's when the backend
3828    /// read one, an item without provenance writes `prov: []`, and the page
3829    /// map still comes from the flat stream's markers.
3830    #[test]
3831    fn tree_items_carry_exact_provenance_and_dpi() {
3832        use crate::tree::{ItemTree, TreeKind, TreeProv};
3833        let text = |label: &str, t: &str| TreeKind::Text {
3834            label: label.into(),
3835            text: t.into(),
3836            orig: None,
3837            formatting: None,
3838            hyperlink: None,
3839            level: None,
3840            list: None,
3841        };
3842        let mut t = ItemTree::default();
3843        let slide = t.add(
3844            None,
3845            None,
3846            TreeKind::Group {
3847                label: "chapter".into(),
3848                name: "slide-0".into(),
3849            },
3850        );
3851        t.add_with_prov(
3852            Some(slide),
3853            None,
3854            text("paragraph", "héllo"),
3855            TreeProv {
3856                page_no: 1,
3857                bbox: [914400.0, 1828800.0, 2743200.0, 457200.0],
3858                bottom_left: true,
3859                charspan: [0, 5],
3860            },
3861        );
3862        t.add_with_prov(
3863            Some(slide),
3864            None,
3865            TreeKind::Picture {
3866                captions: Vec::new(),
3867                image: Some(crate::PictureImage {
3868                    dpi: crate::PictureImage::DEFAULT_DPI,
3869                    mimetype: "image/png".into(),
3870                    width: 2,
3871                    height: 2,
3872                    data: vec![0],
3873                    display_size: None,
3874                }),
3875                extra_classes: Vec::new(),
3876                classification: None,
3877                description: None,
3878                confidence: None,
3879                chart: None,
3880                dpi: Some(300),
3881            },
3882            TreeProv {
3883                page_no: 1,
3884                bbox: [0.0; 4],
3885                bottom_left: false,
3886                charspan: [0, 0],
3887            },
3888        );
3889        t.add(
3890            Some(slide),
3891            Some(ContentLayer::Notes),
3892            text("text", "no geometry"),
3893        );
3894        let mut doc = DoclingDocument::new("t");
3895        doc.push(Node::PageInfo {
3896            page_no: 1,
3897            width: 9144000.0,
3898            height: 6858000.0,
3899        });
3900        doc.tree = Some(t);
3901        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3902        assert_eq!(
3903            v["texts"][0]["prov"],
3904            serde_json::json!([{
3905                "page_no": 1,
3906                "bbox": { "l": 914400.0, "t": 1828800.0, "r": 2743200.0, "b": 457200.0, "coord_origin": "BOTTOMLEFT" },
3907                "charspan": [0, 5],
3908            }])
3909        );
3910        assert_eq!(v["texts"][0]["label"], "paragraph");
3911        assert_eq!(
3912            v["pictures"][0]["prov"][0]["bbox"]["coord_origin"],
3913            "TOPLEFT"
3914        );
3915        assert_eq!(v["pictures"][0]["image"]["dpi"], 300);
3916        assert_eq!(v["texts"][1]["prov"], serde_json::json!([]));
3917        assert_eq!(v["texts"][1]["content_layer"], "notes");
3918        assert_eq!(v["pages"]["1"]["size"]["width"], 9144000.0);
3919        assert_eq!(v["pages"]["1"]["page_no"], 1);
3920    }
3921
3922    /// docling-core's `validate_document` clamps every provenance box (and a
3923    /// one-page table's cell boxes) into its page — the state every
3924    /// `ConversionResult` leaves a document in, so the state docling's JSON
3925    /// shows. A box on a page the document does not describe is left alone.
3926    #[test]
3927    fn provenance_boxes_are_clamped_to_their_page() {
3928        let mut doc = DoclingDocument::new("t");
3929        doc.push(Node::PageInfo {
3930            page_no: 1,
3931            width: 10.0,
3932            height: 8.0,
3933        });
3934        doc.push(Node::Prov {
3935            page_no: 1,
3936            bbox: [-1.0, 2.0, 12.0, 9.5],
3937            charspan: [0, 1],
3938            bottom_left: false,
3939            seq: None,
3940            inner: Box::new(Node::Paragraph { text: "x".into() }),
3941        });
3942        let mut table = Table {
3943            rows: vec![vec!["a".into()]],
3944            ..Table::default()
3945        };
3946        table.cells = Some(vec![crate::TableCell {
3947            text: "a".into(),
3948            bbox: Some([1.0, 1.0, 11.0, 9.0]),
3949            start_row: 0,
3950            start_col: 0,
3951            row_span: 1,
3952            col_span: 1,
3953            column_header: false,
3954            row_header: false,
3955            row_section: false,
3956        }]);
3957        doc.push(Node::Prov {
3958            page_no: 1,
3959            bbox: [0.0, 0.0, 10.0, 8.0],
3960            charspan: [0, 0],
3961            bottom_left: false,
3962            seq: None,
3963            inner: Box::new(Node::Table(table)),
3964        });
3965        doc.push(Node::Prov {
3966            page_no: 7,
3967            bbox: [-5.0, 0.0, 50.0, 50.0],
3968            charspan: [0, 1],
3969            bottom_left: false,
3970            seq: None,
3971            inner: Box::new(Node::Paragraph { text: "y".into() }),
3972        });
3973        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3974        assert_eq!(
3975            v["texts"][0]["prov"][0]["bbox"],
3976            serde_json::json!({ "l": 0.0, "t": 2.0, "r": 10.0, "b": 8.0, "coord_origin": "TOPLEFT" })
3977        );
3978        let cell = &v["tables"][0]["data"]["table_cells"][0]["bbox"];
3979        assert_eq!(
3980            (cell["l"].as_f64(), cell["r"].as_f64(), cell["b"].as_f64()),
3981            (Some(1.0), Some(10.0), Some(8.0))
3982        );
3983        assert_eq!(v["tables"][0]["data"]["grid"][0][0]["bbox"]["r"], 10.0);
3984        assert_eq!(
3985            v["texts"][1]["prov"][0]["bbox"]["r"], 50.0,
3986            "page 7 is not described"
3987        );
3988    }
3989
3990    /// docling-core's `validate_misplaced_list_items`, as it re-homes list
3991    /// items outside a `list` group (#527) — the refs below are what
3992    /// docling-core 2.99 writes for the same document: the two consecutive
3993    /// items on the body share a group, each item in another group gets its
3994    /// own, the runs are handled last-first (new groups and re-added texts
3995    /// numbered in that order), and a well-placed item is left alone.
3996    #[test]
3997    fn misplaced_list_items_are_wrapped_like_docling_core() {
3998        use crate::tree::{ItemTree, ListMeta, TreeKind};
3999        let mut t = ItemTree::default();
4000        let li = |txt: &str| TreeKind::Text {
4001            label: "list_item".into(),
4002            text: txt.into(),
4003            orig: None,
4004            formatting: None,
4005            hyperlink: None,
4006            level: None,
4007            list: Some(ListMeta {
4008                enumerated: false,
4009                marker: "-".into(),
4010            }),
4011        };
4012        let group = |label: &str, name: &str| TreeKind::Group {
4013            label: label.into(),
4014            name: name.into(),
4015        };
4016        t.add(None, None, li("A"));
4017        t.add(None, None, li("B"));
4018        t.add(
4019            None,
4020            None,
4021            TreeKind::Text {
4022                label: "text".into(),
4023                text: "plain".into(),
4024                orig: None,
4025                formatting: None,
4026                hyperlink: None,
4027                level: None,
4028                list: None,
4029            },
4030        );
4031        let cell = t.add(None, None, group("unspecified", "cell"));
4032        t.add(Some(cell), None, li("C"));
4033        t.add(Some(cell), None, li("D"));
4034        let list = t.add(None, None, group("list", "list"));
4035        t.add(Some(list), None, li("E"));
4036        let doc = DoclingDocument {
4037            tree: Some(t),
4038            ..DoclingDocument::new("t")
4039        };
4040        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4041        let refs = |x: &Value| -> Vec<String> {
4042            x.as_array()
4043                .unwrap()
4044                .iter()
4045                .map(|r| r["$ref"].as_str().unwrap().to_string())
4046                .collect()
4047        };
4048        assert_eq!(
4049            refs(&v["body"]["children"]),
4050            ["#/groups/4", "#/texts/0", "#/groups/0", "#/groups/1"]
4051        );
4052        assert_eq!(
4053            refs(&v["groups"][0]["children"]),
4054            ["#/groups/3", "#/groups/2"]
4055        );
4056        for (g, name, kids) in [
4057            (2, "group", vec!["#/texts/2"]),
4058            (3, "group", vec!["#/texts/3"]),
4059            (4, "group", vec!["#/texts/4", "#/texts/5"]),
4060            (1, "list", vec!["#/texts/1"]),
4061        ] {
4062            assert_eq!(v["groups"][g]["label"], "list");
4063            assert_eq!(v["groups"][g]["name"], name);
4064            assert_eq!(refs(&v["groups"][g]["children"]), kids);
4065        }
4066        let texts: Vec<&str> = v["texts"]
4067            .as_array()
4068            .unwrap()
4069            .iter()
4070            .map(|t| t["text"].as_str().unwrap())
4071            .collect();
4072        assert_eq!(texts, ["plain", "E", "D", "C", "A", "B"]);
4073        assert_eq!(v["texts"][2]["parent"]["$ref"], "#/groups/2");
4074    }
4075
4076    /// A child the tree still lists after deleting it is left out instead
4077    /// of written as `"$ref": ""`, which docling-core rejects (#527).
4078    #[test]
4079    fn a_deleted_child_is_not_written_as_an_empty_ref() {
4080        use crate::tree::{ItemTree, TreeKind};
4081        let mut t = ItemTree::default();
4082        let text = |txt: &str| TreeKind::Text {
4083            label: "text".into(),
4084            text: txt.into(),
4085            orig: None,
4086            formatting: None,
4087            hyperlink: None,
4088            level: None,
4089            list: None,
4090        };
4091        let g = t.add(
4092            None,
4093            None,
4094            TreeKind::Group {
4095                label: "unspecified".into(),
4096                name: "g".into(),
4097            },
4098        );
4099        let gone = t.add(Some(g), None, text(""));
4100        t.add(Some(g), None, text("kept"));
4101        t.items[gone].deleted = true; // still in `g`'s children
4102        let doc = DoclingDocument {
4103            tree: Some(t),
4104            ..DoclingDocument::new("t")
4105        };
4106        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4107        assert_eq!(
4108            v["groups"][0]["children"],
4109            serde_json::json!([{"$ref": "#/texts/0"}])
4110        );
4111    }
4112
4113    #[test]
4114    fn a_backend_item_tree_is_written_verbatim() {
4115        use crate::tree::{Formatting, ItemTree, ListMeta, TreeKind};
4116        let mut t = ItemTree::default();
4117        let text = |label: &str, txt: &str| TreeKind::Text {
4118            label: label.into(),
4119            text: txt.into(),
4120            orig: None,
4121            formatting: None,
4122            hyperlink: None,
4123            level: None,
4124            list: None,
4125        };
4126        let title = t.add(None, Some(ContentLayer::Furniture), text("title", "Page"));
4127        let h = t.add(None, None, text("title", "Heading"));
4128        let group = t.add(
4129            Some(h),
4130            None,
4131            TreeKind::Group {
4132                label: "inline".into(),
4133                name: "group".into(),
4134            },
4135        );
4136        t.add(
4137            Some(group),
4138            None,
4139            TreeKind::Text {
4140                label: "text".into(),
4141                text: "bold".into(),
4142                orig: None,
4143                formatting: Some(Formatting {
4144                    bold: true,
4145                    ..Formatting::default()
4146                }),
4147                hyperlink: Some("https://example.com/".into()),
4148                level: None,
4149                list: None,
4150            },
4151        );
4152        t.add(
4153            Some(group),
4154            None,
4155            TreeKind::Code {
4156                text: "x = 1".into(),
4157                orig: None,
4158                language: Some("python".into()),
4159                formatting: None,
4160                hyperlink: None,
4161                captions: Vec::new(),
4162            },
4163        );
4164        let sub = t.add(
4165            Some(h),
4166            None,
4167            TreeKind::Text {
4168                label: "section_header".into(),
4169                text: "Sub".into(),
4170                orig: Some("Sub\u{2019}".into()),
4171                formatting: None,
4172                hyperlink: None,
4173                level: Some(1),
4174                list: None,
4175            },
4176        );
4177        let item = t.add(
4178            Some(sub),
4179            None,
4180            TreeKind::Text {
4181                label: "list_item".into(),
4182                text: "item".into(),
4183                orig: None,
4184                formatting: None,
4185                hyperlink: None,
4186                level: None,
4187                list: Some(ListMeta {
4188                    enumerated: true,
4189                    marker: "3.".into(),
4190                }),
4191            },
4192        );
4193        let _region = t.add(
4194            Some(sub),
4195            None,
4196            TreeKind::FieldRegion {
4197                items: vec![crate::FieldItem {
4198                    marker: None,
4199                    key: Some("Name".into()),
4200                    value: Some("Duck".into()),
4201                    value_kind: Some("read_only".into()),
4202                }],
4203            },
4204        );
4205        let table = t.add(
4206            Some(sub),
4207            None,
4208            TreeKind::Table {
4209                table: Table {
4210                    rows: vec![vec!["a  \n&lt;".into(), "b".into()]],
4211                    cells: Some(vec![
4212                        crate::TableCell {
4213                            text: "a  \n&lt;".into(),
4214                            bbox: None,
4215                            start_row: 0,
4216                            start_col: 0,
4217                            row_span: 3,
4218                            col_span: 1,
4219                            column_header: false,
4220                            row_header: true,
4221                            row_section: false,
4222                        },
4223                        crate::TableCell {
4224                            text: "b".into(),
4225                            bbox: None,
4226                            start_row: 0,
4227                            start_col: 1,
4228                            row_span: 1,
4229                            col_span: 1,
4230                            column_header: false,
4231                            row_header: false,
4232                            row_section: false,
4233                        },
4234                    ]),
4235                    ..Table::default()
4236                },
4237                rich_cells: vec![(0, 1, 0)], // patched below
4238                captions: Vec::new(),
4239            },
4240        );
4241        let cell_group = t.add(
4242            Some(table),
4243            None,
4244            TreeKind::Group {
4245                label: "unspecified".into(),
4246                name: "rich_cell_group_1_0_0".into(),
4247            },
4248        );
4249        if let TreeKind::Table { rich_cells, .. } = &mut t.items[table].kind {
4250            *rich_cells = vec![(0, 1, cell_group)];
4251        }
4252        let after = t.add(Some(sub), None, text("text", "after the region"));
4253        let _ = (title, after);
4254        // A list item belongs in a `list` group — one outside it would be
4255        // re-homed by `wrap_misplaced_list_items` (created last, so the
4256        // other groups keep their numbers).
4257        let list = t.add(
4258            Some(sub),
4259            None,
4260            TreeKind::Group {
4261                label: "list".into(),
4262                name: "list".into(),
4263            },
4264        );
4265        t.reparent(item, Some(list));
4266
4267        let doc = DoclingDocument {
4268            tree: Some(t),
4269            ..DoclingDocument::new("t")
4270        };
4271        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4272        // Creation order: Page, Heading, bold, x = 1, Sub, item, [Name, Duck], after.
4273        let texts: Vec<&str> = v["texts"]
4274            .as_array()
4275            .unwrap()
4276            .iter()
4277            .map(|t| t["text"].as_str().unwrap())
4278            .collect();
4279        assert_eq!(
4280            texts,
4281            [
4282                "Page",
4283                "Heading",
4284                "bold",
4285                "x = 1",
4286                "Sub",
4287                "item",
4288                "Name",
4289                "Duck",
4290                "after the region"
4291            ]
4292        );
4293        assert_eq!(
4294            v["body"]["children"],
4295            serde_json::json!([{"$ref": "#/texts/0"}, {"$ref": "#/texts/1"}])
4296        );
4297        assert_eq!(v["texts"][0]["content_layer"], "furniture");
4298        assert_eq!(
4299            v["texts"][1]["children"],
4300            serde_json::json!([{"$ref": "#/groups/0"}, {"$ref": "#/texts/4"}])
4301        );
4302        let bold = &v["texts"][2];
4303        assert_eq!(bold["parent"]["$ref"], "#/groups/0");
4304        let keys: Vec<&str> = bold
4305            .as_object()
4306            .unwrap()
4307            .keys()
4308            .map(String::as_str)
4309            .collect();
4310        assert_eq!(
4311            keys,
4312            [
4313                "self_ref",
4314                "parent",
4315                "children",
4316                "content_layer",
4317                "label",
4318                "prov",
4319                "orig",
4320                "text",
4321                "formatting",
4322                "hyperlink"
4323            ]
4324        );
4325        assert_eq!(
4326            bold["formatting"],
4327            serde_json::json!({"bold": true, "italic": false, "underline": false, "strikethrough": false, "script": "baseline"})
4328        );
4329        let code = &v["texts"][3];
4330        assert_eq!(code["label"], "code");
4331        assert_eq!(code["code_language"], "Python");
4332        let sub = &v["texts"][4];
4333        assert_eq!(sub["orig"], "Sub\u{2019}");
4334        assert_eq!(sub["level"], 1);
4335        let item = &v["texts"][5];
4336        let keys: Vec<&str> = item
4337            .as_object()
4338            .unwrap()
4339            .keys()
4340            .map(String::as_str)
4341            .collect();
4342        assert_eq!(
4343            keys,
4344            [
4345                "self_ref",
4346                "parent",
4347                "children",
4348                "content_layer",
4349                "label",
4350                "prov",
4351                "orig",
4352                "text",
4353                "enumerated",
4354                "marker"
4355            ]
4356        );
4357        assert_eq!(item["marker"], "3.");
4358        assert_eq!(v["texts"][7]["kind"], "read_only");
4359        assert_eq!(v["field_regions"][0]["parent"]["$ref"], "#/texts/4");
4360        let table = &v["tables"][0];
4361        assert_eq!(
4362            table["children"],
4363            serde_json::json!([{"$ref": "#/groups/1"}])
4364        );
4365        let cells = table["data"]["table_cells"].as_array().unwrap();
4366        assert_eq!(
4367            cells[0]["text"], "a  \n&lt;",
4368            "raw cell text is written verbatim"
4369        );
4370        assert_eq!(
4371            cells[0]["end_row_offset_idx"], 3,
4372            "declared spans are not clamped"
4373        );
4374        assert_eq!(cells[1]["ref"], serde_json::json!({"$ref": "#/groups/1"}));
4375        assert!(cells[0].get("ref").is_none());
4376        assert!(
4377            table["data"]["grid"][0][1].get("ref").is_none(),
4378            "the grid shows plain cells"
4379        );
4380        assert_eq!(v["groups"][1]["name"], "rich_cell_group_1_0_0");
4381    }
4382
4383    /// A comment section that links its note text rather than its group — the
4384    /// spreadsheet shape, where docling-core's `add_comment` appends the text
4385    /// item's ref to each target.
4386    #[test]
4387    fn a_comment_section_can_be_referenced_by_its_note_text() {
4388        let doc = DoclingDocument {
4389            name: "c".into(),
4390            nodes: vec![
4391                Node::Commented {
4392                    comments: vec![0],
4393                    inner: Box::new(Node::Paragraph {
4394                        text: "annotated".into(),
4395                    }),
4396                },
4397                Node::CommentSection {
4398                    name: "comment-Sheet1-A1".into(),
4399                    text: "[author: A]: note".into(),
4400                    refs_note_text: true,
4401                    grouped: true,
4402                },
4403            ],
4404            ..DoclingDocument::new("c")
4405        };
4406        let v = crate::json::to_json(&doc);
4407        assert_eq!(v["groups"][0]["name"], "comment-Sheet1-A1");
4408        assert_eq!(v["texts"][0]["comments"][0]["$ref"], "#/texts/1");
4409    }
4410
4411    /// A thread's messages are notes of one `comment_section` group, which is
4412    /// listed once among its parent's children however many notes it holds.
4413    #[test]
4414    fn a_comment_thread_is_one_child_of_its_parent() {
4415        let note = |text: &str| Node::CommentSection {
4416            name: "comment-Sheet1-F7".into(),
4417            text: text.into(),
4418            refs_note_text: true,
4419            grouped: true,
4420        };
4421        let doc = DoclingDocument {
4422            name: "c".into(),
4423            nodes: vec![note("[author: A]: first"), note("[author: B]: reply")],
4424            ..DoclingDocument::new("c")
4425        };
4426        let v = crate::json::to_json(&doc);
4427        assert_eq!(v["body"]["children"].as_array().unwrap().len(), 1);
4428        assert_eq!(v["groups"][0]["children"].as_array().unwrap().len(), 2);
4429    }
4430
4431    /// docx reviewer comments: a `comment_section` group on the notes layer
4432    /// holding the note text, and a `comments` back-ref on the annotated item —
4433    /// keyed between `prov` and `orig`, the slot docling emits it in.
4434    #[test]
4435    fn comment_sections_link_back_to_their_items() {
4436        let doc = DoclingDocument {
4437            name: "c".into(),
4438            nodes: vec![
4439                Node::Commented {
4440                    comments: vec![0],
4441                    inner: Box::new(Node::Paragraph {
4442                        text: "annotated".into(),
4443                    }),
4444                },
4445                Node::Paragraph {
4446                    text: "plain".into(),
4447                },
4448                Node::CommentSection {
4449                    name: "comment-7".into(),
4450                    text: "[time: t]: note".into(),
4451                    refs_note_text: false,
4452                    grouped: true,
4453                },
4454            ],
4455            ..DoclingDocument::new("c")
4456        };
4457        let v = crate::json::to_json(&doc);
4458        // The group is the comment section; its only child is the notes text.
4459        assert_eq!(v["groups"][0]["label"], "comment_section");
4460        assert_eq!(v["groups"][0]["name"], "comment-7");
4461        assert_eq!(v["groups"][0]["content_layer"], "notes");
4462        assert_eq!(v["groups"][0]["children"][0]["$ref"], "#/texts/2");
4463        assert_eq!(v["texts"][2]["content_layer"], "notes");
4464        // The annotated item points back at the group; the plain one has no key.
4465        assert_eq!(v["texts"][0]["comments"][0]["$ref"], "#/groups/0");
4466        assert!(v["texts"][1].get("comments").is_none());
4467        // docling's key order: … prov, comments, orig, text.
4468        let keys: Vec<&str> = v["texts"][0]
4469            .as_object()
4470            .unwrap()
4471            .keys()
4472            .map(String::as_str)
4473            .collect();
4474        assert_eq!(
4475            &keys[keys.len() - 4..],
4476            &["prov", "comments", "orig", "text"]
4477        );
4478    }
4479
4480    fn picture(caption: &str, caption_parent: CaptionParent) -> Node {
4481        Node::Picture {
4482            caption: Some(caption.into()),
4483            caption_href: None,
4484            image: None,
4485            classification: None,
4486            description: None,
4487            caption_parent,
4488            caption_location: None,
4489        }
4490    }
4491
4492    fn group(children: Vec<Node>) -> Node {
4493        Node::Group {
4494            label: "section".into(),
4495            name: None,
4496            layer: None,
4497            children,
4498        }
4499    }
4500
4501    fn refs(v: &Value) -> Vec<&str> {
4502        v.as_array()
4503            .unwrap()
4504            .iter()
4505            .map(|r| r["$ref"].as_str().unwrap())
4506            .collect()
4507    }
4508
4509    /// #390: a declarative backend's caption is docling's `add_text` default —
4510    /// a body child, appended as it is created — wherever the picture sits:
4511    /// ahead of a top-level picture, behind the top-level item enclosing a
4512    /// nested one. The picture references it either way and has no children.
4513    #[test]
4514    fn a_body_caption_follows_the_enclosing_top_level_item() {
4515        let mut doc = DoclingDocument::new("t");
4516        doc.push(picture("top", CaptionParent::Body));
4517        doc.push(group(vec![
4518            Node::Paragraph { text: "p".into() },
4519            picture("nested", CaptionParent::Body),
4520        ]));
4521        doc.push(Node::Paragraph {
4522            text: "after".into(),
4523        });
4524        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4525        assert_eq!(
4526            refs(&v["body"]["children"]),
4527            [
4528                "#/texts/0",
4529                "#/pictures/0",
4530                "#/groups/0",
4531                "#/texts/2",
4532                "#/texts/3"
4533            ]
4534        );
4535        assert_eq!(
4536            refs(&v["groups"][0]["children"]),
4537            ["#/texts/1", "#/pictures/1"]
4538        );
4539        for (cap, pic) in [(0, 0), (2, 1)] {
4540            assert_eq!(v["texts"][cap]["label"], "caption");
4541            assert_eq!(v["texts"][cap]["parent"]["$ref"], "#/body");
4542            assert_eq!(
4543                refs(&v["pictures"][pic]["captions"]),
4544                [format!("#/texts/{cap}")]
4545            );
4546            assert_eq!(v["pictures"][pic]["children"], serde_json::json!([]));
4547        }
4548    }
4549
4550    /// The PDF pipeline's caption is the picture's (or table's) own child,
4551    /// as docling attaches a layout caption.
4552    #[test]
4553    fn an_item_caption_is_the_items_first_child() {
4554        let mut doc = DoclingDocument::new("t");
4555        doc.push(picture("fig", CaptionParent::Item));
4556        doc.push(Node::Table(Table {
4557            rows: vec![vec!["a".into()]],
4558            caption: Some("tab".into()),
4559            caption_parent: CaptionParent::Item,
4560            ..Table::default()
4561        }));
4562        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4563        assert_eq!(refs(&v["body"]["children"]), ["#/pictures/0", "#/tables/0"]);
4564        assert_eq!(v["texts"][0]["parent"]["$ref"], "#/pictures/0");
4565        assert_eq!(refs(&v["pictures"][0]["children"]), ["#/texts/0"]);
4566        assert_eq!(refs(&v["pictures"][0]["captions"]), ["#/texts/0"]);
4567        assert_eq!(v["texts"][1]["parent"]["$ref"], "#/tables/0");
4568        assert_eq!(refs(&v["tables"][0]["children"]), ["#/texts/1"]);
4569        assert_eq!(refs(&v["tables"][0]["captions"]), ["#/texts/1"]);
4570    }
4571
4572    /// A PDF picture's contained text (`Node::PictureChildren`) is written as
4573    /// docling's `_add_child_elements` writes it: items parented to the
4574    /// picture, after its caption in the picture's `children`, never in the
4575    /// body; a list item opens its own list group under the picture. The
4576    /// Markdown and the chunker's refs are unaffected.
4577    #[test]
4578    fn picture_children_hang_off_the_picture_after_its_caption() {
4579        let mut doc = DoclingDocument::new("t");
4580        doc.push(picture("fig", CaptionParent::Item));
4581        doc.push(Node::PictureChildren(vec![
4582            Node::Heading {
4583                level: 2,
4584                text: "in-figure title".into(),
4585            },
4586            Node::Paragraph {
4587                text: "axis label".into(),
4588            },
4589            Node::ListItem {
4590                ordered: false,
4591                number: 0,
4592                first_in_list: true,
4593                text: "callout".into(),
4594                level: 0,
4595                marker: None,
4596                location: None,
4597                dclx: None,
4598                href: None,
4599                layer: None,
4600            },
4601        ]));
4602        doc.push(Node::Paragraph {
4603            text: "after".into(),
4604        });
4605        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4606        assert_eq!(refs(&v["body"]["children"]), ["#/pictures/0", "#/texts/4"]);
4607        assert_eq!(
4608            refs(&v["pictures"][0]["children"]),
4609            ["#/texts/0", "#/texts/1", "#/texts/2", "#/groups/0"]
4610        );
4611        assert_eq!(refs(&v["pictures"][0]["captions"]), ["#/texts/0"]);
4612        assert_eq!(v["texts"][1]["label"], "section_header");
4613        assert_eq!(v["texts"][2]["label"], "text");
4614        for t in 1..=2 {
4615            assert_eq!(v["texts"][t]["parent"]["$ref"], "#/pictures/0");
4616            assert_eq!(v["texts"][t]["content_layer"], "body");
4617        }
4618        assert_eq!(v["groups"][0]["parent"]["$ref"], "#/pictures/0");
4619        assert_eq!(v["texts"][3]["parent"]["$ref"], "#/groups/0");
4620        let md = doc.export_to_markdown();
4621        assert!(
4622            !md.contains("axis label") && !md.contains("callout"),
4623            "{md}"
4624        );
4625        assert!(md.contains("after"), "{md}");
4626    }
4627
4628    /// A container caption sits beside its item under the item's parent —
4629    /// ahead of it (an office chart's title) or behind it (an HTML
4630    /// `<figure>`'s table, whose figcaption docling adds after the table).
4631    #[test]
4632    fn a_container_caption_is_the_items_sibling() {
4633        let mut doc = DoclingDocument::new("t");
4634        doc.push(group(vec![
4635            picture("chart", CaptionParent::Container),
4636            Node::Table(Table {
4637                rows: vec![vec!["a".into()]],
4638                caption: Some("figcaption".into()),
4639                caption_parent: CaptionParent::ContainerAfter,
4640                ..Table::default()
4641            }),
4642        ]));
4643        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4644        assert_eq!(refs(&v["body"]["children"]), ["#/groups/0"]);
4645        assert_eq!(
4646            refs(&v["groups"][0]["children"]),
4647            ["#/texts/0", "#/pictures/0", "#/tables/0", "#/texts/1"]
4648        );
4649        assert_eq!(v["texts"][0]["parent"]["$ref"], "#/groups/0");
4650        assert_eq!(v["texts"][1]["parent"]["$ref"], "#/groups/0");
4651        assert_eq!(v["pictures"][0]["children"], serde_json::json!([]));
4652        assert_eq!(v["tables"][0]["children"], serde_json::json!([]));
4653    }
4654
4655    /// A PDF footnote (#620 follow-up): the JSON keeps docling's
4656    /// `footnote` label, the raw text and the link as `hyperlink`; the
4657    /// Markdown still wraps the whole item as `[text](uri)`, and the plain
4658    /// text drops the link like docling-core's `export_to_text`.
4659    #[test]
4660    fn a_labeled_text_keeps_its_label_and_hyperlink_out_of_the_text() {
4661        let mut doc = DoclingDocument::new("t");
4662        doc.push(Node::LabeledText {
4663            label: "footnote".into(),
4664            text: "1 https://example.com/a\\_b".into(),
4665            href: Some("https://example.com/a_b".into()),
4666        });
4667        doc.push(Node::LabeledText {
4668            label: "footnote".into(),
4669            text: "© 2022 the authors".into(),
4670            href: None,
4671        });
4672        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4673        let t = &v["texts"][0];
4674        assert_eq!(t["label"], "footnote");
4675        assert_eq!(t["text"], "1 https://example.com/a_b");
4676        assert_eq!(t["orig"], "1 https://example.com/a_b");
4677        assert_eq!(t["hyperlink"], "https://example.com/a_b");
4678        assert_eq!(v["texts"][1]["label"], "footnote");
4679        assert!(v["texts"][1].get("hyperlink").is_none());
4680        assert_eq!(
4681            doc.export_to_markdown(),
4682            "[1 https://example.com/a\\_b](https://example.com/a_b)\n\n© 2022 the authors\n"
4683        );
4684        assert_eq!(
4685            doc.export_to_text(),
4686            "1 https://example.com/a_b\n\n© 2022 the authors"
4687        );
4688    }
4689}