docling 1.93.4

//! DOC (Word 97–2004 binary, [MS-DOC]) backend — issue #127.
//!
//! Native parsing, no external converter (docling proper shells out to
//! LibreOffice for these files — `docling` PR #3804). The format is a CFB
//! container ([`cfb`]) holding a `WordDocument` stream (FIB header + raw text)
//! and a `0Table`/`1Table` stream (the piece table and formatting):
//!
//! 1. The **FIB** locates the CLX in the table stream and says how long the
//!    main document text is (`ccpText`).
//! 2. The **piece table** (CLX → PlcPcd) maps character positions (CPs) to
//!    file offsets (FCs) — pieces are either 8-bit CP1252 or UTF-16LE.
//! 3. Text is split into paragraphs at the paragraph mark (`\r`) / cell mark
//!    (`0x07`); each paragraph's properties come from its **PAPX** (found via
//!    the PlcfBtePapx → FKP page for the mark's FC): the style index `istd`,
//!    `fInTable` (table cell content) and `fTtp` (table row terminator).
//! 4. The **stylesheet** (STSH) maps `istd` to the built-in style identifier
//!    `sti` — 1–9 are the Heading 1–9 styles, giving real headings.
//!
//! Scope: headings, paragraphs, list items (by list-format reference),
//! tables (cell/row marks), and embedded pictures — both inline (`0x01`
//! anchor → `sprmCPicLocation` → PICF in the Data stream) and floating
//! (`0x08` anchor → PlcfSpa → the drawing's shape → BLIP store, with
//! delay-stream data in `WordDocument`), decoded via [`officeart`].
//!
//! The other **stories** (#535) follow the main text in the same CP space —
//! footnotes (`ccpFtn`), headers/footers (`ccpHdd`), comments, endnotes,
//! text boxes (`ccpTxbx`) — and are read too: a text box's story
//! (`PlcftxbxTxt`, linked to its shape by `lid`) is placed at the shape's
//! anchor (a `textbox` section group, or extra paragraphs of the table cell
//! it is anchored in, as the DOCX backend reads the same document); each
//! section's header/footer stories (`PlcfHdd`, after the six separator
//! stories) become `page_header` / `page_footer` furniture; footnote and
//! endnote bodies (`PlcffndTxt` / `PlcfendTxt`) `footnote` furniture after
//! the body. Comments and header text boxes are not read.
//!
//! The FIB is read through [`Fib`], which locates `fibRgLw` and
//! `fibRgFcLcb` from the counts the stream itself declares (`csw`, `cslw`,
//! `cbRgFcLcb`) instead of fixed offsets, so a short or truncated FIB is an
//! error naming what is missing and an `fc`/`lcb` pair beyond the writer's
//! `cbRgFcLcb` reads as "structure absent" (#512).
//!
//! **Word 6.0 / Word 95** (`nFib` 101–105, the pre-97 FIB — no table stream,
//! 8-bit text only) converts too, as text: the FIB's `fcMin`/`ccpText`
//! locate the main text in `WordDocument`, or its CLX does for a fast-saved
//! (complex) file; paragraphs split at the paragraph/cell/page marks. That
//! format's stylesheet, PAPX and picture structures differ from Word 97's
//! and are not read, so its output is body paragraphs (no headings, lists,
//! tables or pictures) — where it used to be rejected outright. Text decodes
//! as Windows-1252, the code page of the Western editions, or as UTF-16LE
//! when the FIB's `fExtChar` is set (the Far East editions). Older files
//! (Word for Windows 1.x/2.0) are not compound files and never reach here.

use docling_core::{DoclingDocument, Node, PictureImage, Table};

use crate::backend::cfb::CompoundFile;
use crate::backend::officeart;
use crate::backend::DeclarativeBackend;
use crate::error::ConversionError;
use crate::source::SourceDocument;

pub struct DocBackend;

impl DeclarativeBackend for DocBackend {
    fn convert(&self, source: &SourceDocument) -> Result<DoclingDocument, ConversionError> {
        let cfb = CompoundFile::open(&source.bytes).ok_or_else(|| {
            ConversionError::Parse(CompoundFile::open_error("doc", &source.bytes))
        })?;
        let word = cfb
            .stream("WordDocument")
            .ok_or_else(|| ConversionError::Parse(cfb.stream_error("doc", "WordDocument")))?;
        let w_ident = u16_at(&word, 0).ok_or_else(|| {
            ConversionError::Parse(format!(
                "doc: WordDocument stream too short for a FIB ({} bytes)",
                word.len()
            ))
        })?;
        let n_fib = u16_at(&word, 2).unwrap_or(0);
        let flags = u16_at(&word, 0x0A).unwrap_or(0);
        if flags & 0x0100 != 0 {
            return Err(ConversionError::Parse("doc: document is encrypted".into()));
        }
        if w_ident != 0xA5EC {
            if (101..=105).contains(&n_fib) {
                return convert_word6(&source.name, &word, flags);
            }
            return Err(ConversionError::Parse(format!(
                "doc: unsupported Word binary format (wIdent {w_ident:#06X}, nFib {n_fib}); \
                 Word 6.0/95 and Word 97 or later are read"
            )));
        }
        let fib = Fib::parse(&word)?;
        let table_name = if flags & 0x0200 != 0 {
            "1Table"
        } else {
            "0Table"
        };
        let table = cfb
            .stream(table_name)
            .ok_or_else(|| ConversionError::Parse(format!("doc: no {table_name} stream")))?;

        let ccp_text = fib.ccp_text as u64;
        let (fc_clx, lcb_clx) = fib.fc_lcb(Fib::CLX);
        // Two distinct failures, reported apart (#512): a CLX the FIB places
        // outside the table stream means the FIB and the table stream do not
        // belong together (or one is truncated); one inside it that does not
        // parse is a damaged piece table.
        let clx = fc_clx
            .checked_add(lcb_clx)
            .and_then(|end| table.get(fc_clx..end))
            .ok_or_else(|| {
                ConversionError::Parse(format!(
                    "doc: piece table (fcClx {fc_clx}, lcbClx {lcb_clx}) lies outside the \
                     {table_name} stream ({} bytes)",
                    table.len()
                ))
            })?;
        let pieces = parse_piece_table(clx, None).ok_or_else(|| {
            ConversionError::Parse(format!(
                "doc: bad piece table (fcClx {fc_clx}, lcbClx {lcb_clx} in {table_name})"
            ))
        })?;

        // Styles (istd → sti) and paragraph properties (FC → PAPX).
        let stis = parse_stsh(fib.part(&table, Fib::STSHF));
        let bte = fib.part(&table, Fib::PLCF_BTE_PAPX);
        // Character-run properties (bold/italic): PlcfBteChpx → CHPX FKPs.
        let btec = fib.part(&table, Fib::PLCF_BTE_CHPX);
        let mut chpx_cache = ChpxCache::default();

        // List tables: ilfo → numbering kind/start per level (ordered lists).
        let (fc_lst, lcb_lst) = fib.fc_lcb(Fib::PLF_LST);
        // `lcbPlfLst` covers only the LSTF array; the per-list LVL structures
        // follow it directly in the table stream, so hand `parse` the tail.
        let lists = ListTables::parse(
            table.get(fc_lst..).unwrap_or(&[]),
            lcb_lst,
            fib.part(&table, Fib::PLF_LFO),
        );

        // Pictures: the Data stream holds inline PICFs; the drawing tables
        // (fcDggInfo, in the table stream) + PlcfSpa anchor floating shapes.
        let data = cfb.stream("Data").unwrap_or_default();
        let spa = parse_plcf_spa(fib.part(&table, Fib::PLCSPA_MOM));
        let drawings = Drawings::parse(fib.part(&table, Fib::DGG_INFO), &word);

        // The stories follow each other in one CP space ([MS-DOC] 2.3.1):
        // main text, footnotes, headers, comments, endnotes, text boxes.
        let ftn_base = ccp_text;
        let hdd_base = ftn_base + fib.ccp_ftn as u64;
        let edn_base = hdd_base + fib.ccp_hdd as u64 + fib.ccp_atn as u64;
        let txbx_base = edn_base + fib.ccp_edn as u64;
        let story = Story {
            word: &word,
            pieces: &pieces,
            bte,
            btec,
            stis: &stis,
            data: &data,
            spa: &spa,
            drawings: &drawings,
            textboxes: parse_textboxes(
                fib.part(&table, Fib::PLCF_TXBX_TXT),
                txbx_base,
                fib.ccp_txbx as u64,
            ),
            placed: Default::default(),
            lists: &lists,
        };

        // Walk the main-document text paragraph by paragraph, assembling nodes.
        let mut doc = DoclingDocument::new(&source.name);
        story.walk(&mut chpx_cache, 0, ccp_text, true, &mut doc);
        // A text box no anchor in the main text placed (its shape lives in a
        // header, or the drawing tables disagree) still reaches the document:
        // at the end of the body, in story order.
        let mut unplaced: Vec<(u64, u64)> = story
            .textboxes
            .iter()
            .filter(|(spid, _)| !story.placed.borrow().contains(spid))
            .map(|(_, &range)| range)
            .collect();
        unplaced.sort_unstable();
        for (a, b) in unplaced {
            let mut inner = DoclingDocument::new("");
            story.walk(&mut chpx_cache, a, b, false, &mut inner);
            if !inner.nodes.is_empty() {
                doc.push(Node::Group {
                    label: "section".into(),
                    name: Some("textbox".into()),
                    layer: None,
                    children: inner.nodes,
                });
            }
        }

        // The other stories (#535): headers/footers, then the note bodies —
        // furniture, after the body, where the DOCX backend puts them.
        for (footer, text) in header_footer_texts(
            &story,
            &mut chpx_cache,
            fib.part(&table, Fib::PLCF_HDD),
            hdd_base,
            fib.ccp_hdd as u64,
        ) {
            doc.push(Node::FurnitureText {
                label: if footer { "page_footer" } else { "page_header" }.into(),
                text,
            });
        }
        for (refs, txt, base, len) in [
            (Fib::PLCF_FND_REF, Fib::PLCF_FND_TXT, ftn_base, fib.ccp_ftn),
            (Fib::PLCF_END_REF, Fib::PLCF_END_TXT, edn_base, fib.ccp_edn),
        ] {
            for text in note_texts(
                &story,
                &mut chpx_cache,
                fib.part(&table, refs),
                fib.part(&table, txt),
                base,
                len as u64,
            ) {
                doc.push(Node::FurnitureText {
                    label: "footnote".into(),
                    text,
                });
            }
        }
        Ok(doc)
    }
}

