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