Skip to main content

docling_core/
json.rs

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