/// One Word 97 document's text, for walking any of its stories: the piece
/// table over the whole CP space and the lookups a paragraph needs.
struct Story<'a> {
    word: &'a [u8],
    pieces: &'a [Piece],
    bte: &'a [u8],
    btec: &'a [u8],
    stis: &'a [StyleDef],
    data: &'a [u8],
    spa: &'a [(u64, u32)],
    drawings: &'a Drawings,
    /// Shape id → its text box story, as absolute CPs (`[start, end)`).
    textboxes: std::collections::HashMap<u32, (u64, u64)>,
    /// The text boxes placed at an anchor so far (shape ids).
    placed: std::cell::RefCell<std::collections::HashSet<u32>>,
    lists: &'a ListTables,
}

impl Story<'_> {
    /// The character at absolute `cp` and its FC, via the piece table.
    fn char_at(&self, cp: u64) -> Option<(char, u64)> {
        let k = self.pieces.partition_point(|p| p.cp_end <= cp);
        let piece = self.pieces.get(k).filter(|p| p.cp_start <= cp)?;
        let i = cp - piece.cp_start;
        Some((piece_char(self.word, piece, i), piece_fc(piece, i)))
    }

    /// Walk CPs `from..to` paragraph by paragraph into `doc`. Only the main
    /// story places text boxes (`textboxes`): a text box's own story never
    /// anchors another.
    fn walk(
        &self,
        cache: &mut ChpxCache,
        from: u64,
        to: u64,
        textboxes: bool,
        doc: &mut DoclingDocument,
    ) {
        let mut builder = NodeBuilder::new(self.lists.clone());
        let mut para = ParaAccum::default();
        for cp in from..to {
            let Some((ch, fc)) = self.char_at(cp) else {
                break;
            };
            match ch {
                '\r' | '\u{0007}' | '\u{000C}' => {
                    // Paragraph / cell / page mark: property lookup is by
                    // the mark's own FC.
                    let props = paragraph_props(self.word, self.bte, fc);
                    para.finish(ch, props, self.stis, &mut builder, doc);
                }
                // Inline picture anchor: the run's CHPX locates the PICF.
                '\u{0001}' => {
                    if let Some(pic_fc) = cache.props(self.word, self.btec, fc).pic_fc {
                        para.add_picture(inline_picture(self.data, pic_fc));
                    }
                }
                // Floating-shape anchor: PlcfSpa maps this CP to a shape — its
                // pictures, and its text box story (#535).
                '\u{0008}' => {
                    if let Some(spid) = spa_shape_at(self.spa, cp) {
                        for image in self.drawings.shape_pictures(spid, 0) {
                            para.add_picture(image);
                        }
                        if let Some(&(a, b)) = self.textboxes.get(&spid).filter(|_| textboxes) {
                            self.placed.borrow_mut().insert(spid);
                            let mut inner = DoclingDocument::new("");
                            self.walk(cache, a, b, false, &mut inner);
                            if !inner.nodes.is_empty() {
                                para.textboxes.push(inner.nodes);
                            }
                        }
                    }
                }
                _ => para.push(ch, cache.props(self.word, self.btec, fc)),
            }
        }
        para.finish('\r', ParaProps::default(), self.stis, &mut builder, doc);
        builder.flush(doc);
    }

    /// The plain text of CPs `from..to`, one entry per non-empty paragraph
    /// (fields resolved to their results, note reference marks dropped) —
    /// header/footer and note bodies.
    fn paragraphs(&self, cache: &mut ChpxCache, from: u64, to: u64) -> Vec<String> {
        let mut out = Vec::new();
        let mut para = ParaAccum::default();
        for cp in from..to {
            let Some((ch, fc)) = self.char_at(cp) else {
                break;
            };
            match ch {
                '\r' | '\u{0007}' | '\u{000C}' => {
                    let text = para.plain().trim().to_string();
                    para.segments.clear();
                    para.field_stack.clear();
                    if !text.is_empty() {
                        out.push(text);
                    }
                }
                _ => para.push(ch, cache.props(self.word, self.btec, fc)),
            }
        }
        let text = para.plain().trim().to_string();
        if !text.is_empty() {
            out.push(text);
        }
        out
    }
}

/// `PlcftxbxTxt` ([MS-DOC] 2.8.28): `n + 1` CPs into the text box story,
/// then `n` 22-byte FTXBXS whose `lid` (at byte 14) is the shape id of the
/// box showing that story — what PlcfSpa's anchors name. Word appends a
/// dummy last entry (`lid` 0 / -1), skipped. Ranges come back absolute
/// (`base` = the text box story's first CP), clamped to its `len`.
fn parse_textboxes(plc: &[u8], base: u64, len: u64) -> std::collections::HashMap<u32, (u64, u64)> {
    let mut out = std::collections::HashMap::new();
    if plc.len() < 4 {
        return out;
    }
    let n = (plc.len() - 4) / (4 + 22);
    for i in 0..n {
        let (Some(a), Some(b)) = (u32_at(plc, i * 4), u32_at(plc, i * 4 + 4)) else {
            break;
        };
        let Some(lid) = u32_at(plc, (n + 1) * 4 + i * 22 + 14) else {
            break;
        };
        let (a, b) = (a as u64, (b as u64).min(len));
        if lid != 0 && lid != u32::MAX && b > a {
            out.insert(lid, (base + a, base + b));
        }
    }
    out
}

/// Each section's header / footer text (#535): `PlcfHdd`'s CPs into the
/// header story — six separator stories first, then per section even /
/// odd (default) / first header and footer, as `(is_footer, paragraph)`
/// in reading order (default, first, even — headers before footers), each
/// distinct paragraph once.
fn header_footer_texts(
    story: &Story,
    cache: &mut ChpxCache,
    plc: &[u8],
    base: u64,
    len: u64,
) -> Vec<(bool, String)> {
    let cps: Vec<u64> = plc
        .chunks_exact(4)
        .filter_map(|c| u32_at(c, 0).map(u64::from))
        .collect();
    let mut out: Vec<(bool, String)> = Vec::new();
    let mut section = 6;
    while section + 6 < cps.len() {
        // Story order within a section: even hdr, odd hdr, even ftr, odd
        // ftr, first hdr, first ftr.
        for (k, footer) in [
            (1, false),
            (4, false),
            (0, false),
            (3, true),
            (5, true),
            (2, true),
        ] {
            let (a, b) = (cps[section + k], cps[section + k + 1].min(len));
            if a >= b {
                continue;
            }
            for text in story.paragraphs(cache, base + a, base + b) {
                if !out.iter().any(|(f, t)| *f == footer && *t == text) {
                    out.push((footer, text));
                }
            }
        }
        section += 6;
    }
    out
}

/// The footnote (or endnote) bodies (#535): `refs` (PlcffndRef: `n + 1`
/// CPs + `n` 2-byte FRDs) says how many there are; `txt` (PlcffndTxt) gives
/// each one's CPs in its story, starting at `base`. A note's paragraphs
/// are joined with a space, like the DOCX backend's.
fn note_texts(
    story: &Story,
    cache: &mut ChpxCache,
    refs: &[u8],
    txt: &[u8],
    base: u64,
    len: u64,
) -> Vec<String> {
    if refs.len() < 4 || len == 0 {
        return Vec::new();
    }
    let n = (refs.len() - 4) / 6;
    (0..n)
        .filter_map(|i| {
            let a = u32_at(txt, i * 4)? as u64;
            let b = (u32_at(txt, i * 4 + 4)? as u64).min(len);
            (a < b).then(|| story.paragraphs(cache, base + a, base + b).join(" "))
        })
        .filter(|t| !t.is_empty())
        .collect()
}

/// The Word 97+ FIB, located from the counts the stream declares
/// ([MS-DOC] 2.5.1): `FibBase` (32 bytes), `csw` + `fibRgW`, `cslw` +
/// `fibRgLw`, `cbRgFcLcb` + `fibRgFcLcbBlob`. Writers size these arrays by
/// `nFib`; reading them through the declared counts — rather than the
/// fixed offsets of the common `csw = 14`, `cslw = 22` layout — keeps a
/// non-standard or truncated FIB from silently reading garbage.
struct Fib<'a> {
    ccp_text: u32,
    /// The other stories' lengths in CPs, in their CP-space order after the
    /// main text ([MS-DOC] 2.5.4 `FibRgLw97`); 0 when the FIB is too short
    /// to say.
    ccp_ftn: u32,
    ccp_hdd: u32,
    ccp_atn: u32,
    ccp_edn: u32,
    ccp_txbx: u32,
    /// `fibRgFcLcbBlob`: `(fc, lcb)` u32 pairs.
    fc_lcb: &'a [u8],
}

impl<'a> Fib<'a> {
    /// Indices into `FibRgFcLcb97` (each an 8-byte `fc`/`lcb` pair).
    const STSHF: usize = 1;
    const PLCF_FND_REF: usize = 2;
    const PLCF_FND_TXT: usize = 3;
    const PLCF_HDD: usize = 11;
    const PLCF_BTE_CHPX: usize = 12;
    const PLCF_BTE_PAPX: usize = 13;
    const CLX: usize = 33;
    const PLCSPA_MOM: usize = 40;
    const PLCF_END_REF: usize = 46;
    const PLCF_END_TXT: usize = 47;
    const DGG_INFO: usize = 50;
    const PLCF_TXBX_TXT: usize = 56;
    const PLF_LST: usize = 73;
    const PLF_LFO: usize = 74;

