Skip to main content

docling_core/
document.rs

1//! The unified document representation.
2
3use crate::markdown::{to_markdown, to_markdown_images};
4use crate::ImageMode;
5
6/// The unified, format-agnostic document produced by every backend.
7///
8/// This is the heart of docling: backends parse their source format into a
9/// `DoclingDocument`, and serializers turn it back into Markdown, HTML, JSON,
10/// etc. Phase 0 uses a flat sequence of [`Node`]s; the production schema will
11/// match docling-core's body-tree-with-references layout.
12#[derive(Debug, Clone, PartialEq)]
13pub struct DoclingDocument {
14    /// Logical document name (usually the input file stem).
15    pub name: String,
16    /// Top-level content, in reading order.
17    pub nodes: Vec<Node>,
18    /// Default Markdown export mode for [`Self::export_to_markdown`]. `false`
19    /// (the default) reproduces docling's legacy output byte-for-byte; `true`
20    /// emits cleaner, more conformant Markdown. Set by `DocumentConverter`.
21    pub strict_markdown: bool,
22    /// Emit tables in the compact `| a | b |` / `| - | - |` form rather than
23    /// docling-core's width-padded GitHub serializer. The PDF backend sets this
24    /// (its committed groundtruth corpus predates the padded serializer); DOCX/HTML
25    /// leave it `false` to match current published docling.
26    pub compact_tables: bool,
27    /// Render a picture's author-written alt text (#676: the `descr` /
28    /// `title` of an OOXML picture's non-visual properties, carried as a
29    /// [`PictureDescription`] whose provenance is
30    /// [`PictureDescription::ALT_TEXT`]) in the Markdown and HTML exports
31    /// (the `![alt](…)` of an image line or the line above a placeholder;
32    /// the `<img alt>` and the description text). `false` (the default)
33    /// keeps it to the JSON (and DCLX) output, so the default Markdown and
34    /// HTML stay byte-for-byte docling's; strict Markdown renders it
35    /// regardless. Set by `DocumentConverter::picture_alt_text`.
36    pub picture_alt_text: bool,
37    /// What the file says about itself (#679): an EPUB's Dublin Core, an
38    /// Office package's properties, a photo's EXIF, an audio file's tags —
39    /// see [`crate::metadata`]. Read by the converter when
40    /// [`metadata_output`](Self::metadata_output) asks for it (a document
41    /// read from docling JSON keeps the `metadata` the JSON carried).
42    pub metadata: crate::metadata::DocumentMetadata,
43    /// Where [`metadata`](Self::metadata) goes in the exports: nowhere (the
44    /// default — every export stays docling's), the JSON's `metadata`
45    /// object, or that and YAML front matter at the top of the Markdown.
46    /// Set by `DocumentConverter::metadata_output`.
47    pub metadata_output: crate::metadata::MetadataOutput,
48    /// Text the Markdown export inserts between two pages — docling-core's
49    /// `MarkdownParams.page_break_placeholder` (e.g. `"<!-- page break -->"`).
50    /// `None` (the default) omits page breaks from Markdown, as docling does.
51    /// Set by `DocumentConverter::page_break_placeholder`. See
52    /// [`crate::markdown`] for where a break lands (only between two rendered
53    /// blocks that sit on different pages, never leading or trailing).
54    pub page_break_placeholder: Option<String>,
55    /// Hyperlinks recovered from the source, as `(anchor_text, href)` pairs in
56    /// document order. docling's standard pipeline drops PDF link annotations, so
57    /// these are rendered as Markdown `[anchor](href)` **only in strict mode**
58    /// (legacy/docling output is left byte-for-byte unchanged). The PDF backend
59    /// populates this from pdfium link annotations; other backends leave it empty.
60    pub links: Vec<(String, String)>,
61    /// Conversion-confidence report (#183), populated by the PDF/image ML
62    /// pipeline; `None` for declarative conversions. Deliberately **not**
63    /// part of any document export (docling keeps it on the conversion
64    /// result, outside the document schema) — docling-serve surfaces it in
65    /// the HTTP response instead.
66    pub confidence: Option<crate::confidence::ConfidenceReport>,
67    /// docling's item tree, when the backend built one (the HTML backend
68    /// does): the JSON export serializes it instead of deriving a tree from
69    /// `nodes`, so the JSON carries upstream's exact parent/child structure,
70    /// item numbering, inline groups, formatting and content layers. Every
71    /// other serializer reads `nodes`. See [`crate::tree`].
72    pub tree: Option<crate::tree::ItemTree>,
73    /// Rendered page images by 1-based page number — docling's
74    /// `PageItem.image`, filled by the PDF/image pipeline only when page
75    /// images are requested (docling's `generate_page_images`, #520). The
76    /// JSON export writes each as the page's `image`, so docling-core's
77    /// `TableItem.get_image` / `FormulaItem.get_image` can crop from it.
78    /// Empty otherwise; no other export reads it.
79    pub page_images: std::collections::BTreeMap<usize, PictureImage>,
80    /// What the reader ran into and read around (#912): a limit it hit —
81    /// an HTML page nested past `DOCLING_RS_MAX_HTML_DEPTH`, read as flat
82    /// text with no item tree and no source blocks — named, with the
83    /// effective limit, so a caller sees why the document lacks what it
84    /// lacks instead of an unexplained success. The converter reports each
85    /// as a `partial_success` error item.
86    pub notices: Vec<Notice>,
87}
88
89/// Something the reader did instead of what it does by default (#912),
90/// with the reason — see [`DoclingDocument::notices`].
91#[derive(Debug, Clone, PartialEq, Eq)]
92pub struct Notice {
93    pub kind: NoticeKind,
94    /// One line: what was hit, the effective limit, what the document
95    /// lacks because of it.
96    pub message: String,
97}
98
99/// What a [`Notice`] is about.
100#[derive(Debug, Clone, PartialEq, Eq)]
101pub enum NoticeKind {
102    /// The source nests deeper than the cap `variable` sets (its effective
103    /// value `limit`): it was read as flat text — the content is there,
104    /// the item tree and the source blocks are not.
105    DepthLimit {
106        /// The environment variable that sets the cap.
107        variable: &'static str,
108        limit: usize,
109    },
110}
111
112impl Notice {
113    /// A [`NoticeKind::DepthLimit`] notice for `what` (the format read).
114    pub fn depth_limit(what: &str, variable: &'static str, limit: usize) -> Self {
115        Notice {
116            kind: NoticeKind::DepthLimit { variable, limit },
117            message: format!(
118                "{what} nested deeper than {limit} elements ({variable}): read as flat text, \
119                 without the item tree and the source blocks"
120            ),
121        }
122    }
123}
124
125/// A single piece of document content.
126#[derive(Debug, Clone, PartialEq)]
127pub enum Node {
128    /// A heading. `level` is 1-6.
129    Heading { level: u8, text: String },
130    /// A run of body text.
131    Paragraph { text: String },
132    /// A form checkbox (docling's `checkbox_selected`/`checkbox_unselected`): its
133    /// clean label `text` with the checked state. DocLang emits a `<checkbox>`
134    /// element head; Markdown/JSON render the task-list form (`- [x] `/`- [ ] `).
135    CheckboxItem { checked: bool, text: String },
136    /// A single list item at the given nesting `level` (0 = top). For ordered
137    /// items, `number` is the display number (honoring the list's `start`); it
138    /// is unused for unordered items. `first_in_list` marks the first item of a
139    /// list so the serializer can blank-line-separate adjacent sibling lists.
140    ///
141    /// `marker` is the DocLang enumeration marker (`"1."`, `"1.1."`, …) when the
142    /// backend provides one — HTML and DOCX set it for enumerated items, so
143    /// DocLang emits `<ldiv><marker>…</marker></ldiv>`; Markdown and the other
144    /// declarative backends leave it `None`, giving a bare `<ldiv/>` (matching
145    /// docling, whose Markdown backend passes no marker).
146    ListItem {
147        ordered: bool,
148        number: u64,
149        first_in_list: bool,
150        text: String,
151        level: u8,
152        marker: Option<String>,
153        /// Optional layout provenance (`x0,y0,x1,y1`, normalized to 0–511): the
154        /// four DocLang `<location>` values emitted inside the `<list>` right
155        /// after the item's `<ldiv>`. Set only by backends with real geometry
156        /// (e.g. PPTX shapes); `None` for the declarative backends. Kept on the
157        /// item itself (rather than a [`Node::Located`] wrapper) so consecutive
158        /// items still group into one `<list>`.
159        location: Option<[u16; 4]>,
160        /// DocLang-only override for items whose DocLang form diverges from their
161        /// flat Markdown `text`. Markdown/JSON always render the fields above; the
162        /// DocLang serializer, when this is `Some`, takes the list kind, marker,
163        /// and content from here instead. Used for docx multilevel numbering
164        /// (Markdown shows `- 1.1. x`, DocLang an ordered `<marker>1.1.</marker>`
165        /// with clean text) and inline equations/formatting in list items.
166        dclx: Option<ListItemDclx>,
167        /// JSON-only: the item as docling's `ListItemMarkerProcessor` leaves
168        /// it on a page pipeline (PDF) — `orig` with the marker, `text`
169        /// without it, the marker itself and whether it enumerates. Markdown
170        /// and DocLang keep reading the fields above, whose spelling follows
171        /// docling-core's serializers (`- [3] text` is a bullet item there).
172        /// `None` for every other backend: the JSON then writes `text` twice
173        /// and `-` or `N.` as before.
174        split: Option<Box<ListItemSplit>>,
175        /// The item's hyperlink target, when its content is a link — docling's
176        /// HTML backend emits it as an `<href uri=…/>` in the item head, and the
177        /// anchor's Markdown link markup is stripped from the rendered content.
178        /// `None` for a plain item; ignored by Markdown/JSON.
179        href: Option<String>,
180        /// Non-body content layer (docling's HTML site chrome before the first
181        /// heading → `furniture`). DocLang emits a `<layer value=…/>` in the item
182        /// head; Markdown/JSON drop a non-body item entirely.
183        layer: Option<ContentLayer>,
184    },
185    /// A fenced code block.
186    Code {
187        language: Option<String>,
188        text: String,
189        /// The original (pre-enrichment) text when the CodeFormula model
190        /// rewrote `text`: docling keeps the raw extraction in the JSON `orig`
191        /// field while `text` carries the model output. `None` → `orig == text`.
192        orig: Option<String>,
193        /// A line-preserving rendering, when the backend can reconstruct one
194        /// but docling's own output for the format cannot. The PDF pipeline
195        /// sets it (docling-parse joins code lines with single spaces, so
196        /// `text` carries that flat docling-parity form): **strict** Markdown
197        /// prefers `pretty`, every byte-conformance surface (legacy Markdown,
198        /// JSON, DocLang, chunks) serializes `text`.
199        pretty: Option<String>,
200    },
201    /// A table. The first row is treated as the header.
202    Table(Table),
203    /// A picture/figure, with an optional caption and (when a backend extracts
204    /// it) the embedded image itself.
205    Picture {
206        caption: Option<String>,
207        /// Hyperlink annotation on the caption (docling's caption text item
208        /// `hyperlink`): the HTML backend sets it when an `<a href>` wraps the
209        /// image whose `alt` became the caption. DocLang emits the block-form
210        /// `<caption>` with an `<href uri=…/>` head; JSON puts `hyperlink` on
211        /// the caption item; Markdown and LaTeX print the plain caption text,
212        /// as docling does.
213        caption_href: Option<String>,
214        image: Option<PictureImage>,
215        /// DocumentPictureClassifier predictions (all classes, descending
216        /// confidence), when the picture-classification enrichment ran.
217        /// Serialized as docling's `classification` annotation + `meta` field
218        /// on the JSON picture item; Markdown/DocLang output is unaffected.
219        classification: Option<Vec<PictureClass>>,
220        /// Text read off the embedded image by the picture-OCR enrichment
221        /// (#645) — docling's `PictureDescriptionData` annotation /
222        /// `meta.description`, which is where upstream's picture-description
223        /// models (VLM captioning) put their text too. JSON and DCLX carry it
224        /// structurally; Markdown prints it between the caption and the
225        /// image placeholder, where docling's picture serializer renders
226        /// annotations. `None` when the enrichment did not run or read no
227        /// text, so every default export stays unchanged.
228        description: Option<PictureDescription>,
229        /// Where the caption item hangs in the JSON tree (#390); see
230        /// [`CaptionParent`]. Markdown, DocLang and LaTeX ignore it.
231        caption_parent: CaptionParent,
232        /// The caption's own box on the picture's page (0–511 grid, like
233        /// [`Node::Located`]) — the PDF pipeline's caption layout region. The
234        /// JSON export writes it as the caption item's `prov` (#609), as
235        /// docling's `ReadingOrderModel._add_caption_or_footnote` does; `None`
236        /// (every declarative backend) leaves the caption without one.
237        caption_location: Option<[u16; 4]>,
238    },
239    /// A display-math formula item decoded by the CodeFormula enrichment:
240    /// `latex` is the model's LaTeX (no `$$` wrapping), `orig` the raw glyph
241    /// text extracted from the PDF. Markdown renders `$$latex$$`; JSON emits a
242    /// `formula` text item (docling's un-enriched pipeline instead emits a
243    /// placeholder paragraph — see the PDF assembler).
244    Formula {
245        latex: String,
246        orig: String,
247        location: Option<[u16; 4]>,
248    },
249    /// A standalone caption item (docling's `DocItemLabel.CAPTION` text that
250    /// no picture or table claims): the HTML backend emits a `<figure>`'s
251    /// `<figcaption>` this way when the figure produced no picture and its
252    /// first item is not a table (docling#4050). `href` is the caption's
253    /// hyperlink annotation (the first link inside the figcaption); Markdown
254    /// renders it as `[text](href)`, JSON puts `hyperlink` on the caption
255    /// item, DocLang emits the block-form `<caption>` with an `<href>` head.
256    Caption { text: String, href: Option<String> },
257    /// A body text item with a docling label of its own and an optional
258    /// hyperlink — the PDF pipeline's `footnote` regions, whose item docling
259    /// keeps as a `footnote` text with the link annotation covering it as its
260    /// `hyperlink` (`PageAssembleModel._match_hyperlink`). The JSON writes
261    /// exactly that (label, raw text, `hyperlink`); every other serializer
262    /// renders it as the paragraph [`Self::labeled_markdown`] spells —
263    /// docling's Markdown wraps a linked item's whole text, `[text](uri)`.
264    LabeledText {
265        label: String,
266        text: String,
267        href: Option<String>,
268    },
269    /// A chart (docling's `PictureItem` classified as a chart, carrying a
270    /// `PictureTabularChartData` annotation). Markdown and JSON render it exactly
271    /// like a [`Node::Picture`] placeholder (an `<!-- image -->` / `picture`
272    /// item); the DocLang serializer emits `<picture class="chart">` with a
273    /// `<label value="{kind}"/>` and the data `table` as a `<tabular>`.
274    Chart {
275        /// docling's classification label, e.g. `bar_chart`, `line_chart`.
276        kind: String,
277        /// The chart's data grid (row 0 is the header band).
278        table: Table,
279        /// The chart title (docling's caption item on the picture).
280        caption: Option<String>,
281        /// DocLang `<location>` provenance for the picture element.
282        location: Option<[u16; 4]>,
283    },
284    /// A logical grouping of child nodes (e.g. a list, a section, a spreadsheet
285    /// sheet). `name` is docling's group name when it differs from the label —
286    /// an xlsx sheet group is `label: "sheet"`, `name: Some("Sheet1")`. `layer`
287    /// puts the group *and* everything it contains on a non-body content layer
288    /// (a hidden sheet is `invisible`), which is how the serializers that only
289    /// render body content know to skip it; DocLang stamps each child with the
290    /// layer token, exactly as a [`Node::Furniture`] wrapper on each would.
291    /// DocLang has no group element, so a group is transparent there.
292    Group {
293        label: String,
294        name: Option<String>,
295        layer: Option<ContentLayer>,
296        children: Vec<Node>,
297    },
298    /// A form key-value region (docling's `field_region`): a set of form fields,
299    /// each pairing an optional marker, key, and value. Backends detect these
300    /// from form structure (e.g. HTML's `keyN` / `keyN_valueM` / `keyN_marker`
301    /// `id`-convention); the serializers render each item's parts as separate
302    /// labelled texts (`marker` / `field_key` / `field_value`).
303    FieldRegion { items: Vec<FieldItem> },
304    /// docling's `KeyValueItem`: a graph of key and value cells and the links
305    /// between them (docling-core's `GraphData`). The XBRL backend builds one
306    /// from an instance's numeric facts and the presentation and calculation
307    /// hierarchies of its taxonomy. Only the JSON export carries the graph:
308    /// docling's Markdown serializer has no rendering for the item and writes
309    /// its `<!-- missing-key-value-item -->` placeholder, which the Markdown
310    /// export reproduces; the other serializers omit it.
311    KeyValueGraph {
312        cells: Vec<GraphCell>,
313        links: Vec<GraphLink>,
314    },
315    /// Rich inline content — docling's `InlineGroup`: a run of styled text
316    /// segments that a backend captured with formatting (`<bold>`, `<italic>`,
317    /// `<underline>`, `<strikethrough>`, sub/superscript, inline `<code>`) the
318    /// flat Markdown text cannot represent. Markdown/JSON render this exactly
319    /// like `Paragraph { text: md_text }` (so their output is unchanged); the
320    /// DocLang serializer uses the structured `runs`. `unwrapped` is set when the
321    /// group's docling parent is a heading/text (no enclosing `<text>` wrapper).
322    InlineGroup {
323        unwrapped: bool,
324        runs: Vec<InlineRun>,
325        md_text: String,
326    },
327    /// A PDF text item whose superscripts and subscripts the opt-in
328    /// script-position stage marked (#1005, docling's `ScriptPositionModel`,
329    /// `script_position_options.enabled`). `inner` is the item — a paragraph
330    /// or a footnote — with its text already the runs' joined text (Markdown-
331    /// escaped, `E = mc2 in 1905.`): every serializer but JSON and DocLang
332    /// renders it as it is. The JSON writes docling's shape — the item with
333    /// an empty `text`, holding an inline group of the runs, each a text item
334    /// with `formatting.script` and the box of its own characters — and
335    /// DocLang writes the runs as an inline group.
336    ScriptText {
337        inner: Box<Node>,
338        runs: Vec<ScriptRun>,
339    },
340    /// A node in a non-body content layer — `furniture` (page headers/footers,
341    /// the HTML `<title>`, site navigation/chrome) or `notes` (docx comments).
342    /// Markdown and JSON omit these layers by default; DocLang renders the wrapped
343    /// node with a `<layer value="{layer}"/>` head.
344    Furniture {
345        layer: ContentLayer,
346        inner: Box<Node>,
347    },
348    /// One reviewer comment: docling's notes-layer `comment_section` group
349    /// holding a single text item. `name` is docling's own — `comment-{id}` for
350    /// a docx `w:comment`, `comment-{sheet}-{cell}` for a spreadsheet cell note.
351    /// JSON emits the group plus its notes-layer text; DocLang emits the flat
352    /// `<text><layer value="notes"/>…</text>` upstream writes (its DocLang
353    /// carries no group for comments); Markdown and LaTeX omit the notes layer.
354    ///
355    /// `refs_note_text` picks what a [`Node::Commented`] annotation points at,
356    /// mirroring an upstream asymmetry: docling-core's `add_comment` appends the
357    /// **note text**'s ref to each target (which is what the xlsx backend gets),
358    /// while the docx backend overwrites that with the **group**'s ref so a
359    /// comment's replies group together.
360    ///
361    /// `grouped` is whether docling wraps the note in a `comment_section`
362    /// group at all: the docx and spreadsheet backends do, while backends that
363    /// call docling-core's `add_comment` directly (Pages, #383) get a bare
364    /// notes-layer text item under the body — JSON then emits no group and
365    /// `name` is unused.
366    CommentSection {
367        name: String,
368        text: String,
369        refs_note_text: bool,
370        grouped: bool,
371    },
372    /// A body item annotated by reviewer comments: `comments` are indices into
373    /// the document's [`Node::CommentSection`] nodes, in document order. JSON
374    /// emits docling's `comments: [{"$ref": …}]` on the item, each ref pointing
375    /// where the section says (see [`Node::CommentSection::refs_note_text`]);
376    /// every other serializer renders `inner` unchanged.
377    Commented {
378        comments: Vec<usize>,
379        inner: Box<Node>,
380    },
381    /// A text node taken from a time-based track — an ASR segment (#614):
382    /// A link destination (#852: a `.doc` bookmark; the DOCX item tree
383    /// keeps its own, #849): the identifier the document's internal links
384    /// (`#id`) point at. Rendered by nothing but the JSON builder, which
385    /// hands it to the next text item for the Pandoc AST (`_anchors`).
386    Anchor { id: String },
387    /// docling's `TrackSource`. The JSON writes docling's ASR text item — `cue`
388    /// (the segment's words) as its text, `track` as its `source: [{"kind":
389    /// "track", …}]` — which the WebVTT export makes a cue of; every other
390    /// serializer renders `inner` (the `[time: start-end] words` paragraph)
391    /// unchanged.
392    Track {
393        track: crate::tree::TreeTrack,
394        cue: String,
395        inner: Box<Node>,
396    },
397    /// A node carrying layout provenance — the four DocLang `<location>` values
398    /// (`x0,y0,x1,y1`, normalized to 0–511) docling attaches to elements from
399    /// backends with real geometry (e.g. the slide shapes in PPTX). Markdown and
400    /// JSON render the wrapped node unchanged; DocLang emits the `<location>`
401    /// tokens as the element's first children.
402    Located {
403        location: [u16; 4],
404        inner: Box<Node>,
405    },
406    /// Exact page provenance for a backend whose geometry already *is* the
407    /// page's coordinate system — an XLSX item's cell-index box on its sheet,
408    /// which docling writes verbatim (`bbox` in a top-left origin, the
409    /// `charspan` the backend chose) and sizes the page from. The 0–511 grid
410    /// of a [`Node::Located`] cannot round-trip such integers exactly, so the
411    /// JSON export reads this wrapper; every other serializer renders `inner`
412    /// unchanged (DocLang keeps taking its `<location>` tokens from the grid).
413    Prov {
414        page_no: usize,
415        /// `[l, t, r, b]`, page units, top-left origin.
416        bbox: [f32; 4],
417        /// docling's `charspan` for the item (`[0, 0]` for an XLSX table).
418        charspan: [usize; 2],
419        /// The bbox's origin: docling's `BOTTOMLEFT` (a PDF page's
420        /// provenance, as a docling-JSON input carries it — #899) or
421        /// `TOPLEFT` (an XLSX sheet's cell box).
422        bottom_left: bool,
423        /// The item's creation rank among its siblings, when that differs
424        /// from the node order: docling numbers `#/tables/N` / `#/texts/N` /
425        /// `#/pictures/N` in the order it *creates* items (a sheet's tables,
426        /// then its images, then its charts) and only afterwards sorts the
427        /// container's children by position. The JSON export adds siblings in
428        /// this order and lays their refs out in node order; `None` when the
429        /// two orders coincide.
430        seq: Option<usize>,
431        inner: Box<Node>,
432    },
433    /// A PDF page header or footer (docling's `page_header`/`page_footer`
434    /// furniture): DocLang emits `<page_header>`/`<page_footer>` with a
435    /// `<layer value="furniture"/>` head, the four `<location>` tokens, then the
436    /// text. The JSON writes it as a body-parented `page_header`/`page_footer`
437    /// text item on the furniture layer; Markdown omits it.
438    PageFurniture {
439        footer: bool,
440        location: [u16; 4],
441        text: String,
442    },
443    /// A furniture-layer text item with an explicit docling label — a page
444    /// header / footer paragraph (`page_header` / `page_footer`) or a note
445    /// body (`footnote`) from a backend that builds no item tree (#535: the
446    /// Word 97 `.doc` stories). The JSON writes a body-parented item of that
447    /// label on the furniture layer; DocLang `<{label}>` with a `<layer
448    /// value="furniture"/>` head (docling-core's own shape); Markdown, LaTeX
449    /// and the chunker leave it out like any furniture.
450    FurnitureText { label: String, text: String },
451    /// The text a PDF picture contains, kept the way docling keeps it: every
452    /// regular layout cluster > 80 % inside a picture cluster is that
453    /// `PictureItem`'s child (`LayoutPostprocessor._set_cluster_children`,
454    /// `ReadingOrderModel._add_child_elements`). Emitted right after its
455    /// picture node. The JSON export writes these nodes as items parented to
456    /// that picture, after its caption; docling's Markdown and LaTeX picture
457    /// serializers print only the caption and the image, so every other
458    /// serializer skips it — except the Markdown export asked to
459    /// `traverse_pictures` ([`MarkdownExportOptions`], #599), which renders
460    /// them after the picture like upstream's item walk does.
461    PictureChildren(Vec<Node>),
462    /// A page boundary — docling's implicit page break between pages. The PPTX
463    /// backend emits one between consecutive slides. DocLang renders it as
464    /// `<page_break/>`; Markdown and JSON omit it (matching docling's default
465    /// exports, which carry page breaks only in the document model).
466    PageBreak,
467    /// A text item docling hangs in a *list group*, after the item before it
468    /// (an AsciiDoc paragraph still pending when a list opened is flushed into
469    /// the list's group): docling-core's list serializer prints it as one more
470    /// line of the list, indented to the group's depth `level` — or, `glue`,
471    /// when it is an inline group, appended to the line before it with no
472    /// separator at all. `text` is Markdown, like a paragraph's. Every other
473    /// serializer reads it as a paragraph.
474    ListText { level: u8, text: String, glue: bool },
475    /// An invisible page marker — the first node of every page the PDF paths
476    /// assemble: the 1-based page number and the page size in PDF points. It
477    /// carries exactly what the JSON export needs to populate docling's
478    /// `pages` map and to denormalize the 0–511 `<location>` grid back into
479    /// BOTTOMLEFT point bboxes for per-item `prov` (#171). Every other
480    /// serializer skips it, so Markdown / DocLang / DocTags output is
481    /// byte-for-byte unchanged.
482    PageInfo {
483        /// 1-based page number (0 = "not yet numbered": the assembler emits
484        /// the marker, the document-level collector stamps the real number).
485        page_no: usize,
486        /// Page width in PDF points.
487        width: f32,
488        /// Page height in PDF points.
489        height: f32,
490    },
491    /// One more provenance fragment of the last located text item before it
492    /// (#1127): a PDF paragraph the assembler joined across a page break keeps
493    /// the continuation's box this way, as an invisible marker right after the
494    /// joined paragraph; its grid box is on the page `page_skip` page markers
495    /// further on, numbered and sized like every other location there.
496    /// docling's merged `TextItem` lists one `prov` per fragment
497    /// (`ReadingOrderModel`: the first fragment's, then each continuation's
498    /// with its `charspan` into the joined text); the JSON export appends this
499    /// fragment to that item's `prov` once it reaches the fragment's page,
500    /// first ending the entry before it at `prev_end`. Every other serializer
501    /// skips it.
502    ProvContinuation {
503        /// The continuation's box on its page, the 0–511 `<location>` grid.
504        location: [u16; 4],
505        /// Where the fragment before this one ends, in characters of the
506        /// item's (unescaped) text: that entry's `charspan` end.
507        prev_end: usize,
508        /// This fragment's `charspan` in the item's (unescaped) text.
509        span: [usize; 2],
510        /// How many [`Node::PageInfo`] markers follow before the fragment's
511        /// page (1 = the next page). The marker stands right after its item
512        /// — nothing a later pass inserts can come between them — so its page
513        /// is counted rather than implied by position.
514        page_skip: usize,
515    },
516    /// A node docling keeps in the document model (and DocLang) but leaves out
517    /// of the Markdown and JSON exports — e.g. an ODF *presentation*'s pictures
518    /// and charts, which appear in the `.dclx` body but not in its `.md`/`.json`.
519    /// DocLang renders the wrapped node in place; Markdown and JSON skip it.
520    DoclangOnly(Box<Node>),
521    /// A verbatim plain-text dump: one text item holding text whose line
522    /// breaks are content (a nested table flattened to its cells' text, an
523    /// ODF text box's raw text). Markdown/JSON render it as one text block,
524    /// DocLang as one `<text>` whose `<content>` keeps the breaks.
525    TextDump(String),
526}
527
528/// One run of a [`Node::ScriptText`]: a piece of the item's text at one
529/// script position, with its provenance — one entry per page it is on.
530#[derive(Debug, Clone, PartialEq)]
531pub struct ScriptRun {
532    /// The run's raw text (not Markdown-escaped), its spaces included:
533    /// serializers join runs with nothing.
534    pub text: String,
535    pub script: Script,
536    /// The run's provenance, one per page, in text order.
537    pub prov: Vec<ScriptRunProv>,
538    /// The item's link, on its baseline runs (each linked run exports as a
539    /// link of its own, so a marker stays out of it).
540    pub hyperlink: Option<String>,
541}
542
543/// Where a [`ScriptRun`] sits on one page: docling's `ProvenanceItem` with a
544/// bottom-left-origin box.
545#[derive(Debug, Clone, Copy, PartialEq)]
546pub struct ScriptRunProv {
547    /// 1-based page number.
548    pub page_no: usize,
549    /// `[l, t, r, b]`, PDF points, bottom-left origin (`t > b`).
550    pub bbox: [f32; 4],
551    /// The run's characters on this page, as a span of its `text`.
552    pub charspan: [usize; 2],
553}
554
555/// Vertical text position of an [`InlineRun`] — docling's `Script`.
556#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
557pub enum Script {
558    #[default]
559    Baseline,
560    Sub,
561    Super,
562}
563
564/// One styled segment of a [`Node::InlineGroup`] — the docling.rs analogue of a
565/// `TextItem` inside an `InlineGroup`, carrying the ancestor formatting docling
566/// tracks. `text` is already whitespace-normalized/trimmed (one segment per
567/// source text node). A hyperlink is intentionally not stored: DocLang drops the
568/// target inside inline scope, keeping only the anchor text.
569#[derive(Debug, Clone, PartialEq, Eq, Default)]
570pub struct InlineRun {
571    pub text: String,
572    pub bold: bool,
573    pub italic: bool,
574    pub underline: bool,
575    pub strike: bool,
576    pub script: Script,
577    pub code: bool,
578    /// An inline equation (`text` holds LaTeX): DocLang renders `<formula>…`,
579    /// Markdown/JSON keep the `$…$` already baked into the group's `md_text`.
580    pub formula: bool,
581}
582
583/// A DocLang content layer other than the default `body` (see [`Node::Furniture`]).
584#[derive(Debug, Clone, Copy, PartialEq, Eq)]
585pub enum ContentLayer {
586    /// Page headers/footers, HTML `<title>`, site navigation/chrome.
587    Furniture,
588    /// Editorial notes (docx reviewer comments).
589    Notes,
590    /// Invisible content (hidden spreadsheet sheets).
591    Invisible,
592    /// Background content (watermarks): docling-core 2.99's `background`
593    /// layer, which DocLang has and an `invisible` item is written to
594    /// (docling-core#800) — read back from a DocLang document.
595    Background,
596}
597
598impl ContentLayer {
599    /// The `<layer value="…"/>` token value.
600    pub fn value(self) -> &'static str {
601        match self {
602            ContentLayer::Furniture => "furniture",
603            ContentLayer::Notes => "notes",
604            ContentLayer::Invisible => "invisible",
605            ContentLayer::Background => "background",
606        }
607    }
608}
609
610/// A set of content layers, `body` included — docling-core's
611/// `set[ContentLayer]` (`HTMLParams.layers`,
612/// `export_to_html(included_content_layers=…)`), where `body` is a member
613/// like any other. [`Default`] is docling's `DEFAULT_CONTENT_LAYERS`: body
614/// only, so an export built with it is unchanged from before layers could
615/// be chosen (#499).
616#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
617pub struct ContentLayers {
618    /// The main content (items without an explicit layer).
619    pub body: bool,
620    /// [`ContentLayer::Furniture`]: page headers/footers, navigation chrome.
621    pub furniture: bool,
622    /// [`ContentLayer::Notes`]: reviewer comments and other editorial notes.
623    pub notes: bool,
624    /// [`ContentLayer::Invisible`]: hidden content (hidden sheets, …).
625    pub invisible: bool,
626    /// [`ContentLayer::Background`]: background content (watermarks).
627    pub background: bool,
628}
629
630impl Default for ContentLayers {
631    fn default() -> Self {
632        Self::BODY
633    }
634}
635
636impl ContentLayers {
637    /// Body only — docling's `DEFAULT_CONTENT_LAYERS`.
638    pub const BODY: Self = Self {
639        body: true,
640        furniture: false,
641        notes: false,
642        invisible: false,
643        background: false,
644    };
645    /// Every layer — Python's `set(ContentLayer)`.
646    pub const ALL: Self = Self {
647        body: true,
648        furniture: true,
649        notes: true,
650        invisible: true,
651        background: true,
652    };
653    /// No layer at all (nothing renders); build a set from it with
654    /// [`with`](Self::with) / [`with_body`](Self::with_body).
655    pub const NONE: Self = Self {
656        body: false,
657        furniture: false,
658        notes: false,
659        invisible: false,
660        background: false,
661    };
662
663    /// The set plus `layer`.
664    pub const fn with(mut self, layer: ContentLayer) -> Self {
665        match layer {
666            ContentLayer::Furniture => self.furniture = true,
667            ContentLayer::Notes => self.notes = true,
668            ContentLayer::Invisible => self.invisible = true,
669            ContentLayer::Background => self.background = true,
670        }
671        self
672    }
673
674    /// The set plus the body layer.
675    pub const fn with_body(mut self) -> Self {
676        self.body = true;
677        self
678    }
679
680    /// Whether `layer` is in the set; `None` is the body layer.
681    pub fn contains(&self, layer: Option<ContentLayer>) -> bool {
682        match layer {
683            None => self.body,
684            Some(ContentLayer::Furniture) => self.furniture,
685            Some(ContentLayer::Notes) => self.notes,
686            Some(ContentLayer::Invisible) => self.invisible,
687            Some(ContentLayer::Background) => self.background,
688        }
689    }
690
691    /// Whether the layer spelled `name` (`body`, `furniture`, `notes`,
692    /// `invisible`, `background` — the JSON `content_layer` values) is in
693    /// the set; an unknown name is not.
694    pub fn contains_name(&self, name: &str) -> bool {
695        match name {
696            "body" => self.body,
697            "furniture" => self.furniture,
698            "notes" => self.notes,
699            "invisible" => self.invisible,
700            "background" => self.background,
701            _ => false,
702        }
703    }
704
705    /// Parse a comma-separated list of layer names (`body,furniture`;
706    /// whitespace around a name is ignored, `all` is every layer). An
707    /// unknown name is the error.
708    pub fn parse_list(list: &str) -> Result<Self, String> {
709        let mut set = Self::NONE;
710        for name in list.split(',').map(str::trim).filter(|n| !n.is_empty()) {
711            match name {
712                "body" => set.body = true,
713                "furniture" => set.furniture = true,
714                "notes" => set.notes = true,
715                "invisible" => set.invisible = true,
716                "background" => set.background = true,
717                "all" => set = Self::ALL,
718                other => {
719                    return Err(format!(
720                        "unknown content layer `{other}` (expected body, furniture, notes, invisible, background or all)"
721                    ))
722                }
723            }
724        }
725        Ok(set)
726    }
727}
728
729/// Options of the HTML export ([`DoclingDocument::export_to_html_with`]):
730/// docling-core's `HTMLParams` subset the port honours. [`Default`] is
731/// upstream's default export — placeholder images, `artifacts` as the
732/// referenced-image directory, the body layer only.
733#[derive(Debug, Clone, PartialEq, Eq)]
734pub struct HtmlExportOptions {
735    /// How pictures render (`HTMLParams.image_mode`): nothing but captions
736    /// and meta for [`ImageMode::Placeholder`], `data:` URIs when embedded,
737    /// `<img src>` paths under [`artifacts_dir`](Self::artifacts_dir) when
738    /// referenced.
739    pub image_mode: ImageMode,
740    /// The directory referenced images are named under, the Markdown
741    /// export's convention (`<artifacts_dir>/image_NNNNNN.<ext>`).
742    pub artifacts_dir: String,
743    /// The content layers rendered (`HTMLParams.layers`, #499): an item on a
744    /// layer outside the set is skipped, its children still walked — exactly
745    /// how docling-core's `get_excluded_refs` reads the set.
746    pub layers: ContentLayers,
747}
748
749impl Default for HtmlExportOptions {
750    fn default() -> Self {
751        Self {
752            image_mode: ImageMode::Placeholder,
753            artifacts_dir: "artifacts".to_string(),
754            layers: ContentLayers::BODY,
755        }
756    }
757}
758
759/// Options of the Markdown export
760/// ([`DoclingDocument::export_to_markdown_with_options`], #599): the
761/// docling-core `MarkdownParams` the port honours beyond the image mode.
762/// [`Default`] is upstream's default export — placeholder images,
763/// `artifacts` as the referenced-image directory, the body layer only, no
764/// picture traversal, HTML and underscore escaping on, `<!-- image -->` —
765/// so a document exported with it is byte-identical to
766/// [`DoclingDocument::export_to_markdown`].
767#[derive(Debug, Clone, PartialEq, Eq)]
768pub struct MarkdownExportOptions {
769    /// How pictures render (`MarkdownParams.image_mode`): the placeholder,
770    /// `data:` URIs when embedded, `![Image](<artifacts_dir>/image_NNNNNN.<ext>)`
771    /// when referenced (the bytes come back for the caller to write).
772    pub image_mode: ImageMode,
773    /// The directory referenced images are named under.
774    pub artifacts_dir: String,
775    /// The content layers rendered (`MarkdownParams.layers`,
776    /// `export_to_markdown(included_content_layers=…)`): an item on a layer
777    /// outside the set is skipped, its children still walked. The default
778    /// body-only set drops page headers/footers (`furniture`), reviewer
779    /// comments (`notes`) and hidden sheets (`invisible`), as upstream does; a
780    /// scanned form's running header reads out with
781    /// `ContentLayers::BODY.with(ContentLayer::Furniture)`. The extra items
782    /// render through the body's serializers — a page header is a paragraph.
783    pub layers: ContentLayers,
784    /// `CommonParams.traverse_pictures`: render the text items nested in a
785    /// picture (the PDF pipeline's picture children — a bordered form laid
786    /// out as one picture holds every field as a child) after the picture's
787    /// own caption and image, as upstream yields them. Off, a picture prints
788    /// only its caption and image.
789    pub traverse_pictures: bool,
790    /// `MarkdownParams.escape_html`: `&`, `<` and `>` in text as `&amp;`,
791    /// `&lt;`, `&gt;` (Python's `html.escape(quote=False)`). Off, `R&D` stays
792    /// `R&D`.
793    pub escape_html: bool,
794    /// `MarkdownParams.escape_underscores`: `_` in text as `\_`. Off, the
795    /// text keeps its underscores.
796    pub escape_underscores: bool,
797    /// `MarkdownParams.image_placeholder`: what a picture prints as when it
798    /// renders no image data (the placeholder mode, or a picture without a
799    /// payload); upstream's `<!-- image -->`.
800    pub image_placeholder: String,
801    /// docling-core's `PlainTextDocSerializer` (#613, `export_to_text`,
802    /// docling's `--to text`): the Markdown walk with the decoration turned
803    /// off — headings without `#`, bold/italic/strikethrough markers and
804    /// inline code backticks dropped, a hyperlink reduced to its label, code
805    /// blocks unfenced, no GFM hard line breaks. List bullets/numbers,
806    /// checkbox marks and table grids stay. [`Self::plain_text`] pairs it
807    /// with upstream's `PlainTextParams` (no escaping, an empty image
808    /// placeholder).
809    pub plain_text: bool,
810}
811
812impl MarkdownExportOptions {
813    /// docling-core's `PlainTextParams` defaults (#613): [`Self::plain_text`]
814    /// on, HTML and underscore escaping off, pictures print nothing (their
815    /// captions still do), body layer only, no picture traversal — what
816    /// `DoclingDocument.export_to_text()` and docling's `--to text` write.
817    pub fn plain_text() -> Self {
818        Self {
819            escape_html: false,
820            escape_underscores: false,
821            image_placeholder: String::new(),
822            plain_text: true,
823            ..Self::default()
824        }
825    }
826}
827
828impl Default for MarkdownExportOptions {
829    fn default() -> Self {
830        Self {
831            image_mode: ImageMode::Placeholder,
832            artifacts_dir: "artifacts".to_string(),
833            layers: ContentLayers::BODY,
834            traverse_pictures: false,
835            escape_html: true,
836            escape_underscores: true,
837            image_placeholder: "<!-- image -->".to_string(),
838            plain_text: false,
839        }
840    }
841}
842
843/// DocLang-only content for a [`Node::ListItem`] whose DocLang form differs from
844/// its flat Markdown `text` (see [`Node::ListItem::dclx`]). `ordered` picks the
845/// enclosing `<list>` kind, `marker` the `<ldiv><marker>`; content is `runs`
846/// (structured equations/formatting) when non-empty, else `text` re-parsed for
847/// inline markers.
848#[derive(Debug, Clone, PartialEq, Eq, Default)]
849pub struct ListItemDclx {
850    pub ordered: bool,
851    pub marker: Option<String>,
852    pub text: String,
853    pub runs: Vec<InlineRun>,
854}
855
856/// A page pipeline's list item as docling's `ListItemMarkerProcessor`
857/// exports it to JSON (see [`Node::ListItem::split`]): the source text
858/// (`orig`), the `marker` split off its head (empty when it has none), the
859/// `text` left, and `enumerated` for a numbered marker of any spelling (`1.`,
860/// `[1]`, `a)`, `iv.`). Plain text, not Markdown-escaped.
861#[derive(Debug, Clone, PartialEq, Eq, Default)]
862pub struct ListItemSplit {
863    pub orig: String,
864    pub marker: String,
865    pub text: String,
866    pub enumerated: bool,
867}
868
869impl Node {
870    /// The paragraph a [`Node::LabeledText`] renders as outside the JSON:
871    /// its text, wrapped as `[text](uri)` when it carries a hyperlink. Any
872    /// other node is returned unchanged.
873    pub fn labeled_as_paragraph(&self) -> std::borrow::Cow<'_, Node> {
874        match self {
875            Node::LabeledText { text, href, .. } => std::borrow::Cow::Owned(Node::Paragraph {
876                text: match href {
877                    Some(uri) => crate::hyperlink::markdown_link(text, uri),
878                    None => text.clone(),
879                },
880            }),
881            other => std::borrow::Cow::Borrowed(other),
882        }
883    }
884}
885
886impl InlineRun {
887    /// A run with no active formatting (renders as bare inline text).
888    pub fn is_plain(&self) -> bool {
889        !self.bold
890            && !self.italic
891            && !self.underline
892            && !self.strike
893            && !self.code
894            && !self.formula
895            && self.script == Script::Baseline
896    }
897}
898
899/// Build the [`Node`] for a paragraph of inline content from its structured
900/// `runs` and Markdown text, applying docling's `InlineGroup` boundary:
901///
902/// * a single plain run (or none) → a plain [`Node::Paragraph`] (which the
903///   serializers render as `<text>…</text>`, and a lone hyperlink via `<href>`);
904/// * a single uniformly-formatted run, or two or more runs → a
905///   [`Node::InlineGroup`]. `unwrapped` (the group's docling parent is a
906///   heading, so no enclosing `<text>`) only applies to multi-run groups.
907///
908/// Markdown/JSON render the group's `md_text`, so their output is identical to
909/// emitting a `Paragraph` — the structured runs are DocLang-only.
910pub fn inline_paragraph_node(md_text: String, runs: Vec<InlineRun>, unwrapped: bool) -> Node {
911    let single_plain = runs.len() <= 1 && runs.first().is_none_or(|r| r.is_plain());
912    if single_plain {
913        Node::Paragraph { text: md_text }
914    } else {
915        Node::InlineGroup {
916            unwrapped: unwrapped && runs.len() >= 2,
917            runs,
918            md_text,
919        }
920    }
921}
922
923/// One entry of a [`Node::FieldRegion`]: a marker/key/value triple, any of which
924/// may be absent. Mirrors docling's `field_item` with its `marker` / `field_key`
925/// / `field_value` child texts.
926#[derive(Debug, Clone, PartialEq, Default)]
927pub struct FieldItem {
928    pub marker: Option<String>,
929    pub key: Option<String>,
930    pub value: Option<String>,
931    /// docling's `kind` on the `field_value` item — `read_only` or
932    /// `fillable` (the value is or holds a form control); JSON-only.
933    pub value_kind: Option<String>,
934}
935
936/// One node of a [`Node::KeyValueGraph`] — docling-core's `GraphCell`.
937#[derive(Debug, Clone, PartialEq)]
938pub struct GraphCell {
939    /// docling's `GraphCellLabel` value: `key` or `value` (it also knows
940    /// `unspecified` and `checkbox`).
941    pub label: String,
942    /// The cell's number within its graph, what the links refer to.
943    pub cell_id: usize,
944    pub text: String,
945    /// The text before any cleanup — for an XBRL fact key, the concept's
946    /// qualified name where `text` is its local name.
947    pub orig: String,
948}
949
950/// One edge of a [`Node::KeyValueGraph`] — docling-core's `GraphLink`.
951#[derive(Debug, Clone, PartialEq)]
952pub struct GraphLink {
953    /// docling's `GraphLinkLabel` value: `to_value`, `to_child`, `to_parent`
954    /// or `to_key`.
955    pub label: String,
956    pub source_cell_id: usize,
957    pub target_cell_id: usize,
958}
959
960/// One DocumentPictureClassifier prediction — docling-core's
961/// `PictureClassificationClass` (`class_name` + `confidence`).
962#[derive(Debug, Clone, PartialEq)]
963pub struct PictureClass {
964    /// e.g. `bar_chart`, `logo`, `signature` (the classifier's 26-label set).
965    pub class_name: String,
966    pub confidence: f32,
967}
968
969/// A picture's text annotation — docling-core's `PictureDescriptionData`
970/// (`text` + `provenance`), the one shape upstream uses for every model that
971/// writes prose about a picture. The picture-OCR enrichment (#645) fills it
972/// with the lines the OCR engine read off the image, `provenance` naming the
973/// engine (`ppocr` / `tesseract`) the way a VLM description names its model.
974#[derive(Debug, Clone, PartialEq, Eq)]
975pub struct PictureDescription {
976    pub text: String,
977    pub provenance: String,
978}
979
980impl PictureDescription {
981    /// The provenance of a picture's author-written alt text (#676): the
982    /// `descr` (else `title`) of an OOXML picture's non-visual properties
983    /// — what DOCX, PPTX and XLSX authors type into "Alt Text". JSON writes
984    /// it as `meta.description.created_by`; Markdown renders it under strict
985    /// Markdown or `DoclingDocument::picture_alt_text`, HTML under the latter.
986    pub const ALT_TEXT: &'static str = "alt_text";
987
988    /// An alt-text description, see [`Self::ALT_TEXT`].
989    pub fn alt_text(text: impl Into<String>) -> Self {
990        Self {
991            text: text.into(),
992            provenance: Self::ALT_TEXT.to_string(),
993        }
994    }
995
996    /// Whether this description is a picture's alt text.
997    pub fn is_alt_text(&self) -> bool {
998        self.provenance == Self::ALT_TEXT
999    }
1000
1001    /// The (empty) provenance of a description docling's backend writes
1002    /// itself as `PictureMeta.description` — `text` only, no `created_by`
1003    /// and no legacy `annotations` entry: the alt text of an XLSX image
1004    /// placed in a cell (docling#5015). Unlike [`Self::ALT_TEXT`] it is
1005    /// upstream's own output, so every format renders it unconditionally.
1006    pub const DOCLING_META: &'static str = "";
1007
1008    /// A docling-native description, see [`Self::DOCLING_META`].
1009    pub fn docling_meta(text: impl Into<String>) -> Self {
1010        Self {
1011            text: text.into(),
1012            provenance: Self::DOCLING_META.to_string(),
1013        }
1014    }
1015
1016    /// Whether this is a docling-native description ([`Self::DOCLING_META`]).
1017    pub fn is_docling_meta(&self) -> bool {
1018        self.provenance == Self::DOCLING_META
1019    }
1020}
1021
1022/// An extracted picture's raw encoded bytes plus its mimetype and pixel size —
1023/// the docling.rs analogue of docling-core's `ImageRef`.
1024#[derive(Debug, Clone, PartialEq)]
1025pub struct PictureImage {
1026    /// e.g. `image/png`, `image/jpeg`.
1027    pub mimetype: String,
1028    pub width: u32,
1029    pub height: u32,
1030    /// The image file bytes, exactly as embedded (PNG/JPEG/…).
1031    pub data: Vec<u8>,
1032    /// Pixels per inch of the image relative to the page it came from —
1033    /// docling-core's `ImageRef.dpi`, which consumers use to map pixels back
1034    /// to points. A crop rendered from a PDF page at `s` px/pt is `72·s`
1035    /// (docling: `int(72 * images_scale)`, #519); an image embedded in an
1036    /// office file has no render scale and keeps docling's `72`
1037    /// ([`Self::DEFAULT_DPI`]).
1038    pub dpi: u32,
1039    /// The size the picture is *displayed* at in its document, in inches
1040    /// (`[width, height]`, #834): a DOCX drawing's `wp:extent`, an ODT
1041    /// frame's `svg:width` / `svg:height` — not the bitmap's pixel size
1042    /// above, which docling's `ImageRef.size` carries. `None` when the
1043    /// format has no such extent (a PDF crop, a standalone image). The
1044    /// Pandoc export writes it as the `Image`'s `width` / `height`
1045    /// attributes, as Pandoc's own readers do; docling's JSON has no field
1046    /// for it, so the JSON export leaves it out.
1047    pub display_size: Option<[f32; 2]>,
1048}
1049
1050impl PictureImage {
1051    /// docling's `ImageRef` default when no render scale applies.
1052    pub const DEFAULT_DPI: u32 = 72;
1053
1054    /// The `dpi` of an image rendered at `scale` pixels per PDF point
1055    /// (`72·scale`, rounded — `int()` would floor 143.99… to 143).
1056    pub fn dpi_for_scale(scale: f32) -> u32 {
1057        (72.0 * scale).round().max(1.0) as u32
1058    }
1059
1060    /// A `data:` URI for the image (`data:<mimetype>;base64,<…>`).
1061    pub fn data_uri(&self) -> String {
1062        format!(
1063            "data:{};base64,{}",
1064            self.mimetype,
1065            crate::base64::encode(&self.data)
1066        )
1067    }
1068}
1069
1070/// One table cell as a first-class object (#240) — the Rust counterpart of
1071/// docling's `TableCell`: its text, page geometry, grid rectangle and header
1072/// roles. Produced by the PDF TableFormer paths from the predicted OTSL
1073/// structure; `bbox` is `[l, t, r, b]` in page points with a top-left origin.
1074#[derive(Debug, Clone, PartialEq)]
1075pub struct TableCell {
1076    pub text: String,
1077    /// `[l, t, r, b]`, page points, top-left origin; `None` without geometry.
1078    pub bbox: Option<[f32; 4]>,
1079    /// Anchor grid position (0-based row/column offsets).
1080    pub start_row: usize,
1081    pub start_col: usize,
1082    /// Span extents (≥ 1); the covered grid positions repeat the cell's text
1083    /// in [`Table::rows`].
1084    pub row_span: usize,
1085    pub col_span: usize,
1086    /// OTSL `ched` — a column-header cell.
1087    pub column_header: bool,
1088    /// OTSL `rhed` — a row-header cell.
1089    pub row_header: bool,
1090    /// OTSL `srow` — a section-row cell.
1091    pub row_section: bool,
1092}
1093
1094/// Where a picture's or table's caption text item hangs in the docling-JSON
1095/// tree (#390). docling's backends do not agree, and the JSON structure is
1096/// the only surface that shows it (Markdown, DocLang and LaTeX place a
1097/// caption by its item, whatever its parent): the PDF pipeline parents a
1098/// layout caption to the picture or table it belongs to, while every
1099/// declarative backend creates the caption with `doc.add_text(label=CAPTION)`
1100/// and no parent — the document body — even when the item itself sits in a
1101/// group or under a section header (JATS, LaTeX, HTML, Markdown, EPUB,
1102/// AsciiDoc all do). The office backends hang a chart's title caption off the
1103/// chart's container (the sheet group, the slide, docx's current parent,
1104/// docling#4190) — that is [`Node::Chart`]'s own path, not this choice. A
1105/// backend that adds a new captioned item picks the variant matching
1106/// upstream's `add_text` call for that format; the default is upstream's
1107/// default.
1108#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
1109pub enum CaptionParent {
1110    /// `#/body`, listed after the enclosing top-level item — docling's
1111    /// `add_text` default, which every declarative backend leaves alone.
1112    #[default]
1113    Body,
1114    /// The item's own container (its `parent`), listed ahead of the item:
1115    /// the caption is created first, as docling's office backends do.
1116    Container,
1117    /// The item's own container, listed *after* the item: docling's HTML
1118    /// backend adds a `<figure>`-wrapped table, then its `<figcaption>` under
1119    /// `self.parents[self.level]` (docling#4050).
1120    ContainerAfter,
1121    /// The item itself — the caption is the picture's or table's first
1122    /// child, as docling's PDF pipeline attaches a layout caption.
1123    Item,
1124}
1125
1126/// A simple row-major table. By default `rows[0]` is the header row; a
1127/// [`TableStructure`] overlay overrides that and adds column spans.
1128#[derive(Debug, Clone, PartialEq, Default)]
1129pub struct Table {
1130    pub rows: Vec<Vec<String>>,
1131    /// Optional layout provenance: the four DocLang `<location>` values
1132    /// (`x0,y0,x1,y1`, each already normalized to the 0–511 resolution) emitted
1133    /// before the table's cells. Set only by backends with real geometry (e.g.
1134    /// the spreadsheet backend, whose cell grid yields a bounding box); left
1135    /// `None` by declarative backends, which have no coordinates.
1136    pub location: Option<[u16; 4]>,
1137    /// Optional OTSL structure overlay for backends that parse real table
1138    /// geometry (USPTO CALS): explicit header-row count and horizontal-span
1139    /// continuations. `None` → the default (row 0 is the header, no spans).
1140    /// `rows` still carries the full text grid (span text replicated) for
1141    /// Markdown/JSON; DocLang uses this overlay to emit `<ched/>`/`<lcel/>`.
1142    pub structure: Option<TableStructure>,
1143    /// Optional per-cell block content, parallel to `rows`. A *rich* cell (an
1144    /// ODF cell holding a list, several paragraphs, or a nested table) carries
1145    /// its DocLang blocks here; the DocLang serializer emits them after the
1146    /// cell token instead of the flat `rows` text. Markdown/JSON ignore this
1147    /// and render `rows`, so their output is unchanged. `None` (or an empty
1148    /// `Vec` for a given cell) → the flat text is used everywhere.
1149    pub cell_blocks: Option<Vec<Vec<Vec<Node>>>>,
1150    /// Optional caption (docling's `TableItem.captions`): the JATS
1151    /// `<table-wrap>` label+caption, an HTML `<caption>`, etc. Markdown renders
1152    /// it as a text line *before* the grid; JSON emits a caption text item the
1153    /// table references; DocLang emits a `<caption>` as the table's first child.
1154    /// `None` → the table has no caption.
1155    pub caption: Option<String>,
1156    /// Where the caption item hangs in the JSON tree (#390); see
1157    /// [`CaptionParent`]. Only the JSON export reads it.
1158    pub caption_parent: CaptionParent,
1159    /// The caption's own box on the table's page (0–511 grid) — the PDF
1160    /// pipeline's caption layout region, written as the caption item's
1161    /// `prov` (#609); see [`Node::Picture`]'s field of the same name.
1162    pub caption_location: Option<[u16; 4]>,
1163    /// The table's footnotes (docling's `TableItem.footnotes`, #1009): one
1164    /// text each, escaped like [`Self::caption`]. Markdown prints them after
1165    /// the grid, one paragraph each; JSON emits `footnote` text items under
1166    /// the table that its `footnotes` list references (docling-core#675).
1167    pub footnotes: Vec<String>,
1168    /// Optional per-cell bounding boxes, same shape as [`Self::rows`]: `[l, t,
1169    /// r, b]` in page points with a **top-left** origin (the PDF pipeline's
1170    /// native space). Set by the ML pipeline's TableFormer paths — a spanned
1171    /// cell repeats its anchor's box across the covered grid positions — and
1172    /// First-class cells (#240): the authoritative per-cell records —
1173    /// text, page geometry, spans and header roles — when the backend
1174    /// produces them (the PDF TableFormer paths do; declarative backends
1175    /// leave `None`). [`Self::rows`] stays the dense text grid every
1176    /// serializer renders (a spanning cell's text is replicated across its
1177    /// covered positions there); JSON serializes these cells verbatim when
1178    /// present, and the DocLang structure overlay is derived from them.
1179    pub cells: Option<Vec<TableCell>>,
1180    /// The table is a table of contents — docling's `document_index` label
1181    /// (#1091), which the PDF layout model gives a TOC region and docling
1182    /// keeps on the `TableItem`. Only the JSON export (and its read-back)
1183    /// tells it apart: every other serializer renders it as a table, as
1184    /// docling-core does.
1185    pub document_index: bool,
1186}
1187
1188/// The name a [`rich_cell_group`] carries, which the JSON export reads.
1189pub(crate) const RICH_CELL: &str = "rich_cell";
1190
1191/// A rich table cell's blocks as docling's `RichTableCell` (#1119): the one
1192/// entry of a [`Table::cell_blocks`] cell, wrapping the cell's paragraphs and
1193/// pictures in reading order. The JSON export writes it as the table's
1194/// `rich_cell_group_<table>_<col>_<row>` group the cell's `ref` points at,
1195/// as the DOCX backend's item tree does; DocLang, which has no group
1196/// element, renders the blocks in place. [`Table::rows`] keeps the cell's
1197/// Markdown text, its pictures as `<!-- image -->` paragraphs, and the
1198/// JSON's cell text leaves those out (python-docx's `cell.text`).
1199pub fn rich_cell_group(children: Vec<Node>) -> Node {
1200    Node::Group {
1201        label: "unspecified".into(),
1202        name: Some(RICH_CELL.into()),
1203        layer: None,
1204        children,
1205    }
1206}
1207
1208impl Table {
1209    /// A cell's text at a grid position, `None` outside the grid.
1210    pub fn cell_text(&self, row: usize, col: usize) -> Option<&str> {
1211        self.rows.get(row)?.get(col).map(String::as_str)
1212    }
1213
1214    /// Replace the text at a grid position; `false` (and no change) outside
1215    /// the grid. When a first-class cell covers the position, the whole
1216    /// cell is updated: its record text and every grid position its span
1217    /// covers, so the repair shows once in Markdown, not once per covered
1218    /// column.
1219    pub fn set_cell_text(&mut self, row: usize, col: usize, text: impl Into<String>) -> bool {
1220        if self.rows.get(row).and_then(|r| r.get(col)).is_none() {
1221            return false;
1222        }
1223        let text = text.into();
1224        let covering = self.cells.as_mut().and_then(|cells| {
1225            cells.iter_mut().find(|c| {
1226                (c.start_row..c.start_row + c.row_span).contains(&row)
1227                    && (c.start_col..c.start_col + c.col_span).contains(&col)
1228            })
1229        });
1230        if let Some(cell) = covering {
1231            cell.text = text.clone();
1232            let (r0, r1) = (cell.start_row, cell.start_row + cell.row_span);
1233            let (c0, c1) = (cell.start_col, cell.start_col + cell.col_span);
1234            for r in self.rows.iter_mut().take(r1).skip(r0) {
1235                for slot in r.iter_mut().take(c1).skip(c0) {
1236                    *slot = text.clone();
1237                }
1238            }
1239        } else {
1240            self.rows[row][col] = text;
1241        }
1242        true
1243    }
1244
1245    /// Derive first-class cells (#240) from the dense grid plus the
1246    /// [`TableStructure`] overlay — how declarative tables (DOCX/XLSX merged
1247    /// regions, HTML `th`/spans, ODF covered cells, USPTO CALS) get real
1248    /// `TableCell` records without page geometry. Anchors are the positions
1249    /// not marked as span continuations; extents scan the continuation grids
1250    /// right/down (matching the DocLang `lcel`/`ucel` reading). Header roles
1251    /// come from the per-cell `col_header`/`row_header` grids when present,
1252    /// else the `header_row` band, else docling's declarative default (row 0
1253    /// is the header). Without any overlay every position is a 1×1 cell.
1254    pub fn derive_cells(&self) -> Vec<TableCell> {
1255        let s = self.structure.as_ref();
1256        let flag = |grid: Option<&Vec<Vec<bool>>>, r: usize, c: usize| {
1257            grid.and_then(|g| g.get(r))
1258                .and_then(|row| row.get(c))
1259                .copied()
1260                .unwrap_or(false)
1261        };
1262        let col_cont = |r: usize, c: usize| flag(s.map(|s| &s.col_continuation), r, c);
1263        let row_cont = |r: usize, c: usize| flag(s.map(|s| &s.row_continuation), r, c);
1264        let is_col_header = |r: usize, c: usize| match s {
1265            Some(st) if !st.col_header.is_empty() => flag(Some(&st.col_header), r, c),
1266            Some(st) if !st.header_row.is_empty() => st.header_row.get(r).copied().unwrap_or(false),
1267            _ => r == 0,
1268        };
1269        let mut cells = Vec::new();
1270        for (r, row) in self.rows.iter().enumerate() {
1271            for (c, text) in row.iter().enumerate() {
1272                if col_cont(r, c) || row_cont(r, c) {
1273                    continue; // covered by a span anchor
1274                }
1275                let mut col_span = 1;
1276                while c + col_span < row.len() && col_cont(r, c + col_span) {
1277                    col_span += 1;
1278                }
1279                let mut row_span = 1;
1280                while r + row_span < self.rows.len() && row_cont(r + row_span, c) {
1281                    row_span += 1;
1282                }
1283                cells.push(TableCell {
1284                    text: text.clone(),
1285                    bbox: None,
1286                    start_row: r,
1287                    start_col: c,
1288                    row_span,
1289                    col_span,
1290                    column_header: is_col_header(r, c),
1291                    row_header: flag(s.map(|s| &s.row_header), r, c),
1292                    row_section: false,
1293                });
1294            }
1295        }
1296        cells
1297    }
1298
1299    /// The number of leading grid rows that form the column header block —
1300    /// docling-core's `TableData._count_column_header_rows` (docling-core#767,
1301    /// 2.102, #778), shared by the Markdown serializer
1302    /// ([`Self::header_row_count`]) and the chunker's dataframe view, which
1303    /// must agree on where the header ends. Uses the first-class
1304    /// [`Self::cells`] when present (the PDF pipeline's TableFormer flags),
1305    /// else the cells derived from the structure overlay.
1306    ///
1307    /// - A row counts only when a `column_header` cell *starts* on it
1308    ///   (docling-core#723): a header spanning several rows is replicated
1309    ///   into each row it covers, and counting those would pull the data rows
1310    ///   beneath it into the header block.
1311    /// - A row also stops the block when it *carries body text* (#604,
1312    ///   docling-core#766): a cell starting on it that is not a column
1313    ///   header, has non-blank text and does not start in the table's first
1314    ///   column, which holds row labels left unmarked even on header rows. A
1315    ///   scanned form flags its first-column labels `column_header` on every
1316    ///   row; without the check each such row folded its values into the
1317    ///   header.
1318    /// - Row 0 is exempt from that check — model-predicted header rows are
1319    ///   often only partly flagged — unless a later row flags a cell starting
1320    ///   in the first column: that marks a column of row headers, not a
1321    ///   partly flagged header row.
1322    ///
1323    /// No fallback: a table without flags has no header rows here.
1324    pub fn column_header_row_count(&self) -> usize {
1325        if self.rows.is_empty() {
1326            return 0;
1327        }
1328        let derived;
1329        let cells: &[TableCell] = match &self.cells {
1330            Some(c) if !c.is_empty() => c,
1331            _ => {
1332                derived = self.derive_cells();
1333                &derived
1334            }
1335        };
1336        let num_rows = self.rows.len();
1337        let first_col = cells.iter().map(|c| c.start_col).min().unwrap_or(0);
1338        let leading_col_flagged_below = cells.iter().any(|c| {
1339            c.column_header && c.start_col == first_col && (1..num_rows).contains(&c.start_row)
1340        });
1341        let is_header_row = |r: usize| {
1342            let check_body = r > 0 || leading_col_flagged_below;
1343            let mut flagged = false;
1344            for c in cells.iter().filter(|c| c.start_row == r) {
1345                if c.column_header {
1346                    flagged = true;
1347                } else if check_body && c.start_col != first_col && !c.text.trim().is_empty() {
1348                    return false;
1349                }
1350            }
1351            flagged
1352        };
1353        (0..num_rows).take_while(|&r| is_header_row(r)).count()
1354    }
1355
1356    /// The number of leading grid rows the Markdown serializer renders as the
1357    /// header — docling-core's `_count_header_rows`:
1358    /// [`Self::column_header_row_count`], plus upstream's row-0 fallback for
1359    /// GFM, which needs a header row: `1` when no flag sits on any grid row
1360    /// below the first (a spanning header cell counts on every row it
1361    /// covers), so tables from backends that never set the flag keep row 0
1362    /// as the header. When flags exist but none makes a header row, the
1363    /// count is `0` and every row stays in the body under an empty header.
1364    pub fn header_row_count(&self) -> usize {
1365        let count = self.column_header_row_count();
1366        if count > 0 || self.rows.is_empty() {
1367            return count;
1368        }
1369        let derived;
1370        let cells: &[TableCell] = match &self.cells {
1371            Some(c) if !c.is_empty() => c,
1372            _ => {
1373                derived = self.derive_cells();
1374                &derived
1375            }
1376        };
1377        if cells
1378            .iter()
1379            .any(|c| c.column_header && c.start_row + c.row_span.max(1) > 1)
1380        {
1381            0
1382        } else {
1383            1
1384        }
1385    }
1386
1387    /// For every grid position, the position of the cell that covers it — its
1388    /// anchor (top-left start): itself for an unmerged position, the merge's
1389    /// start for one a spanning cell covers. Uses the first-class
1390    /// [`Self::cells`] when present, else the cells derived from the
1391    /// structure overlay. A rich cell's blocks ([`Self::cell_blocks`]) live on
1392    /// its anchor only, so a serializer that repeats a merged cell in every
1393    /// position it covers (docling-core#857) reads them through this.
1394    pub fn span_anchors(&self) -> Vec<Vec<(usize, usize)>> {
1395        let num_cols = self.rows.iter().map(Vec::len).max().unwrap_or(0);
1396        let mut anchors: Vec<Vec<(usize, usize)>> = (0..self.rows.len())
1397            .map(|r| (0..num_cols).map(|c| (r, c)).collect())
1398            .collect();
1399        let derived;
1400        let cells: &[TableCell] = match &self.cells {
1401            Some(c) if !c.is_empty() => c,
1402            _ => {
1403                derived = self.derive_cells();
1404                &derived
1405            }
1406        };
1407        for cell in cells {
1408            let rows = cell.start_row..cell.start_row + cell.row_span.max(1);
1409            for row in anchors.iter_mut().take(rows.end).skip(rows.start) {
1410                let cols = cell.start_col..cell.start_col + cell.col_span.max(1);
1411                for pos in row.iter_mut().take(cols.end).skip(cols.start) {
1412                    *pos = (cell.start_row, cell.start_col);
1413                }
1414            }
1415        }
1416        anchors
1417    }
1418
1419    /// The first-class cell covering a grid position, if any.
1420    pub fn cell_at(&self, row: usize, col: usize) -> Option<&TableCell> {
1421        self.cells.as_ref()?.iter().find(|c| {
1422            (c.start_row..c.start_row + c.row_span).contains(&row)
1423                && (c.start_col..c.start_col + c.col_span).contains(&col)
1424        })
1425    }
1426
1427    /// A cell's bounding box (`[l, t, r, b]`, page points, top-left origin);
1428    /// `None` when no cell with geometry covers the position.
1429    pub fn cell_bbox(&self, row: usize, col: usize) -> Option<[f32; 4]> {
1430        self.cell_at(row, col)?.bbox
1431    }
1432
1433    /// Set (or replace) the bounding box of the cell covering a grid
1434    /// position; `false` outside the text grid. A table without first-class
1435    /// cells materializes them first (one 1×1 cell per grid position, texts
1436    /// from the grid), so declarative tables can be annotated too.
1437    pub fn set_cell_bbox(&mut self, row: usize, col: usize, bbox: [f32; 4]) -> bool {
1438        if self.rows.get(row).and_then(|r| r.get(col)).is_none() {
1439            return false;
1440        }
1441        let rows = &self.rows;
1442        let cells = self.cells.get_or_insert_with(|| {
1443            rows.iter()
1444                .enumerate()
1445                .flat_map(|(r, cols)| {
1446                    cols.iter().enumerate().map(move |(c, text)| TableCell {
1447                        text: text.clone(),
1448                        bbox: None,
1449                        start_row: r,
1450                        start_col: c,
1451                        row_span: 1,
1452                        col_span: 1,
1453                        column_header: false,
1454                        row_header: false,
1455                        row_section: false,
1456                    })
1457                })
1458                .collect()
1459        });
1460        match cells.iter_mut().find(|c| {
1461            (c.start_row..c.start_row + c.row_span).contains(&row)
1462                && (c.start_col..c.start_col + c.col_span).contains(&col)
1463        }) {
1464            Some(cell) => {
1465                cell.bbox = Some(bbox);
1466                true
1467            }
1468            None => {
1469                cells.push(TableCell {
1470                    text: self.rows[row][col].clone(),
1471                    bbox: Some(bbox),
1472                    start_row: row,
1473                    start_col: col,
1474                    row_span: 1,
1475                    col_span: 1,
1476                    column_header: false,
1477                    row_header: false,
1478                    row_section: false,
1479                });
1480                true
1481            }
1482        }
1483    }
1484
1485    /// The anchor position of the cell whose box overlaps `bbox` best
1486    /// (largest intersection-over-union), ties resolved in cell order.
1487    /// `None` when nothing overlaps or the table carries no geometry. This
1488    /// is the lookup half of the repair workflow: find the cell an external
1489    /// OCR box refers to, then [`Self::set_cell_text`] it.
1490    pub fn find_cell_by_bbox(&self, bbox: [f32; 4]) -> Option<(usize, usize)> {
1491        let area = |b: &[f32; 4]| ((b[2] - b[0]) * (b[3] - b[1])).max(0.0);
1492        let mut best: Option<(f32, (usize, usize))> = None;
1493        for cell in self.cells.as_deref()?.iter() {
1494            let Some(cb) = cell.bbox else { continue };
1495            let iw = (bbox[2].min(cb[2]) - bbox[0].max(cb[0])).max(0.0);
1496            let ih = (bbox[3].min(cb[3]) - bbox[1].max(cb[1])).max(0.0);
1497            let inter = iw * ih;
1498            if inter <= 0.0 {
1499                continue;
1500            }
1501            let iou = inter / (area(&bbox) + area(&cb) - inter).max(f32::EPSILON);
1502            if best.is_none_or(|(b, _)| iou > b) {
1503                best = Some((iou, (cell.start_row, cell.start_col)));
1504            }
1505        }
1506        best.map(|(_, pos)| pos)
1507    }
1508
1509    /// Locate the cell overlapping `bbox` best and replace its text — the
1510    /// one-call form of the OCR-repair loop. Returns the updated anchor.
1511    pub fn update_cell_by_bbox(
1512        &mut self,
1513        bbox: [f32; 4],
1514        text: impl Into<String>,
1515    ) -> Option<(usize, usize)> {
1516        let (row, col) = self.find_cell_by_bbox(bbox)?;
1517        self.set_cell_text(row, col, text);
1518        Some((row, col))
1519    }
1520}
1521
1522/// OTSL structure overlay for a [`Table`], parallel to [`Table::rows`].
1523#[derive(Debug, Clone, PartialEq, Default)]
1524pub struct TableStructure {
1525    /// Per-row: `true` if the row's non-empty cells are column headers
1526    /// (emitted as `<ched/>` rather than `<fcel/>`).
1527    pub header_row: Vec<bool>,
1528    /// Same shape as [`Table::rows`]; `true` where a cell continues a
1529    /// horizontal span from its left neighbour (emitted as `<lcel/>`).
1530    pub col_continuation: Vec<Vec<bool>>,
1531    /// Same shape as [`Table::rows`]; `true` where a cell continues a
1532    /// vertical span from the cell above (emitted as `<ucel/>`). Empty or all
1533    /// `false` when the backend has no vertical spans (e.g. USPTO CALS).
1534    pub row_continuation: Vec<Vec<bool>>,
1535    /// Same shape as [`Table::rows`]; `true` where a non-empty cell is a row
1536    /// header (emitted as `<rhed/>`) — a chart's category column. Empty when
1537    /// the table has no row headers.
1538    pub row_header: Vec<Vec<bool>>,
1539    /// Same shape as [`Table::rows`]; `true` where a cell is a *column header*
1540    /// cell (an HTML `<th>`). When non-empty this per-cell grid supersedes the
1541    /// per-row [`Self::header_row`] for `<ched/>` emission, matching docling's
1542    /// cell-level `column_header` flag; the chunker derives its header-row
1543    /// count from it.
1544    pub col_header: Vec<Vec<bool>>,
1545}
1546
1547/// [`for_each_picture_in_mut`], read-only: every picture in `nodes`, however
1548/// nested, for a pass that only looks (the DocLang asset digests, #898).
1549pub fn for_each_picture_in<'a>(nodes: &'a [Node], f: &mut dyn FnMut(&'a Node)) {
1550    for node in nodes {
1551        match node {
1552            Node::Picture { .. } => f(node),
1553            Node::Group { children, .. } | Node::PictureChildren(children) => {
1554                for_each_picture_in(children, f)
1555            }
1556            Node::Located { inner, .. }
1557            | Node::Prov { inner, .. }
1558            | Node::Track { inner, .. }
1559            | Node::Furniture { inner, .. }
1560            | Node::Commented { inner, .. }
1561            | Node::DoclangOnly(inner) => for_each_picture_in(std::slice::from_ref(inner), f),
1562            Node::Table(t) => {
1563                if let Some(blocks) = t.cell_blocks.as_ref() {
1564                    for row in blocks {
1565                        for cell in row {
1566                            for_each_picture_in(cell, f);
1567                        }
1568                    }
1569                }
1570            }
1571            _ => {}
1572        }
1573    }
1574}
1575
1576/// [`DoclingDocument::for_each_picture_mut`] over a node slice — every
1577/// picture in `nodes`, however nested (groups, wrappers, table cell blocks),
1578/// for a caller that holds page batches rather than a document (the
1579/// streaming PDF path, #896).
1580pub fn for_each_picture_in_mut(nodes: &mut [Node], f: &mut dyn FnMut(&mut Node)) {
1581    for node in nodes {
1582        match node {
1583            Node::Picture { .. } => f(node),
1584            Node::Group { children, .. } | Node::PictureChildren(children) => {
1585                for_each_picture_in_mut(children, f)
1586            }
1587            Node::Located { inner, .. }
1588            | Node::Prov { inner, .. }
1589            | Node::Track { inner, .. }
1590            | Node::Furniture { inner, .. }
1591            | Node::Commented { inner, .. }
1592            | Node::DoclangOnly(inner) => for_each_picture_in_mut(std::slice::from_mut(inner), f),
1593            Node::Table(t) => {
1594                if let Some(blocks) = t.cell_blocks.as_mut() {
1595                    for row in blocks {
1596                        for cell in row {
1597                            for_each_picture_in_mut(cell, f);
1598                        }
1599                    }
1600                }
1601            }
1602            _ => {}
1603        }
1604    }
1605}
1606
1607impl DoclingDocument {
1608    /// Create an empty document with the given name.
1609    pub fn new(name: impl Into<String>) -> Self {
1610        Self {
1611            name: name.into(),
1612            nodes: Vec::new(),
1613            strict_markdown: false,
1614            compact_tables: false,
1615            picture_alt_text: false,
1616            metadata: Default::default(),
1617            metadata_output: Default::default(),
1618            page_break_placeholder: None,
1619            links: Vec::new(),
1620            confidence: None,
1621            tree: None,
1622            page_images: std::collections::BTreeMap::new(),
1623            notices: Vec::new(),
1624        }
1625    }
1626
1627    /// Append a node.
1628    /// The document's top-level tables in reading order — the read half of
1629    /// the post-extraction table API (#238). [`Node::Located`] wrappers (the
1630    /// PDF pipeline attaches layout provenance that way) are looked through;
1631    /// tables nested inside rich table cells (`Table::cell_blocks`) are not
1632    /// traversed.
1633    pub fn tables(&self) -> impl Iterator<Item = &Table> {
1634        fn unwrap_table(n: &Node) -> Option<&Table> {
1635            match n {
1636                Node::Table(t) => Some(t),
1637                Node::Located { inner, .. }
1638                | Node::Prov { inner, .. }
1639                | Node::Track { inner, .. } => unwrap_table(inner),
1640                _ => None,
1641            }
1642        }
1643        self.nodes.iter().filter_map(unwrap_table)
1644    }
1645
1646    /// Mutable access to the document's top-level tables, for repair
1647    /// workflows (#238): locate a cell via [`Table::find_cell_by_bbox`], fix
1648    /// its text with [`Table::set_cell_text`], then re-export — every
1649    /// serializer reads the same grid.
1650    pub fn tables_mut(&mut self) -> impl Iterator<Item = &mut Table> {
1651        fn unwrap_table(n: &mut Node) -> Option<&mut Table> {
1652            match n {
1653                Node::Table(t) => Some(t),
1654                Node::Located { inner, .. }
1655                | Node::Prov { inner, .. }
1656                | Node::Track { inner, .. } => unwrap_table(inner),
1657                _ => None,
1658            }
1659        }
1660        self.nodes.iter_mut().filter_map(unwrap_table)
1661    }
1662
1663    pub fn push(&mut self, node: Node) {
1664        self.nodes.push(node);
1665    }
1666
1667    /// Visit every [`Node::Picture`] in the flat node stream, wherever it
1668    /// nests — group children, table cell blocks, a picture's own
1669    /// children, the located/prov/track/comment/furniture wrappers — so an
1670    /// enrichment that reads the embedded images (picture OCR, #645) reaches
1671    /// each one. The callback gets the picture node itself.
1672    pub fn for_each_picture_mut(&mut self, f: &mut dyn FnMut(&mut Node)) {
1673        for_each_picture_in_mut(&mut self.nodes, f);
1674    }
1675
1676    /// Change the unit the pages are measured in: every length in page units
1677    /// — each [`Node::PageInfo`] size, a [`Node::Prov`] box, a first-class
1678    /// table cell's box, a script run's box — is multiplied by `sx`
1679    /// horizontally and `sy` vertically, and every image's `dpi` (its pixels
1680    /// per inch *of the page unit*: a picture crop, a page image) is divided
1681    /// by `sx`, so the same pixels still cover the same part of the page. The
1682    /// 0–511 `<location>` grid is relative to the page and needs nothing. The
1683    /// image input sizes its page from the file's resolution this way once
1684    /// the models have run on its pixels (#1093).
1685    pub fn rescale_page_units(&mut self, sx: f32, sy: f32) {
1686        let scale_box = |b: &mut [f32; 4]| {
1687            b[0] *= sx;
1688            b[1] *= sy;
1689            b[2] *= sx;
1690            b[3] *= sy;
1691        };
1692        let scale_dpi = |img: &mut PictureImage| {
1693            img.dpi = (img.dpi as f32 / sx).round().max(1.0) as u32;
1694        };
1695        fn table(t: &mut Table, scale_box: &dyn Fn(&mut [f32; 4]), walk: &dyn Fn(&mut [Node])) {
1696            for cell in t.cells.iter_mut().flatten() {
1697                if let Some(b) = cell.bbox.as_mut() {
1698                    scale_box(b);
1699                }
1700            }
1701            for row in t.cell_blocks.iter_mut().flatten() {
1702                for cell in row {
1703                    walk(cell);
1704                }
1705            }
1706        }
1707        fn walk(
1708            nodes: &mut [Node],
1709            sx: f32,
1710            sy: f32,
1711            scale_box: &dyn Fn(&mut [f32; 4]),
1712            scale_dpi: &dyn Fn(&mut PictureImage),
1713        ) {
1714            let recurse = |n: &mut [Node]| walk(n, sx, sy, scale_box, scale_dpi);
1715            for node in nodes {
1716                match node {
1717                    Node::PageInfo { width, height, .. } => {
1718                        *width *= sx;
1719                        *height *= sy;
1720                    }
1721                    Node::Prov { bbox, inner, .. } => {
1722                        scale_box(bbox);
1723                        recurse(std::slice::from_mut(inner));
1724                    }
1725                    Node::ScriptText { inner, runs } => {
1726                        for run in runs {
1727                            for prov in &mut run.prov {
1728                                scale_box(&mut prov.bbox);
1729                            }
1730                        }
1731                        recurse(std::slice::from_mut(inner));
1732                    }
1733                    Node::Located { inner, .. }
1734                    | Node::Track { inner, .. }
1735                    | Node::Furniture { inner, .. }
1736                    | Node::Commented { inner, .. }
1737                    | Node::DoclangOnly(inner) => recurse(std::slice::from_mut(inner)),
1738                    Node::Group { children, .. } | Node::PictureChildren(children) => {
1739                        recurse(children)
1740                    }
1741                    Node::Table(t) | Node::Chart { table: t, .. } => table(t, scale_box, &recurse),
1742                    Node::Picture {
1743                        image: Some(img), ..
1744                    } => scale_dpi(img),
1745                    _ => {}
1746                }
1747            }
1748        }
1749        walk(&mut self.nodes, sx, sy, &scale_box, &scale_dpi);
1750        for img in self.page_images.values_mut() {
1751            scale_dpi(img);
1752        }
1753    }
1754
1755    /// Convenience: append a heading.
1756    pub fn add_heading(&mut self, level: u8, text: impl Into<String>) {
1757        self.push(Node::Heading {
1758            level,
1759            text: text.into(),
1760        });
1761    }
1762
1763    /// Convenience: append a paragraph.
1764    pub fn add_paragraph(&mut self, text: impl Into<String>) {
1765        self.push(Node::Paragraph { text: text.into() });
1766    }
1767
1768    /// Serialize the document to Markdown.
1769    ///
1770    /// The Rust equivalent of docling-core's
1771    /// `DoclingDocument.export_to_markdown()`. Uses [`Self::strict_markdown`] to
1772    /// pick between docling-legacy output (default) and the cleaner, more
1773    /// conformant variant.
1774    pub fn export_to_markdown(&self) -> String {
1775        to_markdown(self, self.strict_markdown)
1776    }
1777
1778    /// Serialize to Markdown, explicitly choosing the mode regardless of
1779    /// [`Self::strict_markdown`]. `strict = true` produces cleaner, more
1780    /// conformant Markdown (code-fence languages preserved, no inline-run
1781    /// spacing artifacts); `strict = false` reproduces docling's legacy output.
1782    pub fn export_to_markdown_with(&self, strict: bool) -> String {
1783        to_markdown(self, strict)
1784    }
1785
1786    /// Markdown for this document as the *content of a rich table cell*
1787    /// (docling-core's `in_table_cell` serialization, docling-core#540):
1788    /// headings render as plain text since Markdown tables can't hold them.
1789    /// Backends build a sub-document per rich cell and flatten this into the
1790    /// cell text; no trailing newline.
1791    pub fn export_to_table_cell_markdown(&self) -> String {
1792        crate::markdown::to_markdown_table_cell(self, self.strict_markdown)
1793    }
1794
1795    /// Serialize to docling-core's native JSON wire format (`DoclingDocument`
1796    /// schema), pretty-printed — the Rust equivalent of
1797    /// `DoclingDocument.export_to_dict()` / `save_as_json()`. The output loads
1798    /// back into Python docling-core and round-trips to the same Markdown.
1799    pub fn export_to_json(&self) -> String {
1800        let mut out = Vec::new();
1801        self.write_json_pretty(&mut out)
1802            .expect("DoclingDocument JSON is always serializable");
1803        String::from_utf8(out).expect("serde_json writes UTF-8")
1804    }
1805
1806    /// The same JSON wire format as [`Self::export_to_json`], as a
1807    /// `serde_json::Value` — for callers that append response-level extras
1808    /// (docling-serve adds the confidence report, #183) before serializing.
1809    ///
1810    /// The `Value` is large — ~2.7 KB per text item — so on a long document
1811    /// prefer [`Self::write_json`], which writes the same JSON without it.
1812    pub fn export_to_json_value(&self) -> serde_json::Value {
1813        crate::json::to_json(self)
1814    }
1815
1816    /// Write the JSON of [`Self::export_to_json_value`] to `writer`, compact
1817    /// — byte for byte `serde_json::to_writer(writer, &doc.export_to_json_value())`
1818    /// — without building the `Value`: the export holds its text items in a
1819    /// compact form and serializes them straight to the writer. Wrap a file
1820    /// or socket in a `BufWriter`.
1821    pub fn write_json<W: std::io::Write>(&self, writer: W) -> std::io::Result<()> {
1822        crate::json::write_json(self, writer, false).map_err(std::io::Error::from)
1823    }
1824
1825    /// [`Self::write_json`], indented as [`Self::export_to_json`] is.
1826    pub fn write_json_pretty<W: std::io::Write>(&self, writer: W) -> std::io::Result<()> {
1827        crate::json::write_json(self, writer, true).map_err(std::io::Error::from)
1828    }
1829
1830    /// [`Self::write_json_pretty`] with `extras` appended to the top-level
1831    /// object after `pages` — byte for byte `serde_json::to_writer_pretty`
1832    /// of [`Self::export_to_json_value`] with each `value[key] = v` set (a
1833    /// key the document JSON does not have), without building that `Value`:
1834    /// docling-serve's response adds its `confidence` report this way.
1835    pub fn write_json_pretty_with<W: std::io::Write>(
1836        &self,
1837        writer: W,
1838        extras: &[(&str, &serde_json::Value)],
1839    ) -> std::io::Result<()> {
1840        crate::json::write_json_with(self, writer, true, extras).map_err(std::io::Error::from)
1841    }
1842
1843    /// Serialize to a complete LaTeX document — the Rust counterpart of
1844    /// docling-core's `LaTeXDocSerializer` with default parameters (docling
1845    /// 2.124's `--to latex`, #317). No trailing newline, like the upstream
1846    /// CLI's `<stem>.tex`.
1847    pub fn export_to_latex(&self) -> String {
1848        crate::latex::to_latex(self)
1849    }
1850
1851    /// Serialize to Pandoc's AST as JSON (`pandoc -f json`, #515) with the
1852    /// default options: pictures as captioned figures without image data,
1853    /// body layer only, the [`PANDOC_API_VERSION`](crate::pandoc::PANDOC_API_VERSION)
1854    /// API. One line, no trailing newline. See [`crate::pandoc`].
1855    pub fn export_to_pandoc_json(&self) -> String {
1856        crate::pandoc::to_pandoc(self, &crate::pandoc::PandocExportOptions::default())
1857            .expect("the default Pandoc API version is always supported")
1858            .0
1859    }
1860
1861    /// Pandoc JSON per `options` (image mode, artifacts directory, content
1862    /// layers, required API version). Returns the JSON and, for
1863    /// [`ImageMode::Referenced`], the `(path, bytes)` image files; an
1864    /// unsupported `api_version` is an error.
1865    pub fn export_to_pandoc_json_with(
1866        &self,
1867        options: &crate::pandoc::PandocExportOptions,
1868    ) -> Result<crate::pandoc::PandocOutput, crate::pandoc::PandocError> {
1869        crate::pandoc::to_pandoc(self, options)
1870    }
1871
1872    /// Serialize to DocLang XML (`<doclang version="0.7">…`), the markup that
1873    /// lives inside a `.dclx` archive — the Rust counterpart of docling-core's
1874    /// `export_to_doclang()` with default parameters. No trailing newline; the
1875    /// archive writer appends exactly one.
1876    pub fn export_to_doclang(&self) -> String {
1877        self.export_doclang(crate::doclang::Pictures::Referenced { collect: false })
1878            .0
1879    }
1880
1881    /// [`Self::export_to_doclang`] plus the picture assets its
1882    /// `<src uri="assets/image_….png"/>` references name, as `(path, bytes)`
1883    /// in document order — the parts docling's `save_as_doclang_archive`
1884    /// stores next to `document.xml`. PNG and JPEG pictures come back as PNG
1885    /// (a JPEG re-encoded from its libjpeg-decoded pixels); other encodings
1886    /// keep their own bytes for the archive writer to convert.
1887    pub fn export_to_doclang_with_assets(&self) -> (String, Vec<(String, Vec<u8>)>) {
1888        self.export_doclang(crate::doclang::Pictures::Referenced { collect: true })
1889    }
1890
1891    /// DocLang with docling's `image_mode` for pictures (#884):
1892    /// [`ImageMode::Placeholder`] writes no `<src>` — docling-core's own
1893    /// `export_to_doclang()` default, which upstream's `.dclg` fixtures hold
1894    /// — [`ImageMode::Embedded`] a `data:` URI of the PNG,
1895    /// [`ImageMode::Referenced`] is [`Self::export_to_doclang_with_assets`].
1896    pub fn export_to_doclang_with_images(
1897        &self,
1898        mode: ImageMode,
1899    ) -> (String, Vec<(String, Vec<u8>)>) {
1900        use crate::doclang::Pictures;
1901        self.export_doclang(match mode {
1902            ImageMode::Placeholder => Pictures::Placeholder,
1903            ImageMode::Embedded => Pictures::Embedded,
1904            ImageMode::Referenced => Pictures::Referenced { collect: true },
1905        })
1906    }
1907
1908    /// The item tree's DocLang — docling-core's `DocLangDocSerializer`
1909    /// ported over the tree (`doclang_tree.rs`, #884), the structure the
1910    /// JSON export writes — else (no tree, or one the port does not cover:
1911    /// provenance, picture meta, form fields) the nodes'. The flat nodes
1912    /// cannot carry a footnote's label, a caption's or a cell's inline
1913    /// formulas, text docling never wrote as Markdown, or the whitespace of
1914    /// an inline group's runs, which DocLang 0.9 reads as written.
1915    fn export_doclang(
1916        &self,
1917        pictures: crate::doclang::Pictures,
1918    ) -> (String, Vec<(String, Vec<u8>)>) {
1919        self.tree
1920            .as_ref()
1921            .filter(|t| !t.doclang_nodes)
1922            .and_then(|t| crate::doclang_tree::export(t, pictures))
1923            .unwrap_or_else(|| crate::doclang::render(&self.nodes, pictures))
1924    }
1925
1926    /// Serialize to Markdown with an explicit picture [`ImageMode`] (mirrors
1927    /// docling's `image_mode`). Returns the Markdown and, for
1928    /// [`ImageMode::Referenced`], the `(relative-path, bytes)` of each image the
1929    /// caller should write next to the Markdown file. `artifacts_dir` is the
1930    /// directory name used in referenced links.
1931    pub fn export_to_markdown_with_images(
1932        &self,
1933        image_mode: ImageMode,
1934        artifacts_dir: &str,
1935    ) -> (String, Vec<(String, Vec<u8>)>) {
1936        to_markdown_images(self, self.strict_markdown, image_mode, artifacts_dir)
1937    }
1938
1939    /// Markdown per `options` (#599) — docling-core's
1940    /// `export_to_markdown(included_content_layers=…, image_mode=…,
1941    /// image_placeholder=…, escape_html=…, escape_underscores=…,
1942    /// traverse_pictures=…)`: the content layers rendered, whether a
1943    /// picture's nested text items print, HTML and underscore escaping, the
1944    /// image placeholder, and the image mode with its referenced-image
1945    /// directory. [`Self::strict_markdown`] still picks the Markdown flavour.
1946    /// Returns the Markdown and, for [`ImageMode::Referenced`], the
1947    /// `(path, bytes)` artifacts. With [`MarkdownExportOptions::default`]
1948    /// the Markdown is [`Self::export_to_markdown`]'s byte for byte.
1949    pub fn export_to_markdown_with_options(
1950        &self,
1951        options: &MarkdownExportOptions,
1952    ) -> (String, Vec<(String, Vec<u8>)>) {
1953        crate::markdown::to_markdown_with_options(self, self.strict_markdown, options)
1954    }
1955
1956    /// WebVTT (#614) — what docling's `--to vtt` writes
1957    /// (`DoclingDocument.save_as_vtt`): a cue per timed text item — a WebVTT
1958    /// input's cues, an audio/video transcript's segments — hours always
1959    /// written, the `</v>` of a lone voice span omitted. A document without
1960    /// timed text is the bare `WEBVTT` header. No trailing newline.
1961    pub fn export_to_vtt(&self) -> String {
1962        crate::vtt::to_vtt(self, &crate::vtt::VttExportOptions::default())
1963    }
1964
1965    /// [`Self::export_to_vtt`] with docling-core's `WebVTTParams`
1966    /// (`omit_hours_if_zero`, `omit_voice_end`).
1967    pub fn export_to_vtt_with_options(&self, options: &crate::vtt::VttExportOptions) -> String {
1968        crate::vtt::to_vtt(self, options)
1969    }
1970
1971    /// Plain text — docling-core's `DoclingDocument.export_to_text()` with
1972    /// its defaults (#613, docling's `--to text` / `<stem>.txt`): the
1973    /// Markdown export without decoration ([`MarkdownExportOptions::plain_text`]).
1974    /// Lists keep their bullets and numbers, tables their `|` grid. No
1975    /// trailing newline: upstream's `serialize().text`, which its CLI
1976    /// writes verbatim to `<stem>.txt`.
1977    pub fn export_to_text(&self) -> String {
1978        let (mut text, _) = crate::markdown::to_markdown_with_options(
1979            self,
1980            self.strict_markdown,
1981            &MarkdownExportOptions::plain_text(),
1982        );
1983        if text.ends_with('\n') {
1984            text.pop();
1985        }
1986        text
1987    }
1988
1989    /// A complete HTML document — docling-core's `HTMLDocSerializer` with its
1990    /// defaults (#492): pictures stay out (`ImageRefMode.PLACEHOLDER`, only
1991    /// their captions and meta render). See [`export_to_html_with_images`]
1992    /// for the embedded / referenced modes and [`crate::html`]'s module docs
1993    /// for what is reproduced.
1994    ///
1995    /// [`export_to_html_with_images`]: Self::export_to_html_with_images
1996    pub fn export_to_html(&self) -> String {
1997        crate::html::to_html(self, &HtmlExportOptions::default()).0
1998    }
1999
2000    /// HTML with pictures per `image_mode`: `data:` URIs when embedded, and
2001    /// when referenced `<img src>` paths under `artifacts_dir` whose bytes come
2002    /// back as `(path, bytes)` for the caller to write — the Markdown export's
2003    /// contract and file names.
2004    pub fn export_to_html_with_images(
2005        &self,
2006        image_mode: ImageMode,
2007        artifacts_dir: &str,
2008    ) -> (String, Vec<(String, Vec<u8>)>) {
2009        crate::html::to_html(
2010            self,
2011            &HtmlExportOptions {
2012                image_mode,
2013                artifacts_dir: artifacts_dir.to_string(),
2014                ..HtmlExportOptions::default()
2015            },
2016        )
2017    }
2018
2019    /// HTML rendering the content `layers` — docling-core's
2020    /// `export_to_html(included_content_layers=…)` (#499). The default export
2021    /// is body only; `ContentLayers::BODY.with(ContentLayer::Furniture)` adds
2022    /// page headers/footers, `.with(ContentLayer::Notes)` reviewer comments,
2023    /// [`ContentLayers::ALL`] is Python's `set(ContentLayer)`. An item on a
2024    /// layer outside the set is skipped while its children are still walked,
2025    /// and the items that do render go through the same serializers as the
2026    /// body (a page header is a `<p>`, a comment a `<p>`, a header table a
2027    /// `<table>`), exactly as upstream's `HTMLParams.layers` behaves. Pictures
2028    /// stay placeholders; see [`export_to_html_with`] for the full option set.
2029    ///
2030    /// [`export_to_html_with`]: Self::export_to_html_with
2031    pub fn export_to_html_with_layers(&self, layers: ContentLayers) -> String {
2032        crate::html::to_html(
2033            self,
2034            &HtmlExportOptions {
2035                layers,
2036                ..HtmlExportOptions::default()
2037            },
2038        )
2039        .0
2040    }
2041
2042    /// HTML per `options` — image mode, referenced-image directory and content
2043    /// layers in one call; the other `export_to_html*` methods are
2044    /// shorthands for it. Returns the HTML and, for
2045    /// [`ImageMode::Referenced`], the `(path, bytes)` artifacts.
2046    pub fn export_to_html_with(
2047        &self,
2048        options: &HtmlExportOptions,
2049    ) -> (String, Vec<(String, Vec<u8>)>) {
2050        crate::html::to_html(self, options)
2051    }
2052}
2053
2054#[cfg(test)]
2055mod table_api_tests {
2056    use super::*;
2057
2058    fn cell(
2059        text: &str,
2060        bbox: [f32; 4],
2061        (start_row, start_col): (usize, usize),
2062        (row_span, col_span): (usize, usize),
2063    ) -> TableCell {
2064        TableCell {
2065            text: text.into(),
2066            bbox: Some(bbox),
2067            start_row,
2068            start_col,
2069            row_span,
2070            col_span,
2071            column_header: false,
2072            row_header: false,
2073            row_section: false,
2074        }
2075    }
2076
2077    fn table() -> Table {
2078        Table {
2079            rows: vec![
2080                vec!["Year".into(), "Ducks".into()],
2081                vec!["2019".into(), "120".into()],
2082            ],
2083            cells: Some(vec![
2084                cell("Year", [0.0, 0.0, 50.0, 10.0], (0, 0), (1, 1)),
2085                cell("Ducks", [50.0, 0.0, 100.0, 10.0], (0, 1), (1, 1)),
2086                cell("2019", [0.0, 10.0, 50.0, 20.0], (1, 0), (1, 1)),
2087                cell("120", [50.0, 10.0, 100.0, 20.0], (1, 1), (1, 1)),
2088            ]),
2089            ..Default::default()
2090        }
2091    }
2092
2093    /// Declarative tables derive first-class cells from the structure
2094    /// overlay: continuation grids become span extents, `col_header` (or the
2095    /// row-0 fallback) becomes the header role — the XLSX/DOCX/HTML merge
2096    /// path into real `TableCell`s (#240).
2097    #[test]
2098    fn derive_cells_reads_spans_and_headers_from_structure() {
2099        let t = Table {
2100            rows: vec![
2101                vec!["Wide".into(), "Wide".into(), "C".into()],
2102                vec!["a".into(), "b".into(), "c".into()],
2103            ],
2104            structure: Some(TableStructure {
2105                header_row: vec![true, false],
2106                col_continuation: vec![vec![false, true, false], vec![false; 3]],
2107                row_continuation: vec![vec![false; 3], vec![false; 3]],
2108                row_header: Vec::new(),
2109                col_header: Vec::new(),
2110            }),
2111            ..Default::default()
2112        };
2113        let cells = t.derive_cells();
2114        assert_eq!(cells.len(), 5, "two anchors in row 0, three in row 1");
2115        let wide = &cells[0];
2116        assert_eq!((wide.col_span, wide.row_span), (2, 1));
2117        assert!(wide.column_header, "header_row band");
2118        assert!(cells.iter().skip(2).all(|c| !c.column_header));
2119
2120        // Without any overlay: every position 1x1, row 0 the header
2121        // (docling's declarative default — the old JSON synthesis).
2122        let plain = Table {
2123            rows: vec![vec!["h".into()], vec!["x".into()]],
2124            ..Default::default()
2125        };
2126        let cells = plain.derive_cells();
2127        assert_eq!(cells.len(), 2);
2128        assert!(cells[0].column_header && !cells[1].column_header);
2129    }
2130
2131    /// A spanning cell updates once: the record text and every covered grid
2132    /// position — a repair shows once in Markdown, not once per column.
2133    #[test]
2134    fn span_repair_updates_the_whole_cell() {
2135        let mut t = Table {
2136            rows: vec![
2137                vec!["Wide".into(), "Wide".into(), "C".into()],
2138                vec!["a".into(), "b".into(), "c".into()],
2139            ],
2140            cells: Some(vec![
2141                cell("Wide", [0.0, 0.0, 100.0, 10.0], (0, 0), (1, 2)),
2142                cell("C", [100.0, 0.0, 150.0, 10.0], (0, 2), (1, 1)),
2143            ]),
2144            ..Default::default()
2145        };
2146        // Update through the covered (non-anchor) position.
2147        assert!(t.set_cell_text(0, 1, "Fixed"));
2148        assert_eq!(
2149            t.rows[0],
2150            vec!["Fixed".to_string(), "Fixed".into(), "C".into()]
2151        );
2152        assert_eq!(t.cell_at(0, 1).unwrap().text, "Fixed");
2153        assert_eq!(t.cell_at(0, 1).unwrap().col_span, 2);
2154    }
2155
2156    /// The OCR-repair loop (#238): locate a cell by an external box (best
2157    /// IoU), replace its text, and see the fix in the export — the grid is
2158    /// the single source of truth for every serializer.
2159    #[test]
2160    fn bbox_lookup_and_repair_flow_into_exports() {
2161        let mut doc = DoclingDocument::new("t");
2162        doc.push(Node::Table(table()));
2163        assert_eq!(doc.tables().count(), 1);
2164
2165        let t = doc.tables_mut().next().unwrap();
2166        // A slightly-off OCR box still lands on the (1,1) cell.
2167        assert_eq!(t.find_cell_by_bbox([52.0, 11.0, 98.0, 19.0]), Some((1, 1)));
2168        assert_eq!(
2169            t.update_cell_by_bbox([52.0, 11.0, 98.0, 19.0], "125"),
2170            Some((1, 1))
2171        );
2172        assert_eq!(t.cell_text(1, 1), Some("125"));
2173        assert!(doc.export_to_markdown().contains("125"));
2174
2175        // No overlap → no match, nothing changed.
2176        let t = doc.tables_mut().next().unwrap();
2177        assert_eq!(t.find_cell_by_bbox([500.0, 500.0, 600.0, 600.0]), None);
2178    }
2179
2180    #[test]
2181    fn cell_accessors_bound_check_and_geometry_materializes() {
2182        let mut t = table();
2183        assert_eq!(t.cell_text(0, 0), Some("Year"));
2184        assert_eq!(t.cell_text(5, 0), None);
2185        assert!(!t.set_cell_text(0, 9, "x"), "outside the grid");
2186        assert_eq!(t.cell_bbox(1, 0), Some([0.0, 10.0, 50.0, 20.0]));
2187
2188        // A geometry-less table materializes its box grid on first set.
2189        let mut plain = Table {
2190            rows: vec![vec!["a".into(), "b".into()]],
2191            ..Default::default()
2192        };
2193        assert_eq!(plain.cell_bbox(0, 1), None);
2194        assert!(!plain.set_cell_bbox(0, 5, [0.0; 4]), "outside the grid");
2195        assert!(plain.set_cell_bbox(0, 1, [1.0, 2.0, 3.0, 4.0]));
2196        assert_eq!(plain.cell_bbox(0, 1), Some([1.0, 2.0, 3.0, 4.0]));
2197        assert_eq!(plain.find_cell_by_bbox([1.5, 2.5, 2.5, 3.5]), Some((0, 1)));
2198    }
2199}
2200
2201#[cfg(test)]
2202mod rescale_tests {
2203    use super::*;
2204
2205    fn image(dpi: u32) -> PictureImage {
2206        PictureImage {
2207            mimetype: "image/png".into(),
2208            width: 300,
2209            height: 150,
2210            data: Vec::new(),
2211            dpi,
2212            display_size: None,
2213        }
2214    }
2215
2216    /// #1093: a page measured in pixels re-measured in points — the page size,
2217    /// a table cell's box and a script run's box scale per axis, an image's
2218    /// pixels per inch of the page grow by the inverse, and the 0–511
2219    /// locations, relative to the page, stay.
2220    #[test]
2221    fn a_page_unit_change_scales_lengths_and_resolutions() {
2222        let table = Table {
2223            rows: vec![vec!["a".into()]],
2224            location: Some([10, 20, 30, 40]),
2225            cells: Some(vec![TableCell {
2226                text: "a".into(),
2227                bbox: Some([100.0, 200.0, 300.0, 400.0]),
2228                start_row: 0,
2229                start_col: 0,
2230                row_span: 1,
2231                col_span: 1,
2232                column_header: false,
2233                row_header: false,
2234                row_section: false,
2235            }]),
2236            ..Table::default()
2237        };
2238        let mut doc = DoclingDocument::new("scan");
2239        doc.push(Node::PageInfo {
2240            page_no: 1,
2241            width: 1000.0,
2242            height: 2000.0,
2243        });
2244        doc.push(Node::Located {
2245            location: [1, 2, 3, 4],
2246            inner: Box::new(Node::Table(table)),
2247        });
2248        doc.push(Node::Group {
2249            label: "group".into(),
2250            name: None,
2251            layer: None,
2252            children: vec![Node::Picture {
2253                caption: None,
2254                caption_href: None,
2255                image: Some(image(72)),
2256                classification: None,
2257                description: None,
2258                caption_parent: Default::default(),
2259                caption_location: None,
2260            }],
2261        });
2262        doc.page_images.insert(1, image(144));
2263
2264        doc.rescale_page_units(0.24, 0.5);
2265
2266        assert!(matches!(
2267            doc.nodes[0],
2268            Node::PageInfo { width, height, .. } if width == 240.0 && height == 1000.0
2269        ));
2270        let Node::Located { location, inner } = &doc.nodes[1] else {
2271            panic!("located table")
2272        };
2273        assert_eq!(*location, [1, 2, 3, 4]);
2274        let Node::Table(t) = inner.as_ref() else {
2275            panic!("table")
2276        };
2277        assert_eq!(t.location, Some([10, 20, 30, 40]));
2278        assert_eq!(
2279            t.cells.as_ref().unwrap()[0].bbox,
2280            Some([24.0, 100.0, 72.0, 200.0])
2281        );
2282        let Node::Group { children, .. } = &doc.nodes[2] else {
2283            panic!("group")
2284        };
2285        assert!(matches!(&children[0], Node::Picture { image: Some(i), .. } if i.dpi == 300));
2286        assert_eq!(doc.page_images[&1].dpi, 600);
2287    }
2288}