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                // Without `preserve-order` the map is sorted and the position
1638                // is moot (#970); `remove` is the only removal it has.
1639                #[cfg(feature = "preserve-order")]
1640                obj.shift_remove(k);
1641                #[cfg(not(feature = "preserve-order"))]
1642                obj.remove(k);
1643            }
1644            obj.insert("comments".into(), Value::Array(comment_refs));
1645            for (k, v) in tail {
1646                obj.insert(k, v);
1647            }
1648        }
1649    }
1650
1651    /// The stored JSON object a `#/texts/N`-style self-ref points at.
1652    fn item_mut(&mut self, self_ref: &str) -> Option<&mut Value> {
1653        let idx = ref_index(self_ref)?;
1654        if self_ref.starts_with("#/texts/") {
1655            return self.texts.get_mut(idx).map(|item| item.value_mut(idx));
1656        }
1657        if self_ref.starts_with("#/tables/") {
1658            return self.tables.get_mut(idx).map(|t| &mut t.item);
1659        }
1660        let bucket = if self_ref.starts_with("#/pictures/") {
1661            &mut self.pictures
1662        } else if self_ref.starts_with("#/groups/") {
1663            &mut self.groups
1664        } else {
1665            return None;
1666        };
1667        bucket.get_mut(idx)
1668    }
1669
1670    /// Serialize a backend-built [`ItemTree`](crate::tree::ItemTree): every
1671    /// item in creation order into its bucket, with the parent / children /
1672    /// layer the tree recorded. Returns the body's `children` refs.
1673    fn write_tree(&mut self, tree: &crate::tree::ItemTree) -> Vec<Value> {
1674        use crate::tree::TreeKind;
1675        // Every item's `self_ref` first: children may be listed before they
1676        // are written (a rich cell's group is created after its content).
1677        let mut refs: Vec<String> = Vec::with_capacity(tree.items.len());
1678        let (mut nt, mut ng, mut ntb, mut np, mut nf, mut nk) = (0, 0, 0, 0, 0, 0);
1679        for item in &tree.items {
1680            if item.deleted {
1681                refs.push(String::new());
1682                continue;
1683            }
1684            let r = match &item.kind {
1685                TreeKind::Text { .. } | TreeKind::Code { .. } => {
1686                    nt += 1;
1687                    format!("#/texts/{}", nt - 1)
1688                }
1689                TreeKind::Group { .. } => {
1690                    ng += 1;
1691                    format!("#/groups/{}", ng - 1)
1692                }
1693                TreeKind::Table { .. } => {
1694                    ntb += 1;
1695                    format!("#/tables/{}", ntb - 1)
1696                }
1697                TreeKind::Picture { .. } => {
1698                    np += 1;
1699                    format!("#/pictures/{}", np - 1)
1700                }
1701                TreeKind::FieldRegion { items } => {
1702                    // A region's marker / key / value parts are text items
1703                    // too, numbered where docling creates them.
1704                    nt += items
1705                        .iter()
1706                        .map(|i| {
1707                            [&i.marker, &i.key, &i.value]
1708                                .iter()
1709                                .filter(|p| p.is_some())
1710                                .count()
1711                        })
1712                        .sum::<usize>();
1713                    nf += 1;
1714                    format!("#/field_regions/{}", nf - 1)
1715                }
1716                TreeKind::KeyValueGraph { .. } => {
1717                    nk += 1;
1718                    format!("#/key_value_items/{}", nk - 1)
1719                }
1720            };
1721            refs.push(r);
1722        }
1723        let ref_of = |id: usize| ref_value(refs[id].as_str());
1724        for (id, item) in tree.items.iter().enumerate() {
1725            if item.deleted {
1726                continue;
1727            }
1728            let parent = item.parent.map_or("#/body", |p| refs[p].as_str());
1729            // A deleted item has no ref; one still listed as a child (a stale
1730            // backend link) is left out rather than written as `"$ref": ""`,
1731            // which docling-core rejects on load (#527).
1732            let children: Vec<Value> = item
1733                .children
1734                .iter()
1735                .filter(|&&c| !tree.items[c].deleted)
1736                .map(|&c| ref_of(c))
1737                .collect();
1738            let layer = item.layer.map_or("body", |l| l.value());
1739            // The item's own provenance, consumed by the writer below
1740            // (`take_prov`); an item without one writes `prov: []`.
1741            self.pending_exact = item.prov.as_ref().map(ExactProv::from);
1742            let self_ref = match &item.kind {
1743                TreeKind::Text {
1744                    label,
1745                    text,
1746                    orig,
1747                    formatting,
1748                    hyperlink,
1749                    level,
1750                    list,
1751                } => {
1752                    // docling's field order: …, text, formatting, hyperlink,
1753                    // then the subclass fields (`level`; `enumerated`, `marker`).
1754                    let mut tail = serde_json::Map::new();
1755                    if let Some(f) = formatting {
1756                        tail.insert("formatting".into(), formatting_json(f));
1757                    }
1758                    if let Some(h) = hyperlink {
1759                        tail.insert("hyperlink".into(), json!(h));
1760                    }
1761                    if let Some(l) = level {
1762                        tail.insert("level".into(), json!(l));
1763                    }
1764                    if let Some(l) = list {
1765                        tail.insert("enumerated".into(), json!(l.enumerated));
1766                        tail.insert("marker".into(), json!(l.marker));
1767                    }
1768                    let r = format!("#/texts/{}", self.texts.len());
1769                    let prov = self.take_prov(text.chars().count());
1770                    let mut item_json = json!({
1771                        "self_ref": r,
1772                        "parent": { "$ref": parent },
1773                        "children": children,
1774                        "content_layer": layer,
1775                        "label": label,
1776                        "prov": prov,
1777                    });
1778                    // docling's `comments` back-refs sit between `prov` and
1779                    // `orig`, and are written only when set.
1780                    if !item.comments.is_empty() {
1781                        item_json["comments"] =
1782                            Value::Array(item.comments.iter().map(|&c| ref_of(c)).collect());
1783                    }
1784                    // `DocItem.source`, likewise only when set: a WebVTT
1785                    // cue's `TrackSource`, whose `None` fields are omitted.
1786                    if let Some(track) = &item.source {
1787                        item_json["source"] = json!([track_json(track)]);
1788                    }
1789                    merge(
1790                        &mut item_json,
1791                        json!({
1792                            "orig": orig.as_deref().unwrap_or(text),
1793                            "text": text,
1794                        }),
1795                    );
1796                    merge(&mut item_json, Value::Object(tail));
1797                    if self.note_keys {
1798                        if !item.notes.is_empty() {
1799                            item_json["_notes"] = Value::Array(
1800                                item.notes
1801                                    .iter()
1802                                    .map(|n| json!([n.offset, n.text]))
1803                                    .collect(),
1804                            );
1805                        }
1806                        if item.note_body {
1807                            item_json["_note_body"] = json!(true);
1808                        }
1809                        if !item.anchors.is_empty() {
1810                            item_json["_anchors"] = json!(item.anchors);
1811                        }
1812                        if let Some(number) = &item.number {
1813                            item_json["_number"] = json!(number);
1814                        }
1815                        if let Some(rev) = &item.revision {
1816                            let mut r = serde_json::Map::new();
1817                            r.insert("kind".into(), json!(rev.kind.as_str()));
1818                            if let Some(a) = &rev.author {
1819                                r.insert("author".into(), json!(a));
1820                            }
1821                            if let Some(d) = &rev.date {
1822                                r.insert("date".into(), json!(d));
1823                            }
1824                            item_json["_revision"] = Value::Object(r);
1825                        }
1826                    }
1827                    self.texts.push(Item::json(item_json));
1828                    r
1829                }
1830                TreeKind::Code {
1831                    text,
1832                    orig,
1833                    language,
1834                    formatting,
1835                    hyperlink,
1836                    captions,
1837                } => {
1838                    let r = format!("#/texts/{}", self.texts.len());
1839                    let prov = self.take_prov(text.chars().count());
1840                    let mut item_json = json!({
1841                        "self_ref": r,
1842                        "parent": { "$ref": parent },
1843                        "children": children,
1844                        "content_layer": layer,
1845                        "label": "code",
1846                        "prov": prov,
1847                    });
1848                    if !item.comments.is_empty() {
1849                        item_json["comments"] =
1850                            Value::Array(item.comments.iter().map(|&c| ref_of(c)).collect());
1851                    }
1852                    merge(
1853                        &mut item_json,
1854                        json!({
1855                            "orig": orig.as_deref().unwrap_or(text),
1856                            "text": text,
1857                        }),
1858                    );
1859                    if let Some(f) = formatting {
1860                        item_json["formatting"] = formatting_json(f);
1861                    }
1862                    if let Some(h) = hyperlink {
1863                        item_json["hyperlink"] = json!(h);
1864                    }
1865                    merge(
1866                        &mut item_json,
1867                        json!({
1868                            "captions": captions.iter().map(|&c| ref_of(c)).collect::<Vec<_>>(),
1869                            "references": [],
1870                            "footnotes": [],
1871                            "code_language": code_language(language.as_deref()),
1872                        }),
1873                    );
1874                    self.texts.push(Item::json(item_json));
1875                    r
1876                }
1877                TreeKind::Group { label, name } => {
1878                    self.pending_exact = None;
1879                    let r = format!("#/groups/{}", self.groups.len());
1880                    self.groups.push(json!({
1881                        "self_ref": r,
1882                        "parent": { "$ref": parent },
1883                        "children": children,
1884                        "content_layer": layer,
1885                        "name": name,
1886                        "label": label,
1887                    }));
1888                    r
1889                }
1890                TreeKind::Table {
1891                    table,
1892                    rich_cells,
1893                    captions,
1894                } => {
1895                    // docling's raw cell text: nothing to unescape or strip.
1896                    let r = self.add_table_with(table, parent, true);
1897                    let idx = ref_index(&r).expect("table ref");
1898                    let t = &mut self.tables[idx];
1899                    t.item["children"] = Value::Array(children);
1900                    t.item["content_layer"] = json!(layer);
1901                    t.item["captions"] =
1902                        Value::Array(captions.iter().map(|&c| ref_of(c)).collect());
1903                    // A `RichTableCell` is the plain cell plus a `ref` to the
1904                    // group holding its content — on `table_cells` only; the
1905                    // derived `grid` shows plain cells.
1906                    for &(row, col, group) in rich_cells {
1907                        let cell_ref = ref_of(group);
1908                        for c in t.data.cells.iter_mut() {
1909                            if c.start_row == row && c.start_col == col {
1910                                c.cell_ref = Some(Box::new(cell_ref.clone()));
1911                            }
1912                        }
1913                    }
1914                    r
1915                }
1916                TreeKind::Picture {
1917                    captions,
1918                    image,
1919                    classification,
1920                    extra_classes,
1921                    description,
1922                    confidence,
1923                    chart,
1924                    dpi,
1925                } => {
1926                    // A chart's meta: the kind as the one classification
1927                    // prediction (pydantic's field order puts `confidence`
1928                    // first when present), then the reconstructed data grid
1929                    // (#405).
1930                    let mut meta = classification.as_ref().map(|c| {
1931                        let mut pred = serde_json::Map::new();
1932                        if let Some(conf) = confidence {
1933                            pred.insert("confidence".into(), json!(conf));
1934                        }
1935                        pred.insert("class_name".into(), json!(c));
1936                        let mut preds = vec![Value::Object(pred)];
1937                        preds.extend(extra_classes.iter().map(|c| json!({ "class_name": c })));
1938                        json!({ "classification": { "predictions": preds } })
1939                    });
1940                    if let (Some(m), Some(t)) = (meta.as_mut(), chart) {
1941                        if !t.rows.is_empty() {
1942                            m["tabular_chart"] =
1943                                object([("chart_data", table_data(t).into_value())]);
1944                        }
1945                    }
1946                    // The OCR description (#645) goes first in the meta —
1947                    // `PictureMeta` field order — and as the annotation the
1948                    // flat node writes (see `description_meta`).
1949                    if let Some(desc) = description {
1950                        let mut d = description_meta(desc);
1951                        let mut merged = Map::new();
1952                        merged.insert("description".into(), d["description"].take());
1953                        if let Some(Value::Object(rest)) = meta {
1954                            merged.extend(rest);
1955                        }
1956                        merged.insert("annotations".into(), d["annotations"].take());
1957                        meta = Some(Value::Object(merged));
1958                    }
1959                    // The source of a picture no engine rendered (a LaTeX
1960                    // `tikzpicture`): `PictureMeta.code`.
1961                    if let Some((text, language)) = &item.code_meta {
1962                        let code = json!({ "text": text, "language": language });
1963                        match meta.as_mut() {
1964                            Some(Value::Object(m)) => {
1965                                m.insert("code".into(), code);
1966                            }
1967                            _ => meta = Some(json!({ "code": code })),
1968                        }
1969                    }
1970                    let prov = self.take_prov(0);
1971                    let r = self.push_picture(
1972                        prov,
1973                        captions.iter().map(|&c| ref_of(c)).collect(),
1974                        children,
1975                        image.as_ref(),
1976                        meta,
1977                        parent,
1978                    );
1979                    if let Some(idx) = ref_index(&r) {
1980                        self.pictures[idx]["content_layer"] = json!(layer);
1981                        // The image's dpi is the file's when the backend read
1982                        // it (python-pptx does); the default 72 otherwise.
1983                        if let (Some(dpi), Some(img)) = (dpi, self.pictures[idx].get_mut("image")) {
1984                            img["dpi"] = json!(dpi);
1985                        }
1986                    }
1987                    r
1988                }
1989                TreeKind::FieldRegion { items } => {
1990                    self.pending_exact = None;
1991                    let r = self.add_field_region(items, parent);
1992                    if let Some(region) = self.field_regions.last_mut() {
1993                        region["content_layer"] = json!(layer);
1994                    }
1995                    r
1996                }
1997                TreeKind::KeyValueGraph { cells, links } => {
1998                    self.pending_exact = None;
1999                    let r = self.add_key_value_graph(cells, links, parent);
2000                    if let Some(item) = self.key_value_items.last_mut() {
2001                        item["content_layer"] = json!(layer);
2002                    }
2003                    r
2004                }
2005            };
2006            debug_assert_eq!(self_ref, refs[id], "tree item {id} numbered out of order");
2007        }
2008        tree.body
2009            .iter()
2010            .filter(|&&c| !tree.items[c].deleted)
2011            .map(|&c| ref_of(c))
2012            .collect()
2013    }
2014
2015    fn add_node(&mut self, node: &Node, parent: &str) -> Option<String> {
2016        match node {
2017            Node::Heading { level: 1, text } => {
2018                Some(self.add_text("title", text, parent, json!({})))
2019            }
2020            Node::Heading { level, text } => Some(self.add_text(
2021                "section_header",
2022                text,
2023                parent,
2024                json!({ "level": level.saturating_sub(1) }),
2025            )),
2026            Node::Caption { text, href } => {
2027                let extra = match href {
2028                    Some(url) => json!({ "hyperlink": url }),
2029                    None => json!({}),
2030                };
2031                Some(self.add_text("caption", text, parent, extra))
2032            }
2033            // A PDF footnote: docling's own label, and its link as the item's
2034            // `hyperlink` rather than Markdown baked into the text.
2035            Node::LabeledText { label, text, href } => {
2036                let extra = match href {
2037                    Some(url) => json!({ "hyperlink": url }),
2038                    None => json!({}),
2039                };
2040                Some(self.add_text(label, text, parent, extra))
2041            }
2042            Node::Paragraph { text } | Node::ListText { text, .. } => {
2043                // A whole-paragraph display equation is a formula item (docling
2044                // wraps it in `$$…$$` and, unlike a text item, never escapes it).
2045                let t = text.trim();
2046                match t.strip_prefix("$$").and_then(|s| s.strip_suffix("$$")) {
2047                    Some(inner) if !inner.is_empty() => Some(self.add_formula(inner, parent)),
2048                    _ => Some(self.add_text("text", text, parent, json!({}))),
2049                }
2050            }
2051            Node::CheckboxItem { checked, text } => {
2052                // docling's checkbox item: the `checkbox_selected` /
2053                // `checkbox_unselected` label carries the state and the text
2054                // is the bare option label (right_to_left_03's `خير`,
2055                // docx_checkboxes' `Orange juice`). The `- [x]` task-list
2056                // marker is Markdown's rendering of it, not item text (#609).
2057                let label = if *checked {
2058                    "checkbox_selected"
2059                } else {
2060                    "checkbox_unselected"
2061                };
2062                Some(self.add_text(label, text, parent, json!({})))
2063            }
2064            Node::Code {
2065                language,
2066                text,
2067                orig,
2068                ..
2069            } => Some(self.add_code(text, language.as_deref(), orig.as_deref(), parent)),
2070            // A CodeFormula-decoded display formula: `text` carries the LaTeX,
2071            // `orig` the raw glyph extraction (docling's enriched shape).
2072            Node::Formula {
2073                latex,
2074                orig,
2075                location,
2076            } => {
2077                self.adopt_loc(*location);
2078                Some(self.add_formula_item(latex, orig, parent))
2079            }
2080            // docling's notes-layer `comment_section` group holding the
2081            // comment's text item. What the annotated items point at differs
2082            // upstream: the docx backend links the group (so a comment's
2083            // replies group together), everything going through
2084            // docling-core's `add_comment` links the note text itself.
2085            Node::CommentSection {
2086                name,
2087                text,
2088                refs_note_text,
2089                grouped,
2090            } => {
2091                if !*grouped {
2092                    // docling-core's bare `add_comment`: the note text sits
2093                    // directly under the parent and is what the back-refs
2094                    // point at.
2095                    let child =
2096                        self.add_text("text", text, parent, json!({ "content_layer": "notes" }));
2097                    self.comment_groups.push(child.clone());
2098                    return Some(child);
2099                }
2100                if let Some((_, self_ref)) = self
2101                    .last_comment_section
2102                    .as_ref()
2103                    .filter(|(n, _)| n == name)
2104                    .cloned()
2105                {
2106                    // Another message of the same thread: a further note in
2107                    // the group already open for this cell.
2108                    let child =
2109                        self.add_text("text", text, &self_ref, json!({ "content_layer": "notes" }));
2110                    if let Some(children) =
2111                        self.groups[group_index(&self_ref)]["children"].as_array_mut()
2112                    {
2113                        children.push(ref_value(child.as_str()));
2114                    }
2115                    self.comment_groups.push(if *refs_note_text {
2116                        child
2117                    } else {
2118                        self_ref.clone()
2119                    });
2120                    // The group is already its parent's child: listing it
2121                    // again put a thread's group in the body once per message.
2122                    return None;
2123                }
2124                let self_ref = format!("#/groups/{}", self.groups.len());
2125                self.groups.push(Value::Null);
2126                let child =
2127                    self.add_text("text", text, &self_ref, json!({ "content_layer": "notes" }));
2128                self.groups[group_index(&self_ref)] = json!({
2129                    "self_ref": self_ref,
2130                    "parent": { "$ref": parent },
2131                    "children": [{ "$ref": child }],
2132                    "content_layer": "notes",
2133                    "name": name,
2134                    "label": "comment_section",
2135                });
2136                self.last_comment_section = Some((name.clone(), self_ref.clone()));
2137                self.comment_groups.push(if *refs_note_text {
2138                    child
2139                } else {
2140                    self_ref.clone()
2141                });
2142                Some(self_ref)
2143            }
2144            // The annotation itself is a cross-reference: emit the item, then
2145            // remember it so the group refs can be filled in at the end.
2146            Node::Commented { comments, inner } => {
2147                let item = self.add_node(inner, parent)?;
2148                if !comments.is_empty() {
2149                    self.pending_comments.push((item.clone(), comments.clone()));
2150                }
2151                Some(item)
2152            }
2153            Node::Table(t) => Some(self.add_table(t, parent)),
2154            Node::Picture {
2155                caption,
2156                caption_href,
2157                image,
2158                classification,
2159                description,
2160                caption_parent,
2161                caption_location,
2162            } => Some(self.add_picture(
2163                caption.as_deref(),
2164                caption_href.as_deref(),
2165                image.as_ref(),
2166                picture_meta(classification.as_deref(), description.as_ref()),
2167                parent,
2168                (*caption_parent, *caption_location),
2169            )),
2170            // A chart is a picture item in the JSON with docling's chart
2171            // meta — `classification` (the chart kind, as the one prediction)
2172            // and `tabular_chart.chart_data`, the series reconstructed as a
2173            // `TableData` (#405) — and no image payload.
2174            Node::Chart {
2175                kind,
2176                table,
2177                caption,
2178                location,
2179            } => {
2180                self.adopt_loc(*location);
2181                let mut meta = json!({
2182                    "classification": { "predictions": [{ "class_name": kind }] },
2183                });
2184                if !table.rows.is_empty() {
2185                    meta["tabular_chart"] =
2186                        object([("chart_data", table_data(table).into_value())]);
2187                }
2188                // docling's office backends add the chart's title as a caption
2189                // item of the *container* (the sheet group, the slide), listed
2190                // before the picture that references it, with the chart's own
2191                // box and a charspan over the caption text — not as a child
2192                // of the picture, which is where a PDF caption lives.
2193                let mut captions = Vec::new();
2194                if let Some(cap) = caption.as_deref().filter(|c| !c.is_empty()) {
2195                    let prov = self.prov_slot(unescape_text(cap).chars().count(), true);
2196                    let cap_ref = self.add_text_with("caption", cap, parent, json!({}), prov);
2197                    self.pending_siblings.push(ref_value(cap_ref.as_str()));
2198                    captions.push(ref_value(cap_ref));
2199                }
2200                let prov = self.take_prov(0);
2201                Some(self.push_picture(prov, captions, Vec::new(), None, Some(meta), parent))
2202            }
2203            // A DocLang-only node is omitted from the JSON body.
2204            Node::DoclangOnly(_) => None,
2205            Node::Group {
2206                label,
2207                name,
2208                layer,
2209                children,
2210            } => Some(self.add_group(label, name.as_deref(), *layer, children, parent)),
2211            Node::FieldRegion { items } => Some(self.add_field_region(items, parent)),
2212            Node::KeyValueGraph { cells, links } => {
2213                Some(self.add_key_value_graph(cells, links, parent))
2214            }
2215            // A rich inline group is a text item over its Markdown text; the
2216            // structured runs are DocLang-only, so the JSON matches a paragraph.
2217            Node::InlineGroup { md_text, .. } => {
2218                Some(self.add_text("text", md_text, parent, json!({})))
2219            }
2220            // A plain-text backend dump is a single text item over the file body.
2221            Node::TextDump(text) => Some(self.add_text("text", text, parent, json!({}))),
2222            // Speaker notes are content a deck carries, and docling puts them
2223            // in the JSON on their own layer, so a consumer reading only JSON
2224            // can pick them (#402). Page furniture stays out of the flat
2225            // path; a backend that builds docling's item tree (HTML) puts its
2226            // furniture-layer items in the JSON through `write_tree`.
2227            Node::Furniture {
2228                layer: ContentLayer::Notes,
2229                inner,
2230            } => {
2231                let item = self.add_node(inner, parent)?;
2232                self.set_layer(&item, "notes");
2233                Some(item)
2234            }
2235            Node::Furniture { .. } => None,
2236            // PDF page headers and footers: docling writes them as body-parented
2237            // `page_header`/`page_footer` text items on the furniture layer, so a
2238            // JSON consumer can read running headers (printed page ids, dates).
2239            Node::PageFurniture {
2240                footer,
2241                location,
2242                text,
2243            } => {
2244                if self.cur_page > 0 {
2245                    self.pending_loc = Some(*location);
2246                }
2247                let label = if *footer {
2248                    "page_footer"
2249                } else {
2250                    "page_header"
2251                };
2252                let item = self.add_text(label, text, parent, json!({}));
2253                self.pending_loc = None;
2254                self.set_layer(&item, "furniture");
2255                Some(item)
2256            }
2257            // A labelled furniture paragraph (a `.doc` header / footer or
2258            // note body, #535): the item docling's office backends write.
2259            Node::FurnitureText { label, text } => {
2260                let item = self.add_text(label, text, parent, json!({}));
2261                self.set_layer(&item, "furniture");
2262                Some(item)
2263            }
2264            // A PDF picture's contained text (docling's `_add_child_elements`):
2265            // items parented to the picture just written, listed after its
2266            // caption in that picture's `children`.
2267            Node::PictureChildren(children) => {
2268                let pic = self.pictures.len().checked_sub(1)?;
2269                let pic_ref = format!("#/pictures/{pic}");
2270                let refs = self.walk_into(children, &pic_ref);
2271                if let Some(list) = self.pictures[pic]["children"].as_array_mut() {
2272                    list.extend(refs.into_iter().map(Child::into_value));
2273                }
2274                None
2275            }
2276            // A location wrapper turns into the wrapped item's `prov` entry —
2277            // but only on pages the PDF paths described with a PageInfo marker
2278            // (other geometry-bearing backends, e.g. PPTX shapes, keep their
2279            // pre-#171 provenance-less JSON until they emit markers too).
2280            Node::Located { location, inner } => {
2281                if self.cur_page > 0 {
2282                    self.pending_loc = Some(*location);
2283                }
2284                let r = self.add_node(inner, parent);
2285                self.pending_loc = None;
2286                r
2287            }
2288            Node::Anchor { id } => {
2289                self.pending_anchors.push(id.clone());
2290                None
2291            }
2292            Node::Track { track, cue, inner } => {
2293                self.pending_track = Some((track.clone(), cue.clone()));
2294                let r = self.add_node(inner, parent);
2295                self.pending_track = None;
2296                r
2297            }
2298            Node::Prov {
2299                page_no,
2300                bbox,
2301                charspan,
2302                bottom_left,
2303                inner,
2304                ..
2305            } => {
2306                self.pending_exact = Some(ExactProv {
2307                    page_no: *page_no,
2308                    bbox: bbox.map(f64::from),
2309                    bottom_left: *bottom_left,
2310                    charspan: *charspan,
2311                });
2312                let r = self.add_node(inner, parent);
2313                self.pending_exact = None;
2314                r
2315            }
2316            // Page breaks are DocLang-only; docling omits them from the JSON body.
2317            Node::PageBreak => None,
2318            // The page marker: record the page's number and size for the
2319            // `pages` map, and denormalize every following location against it.
2320            Node::PageInfo {
2321                page_no,
2322                width,
2323                height,
2324            } => {
2325                self.cur_page = *page_no;
2326                self.cur_w = *width as f64;
2327                self.cur_h = *height as f64;
2328                if *page_no > 0 {
2329                    self.pages.push((*page_no, self.cur_w, self.cur_h));
2330                }
2331                None
2332            }
2333            // Handled by `add_list` in `walk`.
2334            Node::ListItem { .. } => None,
2335        }
2336    }
2337
2338    /// A form key-value region: `field_regions/N` holds the region, each field is
2339    /// a `field_items/M` whose children are its `marker` / `field_key` /
2340    /// `field_value` texts (absent parts are simply omitted).
2341    fn add_field_region(&mut self, items: &[crate::FieldItem], parent: &str) -> String {
2342        let self_ref = format!("#/field_regions/{}", self.field_regions.len());
2343        self.field_regions.push(Value::Null);
2344        let region_index = self.field_regions.len() - 1;
2345        let mut item_refs = Vec::new();
2346        for item in items {
2347            item_refs.push(ref_value(self.add_field_item(item, &self_ref)));
2348        }
2349        self.field_regions[region_index] = json!({
2350            "self_ref": self_ref,
2351            "parent": { "$ref": parent },
2352            "children": item_refs,
2353            "content_layer": "body",
2354            "label": "field_region",
2355            "prov": [],
2356        });
2357        self_ref
2358    }
2359
2360    /// A `KeyValueItem`: docling's `GraphData` written cell for cell and link
2361    /// for link (`key_value_items/N`), the item itself childless and without
2362    /// provenance, the way the XBRL backend creates it.
2363    fn add_key_value_graph(
2364        &mut self,
2365        cells: &[crate::GraphCell],
2366        links: &[crate::GraphLink],
2367        parent: &str,
2368    ) -> String {
2369        let self_ref = format!("#/key_value_items/{}", self.key_value_items.len());
2370        let cells: Vec<Value> = cells
2371            .iter()
2372            .map(|c| {
2373                json!({
2374                    "label": c.label,
2375                    "cell_id": c.cell_id,
2376                    "text": c.text,
2377                    "orig": c.orig,
2378                })
2379            })
2380            .collect();
2381        let links: Vec<Value> = links
2382            .iter()
2383            .map(|l| {
2384                json!({
2385                    "label": l.label,
2386                    "source_cell_id": l.source_cell_id,
2387                    "target_cell_id": l.target_cell_id,
2388                })
2389            })
2390            .collect();
2391        self.key_value_items.push(json!({
2392            "self_ref": self_ref,
2393            "parent": { "$ref": parent },
2394            "children": [],
2395            "content_layer": "body",
2396            "label": "key_value_region",
2397            "prov": [],
2398            "captions": [],
2399            "references": [],
2400            "footnotes": [],
2401            "graph": { "cells": cells, "links": links },
2402        }));
2403        self_ref
2404    }
2405
2406    fn add_field_item(&mut self, item: &crate::FieldItem, parent: &str) -> String {
2407        let self_ref = format!("#/field_items/{}", self.field_items.len());
2408        self.field_items.push(Value::Null);
2409        let item_index = self.field_items.len() - 1;
2410        let mut child_refs = Vec::new();
2411        for (label, text) in [
2412            ("marker", &item.marker),
2413            ("field_key", &item.key),
2414            ("field_value", &item.value),
2415        ] {
2416            if let Some(text) = text {
2417                // A value's `kind` (docling's `read_only` / `fillable`)
2418                // follows its text.
2419                let extra = match (label, &item.value_kind) {
2420                    ("field_value", Some(kind)) => json!({ "kind": kind }),
2421                    _ => json!({}),
2422                };
2423                child_refs.push(ref_value(self.add_text(label, text, &self_ref, extra)));
2424            }
2425        }
2426        self.field_items[item_index] = json!({
2427            "self_ref": self_ref,
2428            "parent": { "$ref": parent },
2429            "children": child_refs,
2430            "content_layer": "body",
2431            "label": "field_item",
2432            "prov": [],
2433        });
2434        self_ref
2435    }
2436
2437    /// Move an already-emitted item onto a content layer. Notes are single
2438    /// text items today; a deeper notes subtree would need its children moved
2439    /// too, and no backend builds one.
2440    fn set_layer(&mut self, self_ref: &str, layer: &str) {
2441        if let Some(item) = self.item_mut(self_ref) {
2442            item["content_layer"] = json!(layer);
2443        }
2444    }
2445
2446    fn add_text(&mut self, label: &str, text: &str, parent: &str, extra: Value) -> String {
2447        let prov = self.take_prov_slot(unescape_text(text).chars().count());
2448        self.add_text_with(label, text, parent, extra, prov)
2449    }
2450
2451    /// [`Self::add_text`] with an explicit `prov` (a chart caption shares the
2452    /// chart's box without consuming it).
2453    fn add_text_with(
2454        &mut self,
2455        label: &str,
2456        text: &str,
2457        parent: &str,
2458        extra: Value,
2459        prov: ProvSlot,
2460    ) -> String {
2461        let index = self.texts.len();
2462        let self_ref = format!("#/texts/{index}");
2463        // A [`Node::Track`] item is docling's ASR text item (#614): the
2464        // segment's words as `text`, its timing as `source` — the `[time: …]`
2465        // prefix the wrapped paragraph shows is Markdown's alone. It carries a
2466        // field the compact [`TextItem`] doesn't, so it is built as JSON.
2467        let mut item = match self.pending_track.take() {
2468            None => Item::Text(Box::new(TextItem {
2469                parent: parent.into(),
2470                label: label.into(),
2471                prov,
2472                text: unescape_text(text).into(),
2473            })),
2474            Some((track, cue)) => {
2475                let mut m = serde_json::Map::with_capacity(9);
2476                m.insert("self_ref".into(), Value::String(self_ref.clone()));
2477                m.insert("parent".into(), ref_value(parent));
2478                m.insert("children".into(), Value::Array(Vec::new()));
2479                m.insert("content_layer".into(), "body".into());
2480                m.insert("label".into(), label.into());
2481                m.insert("prov".into(), prov.to_value());
2482                // `DocItem.source` follows `prov` (docling's field order).
2483                m.insert("source".into(), Value::Array(vec![track_json(&track)]));
2484                m.insert("orig".into(), Value::String(cue.clone()));
2485                m.insert("text".into(), Value::String(cue));
2486                Item::json(Value::Object(m))
2487            }
2488        };
2489        if extra.as_object().is_some_and(|e| !e.is_empty()) {
2490            merge(item.value_mut(index), extra);
2491        }
2492        // The link destinations met before this item (#852), on the Pandoc
2493        // path only — docling's model has no field for them.
2494        let anchors = std::mem::take(&mut self.pending_anchors);
2495        if self.note_keys && !anchors.is_empty() {
2496            merge(item.value_mut(index), json!({ "_anchors": anchors }));
2497        }
2498        self.texts.push(item);
2499        self_ref
2500    }
2501
2502    /// A display-math formula item. `latex` is the raw content (no `$$`); docling
2503    /// re-wraps it and never escapes it.
2504    fn add_formula(&mut self, latex: &str, parent: &str) -> String {
2505        let self_ref = format!("#/texts/{}", self.texts.len());
2506        let prov = self.take_prov(latex.chars().count());
2507        self.texts.push(Item::json(json!({
2508            "self_ref": self_ref,
2509            "parent": { "$ref": parent },
2510            "children": [],
2511            "content_layer": "body",
2512            "label": "formula",
2513            "prov": prov,
2514            "orig": latex,
2515            "text": latex,
2516        })));
2517        self_ref
2518    }
2519
2520    /// A CodeFormula-enriched display formula: `text` is the model's LaTeX
2521    /// while `orig` keeps the raw glyph extraction (docling's enriched shape;
2522    /// the plain [`Self::add_formula`] above sets both to the same string).
2523    fn add_formula_item(&mut self, latex: &str, orig: &str, parent: &str) -> String {
2524        let self_ref = format!("#/texts/{}", self.texts.len());
2525        let prov = self.take_prov(latex.chars().count());
2526        self.texts.push(Item::json(json!({
2527            "self_ref": self_ref,
2528            "parent": { "$ref": parent },
2529            "children": [],
2530            "content_layer": "body",
2531            "label": "formula",
2532            "prov": prov,
2533            "orig": orig,
2534            "text": latex,
2535        })));
2536        self_ref
2537    }
2538
2539    fn add_code(
2540        &mut self,
2541        text: &str,
2542        language: Option<&str>,
2543        orig: Option<&str>,
2544        parent: &str,
2545    ) -> String {
2546        let self_ref = format!("#/texts/{}", self.texts.len());
2547        let raw = unescape_text(text);
2548        let prov = self.take_prov(raw.chars().count());
2549        self.texts.push(Item::json(json!({
2550            "self_ref": self_ref,
2551            "parent": { "$ref": parent },
2552            "children": [],
2553            "content_layer": "body",
2554            "label": "code",
2555            "prov": prov,
2556            // With code enrichment, `text` is the model's rewrite while `orig`
2557            // keeps the raw extraction; otherwise both are the same string.
2558            "orig": orig.map(unescape_text).unwrap_or_else(|| raw.clone()),
2559            "text": raw,
2560            "captions": [],
2561            "references": [],
2562            "footnotes": [],
2563            "code_language": code_language(language),
2564        })));
2565        self_ref
2566    }
2567
2568    /// Build a list group from a run of (possibly multi-level) list items. A
2569    /// deeper level starts a nested list under the preceding item.
2570    fn add_list(&mut self, items: &[Node], parent: &str) -> String {
2571        let self_ref = format!("#/groups/{}", self.groups.len());
2572        // reserve the slot so nested groups get later indices
2573        self.groups.push(Value::Null);
2574        let base = level_of(&items[0]);
2575        let mut children = Vec::new();
2576        let mut i = 0;
2577        while i < items.len() {
2578            // Empty paragraphs absorbed into the run (blank lines between items)
2579            // are not list items — skip them.
2580            if !matches!(items[i], Node::ListItem { .. }) {
2581                i += 1;
2582                continue;
2583            }
2584            let lvl = level_of(&items[i]);
2585            if lvl > base {
2586                // shouldn't happen at the head; skip defensively
2587                i += 1;
2588                continue;
2589            }
2590            let item_ref = self.add_list_item(&items[i], &self_ref);
2591            // collect any deeper items that nest under this one
2592            let mut j = i + 1;
2593            while j < items.len() && level_of(&items[j]) > base {
2594                j += 1;
2595            }
2596            if j > i + 1 {
2597                let mut nested = Vec::new();
2598                self.add_sibling_lists(&items[i + 1..j], &item_ref, &mut nested);
2599                // the nested list group(s) are children of this item
2600                if let Some(idx) = ref_index(&item_ref) {
2601                    self.texts[idx].value_mut(idx)["children"]
2602                        .as_array_mut()
2603                        .unwrap()
2604                        .extend(nested);
2605                }
2606            }
2607            children.push(ref_value(item_ref));
2608            i = j;
2609        }
2610        self.groups[group_index(&self_ref)] = json!({
2611            "self_ref": self_ref,
2612            "parent": { "$ref": parent },
2613            "children": children,
2614            "content_layer": "body",
2615            "name": "list",
2616            "label": "list",
2617        });
2618        self_ref
2619    }
2620
2621    fn add_list_item(&mut self, node: &Node, parent: &str) -> String {
2622        let Node::ListItem {
2623            ordered,
2624            number,
2625            text,
2626            location,
2627            ..
2628        } = node
2629        else {
2630            unreachable!()
2631        };
2632        self.adopt_loc(*location);
2633        let self_ref = format!("#/texts/{}", self.texts.len());
2634        let raw = unescape_text(text);
2635        let prov = self.take_prov(raw.chars().count());
2636        let marker = if *ordered {
2637            format!("{number}.")
2638        } else {
2639            "-".to_string()
2640        };
2641        self.texts.push(Item::json(json!({
2642            "self_ref": self_ref,
2643            "parent": { "$ref": parent },
2644            "children": [],
2645            "content_layer": "body",
2646            "label": "list_item",
2647            "prov": prov,
2648            "orig": raw,
2649            "text": raw,
2650            "enumerated": ordered,
2651            "marker": marker,
2652        })));
2653        self_ref
2654    }
2655
2656    fn add_table(&mut self, t: &Table, parent: &str) -> String {
2657        self.add_table_with(t, parent, false)
2658    }
2659
2660    /// [`Self::add_table`]; `raw` cell text is written verbatim (see
2661    /// [`table_data_with`]).
2662    fn add_table_with(&mut self, t: &Table, parent: &str, raw: bool) -> String {
2663        let self_ref = format!("#/tables/{}", self.tables.len());
2664        self.adopt_loc(t.location);
2665        let prov = self.take_prov(0);
2666        // The caption is a separate text item the table references (docling's
2667        // `TableItem.captions`), added before the grid so its box isn't
2668        // inherited by a later item.
2669        let (captions, children) = match t.caption.as_deref().filter(|c| !c.is_empty()) {
2670            Some(cap) => self.add_caption(
2671                cap,
2672                json!({}),
2673                &self_ref,
2674                parent,
2675                (t.caption_parent, t.caption_location),
2676            ),
2677            None => (Vec::new(), Vec::new()),
2678        };
2679        let data = table_data_with(t, raw);
2680        let item = json!({
2681            "self_ref": self_ref,
2682            "parent": { "$ref": parent },
2683            "children": children,
2684            "content_layer": "body",
2685            "label": "table",
2686            "prov": prov,
2687            "captions": captions,
2688            "references": [],
2689            "footnotes": [],
2690            // The typed `data` takes this stand-in's place on output.
2691            "data": null,
2692            "annotations": [],
2693        });
2694        self.tables.push(TableItem { item, data });
2695        self_ref
2696    }
2697
2698    /// Add a picture's or table's caption text item where `choice` says it
2699    /// hangs (#390), returning the `captions` entry for the item and the
2700    /// item's own `children` (the caption, when it is the item's child).
2701    /// The caption never consumes the item's pending provenance — the item
2702    /// takes its box first. Its own box, when the backend kept one (the PDF
2703    /// pipeline's caption region, #609), becomes the caption's `prov` on the
2704    /// item's page, as docling's reading-order model gives every caption the
2705    /// cluster it came from; without one the caption has no `prov`.
2706    fn add_caption(
2707        &mut self,
2708        text: &str,
2709        extra: Value,
2710        self_ref: &str,
2711        parent: &str,
2712        (choice, location): (CaptionParent, Option<[u16; 4]>),
2713    ) -> (Vec<Value>, Vec<Value>) {
2714        // docling's PDF pipeline parents the caption to the item; every
2715        // declarative backend leaves `add_text`'s default — the body — even
2716        // for an item inside a group; the office backends and HTML's
2717        // `<figure>` hang it off the item's container.
2718        let cap_parent = match choice {
2719            CaptionParent::Item => self_ref,
2720            CaptionParent::Container | CaptionParent::ContainerAfter => parent,
2721            CaptionParent::Body => "#/body",
2722        };
2723        if self.cur_page > 0 && location.is_some() {
2724            self.pending_loc = location;
2725        }
2726        let cap_ref = ref_value(self.add_text("caption", text, cap_parent, extra));
2727        match choice {
2728            CaptionParent::Item => return (vec![cap_ref.clone()], vec![cap_ref]),
2729            // Created ahead of the item, so it precedes the item in the
2730            // container's children — and, on the body, in the body's.
2731            CaptionParent::Container => self.pending_siblings.push(cap_ref.clone()),
2732            CaptionParent::Body if parent == "#/body" => {
2733                self.pending_siblings.push(cap_ref.clone())
2734            }
2735            CaptionParent::ContainerAfter => self.pending_after.push(cap_ref.clone()),
2736            // The item sits deeper: the body's children get the caption after
2737            // the top-level item under walk, where docling appended it.
2738            CaptionParent::Body => self.pending_body.push(cap_ref.clone()),
2739        }
2740        (vec![cap_ref], Vec::new())
2741    }
2742
2743    /// `meta` is the picture's docling `PictureMeta` (a classifier's
2744    /// predictions, a chart's kind and data), `None` for a plain picture.
2745    fn add_picture(
2746        &mut self,
2747        caption: Option<&str>,
2748        caption_href: Option<&str>,
2749        image: Option<&crate::PictureImage>,
2750        meta: Option<Value>,
2751        parent: &str,
2752        caption_at: (CaptionParent, Option<[u16; 4]>),
2753    ) -> String {
2754        let self_ref = format!("#/pictures/{}", self.pictures.len());
2755        // Take the picture's own provenance before the caption text is added —
2756        // the caption is a separate item and must not inherit the crop's box.
2757        let prov = self.take_prov(0);
2758        let (captions, children) = match caption.filter(|c| !c.is_empty()) {
2759            Some(cap) => {
2760                // Emit the caption as a text item that the picture references. A
2761                // wrapping `<a href>`'s link rides as docling's `hyperlink` field
2762                // on the caption item (#328).
2763                let extra = match caption_href {
2764                    Some(href) => json!({ "hyperlink": href }),
2765                    None => json!({}),
2766                };
2767                self.add_caption(cap, extra, &self_ref, parent, caption_at)
2768            }
2769            None => (Vec::new(), Vec::new()),
2770        };
2771        self.push_picture(prov, captions, children, image, meta, parent)
2772    }
2773
2774    /// Append the picture item itself — `prov`, `captions` and `children`
2775    /// (a PDF caption is the picture's child) already settled.
2776    fn push_picture(
2777        &mut self,
2778        prov: Value,
2779        captions: Vec<Value>,
2780        children: Vec<Value>,
2781        image: Option<&crate::PictureImage>,
2782        meta: Option<Value>,
2783        parent: &str,
2784    ) -> String {
2785        let self_ref = format!("#/pictures/{}", self.pictures.len());
2786        // The legacy `classification` annotation rides along with a
2787        // classifier's `meta` (see `classification_meta`); a chart's meta has
2788        // none, like docling's.
2789        let annotations = meta
2790            .as_ref()
2791            .and_then(|m| m.get("annotations").cloned())
2792            .unwrap_or_else(|| json!([]));
2793        let meta = meta.map(|mut m| {
2794            if let Some(obj) = m.as_object_mut() {
2795                obj.remove("annotations");
2796            }
2797            m
2798        });
2799        // `meta` sits between `content_layer` and `label` in docling's field
2800        // order (and `preserve_order` keeps ours byte-compatible), so the item
2801        // is built in one shot per shape rather than patched afterwards.
2802        let mut item = match meta {
2803            Some(meta) => json!({
2804                "self_ref": self_ref,
2805                "parent": { "$ref": parent },
2806                "children": children,
2807                "content_layer": "body",
2808                "meta": meta,
2809                "label": "picture",
2810                "prov": prov,
2811                "captions": captions,
2812                "references": [],
2813                "footnotes": [],
2814                "annotations": annotations,
2815            }),
2816            None => json!({
2817                "self_ref": self_ref,
2818                "parent": { "$ref": parent },
2819                "children": children,
2820                "content_layer": "body",
2821                "label": "picture",
2822                "prov": prov,
2823                "captions": captions,
2824                "references": [],
2825                "footnotes": [],
2826                "annotations": annotations,
2827            }),
2828        };
2829        // docling stores the extracted image as an `ImageRef` (data URI + size,
2830        // the size as floats) between `footnotes` and `annotations` — pydantic
2831        // field order, which `preserve_order` lets us reproduce by rebuilding
2832        // the tail.
2833        if let Some(img) = image {
2834            let mut image = image_ref_json(img);
2835            // The displayed size, for the Pandoc writer only (#834):
2836            // docling's `ImageRef` has no field for it.
2837            if self.note_keys {
2838                if let Some([w, h]) = img.display_size {
2839                    image["_display"] = json!([w, h]);
2840                }
2841            }
2842            if let Some(obj) = item.as_object_mut() {
2843                let annotations = obj.remove("annotations").unwrap_or_else(|| json!([]));
2844                obj.insert("image".into(), image);
2845                obj.insert("annotations".into(), annotations);
2846            }
2847        }
2848        self.pictures.push(item);
2849        self_ref
2850    }
2851
2852    fn add_group(
2853        &mut self,
2854        label: &str,
2855        name: Option<&str>,
2856        layer: Option<ContentLayer>,
2857        nodes: &[Node],
2858        parent: &str,
2859    ) -> String {
2860        let self_ref = format!("#/groups/{}", self.groups.len());
2861        self.groups.push(Value::Null);
2862        // Everything the walk creates belongs to this group, so a non-body
2863        // layer (a hidden sheet) is stamped on the whole subtree afterwards —
2864        // docling puts the layer on the group *and* on every item under it.
2865        let mark = (
2866            self.texts.len(),
2867            self.tables.len(),
2868            self.pictures.len(),
2869            self.groups.len(),
2870        );
2871        let children: Vec<Value> = self
2872            .walk_into(nodes, &self_ref)
2873            .into_iter()
2874            .map(Child::into_value)
2875            .collect();
2876        let name = name.unwrap_or(if label == "inline" { "group" } else { label });
2877        let content_layer = layer.map_or("body", |l| l.value());
2878        self.groups[group_index(&self_ref)] = json!({
2879            "self_ref": self_ref,
2880            "parent": { "$ref": parent },
2881            "children": children,
2882            "content_layer": content_layer,
2883            "name": name,
2884            "label": label,
2885        });
2886        if layer.is_some() {
2887            let (t, tb, p, g) = mark;
2888            for item in self.texts[t..]
2889                .iter_mut()
2890                .enumerate()
2891                .map(|(k, item)| item.value_mut(t + k))
2892                .chain(self.tables[tb..].iter_mut().map(|t| &mut t.item))
2893                .chain(self.pictures[p..].iter_mut())
2894                .chain(self.groups[g..].iter_mut())
2895            {
2896                if let Some(obj) = item.as_object_mut() {
2897                    obj.insert("content_layer".into(), json!(content_layer));
2898                }
2899            }
2900        }
2901        self_ref
2902    }
2903
2904    /// Walk a slice of sibling nodes, returning each child's `$ref`; runs of
2905    /// list items are folded into list groups (one per sibling list).
2906    fn walk_into(&mut self, nodes: &[Node], parent: &str) -> Vec<Child> {
2907        // Siblings that all carry a creation rank (an XLSX sheet's items) are
2908        // *added* in that order — so `#/tables/N` and friends are numbered as
2909        // docling numbers them — while their refs keep the node order, which
2910        // is docling's position-sorted `children`.
2911        let seqs: Option<Vec<usize>> = nodes
2912            .iter()
2913            .map(|n| match n {
2914                Node::Prov { seq: Some(s), .. } => Some(*s),
2915                _ => None,
2916            })
2917            .collect();
2918        if let Some(seqs) = seqs.filter(|s| !s.is_empty()) {
2919            let mut order: Vec<usize> = (0..nodes.len()).collect();
2920            order.sort_by_key(|&i| seqs[i]);
2921            let mut slots: Vec<Vec<Child>> = (0..nodes.len()).map(|_| Vec::new()).collect();
2922            for i in order {
2923                if let Some(r) = self.add_node(&nodes[i], parent) {
2924                    slots[i].extend(self.pending_siblings.drain(..).map(Child::json));
2925                    slots[i].push(Child::Ref(r.into()));
2926                    slots[i].extend(self.pending_after.drain(..).map(Child::json));
2927                }
2928                if parent == "#/body" {
2929                    slots[i].extend(self.pending_body.drain(..).map(Child::json));
2930                }
2931            }
2932            return slots.into_iter().flatten().collect();
2933        }
2934        let mut children = Vec::new();
2935        let mut i = 0;
2936        while i < nodes.len() {
2937            if matches!(nodes[i], Node::ListItem { .. }) {
2938                let start = i;
2939                i += 1;
2940                loop {
2941                    match nodes.get(i) {
2942                        Some(Node::ListItem { .. }) => i += 1,
2943                        // Absorb an empty paragraph sitting between two list
2944                        // items (docling keeps the ListGroup contiguous).
2945                        Some(Node::Paragraph { text })
2946                            if text.is_empty()
2947                                && matches!(nodes.get(i + 1), Some(Node::ListItem { .. })) =>
2948                        {
2949                            i += 1
2950                        }
2951                        _ => break,
2952                    }
2953                }
2954                let mut lists = Vec::new();
2955                self.add_sibling_lists(&nodes[start..i], parent, &mut lists);
2956                children.extend(lists.into_iter().map(Child::json));
2957            } else {
2958                if let Some(r) = self.add_node(&nodes[i], parent) {
2959                    children.extend(self.pending_siblings.drain(..).map(Child::json));
2960                    children.push(Child::Ref(r.into()));
2961                    children.extend(self.pending_after.drain(..).map(Child::json));
2962                }
2963                i += 1;
2964            }
2965            // Body-parented captions of items deeper in the tree follow the
2966            // top-level item they were created under (#390).
2967            if parent == "#/body" {
2968                children.extend(self.pending_body.drain(..).map(Child::json));
2969            }
2970        }
2971        children
2972    }
2973
2974    /// A run of list items may hold several *sibling* lists; emit one list group
2975    /// per sibling. The boundary is the backend's `first_in_list` flag on a
2976    /// base-level item — the same rule as the Markdown serializer's blank line
2977    /// (#385; the kind-flip and number-gap guesses are gone).
2978    fn add_sibling_lists(&mut self, run: &[Node], parent: &str, out: &mut Vec<Value>) {
2979        let base = level_of(&run[0]);
2980        let mut seg = 0;
2981        for k in 0..run.len() {
2982            let Node::ListItem {
2983                first_in_list,
2984                level,
2985                ..
2986            } = &run[k]
2987            else {
2988                continue;
2989            };
2990            if *level != base {
2991                continue; // nested item — handled inside add_list
2992            }
2993            if k > seg && *first_in_list {
2994                out.push(ref_value(self.add_list(&run[seg..k], parent)));
2995                seg = k;
2996            }
2997        }
2998        out.push(ref_value(self.add_list(&run[seg..], parent)));
2999    }
3000}
3001
3002fn level_of(node: &Node) -> u8 {
3003    match node {
3004        Node::ListItem { level, .. } => *level,
3005        _ => 0,
3006    }
3007}
3008
3009fn group_index(self_ref: &str) -> usize {
3010    self_ref.rsplit('/').next().unwrap().parse().unwrap()
3011}
3012
3013fn ref_index(self_ref: &str) -> Option<usize> {
3014    self_ref.rsplit('/').next()?.parse().ok()
3015}
3016
3017/// Merge the key/values of `extra` (an object) into `target` (an object).
3018fn merge(target: &mut Value, extra: Value) {
3019    if let (Some(t), Value::Object(e)) = (target.as_object_mut(), extra) {
3020        t.extend(e);
3021    }
3022}
3023
3024/// A JSON object of exactly these entries, in this order. The hot per-item
3025/// constructors use this instead of `json!`: the macro grows its map by
3026/// doubling (an 8-key item kept 14 slots) and deep-copies every interpolated
3027/// `Value` through `to_value`. On a long text-heavy PDF those item objects
3028/// *are* the export's footprint (the same reasoning as [`cell_value`]).
3029fn object<const N: usize>(entries: [(&str, Value); N]) -> Value {
3030    let mut m = serde_json::Map::with_capacity(N);
3031    for (k, v) in entries {
3032        m.insert(k.to_owned(), v);
3033    }
3034    Value::Object(m)
3035}
3036
3037/// A `{"$ref": r}` reference object.
3038fn ref_value(r: impl Into<String>) -> Value {
3039    object([("$ref", Value::String(r.into()))])
3040}
3041
3042/// Reverse [`crate`]'s Markdown text escaping (HTML entities + `\_`).
3043fn unescape_text(s: &str) -> String {
3044    s.replace("&lt;", "<")
3045        .replace("&gt;", ">")
3046        .replace("&amp;", "&")
3047        .replace("\\_", "_")
3048}
3049
3050/// 64-bit FNV-1a, a stand-in for docling's `binary_hash` (we lack the source bytes
3051/// at export time; the value only needs to be a stable u64).
3052fn fnv1a(s: &str) -> u64 {
3053    let mut h: u64 = 0xcbf29ce484222325;
3054    for b in s.bytes() {
3055        h ^= b as u64;
3056        h = h.wrapping_mul(0x100000001b3);
3057    }
3058    h
3059}
3060
3061#[cfg(test)]
3062mod tests {
3063    #[cfg(feature = "preserve-order")]
3064    use crate::ImageMode;
3065    #[cfg(feature = "preserve-order")]
3066    use crate::PictureImage;
3067    use crate::{CaptionParent, ContentLayer, DoclingDocument, Node, Table};
3068    use serde_json::Value;
3069
3070    fn cell_at(text: &str, row: usize, col: usize, col_span: usize) -> crate::TableCell {
3071        crate::TableCell {
3072            text: text.into(),
3073            bbox: None,
3074            start_row: row,
3075            start_col: col,
3076            row_span: 1,
3077            col_span,
3078            column_header: row == 0,
3079            row_header: false,
3080            row_section: false,
3081        }
3082    }
3083
3084    /// First-class cells past the rows: rectangular rows are the grid and
3085    /// clip them (docling's `TableData.grid` on USPTO's overrun replicas);
3086    /// ragged rows — an xlsx table compacted by `skip_empty_cells` (#271) —
3087    /// are no grid, so the cells' extent sizes it and the omitted positions
3088    /// come back as empty filler cells in `grid` only.
3089    #[test]
3090    fn ragged_rows_take_their_grid_from_first_class_cells() {
3091        let cells = vec![
3092            cell_at("h0", 0, 0, 1),
3093            cell_at("h2", 0, 2, 1),
3094            cell_at("wide", 1, 0, 3),
3095        ];
3096        let export = |rows: Vec<Vec<String>>| -> Value {
3097            let mut doc = DoclingDocument::new("t");
3098            doc.push(Node::Table(Table {
3099                rows,
3100                cells: Some(cells.clone()),
3101                ..Table::default()
3102            }));
3103            let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3104            v["tables"][0]["data"].clone()
3105        };
3106        // Compacted rows: 2 and 3 wide, the cells say the grid is 3 wide.
3107        let data = export(vec![
3108            vec!["h0".into(), "h2".into()],
3109            vec!["wide".into(), "wide".into(), "wide".into()],
3110        ]);
3111        assert_eq!(data["num_rows"], 2);
3112        assert_eq!(data["num_cols"], 3);
3113        assert_eq!(data["table_cells"].as_array().unwrap().len(), 3);
3114        let row0: Vec<&str> = data["grid"][0]
3115            .as_array()
3116            .unwrap()
3117            .iter()
3118            .map(|c| c["text"].as_str().unwrap())
3119            .collect();
3120        assert_eq!(row0, ["h0", "", "h2"]);
3121        assert_eq!(data["table_cells"][2]["col_span"], 3);
3122        // Rectangular rows narrower than the cells: the rows win, the cells
3123        // are clipped to them exactly as before.
3124        let data = export(vec![
3125            vec!["h0".into(), "h2".into()],
3126            vec!["wide".into(), "wide".into()],
3127        ]);
3128        assert_eq!(data["num_cols"], 2);
3129        assert_eq!(data["grid"][0].as_array().unwrap().len(), 2);
3130    }
3131
3132    #[cfg(feature = "preserve-order")]
3133    fn doc_with_image() -> DoclingDocument {
3134        let mut doc = DoclingDocument::new("t");
3135        doc.push(Node::Picture {
3136            caption: Some("Fig 1".into()),
3137            caption_href: None,
3138            image: Some(PictureImage {
3139                dpi: crate::PictureImage::DEFAULT_DPI,
3140                mimetype: "image/png".into(),
3141                width: 4,
3142                height: 2,
3143                data: b"foobar".to_vec(),
3144                display_size: None,
3145            }),
3146            classification: None,
3147            description: None,
3148            caption_parent: Default::default(),
3149            caption_location: None,
3150        });
3151        doc
3152    }
3153
3154    /// #402: a deck's speaker notes are content, and docling puts them in the
3155    /// JSON on the `notes` layer so a consumer reading only JSON can pick them
3156    /// out. Markdown still serializes the body layer alone, and page furniture
3157    /// stays out of the JSON, where docling does keep it.
3158    #[test]
3159    fn notes_layer_items_reach_the_json_but_furniture_does_not() {
3160        let mut doc = DoclingDocument::new("t");
3161        doc.push(Node::Heading {
3162            level: 1,
3163            text: "Slide One".into(),
3164        });
3165        doc.push(Node::Furniture {
3166            layer: ContentLayer::Notes,
3167            inner: Box::new(Node::Located {
3168                location: [0, 0, 0, 0],
3169                inner: Box::new(Node::Paragraph {
3170                    text: "Speaker note for slide 1.".into(),
3171                }),
3172            }),
3173        });
3174        doc.push(Node::Furniture {
3175            layer: ContentLayer::Furniture,
3176            inner: Box::new(Node::Paragraph {
3177                text: "page header".into(),
3178            }),
3179        });
3180
3181        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3182        let texts = v["texts"].as_array().unwrap();
3183        assert_eq!(
3184            texts
3185                .iter()
3186                .map(|t| (
3187                    t["label"].as_str().unwrap(),
3188                    t["content_layer"].as_str().unwrap(),
3189                    t["text"].as_str().unwrap()
3190                ))
3191                .collect::<Vec<_>>(),
3192            vec![
3193                ("title", "body", "Slide One"),
3194                ("text", "notes", "Speaker note for slide 1."),
3195            ],
3196            "the note is carried on its own layer; the furniture is not carried"
3197        );
3198        // The body layer is what Markdown serializes, so it does not change.
3199        assert_eq!(doc.export_to_markdown(), "# Slide One\n");
3200    }
3201
3202    /// #410: a backend that describes merged ranges only as continuation
3203    /// flags (xlsx `<mergeCell>`, docx `gridSpan`/`vMerge`) gets docling's
3204    /// one-`TableCell`-per-range JSON: the anchor's offsets and spans, the
3205    /// entry repeated across the grid positions it covers — not a 1×1 cell
3206    /// per position with the text copied into each.
3207    #[test]
3208    fn continuation_flags_become_spanning_cells() {
3209        let mut doc = DoclingDocument::new("t");
3210        // A1:C2 merged ("merged"), then a plain row underneath.
3211        let rows = vec![
3212            vec!["merged".to_string(), "merged".into(), "merged".into()],
3213            vec!["merged".to_string(), "merged".into(), "merged".into()],
3214            vec!["a".to_string(), "b".into(), "c".into()],
3215        ];
3216        doc.push(Node::Table(crate::Table {
3217            rows,
3218            location: None,
3219            structure: Some(crate::TableStructure {
3220                header_row: vec![true, false, false],
3221                col_continuation: vec![
3222                    vec![false, true, true],
3223                    vec![false, true, true],
3224                    vec![false, false, false],
3225                ],
3226                row_continuation: vec![
3227                    vec![false, false, false],
3228                    vec![true, true, true],
3229                    vec![false, false, false],
3230                ],
3231                row_header: Vec::new(),
3232                col_header: Vec::new(),
3233            }),
3234            cell_blocks: None,
3235            cells: None,
3236            caption: None,
3237            caption_parent: Default::default(),
3238            caption_location: None,
3239        }));
3240        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3241        let data = &v["tables"][0]["data"];
3242        assert_eq!(data["num_rows"], 3);
3243        assert_eq!(data["num_cols"], 3);
3244        let cells = data["table_cells"].as_array().unwrap();
3245        assert_eq!(
3246            cells.len(),
3247            4,
3248            "one cell for the range, three for the plain row"
3249        );
3250        assert_eq!(
3251            cells[0],
3252            serde_json::json!({
3253                "row_span": 2, "col_span": 3,
3254                "start_row_offset_idx": 0, "end_row_offset_idx": 2,
3255                "start_col_offset_idx": 0, "end_col_offset_idx": 3,
3256                "text": "merged", "column_header": true, "row_header": false,
3257                "row_section": false, "fillable": false,
3258            })
3259        );
3260        assert_eq!(cells[1]["text"], "a");
3261        assert_eq!(cells[1]["row_span"], 1);
3262        assert_eq!(cells[1]["column_header"], false);
3263        // The grid repeats the range's entry at every position it covers.
3264        let grid = data["grid"].as_array().unwrap();
3265        assert_eq!(grid.len(), 3);
3266        for (r, row) in grid.iter().take(2).enumerate() {
3267            for (c, cell) in row.as_array().unwrap().iter().enumerate() {
3268                assert_eq!(*cell, cells[0], "grid[{r}][{c}]");
3269            }
3270        }
3271        assert_eq!(grid[2][2]["text"], "c");
3272    }
3273
3274    /// A [`Node::Prov`] wrapper is docling's provenance verbatim — the exact
3275    /// box in a top-left origin, the backend's charspan — and the page marker
3276    /// before it sizes the page; a chart's caption becomes a sibling of the
3277    /// picture in the container, listed first, sharing the chart's box with
3278    /// a charspan over its text. That is the JSON shape of an XLSX sheet.
3279    #[test]
3280    fn exact_provenance_pages_and_chart_captions_follow_docling() {
3281        let mut doc = DoclingDocument::new("t");
3282        doc.push(Node::PageInfo {
3283            page_no: 1,
3284            width: 3.0,
3285            height: 4.0,
3286        });
3287        let table = crate::Table {
3288            rows: vec![vec!["a".to_string(), "b".into()]],
3289            ..Default::default()
3290        };
3291        doc.push(Node::Group {
3292            label: "sheet".into(),
3293            name: Some("Data".into()),
3294            layer: None,
3295            children: vec![
3296                // Node order is the position-sorted one; creation order (the
3297                // `seq`) had the chart first — so the chart is `#/pictures/0`
3298                // *and* its caption `#/texts/0`, while the table stays the
3299                // group's first child.
3300                Node::Prov {
3301                    page_no: 1,
3302                    bbox: [0.0, 0.0, 3.0, 4.0],
3303                    charspan: [0, 0],
3304                    bottom_left: false,
3305                    seq: Some(1),
3306                    inner: Box::new(Node::Table(table.clone())),
3307                },
3308                Node::Prov {
3309                    page_no: 1,
3310                    bbox: [0.0, 1.0, 1.0, 1.0],
3311                    charspan: [0, 0],
3312                    bottom_left: false,
3313                    seq: Some(0),
3314                    inner: Box::new(Node::Chart {
3315                        kind: "bar_chart".into(),
3316                        table,
3317                        caption: Some("Sales".into()),
3318                        location: Some([0, 128, 170, 128]),
3319                    }),
3320                },
3321            ],
3322        });
3323        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3324        assert_eq!(
3325            v["pages"],
3326            serde_json::json!({"1": {"size": {"width": 3.0, "height": 4.0}, "page_no": 1}})
3327        );
3328        assert_eq!(
3329            v["tables"][0]["prov"],
3330            serde_json::json!([{
3331                "page_no": 1,
3332                "bbox": {"l": 0.0, "t": 0.0, "r": 3.0, "b": 4.0, "coord_origin": "TOPLEFT"},
3333                "charspan": [0, 0],
3334            }])
3335        );
3336        assert_eq!(v["tables"][0]["data"]["orientation"], "rot_0");
3337        // The caption is the group's child *before* the picture, parented to
3338        // the group, and referenced by the picture.
3339        let sheet = &v["groups"][0];
3340        assert_eq!(
3341            sheet["children"],
3342            serde_json::json!([
3343                {"$ref": "#/tables/0"}, {"$ref": "#/texts/0"}, {"$ref": "#/pictures/0"}
3344            ])
3345        );
3346        let cap = &v["texts"][0];
3347        assert_eq!(cap["label"], "caption");
3348        assert_eq!(cap["parent"], serde_json::json!({"$ref": "#/groups/0"}));
3349        assert_eq!(cap["prov"][0]["charspan"], serde_json::json!([0, 5]));
3350        assert_eq!(cap["prov"][0]["bbox"]["b"], 1.0);
3351        let pic = &v["pictures"][0];
3352        assert_eq!(pic["captions"], serde_json::json!([{"$ref": "#/texts/0"}]));
3353        assert_eq!(pic["prov"][0]["charspan"], serde_json::json!([0, 0]));
3354        assert_eq!(pic["prov"][0]["bbox"]["coord_origin"], "TOPLEFT");
3355        assert_eq!(
3356            pic["meta"]["classification"]["predictions"][0]["class_name"],
3357            "bar_chart"
3358        );
3359        assert_eq!(pic["meta"]["tabular_chart"]["chart_data"]["num_cols"], 2);
3360    }
3361
3362    /// An all-zero location is the "no geometry" sentinel — a slide's speaker
3363    /// notes carry one — and docling writes it as a zero bbox, not as a box
3364    /// spanning the whole page, which is what denormalizing the grid gives.
3365    #[test]
3366    fn a_zero_location_is_a_zero_bbox_not_the_whole_page() {
3367        let mut doc = DoclingDocument::new("t");
3368        doc.push(Node::PageInfo {
3369            page_no: 1,
3370            width: 12192000.0,
3371            height: 6858000.0,
3372        });
3373        doc.push(Node::Furniture {
3374            layer: ContentLayer::Notes,
3375            inner: Box::new(Node::Located {
3376                location: [0, 0, 0, 0],
3377                inner: Box::new(Node::Paragraph {
3378                    text: "a note".into(),
3379                }),
3380            }),
3381        });
3382        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3383        let prov = &v["texts"][0]["prov"][0];
3384        assert_eq!(prov["page_no"], 1);
3385        assert_eq!(prov["charspan"], serde_json::json!([0, 6]));
3386        assert_eq!(
3387            prov["bbox"],
3388            serde_json::json!({"l": 0.0, "t": 0.0, "r": 0.0, "b": 0.0, "coord_origin": "BOTTOMLEFT"})
3389        );
3390        // The page itself is recorded at its true size.
3391        assert_eq!(
3392            v["pages"]["1"]["size"],
3393            serde_json::json!({"width": 12192000.0, "height": 6858000.0})
3394        );
3395    }
3396
3397    /// #171: PageInfo markers become the `pages` map, and `Located` wrappers /
3398    /// node-level locations become per-item `prov` — the 0–511 grid
3399    /// denormalized against the page into BOTTOMLEFT points. Without markers
3400    /// (every declarative backend) the JSON stays exactly as before: empty
3401    /// `pages`, `prov: []` even for located nodes.
3402    /// #609: a PDF caption and a checkbox item carry their own page and box.
3403    /// docling's reading-order model gives every caption the cluster it came
3404    /// from (`_add_caption_or_footnote`), not its picture's or table's, and
3405    /// a checkbox is a text item like any other.
3406    #[test]
3407    fn captions_and_checkboxes_carry_their_own_prov() {
3408        let mut doc = DoclingDocument::new("t");
3409        doc.push(Node::PageInfo {
3410            page_no: 1,
3411            width: 512.0,
3412            height: 512.0,
3413        });
3414        doc.push(Node::Located {
3415            location: [64, 64, 448, 256],
3416            inner: Box::new(Node::Picture {
3417                caption: Some("Figure 1".into()),
3418                caption_href: None,
3419                image: None,
3420                classification: None,
3421                description: None,
3422                caption_parent: CaptionParent::Item,
3423                caption_location: Some([64, 264, 448, 280]),
3424            }),
3425        });
3426        doc.push(Node::PageInfo {
3427            page_no: 2,
3428            width: 512.0,
3429            height: 512.0,
3430        });
3431        doc.push(Node::Located {
3432            location: [64, 120, 448, 300],
3433            inner: Box::new(Node::Table(Table {
3434                rows: vec![vec!["a".into()]],
3435                caption: Some("Table 1".into()),
3436                caption_parent: CaptionParent::Item,
3437                caption_location: Some([64, 100, 300, 112]),
3438                ..Table::default()
3439            })),
3440        });
3441        doc.push(Node::Located {
3442            location: [64, 320, 200, 332],
3443            inner: Box::new(Node::CheckboxItem {
3444                checked: false,
3445                text: "First option".into(),
3446            }),
3447        });
3448        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3449        let texts = v["texts"].as_array().unwrap();
3450        let by_text = |t: &str| texts.iter().find(|x| x["text"] == t).expect(t).clone();
3451        let bbox = |p: &Value| {
3452            let b = &p["prov"][0]["bbox"];
3453            [&b["l"], &b["t"], &b["r"], &b["b"]].map(|x| x.as_f64().unwrap())
3454        };
3455        // Figure 1: its own box (grid == points on a 512 page, flipped to
3456        // BOTTOMLEFT), not the picture's.
3457        let fig = by_text("Figure 1");
3458        assert_eq!(fig["prov"][0]["page_no"], 1);
3459        assert_eq!(bbox(&fig), [64.0, 248.0, 448.0, 232.0]);
3460        assert_eq!(fig["prov"][0]["charspan"], serde_json::json!([0, 8]));
3461        assert_eq!(fig["parent"]["$ref"], "#/pictures/0");
3462        assert_eq!(v["pictures"][0]["prov"][0]["bbox"]["t"], 448.0);
3463        // Table 1 on page 2, its own box; the table keeps its own.
3464        let tab = by_text("Table 1");
3465        assert_eq!(tab["prov"][0]["page_no"], 2);
3466        assert_eq!(bbox(&tab), [64.0, 412.0, 300.0, 400.0]);
3467        assert_eq!(v["tables"][0]["prov"][0]["bbox"]["t"], 392.0);
3468        // The checkbox item.
3469        let cb = by_text("First option");
3470        assert_eq!(cb["label"], "checkbox_unselected");
3471        assert_eq!(cb["prov"][0]["page_no"], 2);
3472        assert_eq!(bbox(&cb), [64.0, 192.0, 200.0, 180.0]);
3473        assert!(texts
3474            .iter()
3475            .all(|t| !t["prov"].as_array().unwrap().is_empty()));
3476
3477        // Without a caption box (every declarative backend) the caption
3478        // still has no prov, and nothing else moves.
3479        let mut plain = DoclingDocument::new("t");
3480        plain.push(Node::PageInfo {
3481            page_no: 1,
3482            width: 512.0,
3483            height: 512.0,
3484        });
3485        plain.push(Node::Located {
3486            location: [64, 64, 448, 256],
3487            inner: Box::new(Node::Picture {
3488                caption: Some("Figure 1".into()),
3489                caption_href: None,
3490                image: None,
3491                classification: None,
3492                description: None,
3493                caption_parent: CaptionParent::Item,
3494                caption_location: None,
3495            }),
3496        });
3497        let v: Value = serde_json::from_str(&plain.export_to_json()).unwrap();
3498        assert_eq!(v["texts"][0]["prov"], serde_json::json!([]));
3499        assert_eq!(v["pictures"][0]["prov"][0]["bbox"]["t"], 448.0);
3500    }
3501
3502    #[test]
3503    fn page_markers_produce_pages_and_prov() {
3504        let mut doc = DoclingDocument::new("t");
3505        doc.push(Node::PageInfo {
3506            page_no: 1,
3507            width: 512.0,
3508            height: 1024.0,
3509        });
3510        doc.push(Node::Located {
3511            location: [128, 64, 256, 128], // quarter/eighth points of the grid
3512            inner: Box::new(Node::Paragraph {
3513                text: "hello".into(),
3514            }),
3515        });
3516        doc.push(Node::Table(Table {
3517            rows: vec![vec!["a".into()]],
3518            location: Some([0, 0, 512, 512]),
3519            ..Table::default()
3520        }));
3521        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3522        assert_eq!(v["pages"]["1"]["page_no"], 1);
3523        assert_eq!(v["pages"]["1"]["size"]["width"], 512.0);
3524        assert_eq!(v["pages"]["1"]["size"]["height"], 1024.0);
3525        // 512-wide page: grid x scales 1:1; 1024-high: grid y doubles, then
3526        // flips to the BOTTOMLEFT origin (t from grid-top 64 → 1024-128=896).
3527        let prov = &v["texts"][0]["prov"][0];
3528        assert_eq!(prov["page_no"], 1);
3529        assert_eq!(prov["bbox"]["l"], 128.0);
3530        assert_eq!(prov["bbox"]["t"], 896.0);
3531        assert_eq!(prov["bbox"]["r"], 256.0);
3532        assert_eq!(prov["bbox"]["b"], 768.0);
3533        assert_eq!(prov["bbox"]["coord_origin"], "BOTTOMLEFT");
3534        assert_eq!(prov["charspan"][1], 5);
3535        // The table adopts its own location field; charspan is [0, 0].
3536        let tprov = &v["tables"][0]["prov"][0];
3537        assert_eq!(tprov["bbox"]["t"], 1024.0);
3538        assert_eq!(tprov["bbox"]["b"], 0.0);
3539        assert_eq!(tprov["charspan"][1], 0);
3540
3541        // No markers → the pre-#171 shape, byte for byte.
3542        let mut plain = DoclingDocument::new("t");
3543        plain.push(Node::Located {
3544            location: [1, 2, 3, 4],
3545            inner: Box::new(Node::Paragraph { text: "x".into() }),
3546        });
3547        let v: Value = serde_json::from_str(&plain.export_to_json()).unwrap();
3548        assert_eq!(v["pages"], serde_json::json!({}));
3549        assert_eq!(v["texts"][0]["prov"], serde_json::json!([]));
3550    }
3551
3552    /// PDF page headers/footers reach the JSON as docling writes them:
3553    /// body-parented text items on the furniture layer, with their box.
3554    #[test]
3555    fn page_furniture_becomes_furniture_layer_text() {
3556        let mut doc = DoclingDocument::new("t");
3557        doc.push(Node::PageInfo {
3558            page_no: 1,
3559            width: 512.0,
3560            height: 512.0,
3561        });
3562        doc.push(Node::PageFurniture {
3563            footer: false,
3564            location: [10, 0, 100, 20],
3565            text: "Chapter 1".into(),
3566        });
3567        doc.push(Node::Paragraph {
3568            text: "body".into(),
3569        });
3570        doc.push(Node::PageFurniture {
3571            footer: true,
3572            location: [400, 490, 500, 512],
3573            text: "1.10.2".into(),
3574        });
3575        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3576        let texts = v["texts"].as_array().unwrap();
3577        assert_eq!(texts.len(), 3);
3578        assert_eq!(texts[0]["label"], "page_header");
3579        assert_eq!(texts[0]["content_layer"], "furniture");
3580        assert_eq!(texts[0]["parent"]["$ref"], "#/body");
3581        assert_eq!(texts[0]["prov"][0]["bbox"]["l"], 10.0);
3582        assert_eq!(texts[1]["content_layer"], "body");
3583        assert_eq!(texts[1]["prov"], serde_json::json!([]));
3584        assert_eq!(texts[2]["label"], "page_footer");
3585        assert_eq!(texts[2]["text"], "1.10.2");
3586        assert_eq!(texts[2]["content_layer"], "furniture");
3587    }
3588
3589    #[test]
3590    #[cfg(feature = "preserve-order")] // field-order assertions (#970)
3591    fn picture_image_in_markdown_modes_and_json() {
3592        let doc = doc_with_image();
3593        // placeholder (default) ignores the image
3594        assert!(doc.export_to_markdown().contains("<!-- image -->"));
3595        // embedded → base64 data URI (b"foobar" → "Zm9vYmFy")
3596        let (md, files) = doc.export_to_markdown_with_images(ImageMode::Embedded, "artifacts");
3597        assert!(
3598            md.contains("![Image](data:image/png;base64,Zm9vYmFy)"),
3599            "got:\n{md}"
3600        );
3601        assert!(files.is_empty());
3602        // referenced → file link + collected bytes
3603        let (md, files) = doc.export_to_markdown_with_images(ImageMode::Referenced, "artifacts");
3604        assert!(
3605            md.contains("![Image](artifacts/image_000000.png)"),
3606            "got:\n{md}"
3607        );
3608        assert_eq!(
3609            files,
3610            vec![("artifacts/image_000000.png".to_string(), b"foobar".to_vec())]
3611        );
3612        // JSON carries the ImageRef (data URI + size — floats, as docling's
3613        // `Size` is — placed before `annotations`).
3614        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3615        assert_eq!(v["pictures"][0]["image"]["mimetype"], "image/png");
3616        assert_eq!(v["pictures"][0]["image"]["size"]["width"], 4.0);
3617        let keys: Vec<&str> = v["pictures"][0]
3618            .as_object()
3619            .unwrap()
3620            .keys()
3621            .map(String::as_str)
3622            .collect();
3623        assert_eq!(&keys[keys.len() - 2..], ["image", "annotations"]);
3624        assert_eq!(
3625            v["pictures"][0]["image"]["uri"],
3626            "data:image/png;base64,Zm9vYmFy"
3627        );
3628    }
3629
3630    #[test]
3631    fn exports_docling_schema() {
3632        let mut doc = DoclingDocument::new("t");
3633        doc.push(Node::Heading {
3634            level: 1,
3635            text: "Title".into(),
3636        });
3637        doc.push(Node::Heading {
3638            level: 2,
3639            text: "Sec".into(),
3640        });
3641        doc.push(Node::Paragraph {
3642            text: "Body &amp; more".into(),
3643        }); // markdown-escaped
3644        doc.push(Node::ListItem {
3645            ordered: false,
3646            number: 0,
3647            first_in_list: true,
3648            text: "one".into(),
3649            level: 0,
3650            marker: None,
3651            location: None,
3652            dclx: None,
3653            href: None,
3654            layer: None,
3655        });
3656        doc.push(Node::ListItem {
3657            ordered: false,
3658            number: 0,
3659            first_in_list: false,
3660            text: "two".into(),
3661            level: 0,
3662            marker: None,
3663            location: None,
3664            dclx: None,
3665            href: None,
3666            layer: None,
3667        });
3668        doc.push(Node::Table(Table {
3669            rows: vec![vec!["A".into(), "B".into()]],
3670            location: None,
3671            structure: None,
3672            cell_blocks: None,
3673            cells: None,
3674            caption: None,
3675            caption_parent: Default::default(),
3676            caption_location: None,
3677        }));
3678
3679        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3680        assert_eq!(v["schema_name"], "DoclingDocument");
3681        assert_eq!(v["version"], "1.10.0");
3682        assert_eq!(v["texts"][0]["label"], "title");
3683        assert_eq!(v["texts"][1]["label"], "section_header");
3684        assert_eq!(v["texts"][1]["level"], 1); // heading level 2 → docling level 1
3685        assert_eq!(v["texts"][2]["text"], "Body & more"); // un-escaped for the wire format
3686                                                          // consecutive list items fold into one list group, parented to it
3687        assert_eq!(v["groups"][0]["label"], "list");
3688        assert_eq!(v["groups"][0]["children"].as_array().unwrap().len(), 2);
3689        assert_eq!(v["texts"][3]["parent"]["$ref"], "#/groups/0");
3690        assert_eq!(v["texts"][3]["marker"], "-");
3691        // table grid + header flag
3692        assert_eq!(v["tables"][0]["data"]["num_cols"], 2);
3693        assert_eq!(v["tables"][0]["data"]["grid"][0][0]["column_header"], true);
3694    }
3695    /// A named group on a non-body layer — docling's hidden spreadsheet sheet:
3696    /// the group carries the sheet's name and the `invisible` layer, and every
3697    /// item inside it carries the layer too.
3698    #[test]
3699    fn a_layered_group_stamps_its_whole_subtree() {
3700        let doc = DoclingDocument {
3701            name: "s".into(),
3702            nodes: vec![
3703                Node::Group {
3704                    label: "sheet".into(),
3705                    name: Some("Sheet1".into()),
3706                    layer: None,
3707                    children: vec![Node::Paragraph {
3708                        text: "visible".into(),
3709                    }],
3710                },
3711                Node::Group {
3712                    label: "sheet".into(),
3713                    name: Some("Sheet2".into()),
3714                    layer: Some(ContentLayer::Invisible),
3715                    children: vec![Node::Paragraph {
3716                        text: "hidden".into(),
3717                    }],
3718                },
3719            ],
3720            ..DoclingDocument::new("s")
3721        };
3722        let v = crate::json::to_json(&doc);
3723        assert_eq!(v["groups"][0]["label"], "sheet");
3724        assert_eq!(v["groups"][0]["name"], "Sheet1");
3725        assert_eq!(v["groups"][0]["content_layer"], "body");
3726        assert_eq!(v["texts"][0]["content_layer"], "body");
3727        assert_eq!(v["groups"][1]["name"], "Sheet2");
3728        assert_eq!(v["groups"][1]["content_layer"], "invisible");
3729        assert_eq!(v["texts"][1]["content_layer"], "invisible");
3730        // The group's children are the items, and the body holds the groups.
3731        assert_eq!(v["groups"][1]["children"][0]["$ref"], "#/texts/1");
3732        assert_eq!(v["body"]["children"][1]["$ref"], "#/groups/1");
3733    }
3734
3735    /// A backend-built item tree is serialized as it is: items numbered in
3736    /// creation order per bucket (a field region's part texts included), the
3737    /// tree's parents / children / layers, docling's field order for
3738    /// `formatting`, `hyperlink`, `level`, `enumerated`/`marker`, a rich
3739    /// cell's `ref` on `table_cells` only, raw cell text.
3740    /// The DOCX tree's extras: an item `delete`d (docling's `delete_items`,
3741    /// the spacer between two items of a resumed list) is neither written nor
3742    /// numbered, `comments` back-refs sit between `prov` and `orig`, and a
3743    /// chart picture carries `classification` plus `tabular_chart`.
3744    #[test]
3745    #[cfg(feature = "preserve-order")] // field-order assertions (#970)
3746    fn deleted_items_comment_refs_and_chart_meta_in_the_tree() {
3747        use crate::tree::{ItemTree, TreeKind};
3748        let mut t = ItemTree::default();
3749        let text = |txt: &str| TreeKind::Text {
3750            label: "text".into(),
3751            text: txt.into(),
3752            orig: None,
3753            formatting: None,
3754            hyperlink: None,
3755            level: None,
3756            list: None,
3757        };
3758        let a = t.add(None, None, text("a"));
3759        let blank = t.add(None, None, text(""));
3760        let b = t.add(None, None, text("b"));
3761        t.delete(blank);
3762        let group = t.add(
3763            None,
3764            Some(ContentLayer::Notes),
3765            TreeKind::Group {
3766                label: "comment_section".into(),
3767                name: "comment-0".into(),
3768            },
3769        );
3770        t.add(Some(group), Some(ContentLayer::Notes), text("note"));
3771        t.items[a].comments.push(group);
3772        t.add(
3773            None,
3774            None,
3775            TreeKind::Picture {
3776                captions: Vec::new(),
3777                image: None,
3778                extra_classes: Vec::new(),
3779                classification: Some("bar_chart".into()),
3780                description: None,
3781                confidence: None,
3782                chart: Some(Table {
3783                    rows: vec![vec!["".into(), "s".into()], vec!["c".into(), "1".into()]],
3784                    ..Table::default()
3785                }),
3786                dpi: None,
3787            },
3788        );
3789        assert_eq!(t.last_text(), Some(4), "the note; the blank is skipped");
3790        assert_eq!(t.bucket_index(b), 1, "numbered past the deleted item");
3791        let mut doc = DoclingDocument::new("t");
3792        doc.tree = Some(t);
3793        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3794        let texts = v["texts"].as_array().unwrap();
3795        assert_eq!(texts.len(), 3);
3796        assert_eq!(texts[1]["text"], "b");
3797        assert_eq!(texts[1]["self_ref"], "#/texts/1");
3798        assert_eq!(
3799            v["body"]["children"],
3800            serde_json::json!([{"$ref": "#/texts/0"}, {"$ref": "#/texts/1"}, {"$ref": "#/groups/0"}, {"$ref": "#/pictures/0"}])
3801        );
3802        let keys: Vec<&str> = texts[0]
3803            .as_object()
3804            .unwrap()
3805            .keys()
3806            .map(String::as_str)
3807            .collect();
3808        assert_eq!(
3809            keys,
3810            vec![
3811                "self_ref",
3812                "parent",
3813                "children",
3814                "content_layer",
3815                "label",
3816                "prov",
3817                "comments",
3818                "orig",
3819                "text"
3820            ]
3821        );
3822        assert_eq!(
3823            texts[0]["comments"],
3824            serde_json::json!([{"$ref": "#/groups/0"}])
3825        );
3826        assert!(texts[1].get("comments").is_none());
3827        let meta = &v["pictures"][0]["meta"];
3828        assert_eq!(
3829            meta["classification"]["predictions"][0]["class_name"],
3830            "bar_chart"
3831        );
3832        assert_eq!(meta["tabular_chart"]["chart_data"]["num_rows"], 2);
3833    }
3834
3835    /// A tree item's `TreeProv` is written verbatim — a raw EMU box with
3836    /// whatever origin tag the backend set (`BOTTOMLEFT` here) and a per-item
3837    /// charspan, a note's zero `TOPLEFT` box — a picture's `image.dpi` is the file's when the backend
3838    /// read one, an item without provenance writes `prov: []`, and the page
3839    /// map still comes from the flat stream's markers.
3840    #[test]
3841    fn tree_items_carry_exact_provenance_and_dpi() {
3842        use crate::tree::{ItemTree, TreeKind, TreeProv};
3843        let text = |label: &str, t: &str| TreeKind::Text {
3844            label: label.into(),
3845            text: t.into(),
3846            orig: None,
3847            formatting: None,
3848            hyperlink: None,
3849            level: None,
3850            list: None,
3851        };
3852        let mut t = ItemTree::default();
3853        let slide = t.add(
3854            None,
3855            None,
3856            TreeKind::Group {
3857                label: "chapter".into(),
3858                name: "slide-0".into(),
3859            },
3860        );
3861        t.add_with_prov(
3862            Some(slide),
3863            None,
3864            text("paragraph", "héllo"),
3865            TreeProv {
3866                page_no: 1,
3867                bbox: [914400.0, 1828800.0, 2743200.0, 457200.0],
3868                bottom_left: true,
3869                charspan: [0, 5],
3870            },
3871        );
3872        t.add_with_prov(
3873            Some(slide),
3874            None,
3875            TreeKind::Picture {
3876                captions: Vec::new(),
3877                image: Some(crate::PictureImage {
3878                    dpi: crate::PictureImage::DEFAULT_DPI,
3879                    mimetype: "image/png".into(),
3880                    width: 2,
3881                    height: 2,
3882                    data: vec![0],
3883                    display_size: None,
3884                }),
3885                extra_classes: Vec::new(),
3886                classification: None,
3887                description: None,
3888                confidence: None,
3889                chart: None,
3890                dpi: Some(300),
3891            },
3892            TreeProv {
3893                page_no: 1,
3894                bbox: [0.0; 4],
3895                bottom_left: false,
3896                charspan: [0, 0],
3897            },
3898        );
3899        t.add(
3900            Some(slide),
3901            Some(ContentLayer::Notes),
3902            text("text", "no geometry"),
3903        );
3904        let mut doc = DoclingDocument::new("t");
3905        doc.push(Node::PageInfo {
3906            page_no: 1,
3907            width: 9144000.0,
3908            height: 6858000.0,
3909        });
3910        doc.tree = Some(t);
3911        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3912        assert_eq!(
3913            v["texts"][0]["prov"],
3914            serde_json::json!([{
3915                "page_no": 1,
3916                "bbox": { "l": 914400.0, "t": 1828800.0, "r": 2743200.0, "b": 457200.0, "coord_origin": "BOTTOMLEFT" },
3917                "charspan": [0, 5],
3918            }])
3919        );
3920        assert_eq!(v["texts"][0]["label"], "paragraph");
3921        assert_eq!(
3922            v["pictures"][0]["prov"][0]["bbox"]["coord_origin"],
3923            "TOPLEFT"
3924        );
3925        assert_eq!(v["pictures"][0]["image"]["dpi"], 300);
3926        assert_eq!(v["texts"][1]["prov"], serde_json::json!([]));
3927        assert_eq!(v["texts"][1]["content_layer"], "notes");
3928        assert_eq!(v["pages"]["1"]["size"]["width"], 9144000.0);
3929        assert_eq!(v["pages"]["1"]["page_no"], 1);
3930    }
3931
3932    /// docling-core's `validate_document` clamps every provenance box (and a
3933    /// one-page table's cell boxes) into its page — the state every
3934    /// `ConversionResult` leaves a document in, so the state docling's JSON
3935    /// shows. A box on a page the document does not describe is left alone.
3936    #[test]
3937    fn provenance_boxes_are_clamped_to_their_page() {
3938        let mut doc = DoclingDocument::new("t");
3939        doc.push(Node::PageInfo {
3940            page_no: 1,
3941            width: 10.0,
3942            height: 8.0,
3943        });
3944        doc.push(Node::Prov {
3945            page_no: 1,
3946            bbox: [-1.0, 2.0, 12.0, 9.5],
3947            charspan: [0, 1],
3948            bottom_left: false,
3949            seq: None,
3950            inner: Box::new(Node::Paragraph { text: "x".into() }),
3951        });
3952        let mut table = Table {
3953            rows: vec![vec!["a".into()]],
3954            ..Table::default()
3955        };
3956        table.cells = Some(vec![crate::TableCell {
3957            text: "a".into(),
3958            bbox: Some([1.0, 1.0, 11.0, 9.0]),
3959            start_row: 0,
3960            start_col: 0,
3961            row_span: 1,
3962            col_span: 1,
3963            column_header: false,
3964            row_header: false,
3965            row_section: false,
3966        }]);
3967        doc.push(Node::Prov {
3968            page_no: 1,
3969            bbox: [0.0, 0.0, 10.0, 8.0],
3970            charspan: [0, 0],
3971            bottom_left: false,
3972            seq: None,
3973            inner: Box::new(Node::Table(table)),
3974        });
3975        doc.push(Node::Prov {
3976            page_no: 7,
3977            bbox: [-5.0, 0.0, 50.0, 50.0],
3978            charspan: [0, 1],
3979            bottom_left: false,
3980            seq: None,
3981            inner: Box::new(Node::Paragraph { text: "y".into() }),
3982        });
3983        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
3984        assert_eq!(
3985            v["texts"][0]["prov"][0]["bbox"],
3986            serde_json::json!({ "l": 0.0, "t": 2.0, "r": 10.0, "b": 8.0, "coord_origin": "TOPLEFT" })
3987        );
3988        let cell = &v["tables"][0]["data"]["table_cells"][0]["bbox"];
3989        assert_eq!(
3990            (cell["l"].as_f64(), cell["r"].as_f64(), cell["b"].as_f64()),
3991            (Some(1.0), Some(10.0), Some(8.0))
3992        );
3993        assert_eq!(v["tables"][0]["data"]["grid"][0][0]["bbox"]["r"], 10.0);
3994        assert_eq!(
3995            v["texts"][1]["prov"][0]["bbox"]["r"], 50.0,
3996            "page 7 is not described"
3997        );
3998    }
3999
4000    /// docling-core's `validate_misplaced_list_items`, as it re-homes list
4001    /// items outside a `list` group (#527) — the refs below are what
4002    /// docling-core 2.99 writes for the same document: the two consecutive
4003    /// items on the body share a group, each item in another group gets its
4004    /// own, the runs are handled last-first (new groups and re-added texts
4005    /// numbered in that order), and a well-placed item is left alone.
4006    #[test]
4007    fn misplaced_list_items_are_wrapped_like_docling_core() {
4008        use crate::tree::{ItemTree, ListMeta, TreeKind};
4009        let mut t = ItemTree::default();
4010        let li = |txt: &str| TreeKind::Text {
4011            label: "list_item".into(),
4012            text: txt.into(),
4013            orig: None,
4014            formatting: None,
4015            hyperlink: None,
4016            level: None,
4017            list: Some(ListMeta {
4018                enumerated: false,
4019                marker: "-".into(),
4020            }),
4021        };
4022        let group = |label: &str, name: &str| TreeKind::Group {
4023            label: label.into(),
4024            name: name.into(),
4025        };
4026        t.add(None, None, li("A"));
4027        t.add(None, None, li("B"));
4028        t.add(
4029            None,
4030            None,
4031            TreeKind::Text {
4032                label: "text".into(),
4033                text: "plain".into(),
4034                orig: None,
4035                formatting: None,
4036                hyperlink: None,
4037                level: None,
4038                list: None,
4039            },
4040        );
4041        let cell = t.add(None, None, group("unspecified", "cell"));
4042        t.add(Some(cell), None, li("C"));
4043        t.add(Some(cell), None, li("D"));
4044        let list = t.add(None, None, group("list", "list"));
4045        t.add(Some(list), None, li("E"));
4046        let doc = DoclingDocument {
4047            tree: Some(t),
4048            ..DoclingDocument::new("t")
4049        };
4050        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4051        let refs = |x: &Value| -> Vec<String> {
4052            x.as_array()
4053                .unwrap()
4054                .iter()
4055                .map(|r| r["$ref"].as_str().unwrap().to_string())
4056                .collect()
4057        };
4058        assert_eq!(
4059            refs(&v["body"]["children"]),
4060            ["#/groups/4", "#/texts/0", "#/groups/0", "#/groups/1"]
4061        );
4062        assert_eq!(
4063            refs(&v["groups"][0]["children"]),
4064            ["#/groups/3", "#/groups/2"]
4065        );
4066        for (g, name, kids) in [
4067            (2, "group", vec!["#/texts/2"]),
4068            (3, "group", vec!["#/texts/3"]),
4069            (4, "group", vec!["#/texts/4", "#/texts/5"]),
4070            (1, "list", vec!["#/texts/1"]),
4071        ] {
4072            assert_eq!(v["groups"][g]["label"], "list");
4073            assert_eq!(v["groups"][g]["name"], name);
4074            assert_eq!(refs(&v["groups"][g]["children"]), kids);
4075        }
4076        let texts: Vec<&str> = v["texts"]
4077            .as_array()
4078            .unwrap()
4079            .iter()
4080            .map(|t| t["text"].as_str().unwrap())
4081            .collect();
4082        assert_eq!(texts, ["plain", "E", "D", "C", "A", "B"]);
4083        assert_eq!(v["texts"][2]["parent"]["$ref"], "#/groups/2");
4084    }
4085
4086    /// A child the tree still lists after deleting it is left out instead
4087    /// of written as `"$ref": ""`, which docling-core rejects (#527).
4088    #[test]
4089    fn a_deleted_child_is_not_written_as_an_empty_ref() {
4090        use crate::tree::{ItemTree, TreeKind};
4091        let mut t = ItemTree::default();
4092        let text = |txt: &str| TreeKind::Text {
4093            label: "text".into(),
4094            text: txt.into(),
4095            orig: None,
4096            formatting: None,
4097            hyperlink: None,
4098            level: None,
4099            list: None,
4100        };
4101        let g = t.add(
4102            None,
4103            None,
4104            TreeKind::Group {
4105                label: "unspecified".into(),
4106                name: "g".into(),
4107            },
4108        );
4109        let gone = t.add(Some(g), None, text(""));
4110        t.add(Some(g), None, text("kept"));
4111        t.items[gone].deleted = true; // still in `g`'s children
4112        let doc = DoclingDocument {
4113            tree: Some(t),
4114            ..DoclingDocument::new("t")
4115        };
4116        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4117        assert_eq!(
4118            v["groups"][0]["children"],
4119            serde_json::json!([{"$ref": "#/texts/0"}])
4120        );
4121    }
4122
4123    #[test]
4124    #[cfg(feature = "preserve-order")] // field-order assertions (#970)
4125    fn a_backend_item_tree_is_written_verbatim() {
4126        use crate::tree::{Formatting, ItemTree, ListMeta, TreeKind};
4127        let mut t = ItemTree::default();
4128        let text = |label: &str, txt: &str| TreeKind::Text {
4129            label: label.into(),
4130            text: txt.into(),
4131            orig: None,
4132            formatting: None,
4133            hyperlink: None,
4134            level: None,
4135            list: None,
4136        };
4137        let title = t.add(None, Some(ContentLayer::Furniture), text("title", "Page"));
4138        let h = t.add(None, None, text("title", "Heading"));
4139        let group = t.add(
4140            Some(h),
4141            None,
4142            TreeKind::Group {
4143                label: "inline".into(),
4144                name: "group".into(),
4145            },
4146        );
4147        t.add(
4148            Some(group),
4149            None,
4150            TreeKind::Text {
4151                label: "text".into(),
4152                text: "bold".into(),
4153                orig: None,
4154                formatting: Some(Formatting {
4155                    bold: true,
4156                    ..Formatting::default()
4157                }),
4158                hyperlink: Some("https://example.com/".into()),
4159                level: None,
4160                list: None,
4161            },
4162        );
4163        t.add(
4164            Some(group),
4165            None,
4166            TreeKind::Code {
4167                text: "x = 1".into(),
4168                orig: None,
4169                language: Some("python".into()),
4170                formatting: None,
4171                hyperlink: None,
4172                captions: Vec::new(),
4173            },
4174        );
4175        let sub = t.add(
4176            Some(h),
4177            None,
4178            TreeKind::Text {
4179                label: "section_header".into(),
4180                text: "Sub".into(),
4181                orig: Some("Sub\u{2019}".into()),
4182                formatting: None,
4183                hyperlink: None,
4184                level: Some(1),
4185                list: None,
4186            },
4187        );
4188        let item = t.add(
4189            Some(sub),
4190            None,
4191            TreeKind::Text {
4192                label: "list_item".into(),
4193                text: "item".into(),
4194                orig: None,
4195                formatting: None,
4196                hyperlink: None,
4197                level: None,
4198                list: Some(ListMeta {
4199                    enumerated: true,
4200                    marker: "3.".into(),
4201                }),
4202            },
4203        );
4204        let _region = t.add(
4205            Some(sub),
4206            None,
4207            TreeKind::FieldRegion {
4208                items: vec![crate::FieldItem {
4209                    marker: None,
4210                    key: Some("Name".into()),
4211                    value: Some("Duck".into()),
4212                    value_kind: Some("read_only".into()),
4213                }],
4214            },
4215        );
4216        let table = t.add(
4217            Some(sub),
4218            None,
4219            TreeKind::Table {
4220                table: Table {
4221                    rows: vec![vec!["a  \n&lt;".into(), "b".into()]],
4222                    cells: Some(vec![
4223                        crate::TableCell {
4224                            text: "a  \n&lt;".into(),
4225                            bbox: None,
4226                            start_row: 0,
4227                            start_col: 0,
4228                            row_span: 3,
4229                            col_span: 1,
4230                            column_header: false,
4231                            row_header: true,
4232                            row_section: false,
4233                        },
4234                        crate::TableCell {
4235                            text: "b".into(),
4236                            bbox: None,
4237                            start_row: 0,
4238                            start_col: 1,
4239                            row_span: 1,
4240                            col_span: 1,
4241                            column_header: false,
4242                            row_header: false,
4243                            row_section: false,
4244                        },
4245                    ]),
4246                    ..Table::default()
4247                },
4248                rich_cells: vec![(0, 1, 0)], // patched below
4249                captions: Vec::new(),
4250            },
4251        );
4252        let cell_group = t.add(
4253            Some(table),
4254            None,
4255            TreeKind::Group {
4256                label: "unspecified".into(),
4257                name: "rich_cell_group_1_0_0".into(),
4258            },
4259        );
4260        if let TreeKind::Table { rich_cells, .. } = &mut t.items[table].kind {
4261            *rich_cells = vec![(0, 1, cell_group)];
4262        }
4263        let after = t.add(Some(sub), None, text("text", "after the region"));
4264        let _ = (title, after);
4265        // A list item belongs in a `list` group — one outside it would be
4266        // re-homed by `wrap_misplaced_list_items` (created last, so the
4267        // other groups keep their numbers).
4268        let list = t.add(
4269            Some(sub),
4270            None,
4271            TreeKind::Group {
4272                label: "list".into(),
4273                name: "list".into(),
4274            },
4275        );
4276        t.reparent(item, Some(list));
4277
4278        let doc = DoclingDocument {
4279            tree: Some(t),
4280            ..DoclingDocument::new("t")
4281        };
4282        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4283        // Creation order: Page, Heading, bold, x = 1, Sub, item, [Name, Duck], after.
4284        let texts: Vec<&str> = v["texts"]
4285            .as_array()
4286            .unwrap()
4287            .iter()
4288            .map(|t| t["text"].as_str().unwrap())
4289            .collect();
4290        assert_eq!(
4291            texts,
4292            [
4293                "Page",
4294                "Heading",
4295                "bold",
4296                "x = 1",
4297                "Sub",
4298                "item",
4299                "Name",
4300                "Duck",
4301                "after the region"
4302            ]
4303        );
4304        assert_eq!(
4305            v["body"]["children"],
4306            serde_json::json!([{"$ref": "#/texts/0"}, {"$ref": "#/texts/1"}])
4307        );
4308        assert_eq!(v["texts"][0]["content_layer"], "furniture");
4309        assert_eq!(
4310            v["texts"][1]["children"],
4311            serde_json::json!([{"$ref": "#/groups/0"}, {"$ref": "#/texts/4"}])
4312        );
4313        let bold = &v["texts"][2];
4314        assert_eq!(bold["parent"]["$ref"], "#/groups/0");
4315        let keys: Vec<&str> = bold
4316            .as_object()
4317            .unwrap()
4318            .keys()
4319            .map(String::as_str)
4320            .collect();
4321        assert_eq!(
4322            keys,
4323            [
4324                "self_ref",
4325                "parent",
4326                "children",
4327                "content_layer",
4328                "label",
4329                "prov",
4330                "orig",
4331                "text",
4332                "formatting",
4333                "hyperlink"
4334            ]
4335        );
4336        assert_eq!(
4337            bold["formatting"],
4338            serde_json::json!({"bold": true, "italic": false, "underline": false, "strikethrough": false, "script": "baseline"})
4339        );
4340        let code = &v["texts"][3];
4341        assert_eq!(code["label"], "code");
4342        assert_eq!(code["code_language"], "Python");
4343        let sub = &v["texts"][4];
4344        assert_eq!(sub["orig"], "Sub\u{2019}");
4345        assert_eq!(sub["level"], 1);
4346        let item = &v["texts"][5];
4347        let keys: Vec<&str> = item
4348            .as_object()
4349            .unwrap()
4350            .keys()
4351            .map(String::as_str)
4352            .collect();
4353        assert_eq!(
4354            keys,
4355            [
4356                "self_ref",
4357                "parent",
4358                "children",
4359                "content_layer",
4360                "label",
4361                "prov",
4362                "orig",
4363                "text",
4364                "enumerated",
4365                "marker"
4366            ]
4367        );
4368        assert_eq!(item["marker"], "3.");
4369        assert_eq!(v["texts"][7]["kind"], "read_only");
4370        assert_eq!(v["field_regions"][0]["parent"]["$ref"], "#/texts/4");
4371        let table = &v["tables"][0];
4372        assert_eq!(
4373            table["children"],
4374            serde_json::json!([{"$ref": "#/groups/1"}])
4375        );
4376        let cells = table["data"]["table_cells"].as_array().unwrap();
4377        assert_eq!(
4378            cells[0]["text"], "a  \n&lt;",
4379            "raw cell text is written verbatim"
4380        );
4381        assert_eq!(
4382            cells[0]["end_row_offset_idx"], 3,
4383            "declared spans are not clamped"
4384        );
4385        assert_eq!(cells[1]["ref"], serde_json::json!({"$ref": "#/groups/1"}));
4386        assert!(cells[0].get("ref").is_none());
4387        assert!(
4388            table["data"]["grid"][0][1].get("ref").is_none(),
4389            "the grid shows plain cells"
4390        );
4391        assert_eq!(v["groups"][1]["name"], "rich_cell_group_1_0_0");
4392    }
4393
4394    /// A comment section that links its note text rather than its group — the
4395    /// spreadsheet shape, where docling-core's `add_comment` appends the text
4396    /// item's ref to each target.
4397    #[test]
4398    fn a_comment_section_can_be_referenced_by_its_note_text() {
4399        let doc = DoclingDocument {
4400            name: "c".into(),
4401            nodes: vec![
4402                Node::Commented {
4403                    comments: vec![0],
4404                    inner: Box::new(Node::Paragraph {
4405                        text: "annotated".into(),
4406                    }),
4407                },
4408                Node::CommentSection {
4409                    name: "comment-Sheet1-A1".into(),
4410                    text: "[author: A]: note".into(),
4411                    refs_note_text: true,
4412                    grouped: true,
4413                },
4414            ],
4415            ..DoclingDocument::new("c")
4416        };
4417        let v = crate::json::to_json(&doc);
4418        assert_eq!(v["groups"][0]["name"], "comment-Sheet1-A1");
4419        assert_eq!(v["texts"][0]["comments"][0]["$ref"], "#/texts/1");
4420    }
4421
4422    /// A thread's messages are notes of one `comment_section` group, which is
4423    /// listed once among its parent's children however many notes it holds.
4424    #[test]
4425    fn a_comment_thread_is_one_child_of_its_parent() {
4426        let note = |text: &str| Node::CommentSection {
4427            name: "comment-Sheet1-F7".into(),
4428            text: text.into(),
4429            refs_note_text: true,
4430            grouped: true,
4431        };
4432        let doc = DoclingDocument {
4433            name: "c".into(),
4434            nodes: vec![note("[author: A]: first"), note("[author: B]: reply")],
4435            ..DoclingDocument::new("c")
4436        };
4437        let v = crate::json::to_json(&doc);
4438        assert_eq!(v["body"]["children"].as_array().unwrap().len(), 1);
4439        assert_eq!(v["groups"][0]["children"].as_array().unwrap().len(), 2);
4440    }
4441
4442    /// docx reviewer comments: a `comment_section` group on the notes layer
4443    /// holding the note text, and a `comments` back-ref on the annotated item —
4444    /// keyed between `prov` and `orig`, the slot docling emits it in.
4445    #[test]
4446    #[cfg(feature = "preserve-order")] // field-order assertions (#970)
4447    fn comment_sections_link_back_to_their_items() {
4448        let doc = DoclingDocument {
4449            name: "c".into(),
4450            nodes: vec![
4451                Node::Commented {
4452                    comments: vec![0],
4453                    inner: Box::new(Node::Paragraph {
4454                        text: "annotated".into(),
4455                    }),
4456                },
4457                Node::Paragraph {
4458                    text: "plain".into(),
4459                },
4460                Node::CommentSection {
4461                    name: "comment-7".into(),
4462                    text: "[time: t]: note".into(),
4463                    refs_note_text: false,
4464                    grouped: true,
4465                },
4466            ],
4467            ..DoclingDocument::new("c")
4468        };
4469        let v = crate::json::to_json(&doc);
4470        // The group is the comment section; its only child is the notes text.
4471        assert_eq!(v["groups"][0]["label"], "comment_section");
4472        assert_eq!(v["groups"][0]["name"], "comment-7");
4473        assert_eq!(v["groups"][0]["content_layer"], "notes");
4474        assert_eq!(v["groups"][0]["children"][0]["$ref"], "#/texts/2");
4475        assert_eq!(v["texts"][2]["content_layer"], "notes");
4476        // The annotated item points back at the group; the plain one has no key.
4477        assert_eq!(v["texts"][0]["comments"][0]["$ref"], "#/groups/0");
4478        assert!(v["texts"][1].get("comments").is_none());
4479        // docling's key order: … prov, comments, orig, text.
4480        let keys: Vec<&str> = v["texts"][0]
4481            .as_object()
4482            .unwrap()
4483            .keys()
4484            .map(String::as_str)
4485            .collect();
4486        assert_eq!(
4487            &keys[keys.len() - 4..],
4488            &["prov", "comments", "orig", "text"]
4489        );
4490    }
4491
4492    fn picture(caption: &str, caption_parent: CaptionParent) -> Node {
4493        Node::Picture {
4494            caption: Some(caption.into()),
4495            caption_href: None,
4496            image: None,
4497            classification: None,
4498            description: None,
4499            caption_parent,
4500            caption_location: None,
4501        }
4502    }
4503
4504    fn group(children: Vec<Node>) -> Node {
4505        Node::Group {
4506            label: "section".into(),
4507            name: None,
4508            layer: None,
4509            children,
4510        }
4511    }
4512
4513    fn refs(v: &Value) -> Vec<&str> {
4514        v.as_array()
4515            .unwrap()
4516            .iter()
4517            .map(|r| r["$ref"].as_str().unwrap())
4518            .collect()
4519    }
4520
4521    /// #390: a declarative backend's caption is docling's `add_text` default —
4522    /// a body child, appended as it is created — wherever the picture sits:
4523    /// ahead of a top-level picture, behind the top-level item enclosing a
4524    /// nested one. The picture references it either way and has no children.
4525    #[test]
4526    fn a_body_caption_follows_the_enclosing_top_level_item() {
4527        let mut doc = DoclingDocument::new("t");
4528        doc.push(picture("top", CaptionParent::Body));
4529        doc.push(group(vec![
4530            Node::Paragraph { text: "p".into() },
4531            picture("nested", CaptionParent::Body),
4532        ]));
4533        doc.push(Node::Paragraph {
4534            text: "after".into(),
4535        });
4536        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4537        assert_eq!(
4538            refs(&v["body"]["children"]),
4539            [
4540                "#/texts/0",
4541                "#/pictures/0",
4542                "#/groups/0",
4543                "#/texts/2",
4544                "#/texts/3"
4545            ]
4546        );
4547        assert_eq!(
4548            refs(&v["groups"][0]["children"]),
4549            ["#/texts/1", "#/pictures/1"]
4550        );
4551        for (cap, pic) in [(0, 0), (2, 1)] {
4552            assert_eq!(v["texts"][cap]["label"], "caption");
4553            assert_eq!(v["texts"][cap]["parent"]["$ref"], "#/body");
4554            assert_eq!(
4555                refs(&v["pictures"][pic]["captions"]),
4556                [format!("#/texts/{cap}")]
4557            );
4558            assert_eq!(v["pictures"][pic]["children"], serde_json::json!([]));
4559        }
4560    }
4561
4562    /// The PDF pipeline's caption is the picture's (or table's) own child,
4563    /// as docling attaches a layout caption.
4564    #[test]
4565    fn an_item_caption_is_the_items_first_child() {
4566        let mut doc = DoclingDocument::new("t");
4567        doc.push(picture("fig", CaptionParent::Item));
4568        doc.push(Node::Table(Table {
4569            rows: vec![vec!["a".into()]],
4570            caption: Some("tab".into()),
4571            caption_parent: CaptionParent::Item,
4572            ..Table::default()
4573        }));
4574        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4575        assert_eq!(refs(&v["body"]["children"]), ["#/pictures/0", "#/tables/0"]);
4576        assert_eq!(v["texts"][0]["parent"]["$ref"], "#/pictures/0");
4577        assert_eq!(refs(&v["pictures"][0]["children"]), ["#/texts/0"]);
4578        assert_eq!(refs(&v["pictures"][0]["captions"]), ["#/texts/0"]);
4579        assert_eq!(v["texts"][1]["parent"]["$ref"], "#/tables/0");
4580        assert_eq!(refs(&v["tables"][0]["children"]), ["#/texts/1"]);
4581        assert_eq!(refs(&v["tables"][0]["captions"]), ["#/texts/1"]);
4582    }
4583
4584    /// A PDF picture's contained text (`Node::PictureChildren`) is written as
4585    /// docling's `_add_child_elements` writes it: items parented to the
4586    /// picture, after its caption in the picture's `children`, never in the
4587    /// body; a list item opens its own list group under the picture. The
4588    /// Markdown and the chunker's refs are unaffected.
4589    #[test]
4590    fn picture_children_hang_off_the_picture_after_its_caption() {
4591        let mut doc = DoclingDocument::new("t");
4592        doc.push(picture("fig", CaptionParent::Item));
4593        doc.push(Node::PictureChildren(vec![
4594            Node::Heading {
4595                level: 2,
4596                text: "in-figure title".into(),
4597            },
4598            Node::Paragraph {
4599                text: "axis label".into(),
4600            },
4601            Node::ListItem {
4602                ordered: false,
4603                number: 0,
4604                first_in_list: true,
4605                text: "callout".into(),
4606                level: 0,
4607                marker: None,
4608                location: None,
4609                dclx: None,
4610                href: None,
4611                layer: None,
4612            },
4613        ]));
4614        doc.push(Node::Paragraph {
4615            text: "after".into(),
4616        });
4617        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4618        assert_eq!(refs(&v["body"]["children"]), ["#/pictures/0", "#/texts/4"]);
4619        assert_eq!(
4620            refs(&v["pictures"][0]["children"]),
4621            ["#/texts/0", "#/texts/1", "#/texts/2", "#/groups/0"]
4622        );
4623        assert_eq!(refs(&v["pictures"][0]["captions"]), ["#/texts/0"]);
4624        assert_eq!(v["texts"][1]["label"], "section_header");
4625        assert_eq!(v["texts"][2]["label"], "text");
4626        for t in 1..=2 {
4627            assert_eq!(v["texts"][t]["parent"]["$ref"], "#/pictures/0");
4628            assert_eq!(v["texts"][t]["content_layer"], "body");
4629        }
4630        assert_eq!(v["groups"][0]["parent"]["$ref"], "#/pictures/0");
4631        assert_eq!(v["texts"][3]["parent"]["$ref"], "#/groups/0");
4632        let md = doc.export_to_markdown();
4633        assert!(
4634            !md.contains("axis label") && !md.contains("callout"),
4635            "{md}"
4636        );
4637        assert!(md.contains("after"), "{md}");
4638    }
4639
4640    /// A container caption sits beside its item under the item's parent —
4641    /// ahead of it (an office chart's title) or behind it (an HTML
4642    /// `<figure>`'s table, whose figcaption docling adds after the table).
4643    #[test]
4644    fn a_container_caption_is_the_items_sibling() {
4645        let mut doc = DoclingDocument::new("t");
4646        doc.push(group(vec![
4647            picture("chart", CaptionParent::Container),
4648            Node::Table(Table {
4649                rows: vec![vec!["a".into()]],
4650                caption: Some("figcaption".into()),
4651                caption_parent: CaptionParent::ContainerAfter,
4652                ..Table::default()
4653            }),
4654        ]));
4655        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4656        assert_eq!(refs(&v["body"]["children"]), ["#/groups/0"]);
4657        assert_eq!(
4658            refs(&v["groups"][0]["children"]),
4659            ["#/texts/0", "#/pictures/0", "#/tables/0", "#/texts/1"]
4660        );
4661        assert_eq!(v["texts"][0]["parent"]["$ref"], "#/groups/0");
4662        assert_eq!(v["texts"][1]["parent"]["$ref"], "#/groups/0");
4663        assert_eq!(v["pictures"][0]["children"], serde_json::json!([]));
4664        assert_eq!(v["tables"][0]["children"], serde_json::json!([]));
4665    }
4666
4667    /// A PDF footnote (#620 follow-up): the JSON keeps docling's
4668    /// `footnote` label, the raw text and the link as `hyperlink`; the
4669    /// Markdown still wraps the whole item as `[text](uri)`, and the plain
4670    /// text drops the link like docling-core's `export_to_text`.
4671    #[test]
4672    fn a_labeled_text_keeps_its_label_and_hyperlink_out_of_the_text() {
4673        let mut doc = DoclingDocument::new("t");
4674        doc.push(Node::LabeledText {
4675            label: "footnote".into(),
4676            text: "1 https://example.com/a\\_b".into(),
4677            href: Some("https://example.com/a_b".into()),
4678        });
4679        doc.push(Node::LabeledText {
4680            label: "footnote".into(),
4681            text: "© 2022 the authors".into(),
4682            href: None,
4683        });
4684        let v: Value = serde_json::from_str(&doc.export_to_json()).unwrap();
4685        let t = &v["texts"][0];
4686        assert_eq!(t["label"], "footnote");
4687        assert_eq!(t["text"], "1 https://example.com/a_b");
4688        assert_eq!(t["orig"], "1 https://example.com/a_b");
4689        assert_eq!(t["hyperlink"], "https://example.com/a_b");
4690        assert_eq!(v["texts"][1]["label"], "footnote");
4691        assert!(v["texts"][1].get("hyperlink").is_none());
4692        assert_eq!(
4693            doc.export_to_markdown(),
4694            "[1 https://example.com/a\\_b](https://example.com/a_b)\n\n© 2022 the authors\n"
4695        );
4696        assert_eq!(
4697            doc.export_to_text(),
4698            "1 https://example.com/a_b\n\n© 2022 the authors"
4699        );
4700    }
4701}