    fn parse(word: &'a [u8]) -> Result<Self, ConversionError> {
        let short = |what: &str, need: usize| {
            ConversionError::Parse(format!(
                "doc: FIB truncated — {what} needs {need} bytes, WordDocument has {}",
                word.len()
            ))
        };
        let csw = u16_at(word, 32).ok_or_else(|| short("csw", 34))? as usize;
        let cslw_at = 34 + csw * 2;
        let cslw = u16_at(word, cslw_at).ok_or_else(|| short("cslw", cslw_at + 2))? as usize;
        let lw_at = cslw_at + 2;
        if cslw < 4 {
            return Err(ConversionError::Parse(format!(
                "doc: FIB's fibRgLw has {cslw} entries, too few for ccpText"
            )));
        }
        let ccp_text = u32_at(word, lw_at + 12).ok_or_else(|| short("ccpText", lw_at + 16))?;
        // `fibRgLw` index → CP count, when the writer's `cslw` covers it.
        let lw = |i: usize| {
            if i < cslw {
                u32_at(word, lw_at + i * 4).unwrap_or(0)
            } else {
                0
            }
        };
        let cb_at = lw_at + cslw * 4;
        let cb = u16_at(word, cb_at).ok_or_else(|| short("cbRgFcLcb", cb_at + 2))? as usize;
        let blob_at = cb_at + 2;
        let fc_lcb = word
            .get(blob_at..blob_at + cb * 8)
            .ok_or_else(|| short("fibRgFcLcbBlob", blob_at + cb * 8))?;
        Ok(Self {
            ccp_text,
            ccp_ftn: lw(4),
            ccp_hdd: lw(5),
            ccp_atn: lw(7),
            ccp_edn: lw(8),
            ccp_txbx: lw(9),
            fc_lcb,
        })
    }

    /// The `index`-th `(fc, lcb)` pair; `(0, 0)` — "absent" — past the
    /// writer's `cbRgFcLcb`.
    fn fc_lcb(&self, index: usize) -> (usize, usize) {
        let fc = u32_at(self.fc_lcb, index * 8).unwrap_or(0) as usize;
        let lcb = u32_at(self.fc_lcb, index * 8 + 4).unwrap_or(0) as usize;
        (fc, lcb)
    }

    /// The bytes of structure `index` in `stream`; empty when absent or when
    /// the range overruns the stream (optional structures degrade).
    fn part<'s>(&self, stream: &'s [u8], index: usize) -> &'s [u8] {
        let (fc, lcb) = self.fc_lcb(index);
        fc.checked_add(lcb)
            .and_then(|end| stream.get(fc..end))
            .unwrap_or(&[])
    }
}

/// Word 6.0 / Word 95 (`nFib` 101–105): main-document text as body
/// paragraphs (module docs). The pre-97 FIB is fixed-layout: `fcMin` at
/// 0x18, `ccpText` at 0x34, `fcClx`/`lcbClx` at 0x160 — the CLX lives in
/// `WordDocument` itself (no table stream) and only matters for a
/// fast-saved file (`fComplex`); otherwise the text is the `ccpText` bytes
/// at `fcMin`. `fExtChar` (flag 0x1000, the Far East editions) makes the
/// text UTF-16LE instead of 8-bit.
fn convert_word6(name: &str, word: &[u8], flags: u16) -> Result<DoclingDocument, ConversionError> {
    let field = |o: usize, what: &str| {
        u32_at(word, o).map(|v| v as usize).ok_or_else(|| {
            ConversionError::Parse(format!(
                "doc: Word 6/95 FIB truncated — no {what} at {o:#x} ({} bytes)",
                word.len()
            ))
        })
    };
    let fc_min = field(0x18, "fcMin")?;
    let ccp_text = field(0x34, "ccpText")? as u64;
    // `fExtChar`: the Far East editions store the text as UTF-16LE.
    let unicode = flags & 0x1000 != 0;
    let pieces = if flags & 0x0004 != 0 {
        let fc_clx = field(0x160, "fcClx")?;
        let lcb_clx = field(0x164, "lcbClx")?;
        let clx = fc_clx
            .checked_add(lcb_clx)
            .and_then(|end| word.get(fc_clx..end))
            .ok_or_else(|| {
                ConversionError::Parse(format!(
                    "doc: piece table (fcClx {fc_clx}, lcbClx {lcb_clx}) lies outside the \
                     WordDocument stream ({} bytes)",
                    word.len()
                ))
            })?;
        parse_piece_table(clx, Some(unicode)).ok_or_else(|| {
            ConversionError::Parse(format!(
                "doc: bad piece table (fcClx {fc_clx}, lcbClx {lcb_clx} in WordDocument)"
            ))
        })?
    } else {
        vec![Piece {
            cp_start: 0,
            cp_end: ccp_text,
            fc: fc_min as u64,
            compressed: !unicode,
        }]
    };

    let mut doc = DoclingDocument::new(name);
    let mut builder = NodeBuilder::new(ListTables::default());
    let mut para = ParaAccum::default();
    let mut cp: u64 = 0;
    'pieces: for piece in &pieces {
        for i in 0..piece.cp_end.saturating_sub(piece.cp_start) {
            if cp >= ccp_text {
                break 'pieces;
            }
            cp += 1;
            match piece_char(word, piece, i) {
                // Paragraph / cell / page marks all end a body paragraph:
                // without the PAPX there is no table structure to rebuild.
                '\r' | '\u{0007}' | '\u{000C}' => {
                    para.finish('\r', ParaProps::default(), &[], &mut builder, &mut doc);
                }
                ch => para.push(ch, CharFmt::default()),
            }
        }
    }
    para.finish('\r', ParaProps::default(), &[], &mut builder, &mut doc);
    builder.flush(&mut doc);
    Ok(doc)
}

/// One piece-table entry: characters `cp_start..cp_end` live at byte offset
/// `fc` (already unmasked) — CP1252 bytes when `compressed`, else UTF-16LE.
struct Piece {
    cp_start: u64,
    cp_end: u64,
    fc: u64,
    compressed: bool,
}

/// The `i`-th character of a piece (bounds-safe; U+FFFD off the end).
fn piece_char(word: &[u8], piece: &Piece, i: u64) -> char {
    if piece.compressed {
        let b = word.get((piece.fc + i) as usize).copied().unwrap_or(0);
        cp1252(b)
    } else {
        let o = (piece.fc + 2 * i) as usize;
        let u = u16_at(word, o).unwrap_or(0xFFFD);
        char::from_u32(u as u32).unwrap_or('\u{FFFD}')
    }
}

/// The byte offset (FC) of the `i`-th character of a piece.
fn piece_fc(piece: &Piece, i: u64) -> u64 {
    if piece.compressed {
        piece.fc + i
    } else {
        piece.fc + 2 * i
    }
}

/// Parse the CLX into pieces. The CLX is a run of `Prc` blocks (0x01, skipped)
/// followed by the `Pcdt` (0x02) holding the PlcPcd.
///
/// `word6`: a Word 6.0/95 CLX — `Some(unicode)` — whose PCD `fc` is a plain
/// byte offset (bit 30 carries no meaning there) to text that is 8-bit, or
/// UTF-16LE throughout when the FIB's `fExtChar` says so.
fn parse_piece_table(clx: &[u8], word6: Option<bool>) -> Option<Vec<Piece>> {
    let mut pos = 0usize;
    loop {
        match clx.get(pos)? {
            0x01 => {
                let cb = u16_at(clx, pos + 1)? as usize;
                pos += 3 + cb;
            }
            0x02 => {
                let lcb = u32_at(clx, pos + 1)? as usize;
                let plc = clx.get(pos + 5..(pos + 5).checked_add(lcb)?)?;
                // n pieces: (n+1) CPs (4 bytes) + n PCDs (8 bytes).
                let n = (lcb.checked_sub(4)?) / 12;
                let mut pieces = Vec::with_capacity(n);
                for i in 0..n {
                    let cp_start = u32_at(plc, i * 4)? as u64;
                    let cp_end = u32_at(plc, (i + 1) * 4)? as u64;
                    let pcd = (n + 1) * 4 + i * 8;
                    let fc_raw = u32_at(plc, pcd + 2)?;
                    let compressed = match word6 {
                        Some(unicode) => !unicode,
                        None => fc_raw & 0x4000_0000 != 0,
                    };
                    let fc = if word6.is_some() {
                        fc_raw as u64
                    } else if compressed {
                        ((fc_raw & 0x3FFF_FFFF) / 2) as u64
                    } else {
                        fc_raw as u64
                    };
                    pieces.push(Piece {
                        cp_start,
                        cp_end,
                        fc,
                        compressed,
                    });
                }
                return Some(pieces);
            }
            _ => return None,
        }
    }
}

/// Properties of one paragraph, read from its PAPX.
#[derive(Default, Clone, Copy)]
struct ParaProps {
    istd: u16,
    in_table: bool,
    ttp: bool,
    /// List-format reference (`sprmPIlfo`): non-zero → the paragraph is a
    /// numbered/bulleted list item.
    ilfo: u16,
    /// List nesting level (`sprmPIlvl`), 0-based.
    ilvl: u8,
    /// Outline level (`sprmPOutLvl`, 0–8 = heading levels 1–9; 9 = body
    /// text). Read off *style* PAPX UPXes only — mirroring docling, which
    /// consults the style definition, never the paragraph's direct formatting.
    outline: Option<u8>,
}

/// Look up the PAPX for the paragraph containing byte offset `fc`:
/// PlcfBtePapx → FKP page (512 bytes in the WordDocument stream) → PapxInFkp.
fn paragraph_props(word: &[u8], bte: &[u8], fc: u64) -> ParaProps {
    let mut props = ParaProps::default();
    let Some(n) = bte.len().checked_sub(4).map(|l| l / 8) else {
        return props;
    };
    if n == 0 {
        return props;
    }
    // aFc[i] <= fc < aFc[i+1] selects PN i.
    let mut pn = None;
    for i in 0..n {
        let lo = u32_at(bte, i * 4).unwrap_or(u32::MAX) as u64;
        let hi = u32_at(bte, (i + 1) * 4).unwrap_or(0) as u64;
        if fc >= lo && fc < hi {
            pn = u32_at(bte, (n + 1) * 4 + i * 4);
            break;
        }
    }
    let Some(pn) = pn else { return props };
    let page_off = (pn & 0x003F_FFFF) as usize * 512;
    let Some(page) = word.get(page_off..page_off + 512) else {
        return props;
    };
    let crun = page[511] as usize;
    if crun == 0 || (crun + 1) * 4 + crun * 13 > 511 {
        return props;
    }
    // rgfc[j] <= fc < rgfc[j+1] selects BxPap j.
    let mut run = None;
    for j in 0..crun {
        let lo = u32_at(page, j * 4).unwrap_or(u32::MAX) as u64;
        let hi = u32_at(page, (j + 1) * 4).unwrap_or(0) as u64;
        if fc >= lo && fc < hi {
            run = Some(j);
            break;
        }
    }
    let Some(j) = run else { return props };
    let b_offset = page[(crun + 1) * 4 + j * 13] as usize;
    if b_offset == 0 {
        return props; // default PAP
    }
    // PapxInFkp at word offset b_offset: cb, or 0 + cb'.
    let mut o = b_offset * 2;
    let Some(&cb) = page.get(o) else { return props };
    let grpprl_len = if cb == 0 {
        o += 2;
        page.get(b_offset * 2 + 1).map(|&c| c as usize * 2)
    } else {
        o += 1;
        Some(cb as usize * 2 - 1)
    };
    let Some(len) = grpprl_len else { return props };
    let Some(grpprl) = page.get(o..(o + len).min(512)) else {
        return props;
    };
    if grpprl.len() < 2 {
        return props;
    }
    props.istd = u16::from_le_bytes([grpprl[0], grpprl[1]]);
    apply_pap_sprms(&grpprl[2..], &mut props);
    props
}

/// Scan a PAP grpprl for the sprms this backend cares about.
fn apply_pap_sprms(mut sprms: &[u8], props: &mut ParaProps) {
    while sprms.len() >= 2 {
        let sprm = u16::from_le_bytes([sprms[0], sprms[1]]);
        sprms = &sprms[2..];
        let spra = sprm >> 13;
        let operand_len = match spra {
            0 | 1 => 1,
            2 | 4 | 5 => 2,
            3 => 4,
            7 => 3,
            _ => {
                // Variable: first byte is the operand size (sprmTDefTable uses
                // a 16-bit size; it never appears in a PAP grpprl we scan).
                match sprms.first() {
                    Some(&cb) => 1 + cb as usize,
                    None => return,
                }
            }
        };
        if sprms.len() < operand_len {
            return;
        }
        match sprm {
            0x2416 => props.in_table = sprms[0] != 0, // sprmPFInTable
            0x2417 => props.ttp = sprms[0] != 0,      // sprmPFTtp
            0x460B => props.ilfo = u16::from_le_bytes([sprms[0], sprms[1]]), // sprmPIlfo
            0x260A => props.ilvl = sprms[0],          // sprmPIlvl
            0x2640 => props.outline = Some(sprms[0]), // sprmPOutLvl
            _ => {}
        }
        sprms = &sprms[operand_len..];
    }
}

/// One paragraph style's identity from the STSH: the built-in style id (`sti`
/// 1–9 are the Heading 1–9 styles, 62 is Title, 0x0FFE/0x0FFF user/none) and
/// the style's own outline level (`sprmPOutLvl` in its PAPX UPX, 0–8 for
/// heading levels 1–9) — OOXML/.doc's language-independent heading marker.
/// A LibreOffice-converted legacy document names its heading styles in the
/// document language with `sti` "user", so the outline level is the only
/// signal left (docling#3961 / #270).
#[derive(Clone, Copy)]
struct StyleDef {
    sti: u16,
    outline: Option<u8>,
}

/// Parse the STSH into `istd → StyleDef`.
fn parse_stsh(stsh: &[u8]) -> Vec<StyleDef> {
    let none = StyleDef {
        sti: 0x0FFF,
        outline: None,
    };
    let Some(cb_stshi) = u16_at(stsh, 0) else {
        return Vec::new();
    };
    let Some(cstd) = u16_at(stsh, 2) else {
        return Vec::new();
    };
    // STSHI: cstd, then cbSTDBaseInFile — the size of each STD's fixed part,
    // which is where the style name (and after it, the UPX array) starts.
    let cb_std_base = u16_at(stsh, 4).unwrap_or(10) as usize;
    let mut styles = Vec::with_capacity(cstd as usize);
    let mut pos = 2 + cb_stshi as usize;
    for _ in 0..cstd {
        let Some(cb_std) = u16_at(stsh, pos) else {
            break;
        };
        pos += 2;
        // Empty slot: cbStd == 0.
        let mut def = none;
        if cb_std >= 2 {
            let std = stsh.get(pos..pos + cb_std as usize).unwrap_or(&[]);
            def.sti = u16_at(std, 0).map(|w| w & 0x0FFF).unwrap_or(0x0FFF);
            let sgc = u16_at(std, 2).map(|w| w & 0x0F).unwrap_or(0);
            // Paragraph styles (sgc 1) carry a PAPX UPX first: after the
            // fixed STDF part comes the 2-byte-counted UTF-16 name (plus its
            // null), then the 2-byte-aligned UPX array — UPX[0] is `istd +
            // grpprl`, the same sprm stream the paragraph walker reads.
            if sgc == 1 {
                if let Some(cch) = u16_at(std, cb_std_base) {
                    let mut upx = cb_std_base + 2 + (cch as usize + 1) * 2;
                    upx += upx & 1;
                    if let Some(cb_upx) = u16_at(std, upx) {
                        let g = std.get(upx + 2..upx + 2 + cb_upx as usize).unwrap_or(&[]);
                        if g.len() >= 2 {
                            let mut props = ParaProps::default();
                            apply_pap_sprms(&g[2..], &mut props);
                            def.outline = props.outline;
                        }
                    }
                }
            }
        }
        styles.push(def);
        pos += cb_std as usize;
        // LPStd entries are 2-byte aligned.
        pos += pos & 1;
    }
    styles
}

/// Character formatting of one run (the subset the Markdown output shows),
/// plus the picture-data offset when the run is a picture anchor.
#[derive(Default, Clone, Copy, PartialEq, Eq)]
struct CharFmt {
    bold: bool,
    italic: bool,
    /// `sprmCPicLocation`: offset of the run's PICF in the Data stream (the
    /// run's `0x01` character is an inline-picture anchor).
    pic_fc: Option<u32>,
}

/// FC → [`CharFmt`] through the PlcfBteChpx and CHPX FKPs, memoizing the last
/// run's FC range — consecutive characters nearly always share a run, so the
/// per-character lookup is amortized to a range check.
#[derive(Default)]
struct ChpxCache {
    lo: u64,
    hi: u64,
    fmt: CharFmt,
}

impl ChpxCache {
    fn props(&mut self, word: &[u8], btec: &[u8], fc: u64) -> CharFmt {
        if fc >= self.lo && fc < self.hi {
            return self.fmt;
        }
        let (fmt, lo, hi) = char_props(word, btec, fc);
        self.lo = lo;
        self.hi = hi;
        self.fmt = fmt;
        fmt
    }
}

/// Look up the CHPX for the character at `fc`: PlcfBteChpx → CHPX FKP page →
/// grpprl scan for `sprmCFBold`/`sprmCFItalic`. Returns the format and the FC
/// range it covers (for the cache).
fn char_props(word: &[u8], btec: &[u8], fc: u64) -> (CharFmt, u64, u64) {
    let fmt = CharFmt::default();
    let Some(n) = btec.len().checked_sub(4).map(|l| l / 8) else {
        return (fmt, fc, fc + 1);
    };
    if n == 0 {
        return (fmt, fc, fc + 1);
    }
    let mut pn = None;
    for i in 0..n {
        let lo = u32_at(btec, i * 4).unwrap_or(u32::MAX) as u64;
        let hi = u32_at(btec, (i + 1) * 4).unwrap_or(0) as u64;
        if fc >= lo && fc < hi {
            pn = u32_at(btec, (n + 1) * 4 + i * 4);
            break;
        }
    }
    let Some(pn) = pn else {
        return (fmt, fc, fc + 1);
    };
    let page_off = (pn & 0x003F_FFFF) as usize * 512;
    let Some(page) = word.get(page_off..page_off + 512) else {
        return (fmt, fc, fc + 1);
    };
    let crun = page[511] as usize;
    if crun == 0 || (crun + 1) * 4 + crun > 511 {
        return (fmt, fc, fc + 1);
    }
    for j in 0..crun {
        let lo = u32_at(page, j * 4).unwrap_or(u32::MAX) as u64;
        let hi = u32_at(page, (j + 1) * 4).unwrap_or(0) as u64;
        if fc < lo || fc >= hi {
            continue;
        }
        // rgb: crun 1-byte word offsets after the FC array; 0 → no CHPX.
        let b = page[(crun + 1) * 4 + j] as usize;
        let mut out = CharFmt::default();
        if b != 0 {
            if let Some(&cb) = page.get(b * 2) {
                if let Some(grpprl) = page.get(b * 2 + 1..(b * 2 + 1 + cb as usize).min(512)) {
                    apply_chp_sprms(grpprl, &mut out);
                }
            }
        }
        return (out, lo, hi);
    }
    (fmt, fc, fc + 1)
}

/// Scan a CHP grpprl for bold/italic. Operand 1 = on, 0x81 = "opposite of the
/// style" — treated as on (the styles the Markdown output cares about are not
/// themselves bold/italic).
fn apply_chp_sprms(mut sprms: &[u8], fmt: &mut CharFmt) {
    while sprms.len() >= 2 {
        let sprm = u16::from_le_bytes([sprms[0], sprms[1]]);
        sprms = &sprms[2..];
        let operand_len = match sprm >> 13 {
            0 | 1 => 1,
            2 | 4 | 5 => 2,
            3 => 4,
            7 => 3,
            _ => match sprms.first() {
                Some(&cb) => 1 + cb as usize,
                None => return,
            },
        };
        if sprms.len() < operand_len {
            return;
        }
        match sprm {
            0x0835 => fmt.bold = sprms[0] == 1 || sprms[0] == 0x81, // sprmCFBold
            0x0836 => fmt.italic = sprms[0] == 1 || sprms[0] == 0x81, // sprmCFItalic
            // sprmCPicLocation: PICF offset in the Data stream.
            0x6A03 => {
                fmt.pic_fc = Some(u32::from_le_bytes([sprms[0], sprms[1], sprms[2], sprms[3]]))
            }
            _ => {}
        }
        sprms = &sprms[operand_len..];
    }
}

/// Decode an inline picture: PICF at `pic_fc` in the Data stream — a header
/// of `cbHeader` bytes (with the total size in `lcb`), then the OfficeArt
/// record tree holding the BLIP. `MM_SHAPEFILE` (0x66) interposes a
/// length-prefixed picture name.
fn inline_picture(data: &[u8], pic_fc: u32) -> Option<PictureImage> {
    let base = pic_fc as usize;
    let lcb = u32::from_le_bytes(data.get(base..base + 4)?.try_into().ok()?) as usize;
    let cb_header = u16::from_le_bytes(data.get(base + 4..base + 6)?.try_into().ok()?) as usize;
    let mm = u16::from_le_bytes(data.get(base + 6..base + 8)?.try_into().ok()?);
    let mut start = base + cb_header;
    if mm == 0x0066 {
        // MM_SHAPEFILE: cchPicName + name precede the OfficeArt data.
        let cch = *data.get(start)? as usize;
        start += 1 + cch;
    }
    let body = data.get(start..base + lcb.max(cb_header))?;
    officeart::first_blip(body, 0)
}

/// Parse the PlcfSpa: floating-shape anchors as `(anchor CP, spid)`.
fn parse_plcf_spa(plc: &[u8]) -> Vec<(u64, u32)> {
    // PLC with 26-byte SPA data: n = (lcb - 4) / 30.
    let Some(n) = plc.len().checked_sub(4).map(|l| l / 30) else {
        return Vec::new();
    };
    (0..n)
        .filter_map(|i| {
            let cp = u32_at(plc, i * 4)? as u64;
            let spid = u32_at(plc, (n + 1) * 4 + i * 26)?;
            Some((cp, spid))
        })
        .collect()
}

/// The spid anchored exactly at `cp`, if any.
fn spa_shape_at(spa: &[(u64, u32)], cp: u64) -> Option<u32> {
    spa.iter()
        .find(|(acp, _)| *acp == cp)
        .map(|(_, spid)| *spid)
}

/// The document's OfficeArt drawing tables: shape id → BLIP index (`pib`),
/// and the BLIP store — each entry either embeds its BLIP record or points
/// at one in the WordDocument (delay) stream via `foDelay`.
struct Drawings {
    /// spid → 1-based pib.
    shape_pib: std::collections::HashMap<u32, u32>,
    /// Group-frame spid → member spids (an anchored group shows every
    /// member's picture).
    groups: std::collections::HashMap<u32, Vec<u32>>,
    /// BStore order: decoded pictures (delay-stream ones resolved eagerly).
    blips: Vec<Option<PictureImage>>,
}

impl Drawings {
    fn parse(dgg: &[u8], delay_stream: &[u8]) -> Self {
        let mut out = Self {
            shape_pib: std::collections::HashMap::new(),
            groups: std::collections::HashMap::new(),
            blips: Vec::new(),
        };
        // The OfficeArtContent in a Word file is NOT a plain record stream:
        // each per-drawing DgContainer is preceded by a raw byte
        // (OfficeArtWordDrawing.dgglbl), which would desynchronize a straight
        // record walk. Parse top-level records with a resync: a position that
        // doesn't hold a well-formed OfficeArt header (0xF0xx type, in-bounds
        // length) skips one byte.
        let mut pos = 0usize;
        while pos + 8 <= dgg.len() {
            let rec_type = u16::from_le_bytes([dgg[pos + 2], dgg[pos + 3]]);
            let len = u32::from_le_bytes([dgg[pos + 4], dgg[pos + 5], dgg[pos + 6], dgg[pos + 7]])
                as usize;
            if (rec_type & 0xFF00) == 0xF000 && pos + 8 + len <= dgg.len() {
                out.walk(&dgg[pos..pos + 8 + len], delay_stream, 0);
                pos += 8 + len;
            } else {
                pos += 1;
            }
        }
        out
    }

    /// spid of an SpContainer body (its FSP record).
    fn sp_spid(sp_body: &[u8]) -> Option<u32> {
        officeart::Records::new(sp_body)
            .find(|(h, _)| h.rec_type == 0xF00A)
            .and_then(|(_, b)| {
                b.get(..4)
                    .map(|x| u32::from_le_bytes([x[0], x[1], x[2], x[3]]))
            })
    }

    fn walk(&mut self, body: &[u8], delay: &[u8], depth: usize) {
        if depth > 16 {
            return;
        }
        for (h, b) in officeart::Records::new(body) {
            match h.rec_type {
                // OfficeArtFBSE: BLIP store entry — embedded record or foDelay.
                0xF007 => {
                    let embedded = b.get(36..).and_then(|tail| officeart::first_blip(tail, 0));
                    let img = embedded.or_else(|| {
                        let fo = u32::from_le_bytes(b.get(28..32)?.try_into().ok()?) as usize;
                        let rec = delay.get(fo..)?;
                        officeart::Records::new(rec)
                            .next()
                            .filter(|(rh, _)| officeart::is_blip(rh.rec_type))
                            .and_then(|(rh, rb)| officeart::decode_blip(&rh, rb))
                    });
                    self.blips.push(img);
                }
                // A group: the frame shape's spid maps to the member spids.
                0xF003 => {
                    let mut frame = None;
                    let mut members = Vec::new();
                    for (h2, b2) in officeart::Records::new(b) {
                        match h2.rec_type {
                            0xF004 => {
                                let spid = Self::sp_spid(b2);
                                let is_frame = officeart::Records::new(b2)
                                    .any(|(h3, _)| h3.rec_type == 0xF009);
                                match (is_frame, frame) {
                                    (true, None) => frame = spid,
                                    _ => members.extend(spid),
                                }
                            }
                            0xF003 => {
                                // Nested group: its frame spid joins as a member.
                                let nested_frame = officeart::Records::new(b2)
                                    .find(|(h3, _)| h3.rec_type == 0xF004)
                                    .and_then(|(_, b3)| Self::sp_spid(b3));
                                members.extend(nested_frame);
                            }
                            _ => {}
                        }
                    }
                    if let Some(frame) = frame {
                        self.groups.insert(frame, members);
                    }
                    // Fall through to the generic recursion below for pib/blip
                    // collection inside the group.
                    self.walk(b, delay, depth + 1);
                }
                // OfficeArtSpContainer: read the FSP spid + FOPT pib property.
                0xF004 => {
                    let mut spid = None;
                    let mut pib = None;
                    for (h2, b2) in officeart::Records::new(b) {
                        match h2.rec_type {
                            0xF00A => {
                                spid = b2
                                    .get(..4)
                                    .map(|x| u32::from_le_bytes([x[0], x[1], x[2], x[3]]));
                            }
                            0xF00B => {
                                // Fixed 6-byte property entries; id bits 0–13.
                                for e in 0..h2.instance as usize {
                                    let o = e * 6;
                                    let Some(entry) = b2.get(o..o + 6) else { break };
                                    let id = u16::from_le_bytes([entry[0], entry[1]]) & 0x3FFF;
                                    if id == 260 {
                                        pib = Some(u32::from_le_bytes([
                                            entry[2], entry[3], entry[4], entry[5],
                                        ]));
                                    }
                                }
                            }
                            _ => {}
                        }
                    }
                    if let (Some(spid), Some(pib)) = (spid, pib) {
                        self.shape_pib.insert(spid, pib);
                    }
                }
                _ if h.version == 0xF => self.walk(b, delay, depth + 1),
                _ => {}
            }
        }
    }

    /// The pictures behind a shape id: a picture shape yields one; a group
    /// yields each member's, in order. `None` entries are undecodable images
    /// (still emitted as placeholders).
    fn shape_pictures(&self, spid: u32, depth: usize) -> Vec<Option<PictureImage>> {
        if depth > 8 {
            return Vec::new();
        }
        if let Some(pib) = self.shape_pib.get(&spid) {
            let img = pib
                .checked_sub(1)
                .and_then(|ix| self.blips.get(ix as usize))
                .cloned()
                .flatten();
            return vec![img];
        }
        match self.groups.get(&spid) {
            Some(members) => members
                .iter()
                .flat_map(|&m| self.shape_pictures(m, depth + 1))
                .collect(),
            None => Vec::new(),
        }
    }
}

/// One piece of a level's number template (`xst`): a literal, or a
/// placeholder for another level's counter (placeholder chars are the level
/// index 0–8 in the raw text).
#[derive(Clone)]
enum LvlPart {
    Level(u8),
    Text(String),
}

/// One list level's numbering: kind, start value, and number template.
#[derive(Clone, Default)]
struct LvlInfo {
    /// Number format code (`nfc`): 0x17 = bullet, 0xFF = none, else numbered.
    nfc: u8,
    start: u32,
    /// The `xst` template (e.g. `1.1.` as [Level(0), ".", Level(1), "."]).
    template: Vec<LvlPart>,
}

/// The document's list tables: `ilfo` (1-based, from `sprmPIlfo`) resolves
/// through the LFO array to a list (`lsid`) and its per-level numbering.
#[derive(Default, Clone)]
struct ListTables {
    /// LFO index (0-based) → lsid.
    lfo_lsids: Vec<u32>,
    /// lsid → per-level info (1 entry for simple lists, 9 otherwise).
    lists: std::collections::HashMap<u32, Vec<LvlInfo>>,
}

impl ListTables {
    /// Parse the PlfLst (`lst_tail` starts at `fcPlfLst`; `lcb_lst` covers the
    /// LSTF array, and the per-list LVLs follow it in the stream) and the
    /// PlfLfo (LFO array). Any malformed structure yields what was parsed so
    /// far — unresolvable items degrade to bullets, never to an error.
    fn parse(lst_tail: &[u8], lcb_lst: usize, plflfo: &[u8]) -> Self {
        let plflst = lst_tail;
        let mut out = Self::default();
        // PlfLst: cLst u16, then cLst LSTFs of 28 bytes, then each list's LVLs.
        let c_lst = u16_at(plflst, 0).unwrap_or(0) as usize;
        let mut lstfs = Vec::with_capacity(c_lst);
        for i in 0..c_lst {
            let base = 2 + i * 28;
            let Some(lsid) = u32_at(plflst, base) else {
                break;
            };
            let simple = plflst.get(base + 26).is_some_and(|&f| f & 0x01 != 0);
            lstfs.push((lsid, if simple { 1usize } else { 9usize }));
        }
        let mut pos = (2 + c_lst * 28).max(lcb_lst);
        'lists: for (lsid, nlvl) in lstfs {
            let mut lvls = Vec::with_capacity(nlvl);
            for _ in 0..nlvl {
                // LVL = LVLF (28 bytes) + grpprlPapx + grpprlChpx + xst.
                let Some(start) = u32_at(plflst, pos) else {
                    break 'lists;
                };
                let Some(&nfc) = plflst.get(pos + 4) else {
                    break 'lists;
                };
                let cb_chpx = plflst.get(pos + 24).copied().unwrap_or(0) as usize;
                let cb_papx = plflst.get(pos + 25).copied().unwrap_or(0) as usize;
                pos += 28 + cb_papx + cb_chpx;
                let cch = u16_at(plflst, pos).unwrap_or(0) as usize;
                pos += 2;
                // xst: UTF-16 template where a code ≤ 8 is a placeholder for
                // that level's counter (`1.1.` = [0, '.', 1, '.']).
                let mut template: Vec<LvlPart> = Vec::new();
                for i in 0..cch {
                    let Some(u) = u16_at(plflst, pos + i * 2) else {
                        break;
                    };
                    if u <= 8 {
                        template.push(LvlPart::Level(u as u8));
                    } else if let Some(c) = char::from_u32(u as u32) {
                        match template.last_mut() {
                            Some(LvlPart::Text(t)) => t.push(c),
                            _ => template.push(LvlPart::Text(c.to_string())),
                        }
                    }
                }
                pos += cch * 2;
                lvls.push(LvlInfo {
                    nfc,
                    start,
                    template,
                });
            }
            out.lists.insert(lsid, lvls);
        }
        // PlfLfo: lfoMac u32, then lfoMac LFOs of 16 bytes (lsid first).
        let lfo_mac = u32_at(plflfo, 0).unwrap_or(0) as usize;
        for i in 0..lfo_mac {
            match u32_at(plflfo, 4 + i * 16) {
                Some(lsid) => out.lfo_lsids.push(lsid),
                None => break,
            }
        }
        out
    }

    /// Numbering info for `(ilfo, ilvl)`, when the tables resolve it.
    fn level(&self, ilfo: u16, ilvl: u8) -> Option<LvlInfo> {
        let lsid = *self.lfo_lsids.get(ilfo.checked_sub(1)? as usize)?;
        let lvls = self.lists.get(&lsid)?;
        lvls.get(ilvl as usize).or_else(|| lvls.first()).cloned()
    }

    /// A level's start value, for counters not yet touched in a run.
    fn level_start(&self, ilfo: u16, ilvl: u8) -> u64 {
        self.level(ilfo, ilvl).map(|l| l.start as u64).unwrap_or(1)
    }
}

/// Accumulates one paragraph's characters as `(text, format)` segments, then
/// classifies the paragraph on its mark.
#[derive(Default)]
struct ParaAccum {
    /// Consecutive same-format runs of the paragraph.
    segments: Vec<(String, CharFmt)>,
    /// Pictures anchored in this paragraph: `(before any text, image)`.
    pictures: Vec<(bool, Option<PictureImage>)>,
    /// Result-text state of any field (`0x13 code 0x14 result 0x15`) stack:
    /// characters inside the *code* part are dropped.
    field_stack: Vec<bool>, // true = in result part
    /// Text boxes anchored in this paragraph, each its story's nodes (#535).
    textboxes: Vec<Vec<Node>>,
}

impl ParaAccum {
    /// Queue a picture anchored at the current position (`None` = a picture
    /// whose bytes couldn't be decoded — still a placeholder node).
    fn add_picture(&mut self, image: Option<PictureImage>) {
        let before_text = self.segments.iter().all(|(t, _)| t.trim().is_empty());
        self.pictures.push((before_text, image));
    }

    fn push(&mut self, ch: char, fmt: CharFmt) {
        match ch {
            '\u{0013}' => self.field_stack.push(false),
            '\u{0014}' => {
                if let Some(top) = self.field_stack.last_mut() {
                    *top = true;
                }
            }
            '\u{0015}' => {
                self.field_stack.pop();
            }
            // Object/drawing/note anchors and other control marks: dropped.
            '\u{0001}' | '\u{0002}' | '\u{0005}' | '\u{0008}' => {}
            '\u{000B}' => self.keep('\n', fmt), // hard line break
            '\u{001E}' => self.keep('-', fmt),  // non-breaking hyphen
            '\u{001F}' => {}                    // soft hyphen
            _ => self.keep(ch, fmt),
        }
    }

    fn keep(&mut self, ch: char, fmt: CharFmt) {
        if !self.field_stack.iter().all(|&r| r) {
            return;
        }
        match self.segments.last_mut() {
            Some((text, last)) if *last == fmt => text.push(ch),
            _ => self.segments.push((ch.to_string(), fmt)),
        }
    }

    /// Flat text, formatting ignored (headings, table-structure decisions).
    fn plain(&self) -> String {
        self.segments.iter().map(|(t, _)| t.as_str()).collect()
    }

    /// Markdown text with `**bold**` / `*italic*` markers per run, whitespace
    /// kept outside the markers (matching the DOCX backend's rendering).
    fn markdown(&self) -> String {
        let mut out = String::new();
        for (text, fmt) in &self.segments {
            if !fmt.bold && !fmt.italic {
                out.push_str(text);
                continue;
            }
            let core = text.trim();
            if core.is_empty() {
                out.push_str(text);
                continue;
            }
            let lead = &text[..text.len() - text.trim_start().len()];
            let trail = &text[text.trim_end().len()..];
            let marker = match (fmt.bold, fmt.italic) {
                (true, true) => "***",
                (true, false) => "**",
                (false, true) => "*",
                _ => unreachable!(),
            };
            out.push_str(lead);
            out.push_str(marker);
            out.push_str(core);
            out.push_str(marker);
            out.push_str(trail);
        }
        out
    }

    fn finish(
        &mut self,
        mark: char,
        props: ParaProps,
        stis: &[StyleDef],
        builder: &mut NodeBuilder,
        doc: &mut DoclingDocument,
    ) {
        let plain = self.plain();
        let markdown = self.markdown();
        let pictures = std::mem::take(&mut self.pictures);
        let textboxes = std::mem::take(&mut self.textboxes);
        self.segments.clear();
        self.field_stack.clear();
        builder.paragraph(plain, markdown, pictures, textboxes, mark, props, stis, doc);
    }
}

/// Turns the classified paragraph stream into nodes, assembling table runs.
#[derive(Default)]
struct NodeBuilder {
    /// In-progress table rows, current row's cells, and the current cell's
    /// accumulated paragraphs (a cell may span several).
    rows: Vec<Vec<String>>,
    cells: Vec<String>,
    cell_text: String,
    /// The `ilfo` of the most recent list item — a new item starts a new list
    /// (`first_in_list`) when its `ilfo` differs. Empty paragraphs between
    /// items do NOT break a list (docling's DOCX behavior: numbering and
    /// grouping continue across gaps); any other node kind does.
    last_ilfo: Option<u16>,
    /// Base `ilvl` of the current contiguous list run (its first item's),
    /// mirroring the DOCX backend's `list_run_base`.
    run_base: Option<u8>,
    lists: ListTables,
    /// Running list counters, keyed by `(ilfo, ilvl)` — docling semantics:
    /// the value is the *current* number (post-increment), deeper levels
    /// zero on a shallower item.
    counters: std::collections::HashMap<(u16, u8), u64>,
}

impl NodeBuilder {
    fn new(lists: ListTables) -> Self {
        Self {
            lists,
            ..Self::default()
        }
    }
    #[allow(clippy::too_many_arguments)]
    fn paragraph(
        &mut self,
        plain: String,
        markdown: String,
        pictures: Vec<(bool, Option<PictureImage>)>,
        textboxes: Vec<Vec<Node>>,
        mark: char,
        props: ParaProps,
        stis: &[StyleDef],
        doc: &mut DoclingDocument,
    ) {
        if props.ttp {
            // Row terminator: close the row.
            if !self.cell_text.is_empty() {
                self.cells.push(std::mem::take(&mut self.cell_text));
            }
            if !self.cells.is_empty() {
                self.rows.push(std::mem::take(&mut self.cells));
            }
            return;
        }
        if props.in_table {
            if !self.cell_text.is_empty() {
                // Multi-paragraph cells join with a blank line, matching the
                // DOCX backend's rich cells (the Markdown table serializer
                // then folds each newline into a space).
                self.cell_text.push_str("\n\n");
            }
            self.cell_text
                .push_str(markdown.trim_end_matches('\u{0007}'));
            // A text box anchored in the cell: its paragraphs are more of the
            // cell's (#535), as the DOCX backend reads the same document.
            for text in textboxes.iter().flatten().filter_map(node_text) {
                if !self.cell_text.is_empty() {
                    self.cell_text.push_str("\n\n");
                }
                self.cell_text.push_str(&text);
            }
            if mark == '\u{0007}' {
                self.cells.push(std::mem::take(&mut self.cell_text));
            }
            return;
        }
        self.flush(doc);
        // Text boxes anchored here (#535): a `textbox` section group each, in
        // front of the anchoring paragraph — the DOCX backend's shape.
        for children in textboxes {
            doc.push(Node::Group {
                label: "section".into(),
                name: Some("textbox".into()),
                layer: None,
                children,
            });
            self.last_ilfo = None;
            self.run_base = None;
        }

        let picture_node = |image: Option<PictureImage>| Node::Picture {
            caption: None,
            caption_href: None,
            image,
            classification: None,
            caption_parent: Default::default(),
        };
        let plain = plain.trim().to_string();
        let text = markdown.trim().to_string();
        if plain.is_empty() {
            // Pictures anchored in an otherwise-empty paragraph are blocks of
            // their own. A blank paragraph does not break a list run
            // (docling's DOCX behavior: items continue across gaps).
            for (_, image) in pictures {
                doc.push(picture_node(image));
            }
            return;
        }
        // Anchored pictures surround the paragraph text by anchor position.
        for (_, image) in pictures.iter().filter(|(before, _)| *before) {
            doc.push(picture_node(image.clone()));
        }
        let after: Vec<_> = pictures
            .into_iter()
            .filter(|(before, _)| !before)
            .map(|(_, image)| image)
            .collect();
        let style = stis.get(props.istd as usize).copied().unwrap_or(StyleDef {
            sti: 0x0FFF,
            outline: None,
        });
        let sti = style.sti;
        // A style that is not one of the built-in Heading/Title styles can
        // still be a heading through its outline level (docling#3961 / #270):
        // LibreOffice-converted legacy documents carry localized user styles
        // ("Επικεφαλίδα 2") whose only heading marker is `sprmPOutLvl`. 0-8
        // are heading levels 1-9; 9 is the "body text" sentinel.
        let outline_heading = (!(1..=9).contains(&sti) && sti != 62)
            .then_some(style.outline)
            .flatten()
            .filter(|l| *l <= 8);
        if (1..=9).contains(&sti) || sti == 62 || outline_heading.is_some() {
            // Mirrors the DOCX backend: docling renders "heading N" at
            // Markdown level N+1 and Title (sti 62) at level 1.
            let level = if sti == 62 {
                1
            } else if let Some(l) = outline_heading {
                l + 2
            } else {
                sti as u8 + 1
            };
            // Headings render without run markers (the style carries the look).
            doc.push(Node::Heading { level, text: plain });
            self.last_ilfo = None;
            self.run_base = None;
        } else if props.ilfo != 0 {
            let lvl = self.lists.level(props.ilfo, props.ilvl);
            // Bullet (0x17) / no-number (0xFF) levels — and unresolvable
            // references — are unordered; everything else numbers.
            let numbered = lvl.as_ref().is_some_and(|l| l.nfc != 0x17 && l.nfc != 0xFF);
            let first_in_list = self.last_ilfo != Some(props.ilfo);
            // The run's base indent (its first item's ilvl) — nested levels
            // indent relative to it, matching the DOCX backend's
            // `list_run_base` (the same list restarted after body text can
            // legitimately sit at a different Markdown depth).
            let base = *self.run_base.get_or_insert(props.ilvl);
            let level = props.ilvl.saturating_sub(base);
            if numbered {
                // docling's counter semantics: bump this level (from the
                // level's own start), zero deeper levels of the same list.
                let start = self.lists.level_start(props.ilfo, props.ilvl);
                let c = self
                    .counters
                    .entry((props.ilfo, props.ilvl))
                    .or_insert(start.saturating_sub(1));
                *c += 1;
                for ((f, l), v) in self.counters.iter_mut() {
                    if *f == props.ilfo && *l > props.ilvl {
                        *v = 0;
                    }
                }
                let marker = self.build_marker(props.ilfo, props.ilvl, lvl.as_ref());
                let number = marker
                    .trim_end_matches(['.', ')'])
                    .rsplit(['.', ')'])
                    .next()
                    .and_then(|s| s.trim().parse::<u64>().ok())
                    .unwrap_or(1);
                if cached_regex!(r"^\d+[.)]$").is_match(&marker) {
                    // A plain `N.` marker: ordered in Markdown and DocLang.
                    doc.push(Node::ListItem {
                        ordered: true,
                        number,
                        first_in_list,
                        text,
                        level,
                        marker: Some(marker),
                        location: None,
                        dclx: None,
                        href: None,
                        layer: None,
                    });
                } else {
                    // A multilevel marker (`1.1.`): Markdown bullet with the
                    // marker as a text prefix, ordered DocLang item with a
                    // clean-text `<marker>` — same as the DOCX backend.
                    let dclx = Some(docling_core::ListItemDclx {
                        ordered: true,
                        marker: Some(marker.clone()),
                        text: text.clone(),
                        runs: Vec::new(),
                    });
                    doc.push(Node::ListItem {
                        ordered: false,
                        number,
                        first_in_list,
                        text: format!("{marker} {text}"),
                        level,
                        marker: None,
                        location: None,
                        dclx,
                        href: None,
                        layer: None,
                    });
                }
            } else {
                doc.push(Node::ListItem {
                    ordered: false,
                    number: 0,
                    first_in_list,
                    text,
                    level,
                    marker: None,
                    location: None,
                    dclx: None,
                    href: None,
                    layer: None,
                });
            }
            self.last_ilfo = Some(props.ilfo);
        } else {
            doc.push(Node::Paragraph { text });
            self.last_ilfo = None;
            self.run_base = None;
        }
        for image in after {
            doc.push(picture_node(image));
        }
    }

    /// Emit any table under construction.
    fn flush(&mut self, doc: &mut DoclingDocument) {
        if !self.cell_text.is_empty() {
            self.cells.push(std::mem::take(&mut self.cell_text));
        }
        if !self.cells.is_empty() {
            self.rows.push(std::mem::take(&mut self.cells));
        }
        if self.rows.is_empty() {
            return;
        }
        let rows = std::mem::take(&mut self.rows);
        // Rectangularize (rows may have ragged cell counts).
        let width = rows.iter().map(|r| r.len()).max().unwrap_or(0);
        let rows: Vec<Vec<String>> = rows
            .into_iter()
            .map(|mut r| {
                r.resize(width, String::new());
                r
            })
            .collect();
        doc.push(Node::Table(Table {
            rows,
            location: None,
            structure: None,
            cell_blocks: None,
            cells: None,
            caption: None,
            caption_parent: Default::default(),
        }));
        self.last_ilfo = None;
        self.run_base = None;
    }

    /// Build the item's enumeration marker from the level's `xst` template —
    /// the DOC twin of the DOCX backend's `build_enum_marker`: a template
    /// with literal text beyond separators substitutes its placeholders;
    /// a bare numeric template falls back to the hierarchical `1.2.` form
    /// joining the counters of levels `0..=ilvl`.
    fn build_marker(&self, ilfo: u16, ilvl: u8, lvl: Option<&LvlInfo>) -> String {
        let counter_at = |l: u8| -> u64 {
            self.counters
                .get(&(ilfo, l))
                .copied()
                .unwrap_or_else(|| self.lists.level_start(ilfo, l))
        };
        if let Some(lvl) = lvl {
            let literal: String = lvl
                .template
                .iter()
                .filter_map(|p| match p {
                    LvlPart::Text(t) => Some(t.as_str()),
                    LvlPart::Level(_) => None,
                })
                .collect();
            let has_levels = lvl.template.iter().any(|p| matches!(p, LvlPart::Level(_)));
            if has_levels
                && !literal
                    .trim_matches(|c: char| " .)(:[]".contains(c))
                    .is_empty()
            {
                return lvl
                    .template
                    .iter()
                    .map(|p| match p {
                        LvlPart::Level(l) => counter_at(*l).to_string(),
                        LvlPart::Text(t) => t.clone(),
                    })
                    .collect();
            }
        }
        let parts: Vec<String> = (0..=ilvl).map(|l| counter_at(l).to_string()).collect();
        parts.join(".") + "."
    }
}

/// A text box node's text, for placing it in a table cell: a paragraph,
/// heading or list item's text, a table's cells.
fn node_text(node: &Node) -> Option<String> {
    let text = match node {
        Node::Paragraph { text } | Node::Heading { text, .. } | Node::ListItem { text, .. } => {
            text.clone()
        }
        Node::Table(t) => t
            .rows
            .iter()
            .flatten()
            .filter(|c| !c.trim().is_empty())
            .cloned()
            .collect::<Vec<_>>()
            .join(" "),
        Node::Group { children, .. } => children
            .iter()
            .filter_map(node_text)
            .collect::<Vec<_>>()
            .join(" "),
        _ => return None,
    };
    (!text.trim().is_empty()).then_some(text)
}

fn u16_at(d: &[u8], o: usize) -> Option<u16> {
    Some(u16::from_le_bytes(d.get(o..o + 2)?.try_into().ok()?))
}

fn u32_at(d: &[u8], o: usize) -> Option<u32> {
    Some(u32::from_le_bytes(d.get(o..o + 4)?.try_into().ok()?))
}

/// Windows-1252 to Unicode (the 0x80–0x9F block differs from Latin-1).
pub(crate) fn cp1252(b: u8) -> char {
    match b {
        0x80 => '€',
        0x82 => '‚',
        0x83 => 'ƒ',
        0x84 => '„',
        0x85 => '…',
        0x86 => '†',
        0x87 => '‡',
        0x88 => 'ˆ',
        0x89 => '‰',
        0x8A => 'Š',
        0x8B => '‹',
        0x8C => 'Œ',
        0x8E => 'Ž',
        0x91 => '\u{2018}',
        0x92 => '\u{2019}',
        0x93 => '\u{201C}',
        0x94 => '\u{201D}',
        0x95 => '•',
        0x96 => '–',
        0x97 => '—',
        0x98 => '˜',
        0x99 => '™',
        0x9A => 'š',
        0x9B => '›',
        0x9C => 'œ',
        0x9E => 'ž',
        0x9F => 'Ÿ',
        other => other as char,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A Word 97 FIB of the usual shape (`csw` 14, `cslw` 22) with
    /// `cbRgFcLcb` pairs, `ccpText` = 1234 and pair 33 (the CLX) = (7, 9).
    fn fib_bytes(cb: u16) -> Vec<u8> {
        let mut w = vec![0u8; 32];
        w[0..2].copy_from_slice(&0xA5ECu16.to_le_bytes());
        w.extend_from_slice(&14u16.to_le_bytes());
        w.extend(std::iter::repeat_n(0, 28));
        w.extend_from_slice(&22u16.to_le_bytes());
        let mut lw = vec![0u8; 88];
        lw[12..16].copy_from_slice(&1234u32.to_le_bytes());
        w.extend(lw);
        w.extend_from_slice(&cb.to_le_bytes());
        let mut blob = vec![0u8; cb as usize * 8];
        if cb > 33 {
            blob[264..268].copy_from_slice(&7u32.to_le_bytes());
            blob[268..272].copy_from_slice(&9u32.to_le_bytes());
        }
        w.extend(blob);
        w
    }

    #[test]
    fn fib_reads_through_the_declared_counts() {
        let w = fib_bytes(0x5D);
        let fib = Fib::parse(&w).expect("well-formed FIB");
        assert_eq!(fib.ccp_text, 1234);
        assert_eq!(fib.fc_lcb(Fib::CLX), (7, 9));
        // The CLX pair sits where the old fixed offsets (418/422) put it.
        assert_eq!(u32_at(&w, 418), Some(7));
        assert_eq!(u32_at(&w, 422), Some(9));
        // A pair past the writer's cbRgFcLcb reads as absent.
        let short = fib_bytes(20);
        let fib = Fib::parse(&short).unwrap();
        assert_eq!(fib.fc_lcb(Fib::CLX), (0, 0));
        assert!(fib.part(&[1, 2, 3], Fib::CLX).is_empty());
    }

    #[test]
    fn truncated_fib_is_an_error_naming_the_field() {
        let w = fib_bytes(0x5D);
        for (cut, field) in [
            (20, "csw"),
            (40, "cslw"),
            (70, "ccpText"),
            (153, "cbRgFcLcb"),
            (300, "fibRgFcLcbBlob"),
        ] {
            let err = Fib::parse(&w[..cut])
                .err()
                .expect("truncated FIB must fail");
            assert!(err.to_string().contains(field), "cut {cut}: {err}");
        }
    }

    #[test]
    fn part_survives_an_overflowing_range() {
        let mut w = fib_bytes(0x5D);
        // fcClx = u32::MAX, lcbClx = u32::MAX: no panic, just absent.
        w[154 + 264..154 + 272].copy_from_slice(&[0xFF; 8]);
        let fib = Fib::parse(&w).unwrap();
        assert!(fib.part(&[0u8; 16], Fib::CLX).is_empty());
    }

    #[test]
    fn unsupported_word_version_is_named() {
        let mut data = std::fs::read(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../tests/data/doc/sources/docx_lists.doc"
        ))
        .unwrap();
        // The WordDocument stream starts with the FIB magic at a sector
        // boundary; turn it into an unknown version.
        let at = (512..data.len())
            .step_by(512)
            .find(|&o| data[o..o + 2] == [0xEC, 0xA5])
            .expect("FIB sector");
        data[at..at + 4].copy_from_slice(&[0x34, 0x12, 0x40, 0x00]);
        let src = SourceDocument::from_bytes("x.doc", InputFormat::Doc, data);
        let Err(err) = DocBackend.convert(&src) else {
            panic!("an unknown Word version must be rejected");
        };
        let err = err.to_string();
        assert!(
            err.contains("wIdent 0x1234") && err.contains("nFib 64"),
            "{err}"
        );
    }
    use crate::InputFormat;

    fn fixture(name: &str) -> SourceDocument {
        let path = format!(
            "{}/../../tests/data/doc/sources/{name}",
            env!("CARGO_MANIFEST_DIR")
        );
        let bytes = std::fs::read(&path).expect("fixture exists");
        SourceDocument::from_bytes(name, InputFormat::Doc, bytes)
    }

    /// #535: the stories after the main text — a text box anchored in a
    /// paragraph and one in a table cell, a page header, a footnote — all
    /// reach the document (Word's own `.doc` of the reporter's repro:
    /// `debut` + footnote MARKFN + text box MARKTB1, a 2×2 table with text
    /// box MARKTB2 in cell (2,1), header MARKHDR, `fin`).
    #[test]
    fn text_boxes_headers_and_footnotes_are_read() {
        let path = format!(
            "{}/tests/data/doc/sources/doc_textbox_header_footnote.doc",
            env!("CARGO_MANIFEST_DIR")
        );
        let bytes = std::fs::read(&path).expect("fixture exists");
        let doc = DocBackend
            .convert(&SourceDocument::from_bytes(
                "doc_textbox_header_footnote.doc",
                InputFormat::Doc,
                bytes,
            ))
            .expect("converts");
        let md = doc.export_to_markdown();
        assert!(md.contains("MARKTB1"), "{md}");
        // In its cell, not after the table.
        assert!(md.contains("| MARKTB2 | b2"), "{md}");
        // Furniture: in the JSON, not the Markdown.
        assert!(!md.contains("MARKHDR") && !md.contains("MARKFN"), "{md}");
        let json: serde_json::Value = serde_json::from_str(&doc.export_to_json()).unwrap();
        let furniture: Vec<(String, String)> = json["texts"]
            .as_array()
            .unwrap()
            .iter()
            .filter(|t| t["content_layer"] == "furniture")
            .map(|t| {
                (
                    t["label"].as_str().unwrap().to_string(),
                    t["text"].as_str().unwrap().to_string(),
                )
            })
            .collect();
        assert_eq!(
            furniture,
            vec![
                ("page_header".to_string(), "MARKHDR".to_string()),
                ("footnote".to_string(), "MARKFN".to_string()),
            ]
        );
        // The text box sits where it is anchored: right after `debut`.
        let groups = json["groups"].as_array().unwrap();
        assert_eq!(groups[0]["name"], "textbox");
        assert_eq!(json["body"]["children"][1]["$ref"], "#/groups/0");
    }

    #[test]
    fn extracts_headings_lists_and_paragraphs() {
        let doc = DocBackend
            .convert(&fixture("docx_lists.doc"))
            .expect("converts");
        let headings = doc
            .nodes
            .iter()
            .filter(|n| matches!(n, Node::Heading { .. }))
            .count();
        let lists = doc
            .nodes
            .iter()
            .filter(|n| matches!(n, Node::ListItem { .. }))
            .count();
        assert!(headings > 0, "expected headings: {:?}", doc.nodes);
        assert!(lists > 0, "expected list items: {:?}", doc.nodes);
    }

    #[test]
    fn extracts_tables_with_cells() {
        let doc = DocBackend
            .convert(&fixture("docx_rich_tables_01.doc"))
            .expect("converts");
        let tables: Vec<&Table> = doc
            .nodes
            .iter()
            .filter_map(|n| match n {
                Node::Table(t) => Some(t),
                _ => None,
            })
            .collect();
        assert!(!tables.is_empty(), "expected tables: {:?}", doc.nodes);
        assert!(tables[0].rows.len() > 1 && tables[0].rows[0].len() > 1);
    }

    #[test]
    fn garbage_is_an_error_not_a_panic() {
        let src = SourceDocument::from_bytes("x.doc", InputFormat::Doc, vec![0u8; 128]);
        assert!(DocBackend.convert(&src).is_err());
    }

    #[test]
    fn extracts_inline_and_floating_images_with_bytes() {
        let doc = DocBackend
            .convert(&fixture("docx_grouped_images.doc"))
            .expect("converts");
        let images: Vec<_> = doc
            .nodes
            .iter()
            .filter_map(|n| match n {
                Node::Picture { image, .. } => Some(image),
                _ => None,
            })
            .collect();
        // 2 grouped + 2 wrapped (floating, via PlcfSpa → Escher pib → delay
        // stream) + 2 inline (Data-stream PICF) — and every one decodable.
        assert_eq!(images.len(), 6, "expected 6 pictures: {:?}", doc.nodes);
        assert!(
            images.iter().all(|i| i.is_some()),
            "every picture should carry decoded bytes"
        );
        let img = images[0].as_ref().unwrap();
        assert!(img.width > 0 && img.height > 0 && !img.data.is_empty());
    }
}