word_ooxml/

reader.rs

//! Reading a `.docx` package into our minimal [`Document`] model.

use std::collections::HashMap;
use std::io::{Read, Seek};

use drawing::{Geometry, PresetShape, ShapeProperties};
use opc::{Package, Relationships, TargetMode};
use xml_core::{BytesStart, Event, Reader};

use crate::error::{Error, Result};
use crate::model::{
    Alignment, Block, Bookmark, BreakKind, CellVerticalAlign, ColorScheme, Comment,
    CustomPropertyValue, Document, DocumentProperties, EmbeddedChart, ExtendedProperties, Field,
    FontScheme, HeaderFooter, Highlight, Hyperlink, Image, ImageFormat, ListLevel, Note, NoteKind,
    NoteReference, NumberFormat, NumberingDefinition, Orientation, PageSetup, Paragraph,
    ProtectionKind, Run, RunContent, StructuredDocumentTag, Style, StyleKind, TabLeader, TabStop,
    TabStopAlignment, Table, TableCell, TableRow, TextDirection, Theme, UnderlineStyle,
    VerticalAlign, VerticalMerge,
};

/// The relationship type identifying the main document part of a WordprocessingML package.
const MAIN_DOCUMENT_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";

/// The relationship type identifying `word/styles.xml`. Unlike the header/ footer relationships,
/// this one isn't referenced by an explicit `r:id` anywhere in `document.xml`'s content — Word (and
/// this reader) locates it purely by relationship type.
const STYLES_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";

/// The relationship type identifying `word/numbering.xml`. Like `STYLES_RELATIONSHIP_TYPE`, located
/// purely by relationship type — a paragraph's `w:numPr/w:numId` is a plain integer, not a
/// relationship id.
const NUMBERING_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";

/// The relationship type identifying `word/footnotes.xml`. Like `STYLES_RELATIONSHIP_TYPE`, located
/// purely by relationship type — a `<w:footnoteReference>`'s `w:id` is a plain integer, not a
/// relationship id.
const FOOTNOTES_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";

/// The relationship type identifying `word/endnotes.xml`, mirroring `FOOTNOTES_RELATIONSHIP_TYPE`.
const ENDNOTES_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";

/// The relationship type identifying `word/comments.xml`. Like `STYLES_RELATIONSHIP_TYPE`, located
/// purely by relationship type — a `<w:commentReference>`'s `w:id` is a plain integer, not a
/// relationship id.
const COMMENTS_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";

/// The relationship type identifying `word/theme/theme1.xml`. Like `STYLES_RELATIONSHIP_TYPE`,
/// located purely by relationship type.
const THEME_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";

/// The relationship type identifying `word/settings.xml`. Like `STYLES_RELATIONSHIP_TYPE`, located
/// purely by relationship type. Unlike the other relationship-type-only parts above,
/// `word/settings.xml` is always written by this crate's own `write_to` (see `writer.rs`) even when
/// near-empty, so in practice this lookup should always succeed for a document this crate produced
/// — but a `.docx` from another producer that genuinely omits it is still handled gracefully
/// (`Document.track_changes` simply stays at its `false` default).
const SETTINGS_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";

/// The relationship type identifying `docProps/core.xml`. Unlike `STYLES_RELATIONSHIP_TYPE` and the
/// other part-relative lookups above, this one is a package-level relationship (declared in the
/// package's own root `_rels/.rels`, alongside `MAIN_DOCUMENT_RELATIONSHIP_TYPE`), not a
/// relationship scoped to `word/document.xml.rels` — matching how `write_to` declares it (see
/// `writer.rs`'s `package.add_relationship` call for `CORE_PROPERTIES_RELATIONSHIP_TYPE`).
const CORE_PROPERTIES_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";

/// The relationship type identifying `docProps/app.xml`. Package-level, same posture as
/// `CORE_PROPERTIES_RELATIONSHIP_TYPE`.
const EXTENDED_PROPERTIES_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";

/// The relationship type identifying `docProps/custom.xml`. Package-level, same posture as
/// `CORE_PROPERTIES_RELATIONSHIP_TYPE` — but unlike core/extended properties, this part (and its
/// relationship) is genuinely optional, only present when `Document.custom_properties` was
/// non-empty at write time (see `writer.rs`).
const CUSTOM_PROPERTIES_RELATIONSHIP_TYPE: &str =
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties";

impl Document {
    /// Reads a `.docx` package from a seekable byte source.
    pub fn read_from<R: Read + Seek>(reader: R) -> Result<Self> {
        let package = Package::read_from(reader)?;
        let main_document_relationship = package
            .relationships()
            .iter()
            .find(|relationship| relationship.rel_type == MAIN_DOCUMENT_RELATIONSHIP_TYPE)
            .ok_or(Error::MissingMainDocument)?;

        // The root relationship's target is a path relative to the package root (e.g.
        // "word/document.xml"); part names are always root-absolute (e.g. "/word/document.xml").
        let part_name = match main_document_relationship.target_mode {
            TargetMode::Internal => format!("/{}", main_document_relationship.target),
            TargetMode::External => return Err(Error::MissingMainDocument),
        };

        let part = package.part(&part_name).ok_or(Error::MissingMainDocument)?;
        let xml = std::str::from_utf8(&part.data)?;

        // Images are referenced from `document.xml` by relationship id (`r:embed`); resolving one
        // to actual bytes means looking it up in `word/_rels/document.xml.rels`
        // (`part.relationships`, already parsed by `opc::Package::read_from`) and then fetching the
        // target part from the package.
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &part.relationships,
        };

        let parsed = parse_document_xml(xml, &resolver)?;
        let mut document = parsed.document;

        // `sectPr`'s `headerReference`/`footerReference` (only the `type="default"` one is captured
        // by `parse_document_xml`) point at a relationship declared in `document.xml`'s own
        // relationships — the same `part.relationships` used to resolve images above.
        if let Some(relationship_id) = parsed.header_relationship_id {
            document.header = Some(resolve_header_footer(
                &package,
                &part.relationships,
                &relationship_id,
            )?);
        }
        if let Some(relationship_id) = parsed.footer_relationship_id {
            document.footer = Some(resolve_header_footer(
                &package,
                &part.relationships,
                &relationship_id,
            )?);
        }
        if let Some(relationship_id) = parsed.header_first_relationship_id {
            document.header_first = Some(resolve_header_footer(
                &package,
                &part.relationships,
                &relationship_id,
            )?);
        }
        if let Some(relationship_id) = parsed.footer_first_relationship_id {
            document.footer_first = Some(resolve_header_footer(
                &package,
                &part.relationships,
                &relationship_id,
            )?);
        }
        if let Some(relationship_id) = parsed.header_even_relationship_id {
            document.header_even = Some(resolve_header_footer(
                &package,
                &part.relationships,
                &relationship_id,
            )?);
        }
        if let Some(relationship_id) = parsed.footer_even_relationship_id {
            document.footer_even = Some(resolve_header_footer(
                &package,
                &part.relationships,
                &relationship_id,
            )?);
        }

        // Unlike header/footer, `word/styles.xml` isn't referenced by an explicit `r:id` anywhere
        // in `document.xml`'s content — find it by relationship type instead, exactly how
        // `write_to` declares it (see `writer.rs`).
        let styles_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == STYLES_RELATIONSHIP_TYPE);
        if let Some(relationship) = styles_relationship {
            let styles_part_name = format!("/word/{}", relationship.target);
            let styles_part = package
                .part(&styles_part_name)
                .ok_or_else(|| Error::MissingStylesPart(styles_part_name.clone()))?;
            let styles_xml = std::str::from_utf8(&styles_part.data)?;
            document.styles = parse_styles_xml(styles_xml)?;
        }

        // Same relationship-type-only lookup as `word/styles.xml` above.
        let numbering_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == NUMBERING_RELATIONSHIP_TYPE);
        if let Some(relationship) = numbering_relationship {
            let numbering_part_name = format!("/word/{}", relationship.target);
            let numbering_part = package
                .part(&numbering_part_name)
                .ok_or_else(|| Error::MissingNumberingPart(numbering_part_name.clone()))?;
            let numbering_xml = std::str::from_utf8(&numbering_part.data)?;
            document.numbering_definitions = parse_numbering_xml(numbering_xml)?;
        }

        // Same relationship-type-only lookup as `word/styles.xml`/ `word/numbering.xml` above. Each
        // part has its own relationships (a footnote could embed its own image), so a fresh
        // [`ImageResolver`] scoped to it is built — mirrors `resolve_header_footer`.
        let footnotes_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == FOOTNOTES_RELATIONSHIP_TYPE);
        if let Some(relationship) = footnotes_relationship {
            let footnotes_part_name = format!("/word/{}", relationship.target);
            let footnotes_part = package
                .part(&footnotes_part_name)
                .ok_or_else(|| Error::MissingFootnotesPart(footnotes_part_name.clone()))?;
            let footnotes_xml = std::str::from_utf8(&footnotes_part.data)?;
            let footnotes_resolver = ImageResolver {
                package: &package,
                part_relationships: &footnotes_part.relationships,
            };
            document.footnotes = parse_notes_xml(footnotes_xml, &footnotes_resolver, b"footnote")?;
        }

        let endnotes_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == ENDNOTES_RELATIONSHIP_TYPE);
        if let Some(relationship) = endnotes_relationship {
            let endnotes_part_name = format!("/word/{}", relationship.target);
            let endnotes_part = package
                .part(&endnotes_part_name)
                .ok_or_else(|| Error::MissingEndnotesPart(endnotes_part_name.clone()))?;
            let endnotes_xml = std::str::from_utf8(&endnotes_part.data)?;
            let endnotes_resolver = ImageResolver {
                package: &package,
                part_relationships: &endnotes_part.relationships,
            };
            document.endnotes = parse_notes_xml(endnotes_xml, &endnotes_resolver, b"endnote")?;
        }

        let comments_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == COMMENTS_RELATIONSHIP_TYPE);
        if let Some(relationship) = comments_relationship {
            let comments_part_name = format!("/word/{}", relationship.target);
            let comments_part = package
                .part(&comments_part_name)
                .ok_or_else(|| Error::MissingCommentsPart(comments_part_name.clone()))?;
            let comments_xml = std::str::from_utf8(&comments_part.data)?;
            let comments_resolver = ImageResolver {
                package: &package,
                part_relationships: &comments_part.relationships,
            };
            document.comments = parse_comments_xml(comments_xml, &comments_resolver)?;
        }

        let theme_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == THEME_RELATIONSHIP_TYPE);
        if let Some(relationship) = theme_relationship {
            let theme_part_name = format!("/word/{}", relationship.target);
            let theme_part = package
                .part(&theme_part_name)
                .ok_or_else(|| Error::MissingThemePart(theme_part_name.clone()))?;
            let theme_xml = std::str::from_utf8(&theme_part.data)?;
            document.theme = Some(parse_theme_xml(theme_xml)?);
        }

        // Same relationship-type-only lookup as `word/styles.xml` etc. above, but tolerant of the
        // part being missing entirely (see `SETTINGS_RELATIONSHIP_TYPE`'s doc comment) — unlike the
        // required parts above, a document with no settings part just keeps `track_changes` at its
        // default `false`.
        let settings_relationship = part
            .relationships
            .iter()
            .find(|relationship| relationship.rel_type == SETTINGS_RELATIONSHIP_TYPE);
        if let Some(relationship) = settings_relationship {
            let settings_part_name = format!("/word/{}", relationship.target);
            if let Some(settings_part) = package.part(&settings_part_name) {
                let settings_xml = std::str::from_utf8(&settings_part.data)?;
                let (track_changes, protection) = parse_settings_xml(settings_xml)?;
                document.track_changes = track_changes;
                document.protection = protection;
            }
        }

        // Package-level relationship (declared in the package's own root `_rels/.rels`, not
        // `word/document.xml.rels`) — see `CORE_PROPERTIES_RELATIONSHIP_TYPE`'s doc comment.
        // Tolerant of the part being missing entirely, same posture as settings above.
        let core_properties_relationship = package
            .relationships()
            .iter()
            .find(|relationship| relationship.rel_type == CORE_PROPERTIES_RELATIONSHIP_TYPE);
        if let Some(relationship) = core_properties_relationship {
            let core_properties_part_name = format!("/{}", relationship.target);
            if let Some(core_properties_part) = package.part(&core_properties_part_name) {
                let core_properties_xml = std::str::from_utf8(&core_properties_part.data)?;
                document.properties = parse_core_properties_xml(core_properties_xml)?;
            }
        }

        // Same package-level lookup as core properties above, tolerant of the part being missing
        // entirely.
        let extended_properties_relationship = package
            .relationships()
            .iter()
            .find(|relationship| relationship.rel_type == EXTENDED_PROPERTIES_RELATIONSHIP_TYPE);
        if let Some(relationship) = extended_properties_relationship {
            let extended_properties_part_name = format!("/{}", relationship.target);
            if let Some(extended_properties_part) = package.part(&extended_properties_part_name) {
                let extended_properties_xml = std::str::from_utf8(&extended_properties_part.data)?;
                document.extended_properties =
                    parse_extended_properties_xml(extended_properties_xml)?;
            }
        }

        // Same package-level lookup as core/extended properties above — but here, tolerance of the
        // part being missing simply means `custom_properties` stays empty, its normal default (this
        // part is genuinely optional, unlike core/extended properties which this crate's own
        // `write_to` always produces).
        let custom_properties_relationship = package
            .relationships()
            .iter()
            .find(|relationship| relationship.rel_type == CUSTOM_PROPERTIES_RELATIONSHIP_TYPE);
        if let Some(relationship) = custom_properties_relationship {
            let custom_properties_part_name = format!("/{}", relationship.target);
            if let Some(custom_properties_part) = package.part(&custom_properties_part_name) {
                let custom_properties_xml = std::str::from_utf8(&custom_properties_part.data)?;
                document.custom_properties = parse_custom_properties_xml(custom_properties_xml)?;
            }
        }

        Ok(document)
    }
}

/// Resolves a `headerReference`/`footerReference`'s relationship id (`r:id`) to its target part
/// (`word/header1.xml`/`word/footer1.xml`) and parses its content: `CT_HdrFtr` reuses the exact
/// same block-level content model as the document body (`EG_BlockLevelElts`), just without a
/// `w:body` wrapper.
fn resolve_header_footer(
    package: &Package,
    document_relationships: &Relationships,
    relationship_id: &str,
) -> Result<HeaderFooter> {
    let relationship = document_relationships
        .by_id(relationship_id)
        .ok_or_else(|| Error::MissingHeaderFooterRelationship(relationship_id.to_string()))?;

    // The relationship's target is relative to `word/` (e.g. "header1.xml"); part names are
    // root-absolute.
    let part_name = format!("/word/{}", relationship.target);
    let part = package
        .part(&part_name)
        .ok_or_else(|| Error::MissingHeaderFooterPart(part_name.clone()))?;
    let xml = std::str::from_utf8(&part.data)?;

    // A header/footer can embed its own image (e.g. a logo); its relationships are scoped to its
    // own part (`headerN.xml.rels`), not the document's.
    let resolver = ImageResolver {
        package,
        part_relationships: &part.relationships,
    };

    Ok(HeaderFooter {
        blocks: parse_blocks(xml, &resolver)?,
    })
}

/// Resolves an image's relationship id (`r:embed`) to its actual bytes and format, by looking it up
/// in the owning part's own relationships (either `word/document.xml`'s, or a header/footer part's)
/// and then fetching the target part from the package. Also used, via its `part_relationships`
/// field directly (see [`hyperlink_from_start`]), to resolve a `<w:hyperlink>`'s `r:id` to its
/// target URL — an external relationship, so unlike an image it is never resolved to a package
/// part.
struct ImageResolver<'a> {
    package: &'a Package,
    part_relationships: &'a Relationships,
}

impl ImageResolver<'_> {
    fn resolve(
        &self,
        relationship_id: &str,
        width_emu: i64,
        height_emu: i64,
        description: String,
    ) -> Result<Image> {
        let relationship = self
            .part_relationships
            .by_id(relationship_id)
            .ok_or_else(|| Error::MissingImageRelationship(relationship_id.to_string()))?;

        // The relationship's target is relative to `word/` (e.g. "media/image1.png"); part names
        // are root-absolute.
        let part_name = format!("/word/{}", relationship.target);
        let part = self
            .package
            .part(&part_name)
            .ok_or_else(|| Error::MissingImagePart(part_name.clone()))?;
        let format = ImageFormat::from_extension(&part_name)
            .ok_or_else(|| Error::UnsupportedImageFormat(part_name.clone()))?;

        Ok(Image {
            data: part.data.clone(),
            format,
            width_emu,
            height_emu,
            description,
            // Populated by `parse_drawing` afterward, if `pic:spPr` carried anything beyond the
            // fixed default rectangle — see.
            shape_properties: None,
        })
    }

    /// Resolves a `<c:chart r:id="..">` relationship id to its `word/charts/chartN.xml` part and
    /// parses it whole into a [`chart::ChartSpace`]. Same resolution posture as
    /// [`ImageResolver::resolve`] (relationship id → part name → package lookup), just for a chart
    /// part instead of a media part.
    fn resolve_chart(&self, relationship_id: &str) -> Result<chart::ChartSpace> {
        let relationship = self
            .part_relationships
            .by_id(relationship_id)
            .ok_or_else(|| Error::MissingChartRelationship(relationship_id.to_string()))?;

        let part_name = format!("/word/{}", relationship.target);
        let part = self
            .package
            .part(&part_name)
            .ok_or_else(|| Error::MissingChartPart(part_name.clone()))?;
        let xml = std::str::from_utf8(&part.data)?;

        Ok(chart::read_chart_space(xml)?)
    }
}

/// The result of parsing `document.xml`: the document itself (blocks and `page_setup` —
/// `header`/`footer`/`header_first`/`footer_first`/ `header_even`/`footer_even` are filled in by
/// the caller, [`Document::read_from`], once these relationship ids are resolved to actual parts),
/// plus the relationship ids of whichever header/footer variants `sectPr` referenced
/// (`w:headerReference`/`w:footerReference`, one pair per `default`/`first`/`even` — `ST_HdrFtr`'s
/// three enumeration values).
struct ParsedDocumentXml {
    document: Document,
    header_relationship_id: Option<String>,
    footer_relationship_id: Option<String>,
    header_first_relationship_id: Option<String>,
    footer_first_relationship_id: Option<String>,
    header_even_relationship_id: Option<String>,
    footer_even_relationship_id: Option<String>,
}

/// Parses the content of `document.xml` into our minimal [`Document`] model: paragraphs (with
/// alignment and bold/italic/underline run properties) and tables (rows of cells, each a sequence
/// of paragraphs), interleaved in reading order, plus the default header/footer's relationship id
/// if `sectPr` references one. Everything else (page size/margins, other formatting,
/// revision-tracking attributes, etc.) is ignored for now.
///
/// This is a small recursive-descent parser: `parse_document_xml` only dispatches on top-level
/// block starts (`w:p`, `w:tbl`) and on `sectPr`'s header/footer references; `parse_paragraph` and
/// `parse_table` each consume events from the shared `reader` up to their own matching end tag,
/// calling back into each other where the grammar nests (a table cell's paragraphs, in particular).
fn parse_document_xml(xml: &str, resolver: &ImageResolver) -> Result<ParsedDocumentXml> {
    let mut document = Document::new();
    let mut header_relationship_id: Option<String> = None;
    let mut footer_relationship_id: Option<String> = None;
    let mut header_first_relationship_id: Option<String> = None;
    let mut footer_first_relationship_id: Option<String> = None;
    let mut header_even_relationship_id: Option<String> = None;
    let mut footer_even_relationship_id: Option<String> = None;
    let mut reader = Reader::from_xml_str(xml);

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"p" => document
                    .blocks
                    .push(Block::Paragraph(parse_paragraph(&mut reader, resolver)?)),
                b"tbl" => document
                    .blocks
                    .push(Block::Table(parse_table(&mut reader, resolver)?)),
                b"sdt" => document.blocks.push(Block::StructuredDocumentTag(
                    parse_structured_document_tag(&mut reader, resolver)?,
                )),
                b"headerReference" => capture_header_footer_reference(
                    &start,
                    &mut header_relationship_id,
                    &mut header_first_relationship_id,
                    &mut header_even_relationship_id,
                ),
                b"footerReference" => capture_header_footer_reference(
                    &start,
                    &mut footer_relationship_id,
                    &mut footer_first_relationship_id,
                    &mut footer_even_relationship_id,
                ),
                b"pgSz" => apply_page_size(&start, &mut document.page_setup),
                b"pgMar" => apply_page_margins(&start, &mut document.page_setup),
                b"cols" => {
                    document.page_setup.columns =
                        raw_attribute(&start, b"num").and_then(|value| value.parse().ok())
                }
                _ => {}
            },

            Event::Empty(start) => match start.local_name().as_ref() {
                b"p" => document.blocks.push(Block::Paragraph(Paragraph::new())),
                b"sdt" => document
                    .blocks
                    .push(Block::StructuredDocumentTag(StructuredDocumentTag::new())),
                b"headerReference" => capture_header_footer_reference(
                    &start,
                    &mut header_relationship_id,
                    &mut header_first_relationship_id,
                    &mut header_even_relationship_id,
                ),
                b"footerReference" => capture_header_footer_reference(
                    &start,
                    &mut footer_relationship_id,
                    &mut footer_first_relationship_id,
                    &mut footer_even_relationship_id,
                ),
                b"pgSz" => apply_page_size(&start, &mut document.page_setup),
                b"pgMar" => apply_page_margins(&start, &mut document.page_setup),
                b"cols" => {
                    document.page_setup.columns =
                        raw_attribute(&start, b"num").and_then(|value| value.parse().ok())
                }
                _ => {}
            },

            _ => {}
        }
    }

    Ok(ParsedDocumentXml {
        document,
        header_relationship_id,
        footer_relationship_id,
        header_first_relationship_id,
        footer_first_relationship_id,
        header_even_relationship_id,
        footer_even_relationship_id,
    })
}

/// Applies a `<w:pgSz>`'s `w:w`/`w:h`/`w:orient` attributes onto `page_setup`, leaving whatever was
/// already there (the `PageSetup::default()` values) unchanged for any attribute that's missing or
/// unparsable — same forgiving policy as the rest of this reader.
fn apply_page_size(start: &BytesStart, page_setup: &mut PageSetup) {
    if let Some(width) = raw_attribute(start, b"w").and_then(|value| value.parse().ok()) {
        page_setup.width_twips = width;
    }
    if let Some(height) = raw_attribute(start, b"h").and_then(|value| value.parse().ok()) {
        page_setup.height_twips = height;
    }
    if let Some(orientation) =
        raw_attribute(start, b"orient").and_then(|value| Orientation::from_attribute_value(&value))
    {
        page_setup.orientation = orientation;
    }
}

/// Applies a `<w:pgMar>`'s margin attributes onto `page_setup`, same leave-as-is-if-missing policy
/// as [`apply_page_size`].
fn apply_page_margins(start: &BytesStart, page_setup: &mut PageSetup) {
    if let Some(value) = raw_attribute(start, b"top").and_then(|value| value.parse().ok()) {
        page_setup.margin_top_twips = value;
    }
    if let Some(value) = raw_attribute(start, b"bottom").and_then(|value| value.parse().ok()) {
        page_setup.margin_bottom_twips = value;
    }
    if let Some(value) = raw_attribute(start, b"left").and_then(|value| value.parse().ok()) {
        page_setup.margin_left_twips = value;
    }
    if let Some(value) = raw_attribute(start, b"right").and_then(|value| value.parse().ok()) {
        page_setup.margin_right_twips = value;
    }
    if let Some(value) = raw_attribute(start, b"header").and_then(|value| value.parse().ok()) {
        page_setup.margin_header_twips = value;
    }
    if let Some(value) = raw_attribute(start, b"footer").and_then(|value| value.parse().ok()) {
        page_setup.margin_footer_twips = value;
    }
    if let Some(value) = raw_attribute(start, b"gutter").and_then(|value| value.parse().ok()) {
        page_setup.margin_gutter_twips = value;
    }
}

/// Parses a sequence of block-level elements (paragraphs and tables, in reading order) from a whole
/// XML part. Shared by header/footer parts (`CT_HdrFtr`, which has no `sectPr` of its own) —
/// `parse_document_xml` keeps its own, similar loop instead of calling this, since it additionally
/// needs to capture `sectPr`'s header/footer references.
fn parse_blocks(xml: &str, resolver: &ImageResolver) -> Result<Vec<Block>> {
    let mut blocks = Vec::new();
    let mut reader = Reader::from_xml_str(xml);

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"p" => blocks.push(Block::Paragraph(parse_paragraph(&mut reader, resolver)?)),
                b"tbl" => blocks.push(Block::Table(parse_table(&mut reader, resolver)?)),
                b"sdt" => blocks.push(Block::StructuredDocumentTag(parse_structured_document_tag(
                    &mut reader,
                    resolver,
                )?)),
                _ => {}
            },

            Event::Empty(start) => match start.local_name().as_ref() {
                b"p" => blocks.push(Block::Paragraph(Paragraph::new())),
                b"sdt" => blocks.push(Block::StructuredDocumentTag(StructuredDocumentTag::new())),
                _ => {}
            },

            _ => {}
        }
    }

    Ok(blocks)
}

/// Captures a `headerReference`/`footerReference`'s `r:id` into whichever of
/// `default_target`/`first_target`/`even_target` matches its `w:type` (`ST_HdrFtr`'s three
/// enumeration values — `default`/`first`/`even`), only if nothing has been captured yet for that
/// variant (the first occurrence of a given type wins).
fn capture_header_footer_reference(
    start: &BytesStart,
    default_target: &mut Option<String>,
    first_target: &mut Option<String>,
    even_target: &mut Option<String>,
) {
    let type_value = raw_attribute(start, b"type");
    match type_value.as_deref() {
        Some("default") if default_target.is_none() => {
            *default_target = raw_attribute(start, b"id")
        }
        Some("first") if first_target.is_none() => *first_target = raw_attribute(start, b"id"),
        Some("even") if even_target.is_none() => *even_target = raw_attribute(start, b"id"),
        _ => {}
    }
}

/// Parses a single `<w:p>` paragraph, assuming its `Start` event was just consumed by the caller.
/// Reads runs (text or an inline image, plus bold/italic/underline) and paragraph alignment
/// (`w:pPr`/`w:jc`), stopping at the matching `</w:p>`.
fn parse_paragraph(reader: &mut Reader<'_>, resolver: &ImageResolver) -> Result<Paragraph> {
    let mut paragraph = Paragraph::new();
    let mut current_run_text: Option<String> = None;
    // Holds `RunContent::Image` or `RunContent::Chart(EmbeddedChart)` — `<w:drawing>`
    // (`parse_drawing`) can produce either.
    let mut current_run_drawing: Option<RunContent> = None;
    // `<w:footnoteReference>`/`<w:endnoteReference>`/`<w:footnoteRef>`/ `<w:endnoteRef>` are,
    // unlike `w:drawing`, always self-closing (`CT_FtnEdnRef`/`CT_Empty` have no content model at
    // all), so this is only ever set from the `Empty` match arm below — see [`RunContent`]'s doc
    // comment for why these are genuine run content, not a sibling wrapper like
    // `w:fldSimple`/`w:hyperlink`.
    let mut current_run_note: Option<RunContent> = None;
    // `<w:br>`/`<w:cr>` (`CT_Br`/`CT_Empty`) are, like the note reference/marker elements above,
    // always self-closing genuine `EG_RunInnerContent` members — only ever set from the `Empty`
    // match arm below.
    let mut current_run_break: Option<RunContent> = None;
    let mut current_run_bold = false;
    let mut current_run_italic = false;
    let mut current_run_underline: Option<UnderlineStyle> = None;
    let mut current_run_underline_color: Option<String> = None;
    let mut current_run_color: Option<String> = None;
    let mut current_run_font_size: Option<u16> = None;
    let mut current_run_font_family: Option<String> = None;
    let mut current_run_highlight: Option<Highlight> = None;
    let mut current_run_strike = false;
    let mut current_run_vertical_align: Option<VerticalAlign> = None;
    let mut current_run_small_caps = false;
    let mut current_run_all_caps = false;
    let mut current_run_shading_color: Option<String> = None;
    let mut current_run_text_border = false;
    let mut current_run_character_spacing: Option<i16> = None;
    let mut current_run_vertical_position: Option<i16> = None;
    let mut current_run_hidden = false;
    let mut current_run_style_id: Option<String> = None;
    // Whether the loop is currently between a `<w:r>` and its matching `</w:r>` (including a
    // field's nested run, between `<w:fldSimple>`'s own `<w:r>` and `</w:r>` — `w:fldSimple`
    // doesn't get its own flag, this one already covers it). Needed because a handful of element
    // names are shared, with different meanings, between `w:pPr` (always consumed before any
    // `<w:r>` in a well-formed document, per `CT_PPrBase`'s sequence — see `write_paragraph`'s doc
    // comment) and `w:rPr` — `w:shd`/`w:spacing` in particular, see their match arms below
    // (`w:pBdr`/`w:bdr` don't collide, different names, so don't need this).
    let mut in_run = false;
    let mut in_text = false;
    // `w:fldSimple` (`CT_SimpleField`) is a sibling of `w:r` in `EG_PContent`, wrapping its own
    // inner run — so while `in_field` is set, the nested `w:r`'s formatting is captured as usual
    // (into `current_run_*` above) but is NOT pushed as its own run at `</w:r>`; instead, one `Run`
    // with `RunContent::Field` is pushed at `</w:fldSimple>`, using whatever formatting the (only)
    // nested run set. `current_field` is `None` for a recognized-but-unsupported instruction (e.g.
    // `DATE`) or an unrecognized one — such fields are silently dropped rather than erroring out
    // the whole document (same policy as an unresolvable image, see `parse_drawing`).
    let mut in_field = false;
    let mut current_field: Option<Field> = None;
    // `w:hyperlink` (`CT_Hyperlink`) is, like `w:fldSimple`, a sibling of `w:r` in `EG_PContent`
    // that wraps its own nested run(s) — but unlike a field, it doesn't suppress the ordinary
    // per-run push at `</w:r>` (a hyperlinked run is still just a run, with `hyperlink` set), so
    // there is no `in_hyperlink` flag to gate on, just `current_hyperlink` cloned onto every run
    // pushed between `<w:hyperlink>` and `</w:hyperlink>`. `None` if the `<w:hyperlink>` has
    // neither `r:id` (and it doesn't resolve to a declared relationship) nor `w:anchor` — such a
    // hyperlink is silently dropped (its nested runs are still kept as plain runs), same policy as
    // an unsupported field.
    let mut current_hyperlink: Option<Hyperlink> = None;
    // Which comment ids are currently "open" (a `w:commentRangeStart` seen, no matching
    // `w:commentRangeEnd` yet) as the loop walks the paragraph's content in order.
    // `w:commentRangeStart`/`w:commentRangeEnd` (`CT_MarkupRange`) are, like `w:footnoteReference`,
    // always self-closing siblings of `w:r` — never nested inside one (see `Run.comment_ids`'s doc
    // comment) — so this list never changes *while* a `<w:r>` is open, meaning every
    // run-construction site below can just clone it directly, with no separate "run started with
    // these ids" snapshot needed.
    let mut open_comment_ids: Vec<u32> = Vec::new();
    // Which bookmarks are currently "open", mirroring `open_comment_ids` exactly
    // (`w:bookmarkStart`/`w:bookmarkEnd` are, like `w:commentRangeStart`/`End`, always self-closing
    // siblings of `w:r` — see `Run.bookmarks`'s doc comment). Unlike comment ids, a bookmark
    // carries its name right on `w:bookmarkStart`, so the full [`Bookmark`] (not just its id) is
    // tracked here.
    let mut open_bookmarks: Vec<Bookmark> = Vec::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"r" => {
                    in_run = true;
                    current_run_text = Some(String::new());
                    current_run_drawing = None;
                    current_run_note = None;
                    current_run_break = None;
                    current_run_bold = false;
                    current_run_italic = false;
                    current_run_underline = None;
                    current_run_underline_color = None;
                    current_run_color = None;
                    current_run_font_size = None;
                    current_run_font_family = None;
                    current_run_highlight = None;
                    current_run_strike = false;
                    current_run_vertical_align = None;
                    current_run_small_caps = false;
                    current_run_all_caps = false;
                    current_run_shading_color = None;
                    current_run_text_border = false;
                    current_run_character_spacing = None;
                    current_run_vertical_position = None;
                    current_run_hidden = false;
                    current_run_style_id = None;
                }
                b"t" => in_text = true,
                b"drawing" => current_run_drawing = parse_drawing(reader, resolver)?,
                b"pStyle" => paragraph.style_id = raw_attribute(&start, b"val"),
                b"ilvl" => {
                    paragraph.numbering_level = raw_attribute(&start, b"val")
                        .and_then(|value| value.parse().ok())
                        .unwrap_or(0)
                }
                b"numId" => {
                    paragraph.numbering_id =
                        raw_attribute(&start, b"val").and_then(|value| value.parse().ok())
                }
                b"jc" => paragraph.alignment = alignment_from_attribute(&start),
                b"b" => current_run_bold = on_off_attribute(&start),
                b"i" => current_run_italic = on_off_attribute(&start),
                b"u" => {
                    current_run_underline = underline_attribute(&start);
                    current_run_underline_color = raw_attribute(&start, b"color");
                }
                b"color" => current_run_color = raw_attribute(&start, b"val"),
                b"sz" => {
                    current_run_font_size = raw_attribute(&start, b"val")
                        .and_then(|value| value.parse::<u16>().ok())
                        .map(|half_points| half_points / 2)
                }
                b"rFonts" => {
                    current_run_font_family =
                        raw_attribute(&start, b"ascii").or_else(|| raw_attribute(&start, b"hAnsi"))
                }
                b"highlight" => {
                    current_run_highlight = raw_attribute(&start, b"val")
                        .and_then(|value| Highlight::from_attribute_value(&value))
                }
                b"strike" => current_run_strike = on_off_attribute(&start),
                b"vertAlign" => {
                    current_run_vertical_align = raw_attribute(&start, b"val")
                        .and_then(|value| VerticalAlign::from_attribute_value(&value))
                }
                b"smallCaps" => current_run_small_caps = on_off_attribute(&start),
                b"caps" => current_run_all_caps = on_off_attribute(&start),
                // `w:shd`/`w:spacing` are shared element names between `w:rPr` (run
                // shading/character spacing) and `w:pPr` (paragraph shading/line-and-before-after
                // spacing) — see `in_run`'s doc comment above for why branching on it is safe here.
                // `w:bdr`/`w:pBdr` don't collide (different names), so `b"bdr"` above is
                // unambiguously run-level.
                b"shd" => {
                    if in_run {
                        current_run_shading_color = raw_attribute(&start, b"fill");
                    } else {
                        paragraph.shading_color = raw_attribute(&start, b"fill");
                    }
                }
                b"bdr" => current_run_text_border = true,
                b"spacing" => {
                    if in_run {
                        current_run_character_spacing = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<i16>().ok());
                    } else {
                        paragraph.space_before = raw_attribute(&start, b"before")
                            .and_then(|value| value.parse::<u32>().ok());
                        paragraph.space_after = raw_attribute(&start, b"after")
                            .and_then(|value| value.parse::<u32>().ok());
                        paragraph.line_spacing = raw_attribute(&start, b"line")
                            .and_then(|value| value.parse::<u32>().ok());
                    }
                }
                b"position" => {
                    current_run_vertical_position =
                        raw_attribute(&start, b"val").and_then(|value| value.parse::<i16>().ok())
                }
                b"vanish" => current_run_hidden = true,
                b"rStyle" => current_run_style_id = raw_attribute(&start, b"val"),
                b"pBdr" => paragraph.border = true,
                b"keepNext" => paragraph.keep_with_next = true,
                b"keepLines" => paragraph.keep_lines_together = true,
                b"pageBreakBefore" => paragraph.page_break_before = true,
                b"contextualSpacing" => paragraph.contextual_spacing = true,
                b"fldSimple" => {
                    in_field = true;
                    current_field =
                        field_from_instruction(raw_attribute(&start, b"instr").as_deref());
                }
                b"hyperlink" => current_hyperlink = hyperlink_from_start(&start, resolver),
                _ => {}
            },

            Event::Empty(start) => match start.local_name().as_ref() {
                b"r" if !in_field => {
                    paragraph.runs.push(Run {
                        hyperlink: current_hyperlink.clone(),
                        comment_ids: open_comment_ids.clone(),
                        bookmarks: open_bookmarks.clone(),
                        ..Run::new("")
                    });
                }
                b"pStyle" => paragraph.style_id = raw_attribute(&start, b"val"),
                b"ilvl" => {
                    paragraph.numbering_level = raw_attribute(&start, b"val")
                        .and_then(|value| value.parse().ok())
                        .unwrap_or(0)
                }
                b"numId" => {
                    paragraph.numbering_id =
                        raw_attribute(&start, b"val").and_then(|value| value.parse().ok())
                }
                b"jc" => paragraph.alignment = alignment_from_attribute(&start),
                b"b" => current_run_bold = on_off_attribute(&start),
                b"i" => current_run_italic = on_off_attribute(&start),
                b"u" => {
                    current_run_underline = underline_attribute(&start);
                    current_run_underline_color = raw_attribute(&start, b"color");
                }
                b"color" => current_run_color = raw_attribute(&start, b"val"),
                b"sz" => {
                    current_run_font_size = raw_attribute(&start, b"val")
                        .and_then(|value| value.parse::<u16>().ok())
                        .map(|half_points| half_points / 2)
                }
                b"rFonts" => {
                    current_run_font_family =
                        raw_attribute(&start, b"ascii").or_else(|| raw_attribute(&start, b"hAnsi"))
                }
                b"highlight" => {
                    current_run_highlight = raw_attribute(&start, b"val")
                        .and_then(|value| Highlight::from_attribute_value(&value))
                }
                b"strike" => current_run_strike = on_off_attribute(&start),
                b"vertAlign" => {
                    current_run_vertical_align = raw_attribute(&start, b"val")
                        .and_then(|value| VerticalAlign::from_attribute_value(&value))
                }
                b"smallCaps" => current_run_small_caps = on_off_attribute(&start),
                b"caps" => current_run_all_caps = on_off_attribute(&start),
                b"shd" => {
                    if in_run {
                        current_run_shading_color = raw_attribute(&start, b"fill");
                    } else {
                        paragraph.shading_color = raw_attribute(&start, b"fill");
                    }
                }
                b"bdr" => current_run_text_border = true,
                b"spacing" => {
                    if in_run {
                        current_run_character_spacing = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<i16>().ok());
                    } else {
                        paragraph.space_before = raw_attribute(&start, b"before")
                            .and_then(|value| value.parse::<u32>().ok());
                        paragraph.space_after = raw_attribute(&start, b"after")
                            .and_then(|value| value.parse::<u32>().ok());
                        paragraph.line_spacing = raw_attribute(&start, b"line")
                            .and_then(|value| value.parse::<u32>().ok());
                    }
                }
                b"position" => {
                    current_run_vertical_position =
                        raw_attribute(&start, b"val").and_then(|value| value.parse::<i16>().ok())
                }
                b"vanish" => current_run_hidden = true,
                b"rStyle" => current_run_style_id = raw_attribute(&start, b"val"),
                b"pBdr" => paragraph.border = true,
                b"keepNext" => paragraph.keep_with_next = true,
                b"keepLines" => paragraph.keep_lines_together = true,
                b"pageBreakBefore" => paragraph.page_break_before = true,
                b"contextualSpacing" => paragraph.contextual_spacing = true,
                // `w:tab` (`CT_TabStop`) has no content model at all — always self-closing. A tab
                // with no (or an unparsable) `w:pos` is silently dropped, same forgiving policy as
                // elsewhere in this reader.
                b"tab" => {
                    if let Some(position) =
                        raw_attribute(&start, b"pos").and_then(|value| value.parse::<i32>().ok())
                    {
                        let mut tab = TabStop::new(position);
                        if let Some(alignment) = raw_attribute(&start, b"val")
                            .and_then(|value| TabStopAlignment::from_attribute_value(&value))
                        {
                            tab = tab.with_alignment(alignment);
                        }
                        if let Some(leader) = raw_attribute(&start, b"leader")
                            .and_then(|value| TabLeader::from_attribute_value(&value))
                        {
                            tab = tab.with_leader(leader);
                        }
                        paragraph.tabs.push(tab);
                    }
                }
                // `w:br`/`w:cr` (`CT_Br`/`CT_Empty`) — see `current_run_break`'s doc comment above.
                b"br" => {
                    current_run_break = Some(RunContent::Break(BreakKind::from_attribute_value(
                        raw_attribute(&start, b"type").as_deref(),
                    )));
                }
                b"cr" => current_run_break = Some(RunContent::CarriageReturn),
                // A field with no inner run at all (e.g. `<w:fldSimple w:instr="PAGE"/>`) — push it
                // immediately, there is no `</w:fldSimple>` to wait for.
                b"fldSimple" => {
                    if let Some(field) =
                        field_from_instruction(raw_attribute(&start, b"instr").as_deref())
                    {
                        paragraph.runs.push(Run {
                            hyperlink: current_hyperlink.clone(),
                            comment_ids: open_comment_ids.clone(),
                            bookmarks: open_bookmarks.clone(),
                            ..Run::with_field(field)
                        });
                    }
                }
                // `w:commentRangeStart`/`w:commentRangeEnd` (`CT_MarkupRange`) are always
                // self-closing (no content model at all) — see `open_comment_ids`'s doc comment
                // above for how these drive `Run.comment_ids`. A start/end with no (or an
                // unparsable) `id` is silently ignored, same forgiving policy as elsewhere in this
                // reader.
                b"commentRangeStart" => {
                    if let Some(id) =
                        raw_attribute(&start, b"id").and_then(|value| value.parse().ok())
                    {
                        open_comment_ids.push(id);
                    }
                }
                b"commentRangeEnd" => {
                    if let Some(id) =
                        raw_attribute(&start, b"id").and_then(|value| value.parse::<u32>().ok())
                    {
                        open_comment_ids.retain(|open_id| *open_id != id);
                    }
                }
                // `w:bookmarkStart`/`w:bookmarkEnd` (`CT_Bookmark`/ `CT_MarkupRange`) — see
                // `open_bookmarks`'s doc comment above. A start with no (or an unparsable)
                // `id`/`name` is silently ignored, same forgiving policy as `commentRangeStart`
                // above.
                b"bookmarkStart" => {
                    if let (Some(id), Some(name)) = (
                        raw_attribute(&start, b"id").and_then(|value| value.parse().ok()),
                        raw_attribute(&start, b"name"),
                    ) {
                        open_bookmarks.push(Bookmark::new(id, name));
                    }
                }
                b"bookmarkEnd" => {
                    if let Some(id) =
                        raw_attribute(&start, b"id").and_then(|value| value.parse::<u32>().ok())
                    {
                        open_bookmarks.retain(|bookmark| bookmark.id != id);
                    }
                }
                // `w:commentReference` is a writer-derived artifact (see
                // `write_comment_range_end_and_reference` in `writer.rs`) with no bearing on
                // `Run.comment_ids` — the range itself (`commentRangeStart`/`End`) is what's
                // authoritative, so this needs no handling beyond not falling through to an
                // unrelated arm.
                b"commentReference" => {}
                b"footnoteReference" => {
                    current_run_note = raw_attribute(&start, b"id")
                        .and_then(|value| value.parse().ok())
                        .map(|id| RunContent::NoteReference(NoteReference::Footnote(id)));
                }
                b"endnoteReference" => {
                    current_run_note = raw_attribute(&start, b"id")
                        .and_then(|value| value.parse().ok())
                        .map(|id| RunContent::NoteReference(NoteReference::Endnote(id)));
                }
                b"footnoteRef" => {
                    current_run_note = Some(RunContent::NoteMarker(NoteKind::Footnote))
                }
                b"endnoteRef" => current_run_note = Some(RunContent::NoteMarker(NoteKind::Endnote)),
                _ => {}
            },

            Event::Text(text) if in_text => {
                if let Some(buffer) = current_run_text.as_mut() {
                    let text = xml_core::decode_text(&text)?;
                    buffer.push_str(&text);
                }
            }

            // `quick_xml` splits a text node's `&entity;`/`&#NNN;` references out into their own
            // dedicated event, distinct from `Text` — a single `<w:t>A &amp; B</w:t>` arrives as
            // `Text("A ")`, `GeneralRef("amp")`, `Text(" B")`, not one `Text` event containing the
            // whole escaped string. Missing this case entirely (there used to be no arm for it
            // here) is what caused entities to vanish without a trace on read — not left escaped,
            // not mis-decoded, just silently dropped by the catch-all `_ => {}` below. See
            // `xml_core::decode_text`'s doc comment for the full story and the CHANGELOG entry.
            Event::GeneralRef(reference) if in_text => {
                if let Some(buffer) = current_run_text.as_mut() {
                    if let Some(resolved) = xml_core::decode_general_ref(&reference)? {
                        buffer.push_str(&resolved);
                    }
                }
            }

            Event::End(end) => match end.local_name().as_ref() {
                b"t" => in_text = false,
                b"r" if in_field => {
                    // The field's own run is pushed once, at `</w:fldSimple>` below, using this
                    // run's formatting (left as-is in `current_run_bold/italic/underline`).
                    in_run = false;
                }
                b"r" => {
                    in_run = false;
                    let bold = current_run_bold;
                    let italic = current_run_italic;
                    let underline = current_run_underline;
                    let underline_color = current_run_underline_color.take();
                    let color = current_run_color.take();
                    let font_size = current_run_font_size;
                    let font_family = current_run_font_family.take();
                    let highlight = current_run_highlight.take();
                    let strike = current_run_strike;
                    let vertical_align = current_run_vertical_align.take();
                    let small_caps = current_run_small_caps;
                    let all_caps = current_run_all_caps;
                    let shading_color = current_run_shading_color.take();
                    let text_border = current_run_text_border;
                    let character_spacing = current_run_character_spacing;
                    let vertical_position = current_run_vertical_position;
                    let hidden = current_run_hidden;
                    let style_id = current_run_style_id.take();
                    let hyperlink = current_hyperlink.clone();
                    let comment_ids = open_comment_ids.clone();
                    let bookmarks = open_bookmarks.clone();
                    let run = if let Some(drawing_content) = current_run_drawing.take() {
                        Run {
                            content: drawing_content,
                            bold,
                            italic,
                            underline,
                            underline_color,
                            color,
                            font_size,
                            font_family,
                            highlight,
                            strike,
                            vertical_align,
                            small_caps,
                            all_caps,
                            shading_color,
                            text_border,
                            character_spacing,
                            vertical_position,
                            hidden,
                            style_id,
                            hyperlink,
                            comment_ids,
                            bookmarks,
                        }
                    } else if let Some(note_content) = current_run_note.take() {
                        Run {
                            content: note_content,
                            bold,
                            italic,
                            underline,
                            underline_color,
                            color,
                            font_size,
                            font_family,
                            highlight,
                            strike,
                            vertical_align,
                            small_caps,
                            all_caps,
                            shading_color,
                            text_border,
                            character_spacing,
                            vertical_position,
                            hidden,
                            style_id,
                            hyperlink,
                            comment_ids,
                            bookmarks,
                        }
                    } else if let Some(break_content) = current_run_break.take() {
                        Run {
                            content: break_content,
                            bold,
                            italic,
                            underline,
                            underline_color,
                            color,
                            font_size,
                            font_family,
                            highlight,
                            strike,
                            vertical_align,
                            small_caps,
                            all_caps,
                            shading_color,
                            text_border,
                            character_spacing,
                            vertical_position,
                            hidden,
                            style_id,
                            hyperlink,
                            comment_ids,
                            bookmarks,
                        }
                    } else {
                        let text = current_run_text.take().unwrap_or_default();
                        Run {
                            content: RunContent::Text(text),
                            bold,
                            italic,
                            underline,
                            underline_color,
                            color,
                            font_size,
                            font_family,
                            highlight,
                            strike,
                            vertical_align,
                            small_caps,
                            all_caps,
                            shading_color,
                            text_border,
                            character_spacing,
                            vertical_position,
                            hidden,
                            style_id,
                            hyperlink,
                            comment_ids,
                            bookmarks,
                        }
                    };
                    paragraph.runs.push(run);
                }
                b"fldSimple" => {
                    if let Some(field) = current_field.take() {
                        paragraph.runs.push(Run {
                            content: RunContent::Field(field),
                            bold: current_run_bold,
                            italic: current_run_italic,
                            underline: current_run_underline,
                            underline_color: current_run_underline_color.take(),
                            color: current_run_color.take(),
                            font_size: current_run_font_size,
                            font_family: current_run_font_family.take(),
                            highlight: current_run_highlight.take(),
                            strike: current_run_strike,
                            vertical_align: current_run_vertical_align.take(),
                            small_caps: current_run_small_caps,
                            all_caps: current_run_all_caps,
                            shading_color: current_run_shading_color.take(),
                            text_border: current_run_text_border,
                            character_spacing: current_run_character_spacing,
                            vertical_position: current_run_vertical_position,
                            hidden: current_run_hidden,
                            style_id: current_run_style_id.take(),
                            hyperlink: current_hyperlink.clone(),
                            comment_ids: open_comment_ids.clone(),
                            bookmarks: open_bookmarks.clone(),
                        });
                    }
                    in_field = false;
                }
                b"hyperlink" => current_hyperlink = None,
                b"p" => break,
                _ => {}
            },

            _ => {}
        }
    }

    Ok(paragraph)
}

/// Parses a single `<w:tbl>` table, assuming its `Start` event was just consumed by the caller.
/// Reads rows and cells, delegating each cell's paragraphs to [`parse_paragraph`] and each cell's
/// own nested `<w:tbl>` (if any — `CT_Tc` allows one, see [`TableCell`]'s doc comment) to a
/// recursive call of this same function, so arbitrarily nested tables round-trip; everything else
/// (`tblPr`, `tblGrid`, cell/row properties) is ignored for now. Stops at the matching `</w:tbl>`.
fn parse_table(reader: &mut Reader<'_>, resolver: &ImageResolver) -> Result<Table> {
    let mut table = Table::new();
    let mut current_row: Option<TableRow> = None;
    let mut current_cell: Option<TableCell> = None;

    // Disambiguation flags, the same pattern as `parse_paragraph`'s `in_run`/`parse_style`'s
    // `in_paragraph_properties`: several element names here are reused across more than one parent
    // in WordprocessingML (`top`/`left`/`bottom`/`right` mean a table border side in
    // `w:tblBorders`, a cell border side in `w:tcBorders`, OR a cell margin side in `w:tcMar`; `jc`
    // means table alignment in `w:tblPr` but is also (unmodeled) valid in `w:trPr`) — a paragraph's
    // own `w:pPr/w:jc`/`w:pBdr` never reach this loop at all, since `p` is fully delegated to
    // `parse_paragraph` before returning here.
    let mut in_table_properties = false;
    let mut in_tbl_borders = false;
    let mut in_tc_borders = false;
    let mut in_tc_mar = false;

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"tblPr" => in_table_properties = true,
                b"tblBorders" => in_tbl_borders = true,
                b"tcBorders" => in_tc_borders = true,
                b"tcMar" => in_tc_mar = true,
                b"tr" => current_row = Some(TableRow::new()),
                b"tc" => current_cell = Some(TableCell::new()),
                b"p" => {
                    let paragraph = parse_paragraph(reader, resolver)?;
                    if let Some(cell) = current_cell.as_mut() {
                        cell.blocks.push(Block::Paragraph(paragraph));
                    }
                }
                // A nested `<w:tbl>` inside a cell (`CT_Tc` allows one, see [`TableCell`]'s doc
                // comment) — recurse, since this function's own precondition ("Start` event already
                // consumed") is exactly what just happened here.
                b"tbl" => {
                    let nested_table = parse_table(reader, resolver)?;
                    if let Some(cell) = current_cell.as_mut() {
                        cell.blocks.push(Block::Table(nested_table));
                    }
                }
                b"tblStyle" => {
                    table.style_id = raw_attribute(&start, b"val");
                }
                b"jc" if in_table_properties => {
                    table.alignment = alignment_from_attribute(&start);
                }
                b"tblInd" => {
                    table.indent_twips =
                        raw_attribute(&start, b"w").and_then(|value| value.parse::<u32>().ok());
                }
                b"top" | b"left" | b"bottom" | b"right" => {
                    apply_table_or_cell_side(
                        &start,
                        start.local_name().as_ref(),
                        in_tbl_borders,
                        in_table_properties,
                        in_tc_borders,
                        in_tc_mar,
                        &mut table,
                        current_cell.as_mut(),
                    );
                }
                b"shd" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.shading_color = raw_attribute(&start, b"fill");
                    }
                }
                b"textDirection" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.text_direction = raw_attribute(&start, b"val")
                            .and_then(|value| TextDirection::from_attribute_value(&value));
                    }
                }
                b"vAlign" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.vertical_alignment = raw_attribute(&start, b"val")
                            .and_then(|value| CellVerticalAlign::from_attribute_value(&value));
                    }
                }
                b"cantSplit" => {
                    if let Some(row) = current_row.as_mut() {
                        row.cant_split = true;
                    }
                }
                b"trHeight" => {
                    if let Some(row) = current_row.as_mut() {
                        row.height_twips = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<u32>().ok());
                    }
                }
                b"tblHeader" => {
                    if let Some(row) = current_row.as_mut() {
                        row.repeat_as_header_row = true;
                    }
                }
                b"gridSpan" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.horizontal_span = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<u32>().ok());
                    }
                }
                b"vMerge" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.vertical_merge = Some(vertical_merge_attribute(&start));
                    }
                }
                // `w:gridCol` is `CT_TblGridCol`, attributes-only, so this always arrives as
                // `Event::Empty` in practice — handled here too anyway, same defensive-coverage
                // policy as the other arms in this match. See `Table.column_widths`'s doc comment
                // for the round-trip nuance this creates: a table WITHOUT explicit widths still
                // gets `column_widths` populated on read, since `w:tblGrid` always carries concrete
                // `w` values in this crate's own output — there is no way to tell "explicitly set
                // to the default" apart from "left unset" once written.
                b"gridCol" => {
                    if let Some(width) =
                        raw_attribute(&start, b"w").and_then(|value| value.parse::<u32>().ok())
                    {
                        table.column_widths.push(width);
                    }
                }
                _ => {}
            },

            Event::Empty(start) => match start.local_name().as_ref() {
                b"p" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.blocks.push(Block::Paragraph(Paragraph::new()));
                    }
                }
                b"tblStyle" => {
                    table.style_id = raw_attribute(&start, b"val");
                }
                b"jc" if in_table_properties => {
                    table.alignment = alignment_from_attribute(&start);
                }
                b"tblInd" => {
                    table.indent_twips =
                        raw_attribute(&start, b"w").and_then(|value| value.parse::<u32>().ok());
                }
                b"top" | b"left" | b"bottom" | b"right" => {
                    apply_table_or_cell_side(
                        &start,
                        start.local_name().as_ref(),
                        in_tbl_borders,
                        in_table_properties,
                        in_tc_borders,
                        in_tc_mar,
                        &mut table,
                        current_cell.as_mut(),
                    );
                }
                b"shd" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.shading_color = raw_attribute(&start, b"fill");
                    }
                }
                b"textDirection" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.text_direction = raw_attribute(&start, b"val")
                            .and_then(|value| TextDirection::from_attribute_value(&value));
                    }
                }
                b"vAlign" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.vertical_alignment = raw_attribute(&start, b"val")
                            .and_then(|value| CellVerticalAlign::from_attribute_value(&value));
                    }
                }
                b"cantSplit" => {
                    if let Some(row) = current_row.as_mut() {
                        row.cant_split = true;
                    }
                }
                b"trHeight" => {
                    if let Some(row) = current_row.as_mut() {
                        row.height_twips = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<u32>().ok());
                    }
                }
                b"tblHeader" => {
                    if let Some(row) = current_row.as_mut() {
                        row.repeat_as_header_row = true;
                    }
                }
                b"gridSpan" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.horizontal_span = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<u32>().ok());
                    }
                }
                b"vMerge" => {
                    if let Some(cell) = current_cell.as_mut() {
                        cell.vertical_merge = Some(vertical_merge_attribute(&start));
                    }
                }
                b"gridCol" => {
                    if let Some(width) =
                        raw_attribute(&start, b"w").and_then(|value| value.parse::<u32>().ok())
                    {
                        table.column_widths.push(width);
                    }
                }
                _ => {}
            },

            Event::End(end) => match end.local_name().as_ref() {
                b"tblPr" => in_table_properties = false,
                b"tblBorders" => in_tbl_borders = false,
                b"tcBorders" => in_tc_borders = false,
                b"tcMar" => in_tc_mar = false,
                b"tc" => {
                    if let (Some(cell), Some(row)) = (current_cell.take(), current_row.as_mut()) {
                        row.cells.push(cell);
                    }
                }
                b"tr" => {
                    if let Some(row) = current_row.take() {
                        table.rows.push(row);
                    }
                }
                b"tbl" => break,
                _ => {}
            },

            _ => {}
        }
    }

    Ok(table)
}

/// Applies a `top`/`left`/`bottom`/`right` element to whichever of
/// `Table.border_color`/`TableCell.border`/`TableCell`'s margin fields it actually belongs to,
/// based on which container it was found in (`in_tbl_borders`/`in_tc_borders`/`in_tc_mar`, mutually
/// exclusive since these elements never nest inside one another) — see `parse_table`'s own doc
/// comment on its disambiguation flags for why this dispatch is needed at all. `tag_name` is the
/// raw local name (`b"top"`/`b"left"`/`b"bottom"`/ `b"right"`), used to pick the right margin field
/// when `in_tc_mar`.
#[allow(clippy::too_many_arguments)]
fn apply_table_or_cell_side(
    start: &BytesStart,
    tag_name: &[u8],
    in_tbl_borders: bool,
    in_table_properties: bool,
    in_tc_borders: bool,
    in_tc_mar: bool,
    table: &mut Table,
    current_cell: Option<&mut TableCell>,
) {
    if in_tc_mar {
        if let Some(cell) = current_cell {
            let value = raw_attribute(start, b"w").and_then(|value| value.parse::<u32>().ok());
            match tag_name {
                b"top" => cell.margin_top_twips = value,
                b"left" => cell.margin_left_twips = value,
                b"bottom" => cell.margin_bottom_twips = value,
                b"right" => cell.margin_right_twips = value,
                _ => {}
            }
        }
    } else if in_tc_borders {
        if let Some(cell) = current_cell {
            cell.border = true;
        }
    } else if in_tbl_borders && in_table_properties {
        if let Some(color) = raw_attribute(start, b"color") {
            if color != "auto" {
                table.border_color = Some(color);
            }
        }
    }
}

/// Parses a single `<w:drawing>` element, assuming its `Start` event was just consumed by the
/// caller. Reads `wp:extent` (size), `wp:docPr` (description/name) and either `a:blip`'s `r:embed`
/// (resolved to actual image bytes via [`ImageResolver::resolve`]) or `c:chart`'s `r:id` (resolved
/// to a whole `chart::ChartSpace` via [`ImageResolver::resolve_chart`],), ignoring everything else
/// (position/shape details, which we always write as a fixed rectangle anyway, for a picture).
/// Returns `None` if the drawing has neither a resolvable `a:blip` nor a resolvable `c:chart` (e.g.
/// an empty/broken reference), rather than failing the whole document. Stops at the matching
/// `</w:drawing>`.
fn parse_drawing(reader: &mut Reader<'_>, resolver: &ImageResolver) -> Result<Option<RunContent>> {
    let mut width_emu: i64 = 0;
    let mut height_emu: i64 = 0;
    let mut description = String::new();
    let mut image_relationship_id: Option<String> = None;
    let mut chart_relationship_id: Option<String> = None;
    // `pic:spPr`'s own geometry/fill/line, if any (its `a:xfrm` is never read back —
    // `width_emu`/`height_emu` from `wp:extent` above stay authoritative, matching `writer.rs`'s
    // own posture of never consulting `shape_properties.transform`).
    let mut shape_properties: Option<ShapeProperties> = None;

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            // Handled before the flatter `Start | Empty` match below since it needs the `Reader`
            // itself (to recurse via `drawing::read_shape_properties`), not just the start tag's
            // attributes.
            Event::Start(start) if start.local_name().as_ref() == b"spPr" => {
                shape_properties = Some(drawing::read_shape_properties(reader)?);
            }
            Event::Empty(start) if start.local_name().as_ref() == b"spPr" => {
                shape_properties = Some(ShapeProperties::new());
            }

            Event::Start(start) | Event::Empty(start) => match start.local_name().as_ref() {
                b"extent" => {
                    width_emu = raw_attribute(&start, b"cx")
                        .and_then(|value| value.parse().ok())
                        .unwrap_or(0);
                    height_emu = raw_attribute(&start, b"cy")
                        .and_then(|value| value.parse().ok())
                        .unwrap_or(0);
                }
                b"docPr" => description = raw_attribute(&start, b"descr").unwrap_or_default(),
                b"blip" => image_relationship_id = raw_attribute(&start, b"embed"),
                // `<c:chart r:id="..">`, a sibling possibility to `a:blip` inside the same
                // `a:graphicData` (never both at once, since `write_embedded_chart` never writes a
                // `pic:pic`/`a:blip` alongside it).
                b"chart" => chart_relationship_id = raw_attribute(&start, b"id"),
                _ => {}
            },

            Event::End(end) if end.local_name().as_ref() == b"drawing" => break,

            _ => {}
        }
    }

    if let Some(id) = image_relationship_id {
        let mut image = resolver.resolve(&id, width_emu, height_emu, description)?;
        if let Some(mut shape_properties) = shape_properties {
            // `writer.rs::write_drawing` always writes its own `<a:xfrm>` unconditionally (derived
            // from `width_emu`/`height_emu`, already captured above), regardless of what the
            // caller's own `shape_properties.transform` held (which is never consulted on write —
            // see that function's doc comment) — so whatever `drawing::read_shape_properties`
            // picked up for `transform` here is always that fixed derived value, never something
            // the caller set, and must never leak into the round-tripped value.
            shape_properties.transform = None;

            // Similarly, `write_drawing` always writes *some* geometry: `shape_properties`'s own
            // (when `Some`), or, when `None`, a fixed default `<a:prstGeom prst="rect">`. That
            // fixed default parses back as exactly `Geometry::Preset(PresetShape::Rectangle)` —
            // indistinguishable, on the wire, from a deliberately-set plain rectangle — so it's
            // normalized back to `None` here too, the same "ambiguous fixed default treated as
            // nothing set" reasoning applied to the whole-`shape_properties` case below.
            if matches!(
                shape_properties.geometry,
                Some(Geometry::Preset(PresetShape::Rectangle))
            ) {
                shape_properties.geometry = None;
            }

            // `effects` must be included in this check: an image whose only `shape_properties`
            // content is `effects` (no fill/line, geometry normalized away above) would otherwise
            // be wrongly treated as "nothing set at all" and silently discarded here, even though
            // `effects` was just correctly parsed.
            let is_fixed_default = shape_properties.geometry.is_none()
                && shape_properties.fill.is_none()
                && shape_properties.line.is_none()
                && shape_properties.effects.is_none();
            if !is_fixed_default {
                image = image.with_shape_properties(shape_properties);
            }
        }
        return Ok(Some(RunContent::Image(Box::new(image))));
    }

    if let Some(id) = chart_relationship_id {
        let chart_space = resolver.resolve_chart(&id)?;
        let chart = EmbeddedChart::new(chart_space, width_emu, height_emu).with_name(description);
        return Ok(Some(RunContent::Chart(Box::new(chart))));
    }

    Ok(None)
}

/// Reads the `w:val` attribute of a `CT_OnOff` element (e.g. `w:b`, `w:i`): absent means "on"
/// (`<w:b/>` alone means bold), otherwise the value is interpreted as an XML boolean (`true`/`1` =>
/// on, `false`/`0` => off).
fn on_off_attribute(start: &BytesStart) -> bool {
    match raw_attribute(start, b"val") {
        None => true,
        Some(value) => matches!(value.as_str(), "true" | "1" | "on"),
    }
}

/// Reads the `w:val` attribute of a `w:u` (`CT_Underline`) element into an [`UnderlineStyle`], or
/// `None` for `"none"`, an unrecognized value, or a missing `val` (schema-optional, but real-world
/// output always includes it when `w:u` is present at all — falls back to
/// [`UnderlineStyle::Single`] to match this reader's previous on/off-only behavior for such a run).
fn underline_attribute(start: &BytesStart) -> Option<UnderlineStyle> {
    match raw_attribute(start, b"val") {
        None => Some(UnderlineStyle::Single),
        Some(value) => UnderlineStyle::from_attribute_value(&value),
    }
}

/// Reads the `w:val` attribute of a `w:vMerge` (`CT_VMerge`) element into a [`VerticalMerge`]. Per
/// ECMA-376's own documented default: if `val` is omitted, the value is assumed to be `continue` —
/// unlike `underline_attribute`'s fallback (a pragmatic choice to preserve old behavior), this
/// default comes directly from the spec text for `CT_VMerge`, not from a guess. An unrecognized
/// value also falls back to `Continue`, the least surprising choice (it keeps the cell as part of
/// whatever merge is already open rather than silently ending it).
fn vertical_merge_attribute(start: &BytesStart) -> VerticalMerge {
    match raw_attribute(start, b"val").as_deref() {
        Some("restart") => VerticalMerge::Restart,
        _ => VerticalMerge::Continue,
    }
}

/// Reads the `w:val` attribute of a `w:jc` (`CT_Jc`) element and maps it to an [`Alignment`].
/// Unrecognized values (the more exotic `ST_Jc` members like `distribute`, or the
/// Strict-conformance `start`/`end` pair) are ignored rather than causing an error, since alignment
/// is a lossy, best-effort read for now.
fn alignment_from_attribute(start: &BytesStart) -> Option<Alignment> {
    match raw_attribute(start, b"val")?.as_str() {
        "left" | "start" => Some(Alignment::Left),
        "center" => Some(Alignment::Center),
        "right" | "end" => Some(Alignment::Right),
        "both" => Some(Alignment::Justify),
        _ => None,
    }
}

/// Reads the decoded, XML-entity-unescaped value of an attribute by its local (non-prefixed) name,
/// or `None` if it isn't present (or isn't valid UTF-8 — see [`xml_core::decode_attribute_value`]'s
/// doc comment).
///
/// Used for both simple keyword-only attributes (on/off flags, alignment values,
/// `ST_NumberFormat`..) where unescaping never actually matters, and genuinely free-form text
/// (hyperlink URLs, image descriptions, style names..) where it does — a URL containing a literal
/// `&` (e.g. `?a=1&b=2`, extremely common) or a description containing an apostrophe would
/// otherwise silently corrupt on a round trip, since `BytesStart:: push_attribute` escapes on
/// write. This one helper covers both cases rather than needing two.
fn raw_attribute(start: &BytesStart, name: &[u8]) -> Option<String> {
    start
        .attributes()
        .flatten()
        .find(|attribute| attribute.key.local_name().as_ref() == name)
        .and_then(|attribute| {
            xml_core::decode_attribute_value(attribute.value.as_ref())
                .ok()
                .flatten()
        })
}

/// Maps a `w:fldSimple`'s `w:instr` (`CT_SimpleField`'s instruction text) to a [`Field`], or `None`
/// if it isn't one of the two field codes this crate supports. Real Word instructions often carry
/// extra switches (e.g. `"PAGE \* MERGEFORMAT"`), so only the first whitespace-separated token is
/// matched, case-insensitively (Word treats field codes as case-insensitive). Matched as whole
/// tokens, not substrings — `"PAGE"` must not match inside `"NUMPAGES"`.
fn field_from_instruction(instr: Option<&str>) -> Option<Field> {
    let first_token = instr?.split_whitespace().next()?;
    if first_token.eq_ignore_ascii_case("PAGE") {
        Some(Field::PageNumber)
    } else if first_token.eq_ignore_ascii_case("NUMPAGES") {
        Some(Field::TotalPages)
    } else {
        None
    }
}

/// Maps a `<w:hyperlink>` start tag's attributes to a [`Hyperlink`]. `r:id` (an external
/// relationship, resolved against `resolver`'s `part_relationships`) takes priority over `w:anchor`
/// if somehow both are present — `CT_Hyperlink`'s schema allows either or both, but a real document
/// only ever sets one. Returns `None` if `r:id` is set but doesn't resolve to a declared
/// relationship (a malformed document) or if neither attribute is present at all — the hyperlink is
/// silently dropped in either case, its nested run(s) still kept as plain runs (same policy as an
/// unsupported field).
fn hyperlink_from_start(start: &BytesStart, resolver: &ImageResolver) -> Option<Hyperlink> {
    if let Some(relationship_id) = raw_attribute(start, b"id") {
        return resolver
            .part_relationships
            .by_id(&relationship_id)
            .map(|relationship| Hyperlink::External(relationship.target.clone()));
    }
    raw_attribute(start, b"anchor").map(Hyperlink::Internal)
}

/// Parses `word/styles.xml` (`CT_Styles`) into a flat list of [`Style`]s. Only `<w:style>` elements
/// whose `w:type` is `paragraph` or `character` are kept (table/numbering styles, and
/// `docDefaults`/`latentStyles`, are ignored — see `Style`'s doc comment for the full list of what
/// isn't modeled).
fn parse_styles_xml(xml: &str) -> Result<Vec<Style>> {
    let mut styles = Vec::new();
    let mut reader = Reader::from_xml_str(xml);

    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::Start(start) if start.local_name().as_ref() == b"style" => {
                if let Some(style) = parse_style(&mut reader, &start)? {
                    styles.push(style);
                }
            }
            _ => {}
        }
    }

    Ok(styles)
}

/// Parses a single `<w:style>` element, assuming its `Start` event was just consumed by the caller
/// (`start` is that same event, kept around to read its `w:type`/`w:styleId` attributes). Reads
/// `w:name`, `w:basedOn`, and — from `w:pPr`/`w:rPr` — alignment, bold/italic/underline, color,
/// font size, font family and highlight, stopping at the matching `</w:style>`. Returns `None` if
/// `w:type` isn't `paragraph` or `character` (the only two [`StyleKind`]s modeled).
fn parse_style(reader: &mut Reader<'_>, start: &BytesStart) -> Result<Option<Style>> {
    let kind = match raw_attribute(start, b"type").as_deref() {
        Some("paragraph") => StyleKind::Paragraph,
        Some("character") => StyleKind::Character,
        _ => {
            skip_to_end(reader, b"style")?;
            return Ok(None);
        }
    };
    let id = raw_attribute(start, b"styleId").unwrap_or_default();

    let mut name = String::new();
    let mut based_on: Option<String> = None;
    let mut alignment: Option<Alignment> = None;
    let mut bold = false;
    let mut italic = false;
    let mut underline: Option<UnderlineStyle> = None;
    let mut underline_color: Option<String> = None;
    let mut color: Option<String> = None;
    let mut font_size: Option<u16> = None;
    let mut font_family: Option<String> = None;
    let mut highlight: Option<Highlight> = None;
    let mut strike = false;
    let mut vertical_align: Option<VerticalAlign> = None;
    let mut small_caps = false;
    let mut all_caps = false;
    let mut shading_color: Option<String> = None;
    let mut text_border = false;
    let mut character_spacing: Option<i16> = None;
    let mut vertical_position: Option<i16> = None;
    let mut hidden = false;
    let mut line_spacing: Option<u32> = None;
    let mut space_before: Option<u32> = None;
    let mut space_after: Option<u32> = None;
    let mut paragraph_shading_color: Option<String> = None;
    let mut paragraph_border = false;
    let mut keep_with_next = false;
    let mut keep_lines_together = false;
    let mut page_break_before = false;
    let mut tabs: Vec<TabStop> = Vec::new();
    let mut contextual_spacing = false;
    // Whether the loop is currently inside `<w:pPr>` rather than `<w:rPr>` — both are direct
    // children of `<w:style>`, `w:pPr` always fully consumed before `w:rPr` starts (`CT_Style`'s
    // own sequence), mirroring `parse_paragraph`'s `in_run` flag and needed for the same reason:
    // `w:shd`/`w:spacing` are shared element names with different meanings depending on which one
    // they're nested in. Flipped back to `false` at `w:rPr`'s own start (no need to watch for
    // `w:pPr`'s end specifically, since `w:rPr` never appears before it).
    let mut in_paragraph_properties = false;

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) | Event::Empty(start) => match start.local_name().as_ref() {
                b"name" => name = raw_attribute(&start, b"val").unwrap_or_default(),
                b"basedOn" => based_on = raw_attribute(&start, b"val"),
                b"pPr" => in_paragraph_properties = true,
                b"rPr" => in_paragraph_properties = false,
                b"pBdr" => paragraph_border = true,
                b"keepNext" => keep_with_next = true,
                b"keepLines" => keep_lines_together = true,
                b"pageBreakBefore" => page_break_before = true,
                b"contextualSpacing" => contextual_spacing = true,
                b"tab" => {
                    if let Some(position) =
                        raw_attribute(&start, b"pos").and_then(|value| value.parse::<i32>().ok())
                    {
                        let mut tab = TabStop::new(position);
                        if let Some(alignment) = raw_attribute(&start, b"val")
                            .and_then(|value| TabStopAlignment::from_attribute_value(&value))
                        {
                            tab = tab.with_alignment(alignment);
                        }
                        if let Some(leader) = raw_attribute(&start, b"leader")
                            .and_then(|value| TabLeader::from_attribute_value(&value))
                        {
                            tab = tab.with_leader(leader);
                        }
                        tabs.push(tab);
                    }
                }
                b"jc" => alignment = alignment_from_attribute(&start),
                b"b" => bold = on_off_attribute(&start),
                b"i" => italic = on_off_attribute(&start),
                b"u" => {
                    underline = underline_attribute(&start);
                    underline_color = raw_attribute(&start, b"color");
                }
                b"color" => color = raw_attribute(&start, b"val"),
                b"sz" => {
                    font_size = raw_attribute(&start, b"val")
                        .and_then(|value| value.parse::<u16>().ok())
                        .map(|half_points| half_points / 2)
                }
                b"rFonts" => {
                    font_family =
                        raw_attribute(&start, b"ascii").or_else(|| raw_attribute(&start, b"hAnsi"))
                }
                b"highlight" => {
                    highlight = raw_attribute(&start, b"val")
                        .and_then(|value| Highlight::from_attribute_value(&value))
                }
                b"strike" => strike = on_off_attribute(&start),
                b"vertAlign" => {
                    vertical_align = raw_attribute(&start, b"val")
                        .and_then(|value| VerticalAlign::from_attribute_value(&value))
                }
                b"smallCaps" => small_caps = on_off_attribute(&start),
                b"caps" => all_caps = on_off_attribute(&start),
                b"shd" => {
                    if in_paragraph_properties {
                        paragraph_shading_color = raw_attribute(&start, b"fill");
                    } else {
                        shading_color = raw_attribute(&start, b"fill");
                    }
                }
                b"bdr" => text_border = true,
                b"spacing" => {
                    if in_paragraph_properties {
                        space_before = raw_attribute(&start, b"before")
                            .and_then(|value| value.parse::<u32>().ok());
                        space_after = raw_attribute(&start, b"after")
                            .and_then(|value| value.parse::<u32>().ok());
                        line_spacing = raw_attribute(&start, b"line")
                            .and_then(|value| value.parse::<u32>().ok());
                    } else {
                        character_spacing = raw_attribute(&start, b"val")
                            .and_then(|value| value.parse::<i16>().ok());
                    }
                }
                b"position" => {
                    vertical_position =
                        raw_attribute(&start, b"val").and_then(|value| value.parse::<i16>().ok())
                }
                b"vanish" => hidden = true,
                _ => {}
            },

            Event::End(end) if end.local_name().as_ref() == b"style" => break,

            _ => {}
        }
    }

    let mut style = Style::new(id, name, kind)
        .with_bold(bold)
        .with_italic(italic);
    if let Some(underline) = underline {
        style = style.with_underline(underline);
    }
    if let Some(underline_color) = underline_color {
        style = style.with_underline_color(underline_color);
    }
    if let Some(based_on) = based_on {
        style = style.with_based_on(based_on);
    }
    if let Some(alignment) = alignment {
        style = style.with_alignment(alignment);
    }
    if let Some(color) = color {
        style = style.with_color(color);
    }
    if let Some(font_size) = font_size {
        style = style.with_font_size(font_size);
    }
    if let Some(font_family) = font_family {
        style = style.with_font_family(font_family);
    }
    if let Some(highlight) = highlight {
        style = style.with_highlight(highlight);
    }
    style = style.with_strike(strike);
    if let Some(vertical_align) = vertical_align {
        style = style.with_vertical_align(vertical_align);
    }
    style = style
        .with_small_caps(small_caps)
        .with_all_caps(all_caps)
        .with_text_border(text_border)
        .with_hidden(hidden);
    if let Some(shading_color) = shading_color {
        style = style.with_shading_color(shading_color);
    }
    if let Some(character_spacing) = character_spacing {
        style = style.with_character_spacing(character_spacing);
    }
    if let Some(vertical_position) = vertical_position {
        style = style.with_vertical_position(vertical_position);
    }
    style = style.with_paragraph_border(paragraph_border);
    if let Some(paragraph_shading_color) = paragraph_shading_color {
        style = style.with_paragraph_shading_color(paragraph_shading_color);
    }
    if let Some(line_spacing) = line_spacing {
        style = style.with_line_spacing(line_spacing);
    }
    if let Some(space_before) = space_before {
        style = style.with_space_before(space_before);
    }
    if let Some(space_after) = space_after {
        style = style.with_space_after(space_after);
    }
    style = style
        .with_keep_with_next(keep_with_next)
        .with_keep_lines_together(keep_lines_together)
        .with_page_break_before(page_break_before)
        .with_contextual_spacing(contextual_spacing);
    for tab in tabs {
        style = style.with_tab(tab);
    }

    Ok(Some(style))
}

/// Consumes events up to and including the matching end tag for an already-open element named
/// `local_name`, without interpreting any of its content — used by `parse_style` to skip over a
/// `<w:style>` whose `w:type` isn't one we model (e.g. `table`, `numbering`).
fn skip_to_end(reader: &mut Reader<'_>, local_name: &[u8]) -> Result<()> {
    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::End(end) if end.local_name().as_ref() == local_name => break,
            _ => {}
        }
    }
    Ok(())
}

/// Parses `word/numbering.xml` (`CT_Numbering`) into a flat list of [`NumberingDefinition`]s, one
/// per `<w:num>` element (see `NumberingDefinition`'s doc comment for why `w:abstractNum` isn't
/// modeled as its own separate type). `CT_Numbering`'s own sequence (`numPicBullet*, abstractNum*,
/// num*`) guarantees every `w:abstractNum` is read before any `w:num` that might reference it, so
/// this is a single forward pass: abstractNums are collected into `abstract_nums` (keyed by
/// `abstractNumId`) as they're read, then each `w:num` is resolved against that map immediately. A
/// `w:num` with no (or an unparsable) `numId`, or referencing an `abstractNumId` that wasn't
/// declared (either way, a malformed document), is skipped/given an empty `levels` list rather than
/// failing the whole document — same policy as elsewhere in this reader.
fn parse_numbering_xml(xml: &str) -> Result<Vec<NumberingDefinition>> {
    let mut abstract_nums: HashMap<u32, Vec<ListLevel>> = HashMap::new();
    let mut definitions = Vec::new();
    let mut reader = Reader::from_xml_str(xml);

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"abstractNum" => match raw_attribute(&start, b"abstractNumId")
                    .and_then(|value| value.parse().ok())
                {
                    Some(id) => {
                        let levels = parse_abstract_num(&mut reader)?;
                        abstract_nums.insert(id, levels);
                    }
                    None => skip_to_end(&mut reader, b"abstractNum")?,
                },
                b"num" => {
                    match raw_attribute(&start, b"numId").and_then(|value| value.parse().ok()) {
                        Some(num_id) => {
                            let abstract_num_id = parse_num_abstract_ref(&mut reader)?;
                            let levels = abstract_num_id
                                .and_then(|id| abstract_nums.get(&id).cloned())
                                .unwrap_or_default();
                            definitions.push(NumberingDefinition::new(num_id, levels));
                        }
                        None => skip_to_end(&mut reader, b"num")?,
                    }
                }
                _ => {}
            },

            _ => {}
        }
    }

    Ok(definitions)
}

/// Parses a single `<w:abstractNum>` element's `<w:lvl>` children into [`ListLevel`]s, assuming its
/// `Start` event was just consumed by the caller. Levels are pushed in the order encountered — real
/// documents (and this crate's own writer) always write them in ascending `ilvl` order with no
/// gaps, so the resulting `Vec`'s index matches `ilvl` without needing to read that attribute at
/// all. Stops at the matching `</w:abstractNum>`.
fn parse_abstract_num(reader: &mut Reader<'_>) -> Result<Vec<ListLevel>> {
    let mut levels = Vec::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::Start(start) if start.local_name().as_ref() == b"lvl" => {
                levels.push(parse_lvl(reader)?)
            }
            Event::End(end) if end.local_name().as_ref() == b"abstractNum" => break,
            _ => {}
        }
    }

    Ok(levels)
}

/// Parses a single `<w:lvl>` element, assuming its `Start` event was just consumed by the caller.
/// Reads `w:numFmt`, `w:lvlText` and — from the nested `w:pPr/w:ind` — the level's indentation,
/// ignoring everything else (`start`, `lvlJc`, `pStyle`, `rPr`. — see [`ListLevel`]'s doc comment
/// for the full list of what isn't modeled). Stops at the matching `</w:lvl>`.
fn parse_lvl(reader: &mut Reader<'_>) -> Result<ListLevel> {
    let mut format = NumberFormat::Decimal;
    let mut text = String::new();
    let mut indent_twips: i32 = 0;
    let mut hanging_twips: i32 = 0;

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) | Event::Empty(start) => match start.local_name().as_ref() {
                b"numFmt" => {
                    format = number_format_from_attribute(&start).unwrap_or(NumberFormat::Decimal)
                }
                b"lvlText" => text = raw_attribute(&start, b"val").unwrap_or_default(),
                b"ind" => {
                    indent_twips = raw_attribute(&start, b"left")
                        .and_then(|value| value.parse().ok())
                        .unwrap_or(0);
                    hanging_twips = raw_attribute(&start, b"hanging")
                        .and_then(|value| value.parse().ok())
                        .unwrap_or(0);
                }
                _ => {}
            },

            Event::End(end) if end.local_name().as_ref() == b"lvl" => break,

            _ => {}
        }
    }

    Ok(ListLevel::new(format, text, indent_twips, hanging_twips))
}

/// Parses a single `<w:num>` element's `<w:abstractNumId>` child (the only one this reader cares
/// about — `lvlOverride` isn't modeled), assuming the `<w:num>` `Start` event was just consumed by
/// the caller. Stops at the matching `</w:num>`.
fn parse_num_abstract_ref(reader: &mut Reader<'_>) -> Result<Option<u32>> {
    let mut abstract_num_id = None;

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) | Event::Empty(start)
                if start.local_name().as_ref() == b"abstractNumId" =>
            {
                abstract_num_id =
                    raw_attribute(&start, b"val").and_then(|value| value.parse().ok());
            }

            Event::End(end) if end.local_name().as_ref() == b"num" => break,

            _ => {}
        }
    }

    Ok(abstract_num_id)
}

/// Maps a `w:numFmt`'s `w:val` (`ST_NumberFormat`) to a [`NumberFormat`], or `None` if it isn't one
/// of the handful this crate models (see [`NumberFormat`]'s doc comment).
fn number_format_from_attribute(start: &BytesStart) -> Option<NumberFormat> {
    match raw_attribute(start, b"val")?.as_str() {
        "bullet" => Some(NumberFormat::Bullet),
        "decimal" => Some(NumberFormat::Decimal),
        "lowerLetter" => Some(NumberFormat::LowerLetter),
        "upperLetter" => Some(NumberFormat::UpperLetter),
        "lowerRoman" => Some(NumberFormat::LowerRoman),
        "upperRoman" => Some(NumberFormat::UpperRoman),
        _ => None,
    }
}

/// Parses `word/footnotes.xml`/`word/endnotes.xml` (`CT_Footnotes`/ `CT_Endnotes`) into a flat list
/// of [`Note`]s, one per `<w:footnote>`/ `<w:endnote>` element (`note_element_name` is
/// `b"footnote"`/ `b"endnote"`).
///
/// Notes of type `"separator"`/`"continuationSeparator"`/ `"continuationNotice"` — the boilerplate
/// entries real Word documents also carry — are skipped rather than exposed as a [`Note`]; see
/// [`Note`]'s doc comment for why. A note with no (or an unparsable) `id` is skipped too (a
/// malformed document), same policy as an unresolvable `w:num` in `parse_numbering_xml`.
fn parse_notes_xml(
    xml: &str,
    resolver: &ImageResolver,
    note_element_name: &[u8],
) -> Result<Vec<Note>> {
    let mut notes = Vec::new();
    let mut reader = Reader::from_xml_str(xml);

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) if start.local_name().as_ref() == note_element_name => {
                let is_special_note = matches!(
                    raw_attribute(&start, b"type").as_deref(),
                    Some("separator" | "continuationSeparator" | "continuationNotice")
                );
                let id = raw_attribute(&start, b"id").and_then(|value| value.parse().ok());

                match (is_special_note, id) {
                    (false, Some(id)) => {
                        let blocks = parse_note_blocks(&mut reader, resolver, note_element_name)?;
                        notes.push(Note { id, blocks });
                    }
                    _ => skip_to_end(&mut reader, note_element_name)?,
                }
            }

            _ => {}
        }
    }

    Ok(notes)
}

/// Parses a single note's/comment's/structured-document-tag's block-level content (`CT_FtnEdn`,
/// `CT_Comment` and `CT_SdtContentBlock` all reuse `EG_BlockLevelElts`/`EG_ContentBlockContent`,
/// the same group `w:body`/[`HeaderFooter`] use), assuming the `<w:footnote>`/
/// `<w:endnote>`/`<w:comment>`/`<w:sdtContent>` `Start` event was just consumed by the caller.
/// Stops at the matching end tag (`stop_local_name`,
/// `b"footnote"`/`b"endnote"`/`b"comment"`/`b"sdtContent"`) — shared verbatim by
/// [`parse_notes_xml`], [`parse_comments_xml`] and [`parse_structured_document_tag`], since none of
/// them actually care whether the surrounding element is a note, a comment or a content control.
/// Handles `w:sdt` itself too, so a nested structured document tag (inside a note, a comment, or
/// another structured document tag) round- trips correctly through the same mutual recursion with
/// [`parse_structured_document_tag`].
fn parse_note_blocks(
    reader: &mut Reader<'_>,
    resolver: &ImageResolver,
    stop_local_name: &[u8],
) -> Result<Vec<Block>> {
    let mut blocks = Vec::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"p" => blocks.push(Block::Paragraph(parse_paragraph(reader, resolver)?)),
                b"tbl" => blocks.push(Block::Table(parse_table(reader, resolver)?)),
                b"sdt" => blocks.push(Block::StructuredDocumentTag(parse_structured_document_tag(
                    reader, resolver,
                )?)),
                _ => {}
            },

            Event::Empty(start) => match start.local_name().as_ref() {
                b"p" => blocks.push(Block::Paragraph(Paragraph::new())),
                b"sdt" => blocks.push(Block::StructuredDocumentTag(StructuredDocumentTag::new())),
                _ => {}
            },

            Event::End(end) if end.local_name().as_ref() == stop_local_name => break,

            _ => {}
        }
    }

    Ok(blocks)
}

/// Parses a single `<w:sdt>` structured document tag / content control (`CT_SdtBlock`), assuming
/// its `Start` event was just consumed by the caller. Reads `w:sdtPr`'s `id`/`tag`/`alias` via
/// [`parse_sdt_properties`] (everything else — `w:lock`, `w:placeholder`, `w:showingPlcHdr`,
/// `w:dataBinding`, `w:temporary`, and the dozen-plus type indicators
/// `w:richText`/`w:text`/`w:date`/. — is silently skipped, see [`StructuredDocumentTag`]'s doc
/// comment for why) and `w:sdtContent`'s block-level content (delegated to [`parse_note_blocks`],
/// which handles `w:sdt` itself too — so a nested content control round-trips correctly). Stops at
/// the matching `</w:sdt>`.
fn parse_structured_document_tag(
    reader: &mut Reader<'_>,
    resolver: &ImageResolver,
) -> Result<StructuredDocumentTag> {
    let mut sdt = StructuredDocumentTag::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"sdtPr" => parse_sdt_properties(reader, &mut sdt)?,
                b"sdtContent" => sdt.blocks = parse_note_blocks(reader, resolver, b"sdtContent")?,
                _ => {}
            },

            Event::End(end) if end.local_name().as_ref() == b"sdt" => break,

            _ => {}
        }
    }

    Ok(sdt)
}

/// Parses `w:sdtPr`'s `id`/`tag`/`alias` children into `sdt`, assuming its `Start` event was just
/// consumed by the caller. `CT_SdtPr` is an unbounded `choice` (every child optional, no fixed
/// order), so this just accumulates whichever of the three it recognizes — via their always-
/// self-closing `<w:../w:val="..">` shape, `CT_DecimalNumber`/`CT_String` having no content model
/// of their own — and silently ignores everything else (`w:lock`, `w:placeholder`, the
/// type-indicator choice..). Stops at the matching `</w:sdtPr>`.
fn parse_sdt_properties(reader: &mut Reader<'_>, sdt: &mut StructuredDocumentTag) -> Result<()> {
    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Empty(start) => match start.local_name().as_ref() {
                b"id" => {
                    sdt.id = raw_attribute(&start, b"val").and_then(|value| value.parse().ok())
                }
                b"tag" => sdt.tag = raw_attribute(&start, b"val"),
                b"alias" => sdt.alias = raw_attribute(&start, b"val"),
                _ => {}
            },

            Event::End(end) if end.local_name().as_ref() == b"sdtPr" => break,

            _ => {}
        }
    }

    Ok(())
}

/// Parses `word/comments.xml` (`CT_Comments`) into a flat list of [`Comment`]s, one per
/// `<w:comment>` element — structurally close to [`parse_notes_xml`] (both share
/// [`parse_note_blocks`] for their content), but with `w:comment`'s extra
/// `author`/`date`/`initials` attributes and no special/boilerplate variant to filter out (unlike
/// footnotes/endnotes, real Word documents don't carry a "separator" comment). A comment with no
/// (or an unparsable) `id` is skipped, same policy as an unresolvable note.
fn parse_comments_xml(xml: &str, resolver: &ImageResolver) -> Result<Vec<Comment>> {
    let mut comments = Vec::new();
    let mut reader = Reader::from_xml_str(xml);

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) if start.local_name().as_ref() == b"comment" => {
                match raw_attribute(&start, b"id").and_then(|value| value.parse().ok()) {
                    Some(id) => {
                        let author = raw_attribute(&start, b"author");
                        let initials = raw_attribute(&start, b"initials");
                        let date = raw_attribute(&start, b"date");
                        let blocks = parse_note_blocks(&mut reader, resolver, b"comment")?;
                        comments.push(Comment {
                            id,
                            author,
                            initials,
                            date,
                            blocks,
                        });
                    }
                    None => skip_to_end(&mut reader, b"comment")?,
                }
            }

            _ => {}
        }
    }

    Ok(comments)
}

/// Parses `word/theme/theme1.xml` (`<a:theme>`, `CT_OfficeStyleSheet`) into a [`Theme`]: the root's
/// `name` attribute, `<a:clrScheme>` and `<a:fontScheme>`. `<a:fmtScheme>` and any
/// `objectDefaults`/ `extraClrSchemeLst` are never matched by this flat scan, so they're skipped
/// without being interpreted — whether reading this crate's own fixed output or a real,
/// externally-authored theme with a genuinely different `fmtScheme` (see [`Theme`]'s doc comment).
fn parse_theme_xml(xml: &str) -> Result<Theme> {
    let mut reader = Reader::from_xml_str(xml);
    let mut name = String::new();
    let mut colors = ColorScheme::office_default();
    let mut fonts = FontScheme::office_default();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => match start.local_name().as_ref() {
                b"theme" => {
                    if let Some(value) = raw_attribute(&start, b"name") {
                        name = value;
                    }
                }
                b"clrScheme" => colors = parse_color_scheme(&mut reader)?,
                b"fontScheme" => fonts = parse_font_scheme(&mut reader)?,
                _ => {}
            },

            _ => {}
        }
    }

    Ok(Theme {
        name,
        colors,
        fonts,
    })
}

/// Parses `word/settings.xml`'s `<w:trackRevisions>` and `<w:documentProtection>` (`CT_Settings`)
/// into `(track_changes, protection)`, feeding [`Document::track_changes`]/[`Document::protection`]
/// — the only two settings this crate reads back from that part (everything else `write_to` may
/// write there, currently just `w:evenAndOddHeaders`, is instead re-derived from `document.xml`
/// itself on read, via `header_even`/`footer_even` being `Some`; see `SETTINGS_RELATIONSHIP_TYPE`'s
/// doc comment for why `w:trackRevisions`/ `w:documentProtection` have no such alternate signal and
/// genuinely need this part read). `<w:trackRevisions w:val="false"/>` (an explicit,
/// present-but-off form, distinct from the element being entirely absent) is treated the same as
/// absence — `on_off_attribute` already gives that same forgiving,
/// attribute-defaults-to-true-when-omitted behavior used everywhere else in this reader.
/// `w:documentProtection`'s `w:edit` value is parsed via [`ProtectionKind::from_attribute_value`],
/// which already returns `None` for `"none"` or any unrecognized value — a password-protected
/// `w:documentProtection` (extra `w:cryptProviderType`/ hash/salt attributes) still parses its
/// `w:edit` value the same way, those extra attributes are just ignored (this crate never writes
/// them, see `Document.protection`'s doc comment).
fn parse_settings_xml(xml: &str) -> Result<(bool, Option<ProtectionKind>)> {
    let mut reader = Reader::from_xml_str(xml);
    let mut track_changes = false;
    let mut protection = None;

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) | Event::Empty(start) => match start.local_name().as_ref() {
                b"trackRevisions" => track_changes = on_off_attribute(&start),
                b"documentProtection" => {
                    protection = raw_attribute(&start, b"edit")
                        .and_then(|value| ProtectionKind::from_attribute_value(&value));
                }
                _ => {}
            },

            _ => {}
        }
    }

    Ok((track_changes, protection))
}

/// Parses `docProps/core.xml` (`CT_CoreProperties`) into a [`DocumentProperties`]. Every child of
/// `CT_CoreProperties` this crate models (`dc:title`/`dc:subject`/`dc:creator`/`cp:keywords`/
/// `dc:description`/`cp:lastModifiedBy`/`cp:revision`/`dcterms:created`/
/// `dcterms:modified`/`cp:category`/`cp:contentStatus`) is a simple leaf text element with no
/// children of its own, so unlike `parse_paragraph`'s `in_run`-style disambiguation, no nesting
/// tracking is needed here: once a tracked element's `Start` is seen, every `Text`/`GeneralRef`
/// event up to its own matching `End` belongs to it. Text is decoded the same way run text is
/// (`xml_core::decode_text`/`decode_general_ref`), so an author name or title containing
/// `&`/`<`/`>` round-trips correctly — the same class of bug this project has already been bitten
/// by once for run text (see the CHANGELOG). Any other child (`dc:identifier`, `dc:language`,
/// `cp:lastPrinted`, `cp:version`..) is silently ignored, matching this reader's usual forgiving
/// policy for unmodeled elements. `xsi:type` on `dcterms:created`/`dcterms:modified` is not
/// inspected — the raw text is taken as-is regardless (see `DocumentProperties`'s doc comment on
/// why dates are plain strings, not validated).
fn parse_core_properties_xml(xml: &str) -> Result<DocumentProperties> {
    let mut reader = Reader::from_xml_str(xml);
    let mut properties = DocumentProperties::new();
    let mut current_element: Option<Vec<u8>> = None;
    let mut buffer = String::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => {
                let local_name = start.local_name().as_ref().to_vec();
                if is_tracked_core_property_element(&local_name) {
                    current_element = Some(local_name);
                    buffer.clear();
                }
            }

            Event::Text(text) if current_element.is_some() => {
                buffer.push_str(&xml_core::decode_text(&text)?);
            }

            Event::GeneralRef(reference) if current_element.is_some() => {
                if let Some(resolved) = xml_core::decode_general_ref(&reference)? {
                    buffer.push_str(&resolved);
                }
            }

            Event::End(end) => {
                if let Some(name) = current_element.take() {
                    if end.local_name().as_ref() == name.as_slice() {
                        apply_core_property(&mut properties, &name, std::mem::take(&mut buffer));
                    } else {
                        // Shouldn't happen for a well-formed leaf element, but keep tracking
                        // defensively rather than losing the buffer silently.
                        current_element = Some(name);
                    }
                }
            }

            _ => {}
        }
    }

    Ok(properties)
}

/// Whether `local_name` is one of the `CT_CoreProperties` children this crate models — see
/// `parse_core_properties_xml`'s doc comment.
fn is_tracked_core_property_element(local_name: &[u8]) -> bool {
    matches!(
        local_name,
        b"title"
            | b"subject"
            | b"creator"
            | b"keywords"
            | b"description"
            | b"lastModifiedBy"
            | b"revision"
            | b"created"
            | b"modified"
            | b"category"
            | b"contentStatus"
    )
}

/// Assigns `value` to `properties`' field matching `local_name` — the inverse of
/// `to_core_properties_xml`'s element-name choices in `writer.rs`.
fn apply_core_property(properties: &mut DocumentProperties, local_name: &[u8], value: String) {
    match local_name {
        b"title" => properties.title = Some(value),
        b"subject" => properties.subject = Some(value),
        b"creator" => properties.creator = Some(value),
        b"keywords" => properties.keywords = Some(value),
        b"description" => properties.description = Some(value),
        b"lastModifiedBy" => properties.last_modified_by = Some(value),
        b"revision" => properties.revision = Some(value),
        b"created" => properties.created = Some(value),
        b"modified" => properties.modified = Some(value),
        b"category" => properties.category = Some(value),
        b"contentStatus" => properties.content_status = Some(value),
        _ => {}
    }
}

/// Parses `docProps/app.xml` (extended properties) into an [`ExtendedProperties`], keeping only
/// `Company`/`Manager` — the same leaf-text-tracking approach as `parse_core_properties_xml`, just
/// with a smaller tracked-element set (`Application` and the many statistics fields — see
/// [`ExtendedProperties`]'s doc comment — are silently ignored, matching this reader's usual
/// forgiving policy for unmodeled elements).
fn parse_extended_properties_xml(xml: &str) -> Result<ExtendedProperties> {
    let mut reader = Reader::from_xml_str(xml);
    let mut properties = ExtendedProperties::new();
    let mut current_element: Option<Vec<u8>> = None;
    let mut buffer = String::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) => {
                let local_name = start.local_name().as_ref().to_vec();
                if local_name == b"Company" || local_name == b"Manager" {
                    current_element = Some(local_name);
                    buffer.clear();
                }
            }

            Event::Text(text) if current_element.is_some() => {
                buffer.push_str(&xml_core::decode_text(&text)?);
            }

            Event::GeneralRef(reference) if current_element.is_some() => {
                if let Some(resolved) = xml_core::decode_general_ref(&reference)? {
                    buffer.push_str(&resolved);
                }
            }

            Event::End(end) => {
                if let Some(name) = current_element.take() {
                    if end.local_name().as_ref() == name.as_slice() {
                        let value = std::mem::take(&mut buffer);
                        match name.as_slice() {
                            b"Company" => properties.company = Some(value),
                            b"Manager" => properties.manager = Some(value),
                            _ => {}
                        }
                    } else {
                        current_element = Some(name);
                    }
                }
            }

            _ => {}
        }
    }

    Ok(properties)
}

/// Parses `docProps/custom.xml` (custom properties) into a `Vec` of `(name, value)` pairs,
/// preserving the file's own `<property>` order (not re-sorted by `pid`, though a well-formed file
/// this crate produced already has them in ascending `pid` order). Each `<property name="..">`
/// element's single variant-type child (`vt:lpwstr`/`vt:bool`/`vt:i4`/ `vt:r8` — see
/// [`CustomPropertyValue`]'s doc comment for which types are modeled) is decoded by its own local
/// name; a property whose variant type isn't one of these four, or that has no `name` attribute, is
/// silently skipped, matching this reader's usual forgiving policy. `fmtid`/`pid` are not validated
/// against `CUSTOM_PROPERTY_FMTID`/a specific sequence — same best-effort posture as elsewhere in
/// this crate.
fn parse_custom_properties_xml(xml: &str) -> Result<Vec<(String, CustomPropertyValue)>> {
    let mut reader = Reader::from_xml_str(xml);
    let mut custom_properties = Vec::new();
    let mut current_name: Option<String> = None;
    let mut current_variant: Option<Vec<u8>> = None;
    let mut buffer = String::new();

    loop {
        match reader.read_event()? {
            Event::Eof => break,

            Event::Start(start) if start.local_name().as_ref() == b"property" => {
                current_name = raw_attribute(&start, b"name");
            }

            Event::Start(start) | Event::Empty(start)
                if current_name.is_some()
                    && matches!(
                        start.local_name().as_ref(),
                        b"lpwstr" | b"bool" | b"i4" | b"r8"
                    ) =>
            {
                current_variant = Some(start.local_name().as_ref().to_vec());
                buffer.clear();
            }

            Event::Text(text) if current_variant.is_some() => {
                buffer.push_str(&xml_core::decode_text(&text)?);
            }

            Event::GeneralRef(reference) if current_variant.is_some() => {
                if let Some(resolved) = xml_core::decode_general_ref(&reference)? {
                    buffer.push_str(&resolved);
                }
            }

            Event::End(end) => {
                if let Some(variant) = current_variant.take() {
                    if end.local_name().as_ref() == variant.as_slice() {
                        if let Some(name) = current_name.clone() {
                            let value = std::mem::take(&mut buffer);
                            let parsed = match variant.as_slice() {
                                b"lpwstr" => Some(CustomPropertyValue::Text(value)),
                                b"bool" => {
                                    Some(CustomPropertyValue::Bool(value == "true" || value == "1"))
                                }
                                b"i4" => value.parse::<i32>().ok().map(CustomPropertyValue::Int),
                                b"r8" => value.parse::<f64>().ok().map(CustomPropertyValue::Number),
                                _ => None,
                            };
                            if let Some(value) = parsed {
                                custom_properties.push((name, value));
                            }
                        }
                    } else {
                        current_variant = Some(variant);
                    }
                } else if end.local_name().as_ref() == b"property" {
                    current_name = None;
                }
            }

            _ => {}
        }
    }

    Ok(custom_properties)
}

/// Parses `<a:clrScheme>`'s 12 fixed-order color slots, assuming its `Start` event was just
/// consumed by the caller. Stops at the matching `</a:clrScheme>`. Any slot this crate doesn't
/// model (there are none in the standard 12, but a malformed/future document could carry an
/// `extLst`) is silently ignored, same policy as elsewhere in this reader.
fn parse_color_scheme(reader: &mut Reader<'_>) -> Result<ColorScheme> {
    let mut colors = ColorScheme::office_default();

    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::End(end) if end.local_name().as_ref() == b"clrScheme" => break,

            Event::Start(start) => {
                let slot = start.local_name().as_ref().to_vec();
                if let Some(value) = read_color_slot_value(reader, &slot)? {
                    assign_color_slot(&mut colors, &slot, value);
                }
            }

            _ => {}
        }
    }

    Ok(colors)
}

/// Reads a single color slot's value (`<a:dk1>`, `<a:accent1>`..): its one child, either
/// `<a:srgbClr val="..">` (used directly) or `<a:sysClr val=".." lastClr="..">` (its `lastClr`
/// fallback RGB is used instead — see [`ColorScheme`]'s doc comment for why the live system-color
/// binding itself isn't preserved). Consumes up to and including the matching end tag for
/// `wrapper_local_name`.
fn read_color_slot_value(
    reader: &mut Reader<'_>,
    wrapper_local_name: &[u8],
) -> Result<Option<String>> {
    let mut value = None;

    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::End(end) if end.local_name().as_ref() == wrapper_local_name => break,

            Event::Empty(start) | Event::Start(start) => match start.local_name().as_ref() {
                b"srgbClr" => value = raw_attribute(&start, b"val"),
                b"sysClr" => {
                    value =
                        raw_attribute(&start, b"lastClr").or_else(|| raw_attribute(&start, b"val"))
                }
                _ => {}
            },

            _ => {}
        }
    }

    Ok(value)
}

/// Assigns a parsed color value to the matching field of `colors`, by its `<a:clrScheme>` child
/// element name (`dk1`/`lt1`/`dk2`/`lt2`/ `accent1`-`accent6`/`hlink`/`folHlink`). Any other name
/// is ignored.
fn assign_color_slot(colors: &mut ColorScheme, slot: &[u8], value: String) {
    match slot {
        b"dk1" => colors.dark1 = value,
        b"lt1" => colors.light1 = value,
        b"dk2" => colors.dark2 = value,
        b"lt2" => colors.light2 = value,
        b"accent1" => colors.accent1 = value,
        b"accent2" => colors.accent2 = value,
        b"accent3" => colors.accent3 = value,
        b"accent4" => colors.accent4 = value,
        b"accent5" => colors.accent5 = value,
        b"accent6" => colors.accent6 = value,
        b"hlink" => colors.hyperlink = value,
        b"folHlink" => colors.followed_hyperlink = value,
        _ => {}
    }
}

/// Parses `<a:fontScheme>`'s `majorFont`/`minorFont`, assuming its `Start` event was just consumed
/// by the caller. Stops at the matching `</a:fontScheme>`. Only each font collection's `<a:latin>`
/// typeface is captured — see [`FontScheme`]'s doc comment for why `ea`/`cs`/per-script fallbacks
/// are ignored.
fn parse_font_scheme(reader: &mut Reader<'_>) -> Result<FontScheme> {
    let mut fonts = FontScheme::office_default();

    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::End(end) if end.local_name().as_ref() == b"fontScheme" => break,

            Event::Start(start) if start.local_name().as_ref() == b"majorFont" => {
                if let Some(typeface) = parse_font_collection_latin(reader, b"majorFont")? {
                    fonts.major_latin = typeface;
                }
            }
            Event::Start(start) if start.local_name().as_ref() == b"minorFont" => {
                if let Some(typeface) = parse_font_collection_latin(reader, b"minorFont")? {
                    fonts.minor_latin = typeface;
                }
            }

            _ => {}
        }
    }

    Ok(fonts)
}

/// Reads a `<a:majorFont>`/`<a:minorFont>` font collection's `<a:latin>` typeface, ignoring
/// `ea`/`cs`/per-script fallback children. Consumes up to and including the matching end tag for
/// `wrapper_local_name`.
fn parse_font_collection_latin(
    reader: &mut Reader<'_>,
    wrapper_local_name: &[u8],
) -> Result<Option<String>> {
    let mut typeface = None;

    loop {
        match reader.read_event()? {
            Event::Eof => break,
            Event::End(end) if end.local_name().as_ref() == wrapper_local_name => break,

            Event::Empty(start) | Event::Start(start)
                if start.local_name().as_ref() == b"latin" =>
            {
                typeface = raw_attribute(&start, b"typeface");
            }

            _ => {}
        }
    }

    Ok(typeface)
}

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

    /// Parses `xml` against an empty package (no images to resolve) — convenient for the many tests
    /// that don't involve `<w:drawing>`.
    fn parse(xml: &str) -> Document {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };
        parse_document_xml(xml, &resolver).unwrap().document
    }

    #[test]
    fn unescapes_xml_special_characters_from_hand_written_xml() {
        // Diagnostic/regression test isolating the READ side only: the XML below is written BY HAND
        // with the entities already present (bypassing this crate's own `Writer` entirely), so this
        // proves whether `parse_paragraph`'s text accumulation correctly unescapes on its own,
        // independent of whether the write side produces correct output.
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>A &amp; B &lt; C &gt; D &apos; E &quot; F</w:t></w:r></w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        assert_eq!(paragraphs[0].text(), r#"A & B < C > D ' E " F"#);
    }

    #[test]
    fn parses_paragraphs_and_runs() {
        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Hello</w:t></w:r></w:p>
<w:p><w:r><w:t>How are you?</w:t></w:r></w:p>
<w:p/>
<w:sectPr><w:pgSz w:w="11906" w:h="16838"/></w:sectPr>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs.len(), 3);
        assert_eq!(paragraphs[0].text(), "Hello");
        assert_eq!(paragraphs[1].text(), "How are you?");
        assert_eq!(paragraphs[2].text(), "");
    }

    #[test]
    fn parses_a_paragraph_with_multiple_runs() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Hello, </w:t></w:r><w:r><w:t>world!</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs.len(), 1);
        assert_eq!(paragraphs[0].runs.len(), 2);
        assert_eq!(paragraphs[0].text(), "Hello, world!");
    }

    #[test]
    fn parses_bold_italic_and_underline_run_properties() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:b/><w:i/><w:u w:val="single"/></w:rPr><w:t>Styled</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        let run = &paragraphs[0].runs[0];
        assert!(run.bold, "{run:?}");
        assert!(run.italic, "{run:?}");
        assert_eq!(run.underline, Some(UnderlineStyle::Single), "{run:?}");
    }

    #[test]
    fn parses_color_size_and_font_family_run_properties() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:rFonts w:ascii="Georgia" w:hAnsi="Georgia"/><w:color w:val="FF0000"/><w:sz w:val="28"/><w:szCs w:val="28"/></w:rPr><w:t>Colorful</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let run = &paragraphs[0].runs[0];

        assert_eq!(run.color.as_deref(), Some("FF0000"));
        assert_eq!(run.font_size, Some(14));
        assert_eq!(run.font_family.as_deref(), Some("Georgia"));
    }

    #[test]
    fn parses_a_highlighted_run() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:highlight w:val="yellow"/></w:rPr><w:t>Highlighted</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].highlight, Some(Highlight::Yellow));
    }

    #[test]
    fn an_unrecognized_highlight_value_is_not_set() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:highlight w:val="none"/></w:rPr><w:t>No highlight</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].highlight, None);
    }

    #[test]
    fn parses_a_struck_through_run() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:strike/></w:rPr><w:t>Struck</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert!(paragraphs[0].runs[0].strike);
    }

    #[test]
    fn parses_a_superscript_run() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:vertAlign w:val="superscript"/></w:rPr><w:t>Superscript</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(
            paragraphs[0].runs[0].vertical_align,
            Some(VerticalAlign::Superscript)
        );
    }

    #[test]
    fn a_baseline_vert_align_value_is_not_set() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:vertAlign w:val="baseline"/></w:rPr><w:t>Normal</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].vertical_align, None);
    }

    #[test]
    fn a_u_element_with_val_none_is_not_underlined() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:u w:val="none"/></w:rPr><w:t>Not underlined</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].underline, None);
    }

    #[test]
    fn parses_a_wave_underline_and_color() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:u w:val="wave" w:color="FF0000"/></w:rPr><w:t>Red wave</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let run = &paragraphs[0].runs[0];

        assert_eq!(run.underline, Some(UnderlineStyle::Wave));
        assert_eq!(run.underline_color.as_deref(), Some("FF0000"));
    }

    #[test]
    fn parses_small_caps_and_all_caps() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:smallCaps/></w:rPr><w:t>Small caps</w:t></w:r><w:r><w:rPr><w:caps/></w:rPr><w:t>All caps</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert!(paragraphs[0].runs[0].small_caps);
        assert!(!paragraphs[0].runs[0].all_caps);
        assert!(paragraphs[0].runs[1].all_caps);
        assert!(!paragraphs[0].runs[1].small_caps);
    }

    #[test]
    fn parses_a_shading_color() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:shd w:val="clear" w:color="auto" w:fill="FFFF00"/></w:rPr><w:t>Highlighted background</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(
            paragraphs[0].runs[0].shading_color.as_deref(),
            Some("FFFF00")
        );
    }

    #[test]
    fn parses_a_text_border() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:bdr w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:rPr><w:t>Bordered</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert!(paragraphs[0].runs[0].text_border);
    }

    #[test]
    fn parses_character_spacing_and_vertical_position() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:spacing w:val="40"/><w:position w:val="-6"/></w:rPr><w:t>Spaced and lowered</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let run = &paragraphs[0].runs[0];

        assert_eq!(run.character_spacing, Some(40));
        assert_eq!(run.vertical_position, Some(-6));
    }

    #[test]
    fn parses_hidden_text() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:vanish/></w:rPr><w:t>Hidden</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert!(paragraphs[0].runs[0].hidden);
    }

    #[test]
    fn parses_paragraph_alignment() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:jc w:val="center"/></w:pPr><w:r><w:t>Centered</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].alignment, Some(Alignment::Center));
    }

    #[test]
    fn paragraphs_without_jc_have_no_alignment() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Default</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].alignment, None);
    }

    #[test]
    fn parses_paragraph_line_spacing_and_before_after() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:spacing w:before="240" w:after="120" w:line="480" w:lineRule="auto"/></w:pPr><w:r><w:t>Spaced out</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].line_spacing, Some(480));
        assert_eq!(paragraphs[0].space_before, Some(240));
        assert_eq!(paragraphs[0].space_after, Some(120));
    }

    #[test]
    fn parses_a_paragraph_shading_color() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:shd w:val="clear" w:color="auto" w:fill="D9D9D9"/></w:pPr><w:r><w:t>Shaded paragraph</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].shading_color.as_deref(), Some("D9D9D9"));
    }

    #[test]
    fn parses_a_paragraph_border() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:pBdr><w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:pBdr></w:pPr><w:r><w:t>Boxed paragraph</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert!(paragraphs[0].border);
    }

    // `w:shd`/`w:spacing` are shared element names between `w:pPr` and `w:rPr` (see `in_run`'s doc
    // comment in `parse_paragraph`) — this regression test proves the two never leak into each
    // other: a paragraph with BOTH a paragraph-level shading/spacing AND a run with its own,
    // different, run-level shading/character-spacing must keep all four values distinct.
    #[test]
    fn paragraph_and_run_level_shading_and_spacing_do_not_collide() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:shd w:val="clear" w:color="auto" w:fill="D9D9D9"/><w:spacing w:before="240" w:after="120" w:line="480" w:lineRule="auto"/></w:pPr><w:r><w:rPr><w:shd w:val="clear" w:color="auto" w:fill="FFFF00"/><w:spacing w:val="40"/></w:rPr><w:t>Run</w:t></w:r></w:p></w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let paragraph = &paragraphs[0];
        let run = &paragraph.runs[0];

        assert_eq!(paragraph.shading_color.as_deref(), Some("D9D9D9"));
        assert_eq!(paragraph.line_spacing, Some(480));
        assert_eq!(paragraph.space_before, Some(240));
        assert_eq!(paragraph.space_after, Some(120));
        assert_eq!(run.shading_color.as_deref(), Some("FFFF00"));
        assert_eq!(run.character_spacing, Some(40));
    }

    #[test]
    fn parses_a_table_of_text_cells() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr>
<w:tblGrid><w:gridCol w:w="2000"/><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>B1</w:t></w:r></w:p></w:tc></w:tr>
<w:tr><w:tc><w:p><w:r><w:t>A2</w:t></w:r></w:p></w:tc><w:tc><w:p/></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables.len(), 1);
        let table = tables[0];
        assert_eq!(table.rows.len(), 2);
        assert_eq!(table.rows[0].cells.len(), 2);
        assert_eq!(table.rows[0].cells[0].text(), "A1");
        assert_eq!(table.rows[0].cells[1].text(), "B1");
        assert_eq!(table.rows[1].cells[0].text(), "A2");
        assert_eq!(table.rows[1].cells[1].text(), "");
    }

    #[test]
    fn parses_a_nested_table_inside_a_cell() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc>
<w:tbl>
<w:tblPr><w:tblW w:w="0" w:type="auto"/></w:tblPr>
<w:tblGrid><w:gridCol w:w="1000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>Inner</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
<w:p/>
</w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let outer_table = document.tables().next().unwrap();
        let cell = &outer_table.rows[0].cells[0];

        let nested_tables: Vec<_> = cell.tables().collect();
        assert_eq!(nested_tables.len(), 1);
        assert_eq!(nested_tables[0].rows[0].cells[0].text(), "Inner");
        // The outer cell's own paragraph text stays empty — only the nested table's text was found
        // above, confirming `TableCell::text` doesn't accidentally reach into a nested table.
        assert_eq!(cell.text(), "");
    }

    #[test]
    fn parses_gridcol_widths_into_column_widths() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblW w:w="4000" w:type="dxa"/><w:tblLayout w:type="fixed"/></w:tblPr>
<w:tblGrid><w:gridCol w:w="1000"/><w:gridCol w:w="3000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>B1</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables[0].column_widths, vec![1000, 3000]);
    }

    #[test]
    fn parses_a_horizontal_cell_merge() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblGrid><w:gridCol w:w="2000"/><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:tcPr><w:gridSpan w:val="2"/></w:tcPr><w:p><w:r><w:t>Spans two columns</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables[0].rows[0].cells[0].horizontal_span, Some(2));
    }

    #[test]
    fn parses_a_vertical_cell_merge() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:tcPr><w:vMerge w:val="restart"/></w:tcPr><w:p><w:r><w:t>Merged</w:t></w:r></w:p></w:tc></w:tr>
<w:tr><w:tc><w:tcPr><w:vMerge/></w:tcPr><w:p/></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(
            tables[0].rows[0].cells[0].vertical_merge,
            Some(VerticalMerge::Restart)
        );
        // `w:vMerge` with no `val` at all defaults to `continue` per ECMA-376 — a real-world Word
        // document commonly omits it exactly like this, relying on the default rather than writing
        // it out.
        assert_eq!(
            tables[0].rows[1].cells[0].vertical_merge,
            Some(VerticalMerge::Continue)
        );
    }

    #[test]
    fn a_cell_with_no_tcpr_has_no_merge_properties() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>Ordinary</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables[0].rows[0].cells[0].horizontal_span, None);
        assert_eq!(tables[0].rows[0].cells[0].vertical_merge, None);
    }

    #[test]
    fn parses_a_custom_table_border_color() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="FF0000"/></w:tblBorders></w:tblPr>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables[0].border_color.as_deref(), Some("FF0000"));
    }

    #[test]
    fn a_table_with_the_fixed_auto_border_color_leaves_border_color_unset() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:tblBorders></w:tblPr>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        // Mirrors the same "don't populate the field for our own fixed default" posture as
        // `Run.underline_color`/`Paragraph.border` — `"auto"` is what this crate itself always
        // wrote before `border_color` existed, so it round-trips back to `None` rather than
        // `Some("auto")`.
        assert_eq!(tables[0].border_color, None);
    }

    #[test]
    fn parses_table_style_alignment_and_indent() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblStyle w:val="TableGrid"/><w:jc w:val="center"/><w:tblInd w:w="200" w:type="dxa"/></w:tblPr>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables[0].style_id.as_deref(), Some("TableGrid"));
        assert_eq!(tables[0].alignment, Some(Alignment::Center));
        assert_eq!(tables[0].indent_twips, Some(200));
    }

    #[test]
    fn parses_a_cell_border_shading_valign_margins_and_text_direction() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:tcPr>
<w:tcBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:tcBorders>
<w:shd w:val="clear" w:color="auto" w:fill="00FF00"/>
<w:tcMar><w:top w:w="10" w:type="dxa"/><w:left w:w="20" w:type="dxa"/><w:bottom w:w="30" w:type="dxa"/><w:right w:w="40" w:type="dxa"/></w:tcMar>
<w:textDirection w:val="btLr"/>
<w:vAlign w:val="bottom"/>
</w:tcPr><w:p><w:r><w:t>Cell</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();
        let cell = &tables[0].rows[0].cells[0];

        assert!(cell.border);
        assert_eq!(cell.shading_color.as_deref(), Some("00FF00"));
        assert_eq!(cell.margin_top_twips, Some(10));
        assert_eq!(cell.margin_left_twips, Some(20));
        assert_eq!(cell.margin_bottom_twips, Some(30));
        assert_eq!(cell.margin_right_twips, Some(40));
        assert_eq!(cell.text_direction, Some(TextDirection::BottomToTop));
        assert_eq!(cell.vertical_alignment, Some(CellVerticalAlign::Bottom));
    }

    #[test]
    fn cell_borders_and_margins_do_not_leak_into_the_table_level_border_color() {
        // Regression test for the `top`/`left`/`bottom`/`right` disambiguation in `parse_table`: a
        // cell's own `w:tcBorders` (fixed "auto" color, same as the table's) must never be mistaken
        // for the table-level `w:tblBorders` and populate `Table.border_color`.
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblPr><w:tblBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="0000FF"/></w:tblBorders></w:tblPr>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:tcPr><w:tcBorders><w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:tcBorders></w:tcPr><w:p><w:r><w:t>Cell</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();

        assert_eq!(tables[0].border_color.as_deref(), Some("0000FF"));
        assert!(tables[0].rows[0].cells[0].border);
    }

    #[test]
    fn parses_row_repeat_as_header_height_and_cant_split() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:trPr><w:cantSplit/><w:trHeight w:val="500" w:hRule="atLeast"/><w:tblHeader/></w:trPr><w:tc><w:p><w:r><w:t>Header</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();
        let row = &tables[0].rows[0];

        assert!(row.repeat_as_header_row);
        assert_eq!(row.height_twips, Some(500));
        assert!(row.cant_split);
    }

    #[test]
    fn a_row_with_no_trpr_has_default_row_properties() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:tbl>
<w:tblGrid><w:gridCol w:w="2000"/></w:tblGrid>
<w:tr><w:tc><w:p><w:r><w:t>Ordinary</w:t></w:r></w:p></w:tc></w:tr>
</w:tbl>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let tables: Vec<_> = document.tables().collect();
        let row = &tables[0].rows[0];

        assert!(!row.repeat_as_header_row);
        assert_eq!(row.height_twips, None);
        assert!(!row.cant_split);
    }

    #[test]
    fn paragraphs_and_tables_are_kept_in_reading_order() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Before</w:t></w:r></w:p>
<w:tbl><w:tr><w:tc><w:p><w:r><w:t>Cell</w:t></w:r></w:p></w:tc></w:tr></w:tbl>
<w:p><w:r><w:t>After</w:t></w:r></w:p>
</w:body>
</w:document>"#;

        let document = parse(xml);

        assert_eq!(document.blocks.len(), 3);
        assert!(matches!(document.blocks[0], Block::Paragraph(ref p) if p.text() == "Before"));
        assert!(matches!(document.blocks[1], Block::Table(_)));
        assert!(matches!(document.blocks[2], Block::Paragraph(ref p) if p.text() == "After"));
    }

    #[test]
    fn resolves_an_inline_image_via_its_relationship() {
        use opc::{Part, Relationship};

        let mut relationships = Relationships::new();
        relationships.add(Relationship {
            id: "rId2".to_string(),
            rel_type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
                .to_string(),
            target: "media/image1.png".to_string(),
            target_mode: TargetMode::Internal,
        });

        let mut package = Package::new();
        package.add_part(Part::new(
            "/word/media/image1.png",
            "image/png",
            vec![0u8, 1, 2, 3],
        ));

        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:drawing><wp:inline>
<wp:extent cx="914400" cy="457200"/>
<wp:docPr id="1" name="rId2" descr="a test image"/>
<a:graphic><a:graphicData uri="picture"><pic:pic><pic:blipFill><a:blip r:embed="rId2"/></pic:blipFill></pic:pic></a:graphicData></a:graphic>
</wp:inline></w:drawing></w:r></w:p></w:body>
</w:document>"#;

        let document = parse_document_xml(xml, &resolver).unwrap().document;
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let image = paragraphs[0].runs[0]
            .image()
            .expect("should be an image run");

        assert_eq!(image.data, vec![0u8, 1, 2, 3]);
        assert_eq!(image.format, ImageFormat::Png);
        assert_eq!(image.width_emu, 914_400);
        assert_eq!(image.height_emu, 457_200);
        assert_eq!(image.description, "a test image");
    }

    #[test]
    fn a_drawing_with_no_blip_yields_no_image_run() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        // A drawing that never got a real picture inserted (e.g. a shape, which we don't support):
        // no `a:blip`, so no relationship to resolve. Should not error out the whole document.
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:drawing><wp:inline><wp:extent cx="1" cy="1"/></wp:inline></w:drawing></w:r></w:p></w:body>
</w:document>"#;

        let document = parse_document_xml(xml, &resolver).unwrap().document;
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs.len(), 1);
        assert!(paragraphs[0].runs[0].image().is_none());
        assert_eq!(paragraphs[0].runs[0].text(), Some(""));
    }

    #[test]
    fn captures_the_default_header_and_footer_relationship_ids_from_sectpr() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Body</w:t></w:r></w:p>
<w:sectPr>
<w:headerReference w:type="even" r:id="rId9"/>
<w:headerReference w:type="default" r:id="rId2"/>
<w:footerReference w:type="default" r:id="rId3"/>
<w:pgSz w:w="11906" w:h="16838"/>
</w:sectPr>
</w:body>
</w:document>"#;

        let parsed = parse_document_xml(xml, &resolver).unwrap();

        // The "default" and "even" references are each captured into their own field (see
        // `capture_header_footer_reference`); no "first" reference is present here, so that one
        // stays `None`.
        assert_eq!(parsed.header_relationship_id.as_deref(), Some("rId2"));
        assert_eq!(parsed.header_even_relationship_id.as_deref(), Some("rId9"));
        assert_eq!(parsed.header_first_relationship_id, None);
        assert_eq!(parsed.footer_relationship_id.as_deref(), Some("rId3"));
    }

    #[test]
    fn no_header_or_footer_reference_yields_none() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Body</w:t></w:r></w:p><w:sectPr><w:pgSz w:w="11906" w:h="16838"/></w:sectPr></w:body>
</w:document>"#,
        );

        assert!(document.header.is_none());
        assert!(document.footer.is_none());
    }

    #[test]
    fn parses_a_page_number_field() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Page </w:t></w:r><w:fldSimple w:instr="PAGE"><w:r><w:rPr><w:b/></w:rPr><w:t>1</w:t></w:r></w:fldSimple></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs.len(), 2);
        assert_eq!(paragraphs[0].runs[0].text(), Some("Page "));
        let field_run = &paragraphs[0].runs[1];
        assert_eq!(field_run.field(), Some(Field::PageNumber));
        // The field's own run carried `<w:b/>` — that formatting is kept.
        assert!(field_run.bold, "{field_run:?}");
    }

    #[test]
    fn parses_a_total_pages_field_and_does_not_confuse_it_with_page() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:fldSimple w:instr="NUMPAGES"><w:r><w:t>1</w:t></w:r></w:fldSimple></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].field(), Some(Field::TotalPages));
    }

    #[test]
    fn an_unsupported_field_instruction_is_silently_dropped() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Before</w:t></w:r><w:fldSimple w:instr="DATE \@ &quot;MM/dd/yyyy&quot;"><w:r><w:t>1/1/2026</w:t></w:r></w:fldSimple><w:r><w:t>After</w:t></w:r></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        // The unsupported DATE field is dropped, but the surrounding text runs are not affected.
        assert_eq!(paragraphs[0].runs.len(), 2);
        assert_eq!(paragraphs[0].runs[0].text(), Some("Before"));
        assert_eq!(paragraphs[0].runs[1].text(), Some("After"));
    }

    #[test]
    fn a_self_closed_field_with_no_inner_run_is_parsed() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:fldSimple w:instr="PAGE"/></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].field(), Some(Field::PageNumber));
    }

    #[test]
    fn parses_a_paragraph_style_referenced_by_pstyle() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:pStyle w:val="Heading1"/><w:jc w:val="center"/></w:pPr><w:r><w:t>Title</w:t></w:r></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].style_id.as_deref(), Some("Heading1"));
        assert_eq!(paragraphs[0].alignment, Some(Alignment::Center));
    }

    #[test]
    fn parses_a_character_style_referenced_by_rstyle() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:rStyle w:val="Strong"/><w:b/></w:rPr><w:t>Bold</w:t></w:r></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].style_id.as_deref(), Some("Strong"));
        assert!(paragraphs[0].runs[0].bold);
    }

    #[test]
    fn a_page_number_field_can_carry_a_run_style() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:fldSimple w:instr="PAGE"><w:r><w:rPr><w:rStyle w:val="PageNumber"/></w:rPr><w:t>1</w:t></w:r></w:fldSimple></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(
            paragraphs[0].runs[0].style_id.as_deref(),
            Some("PageNumber")
        );
    }

    #[test]
    fn parses_styles_xml_into_paragraph_and_character_styles() {
        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1"/>
<w:pPr><w:jc w:val="center"/></w:pPr>
<w:rPr><w:b/></w:rPr>
</w:style>
<w:style w:type="character" w:styleId="Strong">
<w:name w:val="Strong"/>
<w:basedOn w:val="DefaultParagraphFont"/>
<w:rPr><w:b/><w:i/></w:rPr>
</w:style>
<w:style w:type="table" w:styleId="TableGrid">
<w:name w:val="Table Grid"/>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();

        // The `table`-typed style is skipped — only paragraph/character styles are modeled.
        assert_eq!(styles.len(), 2);

        assert_eq!(styles[0].id, "Heading1");
        assert_eq!(styles[0].name, "Heading 1");
        assert_eq!(styles[0].kind, StyleKind::Paragraph);
        assert_eq!(styles[0].alignment, Some(Alignment::Center));
        assert!(styles[0].bold);
        assert_eq!(styles[0].based_on, None);

        assert_eq!(styles[1].id, "Strong");
        assert_eq!(styles[1].kind, StyleKind::Character);
        assert_eq!(styles[1].based_on.as_deref(), Some("DefaultParagraphFont"));
        assert!(styles[1].bold);
        assert!(styles[1].italic);
    }

    #[test]
    fn parses_a_style_with_color_size_and_font_family() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1"/>
<w:rPr><w:rFonts w:ascii="Cambria" w:hAnsi="Cambria"/><w:color w:val="2E74B5"/><w:sz w:val="32"/><w:szCs w:val="32"/></w:rPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();

        assert_eq!(styles[0].color.as_deref(), Some("2E74B5"));
        assert_eq!(styles[0].font_size, Some(16));
        assert_eq!(styles[0].font_family.as_deref(), Some("Cambria"));
    }

    #[test]
    fn parses_a_style_with_a_highlight() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1"/>
<w:rPr><w:highlight w:val="lightGray"/></w:rPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();

        assert_eq!(styles[0].highlight, Some(Highlight::LightGray));
    }

    #[test]
    fn parses_a_style_with_strike_and_subscript() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="character" w:styleId="FootnoteReference">
<w:name w:val="footnote reference"/>
<w:rPr><w:strike/><w:vertAlign w:val="subscript"/></w:rPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();

        assert!(styles[0].strike);
        assert_eq!(styles[0].vertical_align, Some(VerticalAlign::Subscript));
    }

    #[test]
    fn parses_a_style_with_a_double_underline_and_color() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1"/>
<w:rPr><w:u w:val="double" w:color="2E74B5"/></w:rPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();

        assert_eq!(styles[0].underline, Some(UnderlineStyle::Double));
        assert_eq!(styles[0].underline_color.as_deref(), Some("2E74B5"));
    }

    #[test]
    fn parses_a_style_with_small_caps_shading_border_spacing_and_hidden() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="character" w:styleId="Emphasis">
<w:name w:val="Emphasis"/>
<w:rPr><w:smallCaps/><w:caps/><w:shd w:val="clear" w:color="auto" w:fill="FFFF00"/><w:bdr w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:spacing w:val="40"/><w:position w:val="-6"/><w:vanish/></w:rPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();
        let style = &styles[0];

        assert!(style.small_caps);
        assert!(style.all_caps);
        assert_eq!(style.shading_color.as_deref(), Some("FFFF00"));
        assert!(style.text_border);
        assert_eq!(style.character_spacing, Some(40));
        assert_eq!(style.vertical_position, Some(-6));
        assert!(style.hidden);
    }

    #[test]
    fn parses_a_paragraph_style_with_spacing_shading_and_border() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1"/>
<w:pPr><w:pBdr><w:top w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:left w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:bottom w:val="single" w:sz="4" w:space="0" w:color="auto"/><w:right w:val="single" w:sz="4" w:space="0" w:color="auto"/></w:pBdr><w:shd w:val="clear" w:color="auto" w:fill="D9D9D9"/><w:spacing w:before="240" w:after="120" w:line="360" w:lineRule="auto"/></w:pPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();
        let style = &styles[0];

        assert!(style.paragraph_border);
        assert_eq!(style.paragraph_shading_color.as_deref(), Some("D9D9D9"));
        assert_eq!(style.line_spacing, Some(360));
        assert_eq!(style.space_before, Some(240));
        assert_eq!(style.space_after, Some(120));
    }

    #[test]
    fn parses_a_paragraph_style_with_keep_settings_tabs_and_contextual_spacing() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="ListParagraph">
<w:name w:val="List Paragraph"/>
<w:pPr><w:keepNext/><w:keepLines/><w:pageBreakBefore/><w:tabs><w:tab w:val="left" w:pos="720"/></w:tabs><w:contextualSpacing/></w:pPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();
        let style = &styles[0];

        assert!(style.keep_with_next);
        assert!(style.keep_lines_together);
        assert!(style.page_break_before);
        assert!(style.contextual_spacing);
        assert_eq!(style.tabs.len(), 1);
        assert_eq!(style.tabs[0].position_twips, 720);
    }

    // Mirrors `paragraph_and_run_level_shading_and_spacing_do_not_collide` above, but for a style
    // declaring BOTH its own run-level formatting (`w:rPr`) and paragraph-level formatting
    // (`w:pPr`) at once — proves `in_paragraph_properties` correctly routes `w:shd`/`w:spacing` to
    // the right pair of fields depending on which parent they're nested in.
    #[test]
    fn style_paragraph_and_run_level_shading_and_spacing_do_not_collide() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1"/>
<w:pPr><w:shd w:val="clear" w:color="auto" w:fill="D9D9D9"/><w:spacing w:before="240" w:after="120" w:line="480" w:lineRule="auto"/></w:pPr>
<w:rPr><w:shd w:val="clear" w:color="auto" w:fill="FFFF00"/><w:spacing w:val="40"/></w:rPr>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();
        let style = &styles[0];

        assert_eq!(style.paragraph_shading_color.as_deref(), Some("D9D9D9"));
        assert_eq!(style.line_spacing, Some(480));
        assert_eq!(style.space_before, Some(240));
        assert_eq!(style.space_after, Some(120));
        assert_eq!(style.shading_color.as_deref(), Some("FFFF00"));
        assert_eq!(style.character_spacing, Some(40));
    }

    #[test]
    fn an_unrecognized_style_type_is_skipped_without_disturbing_the_next_style() {
        let xml = r#"<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:style w:type="numbering" w:styleId="ListParagraph">
<w:name w:val="List Paragraph"/>
</w:style>
<w:style w:type="paragraph" w:styleId="Normal">
<w:name w:val="Normal"/>
</w:style>
</w:styles>"#;

        let styles = parse_styles_xml(xml).unwrap();

        assert_eq!(styles.len(), 1);
        assert_eq!(styles[0].id, "Normal");
    }

    #[test]
    fn a_document_without_a_styles_relationship_has_no_styles() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Body</w:t></w:r></w:p></w:body>
</w:document>"#,
        );

        assert!(document.styles.is_empty());
    }

    #[test]
    fn resolves_an_external_hyperlink_via_its_relationship() {
        use opc::Relationship;

        let mut relationships = Relationships::new();
        relationships.add(Relationship {
            id: "rId4".to_string(),
            rel_type:
                "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
                    .to_string(),
            target: "https://www.rust-lang.org".to_string(),
            target_mode: TargetMode::External,
        });

        let package = Package::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:hyperlink r:id="rId4"><w:r><w:t>Rust</w:t></w:r></w:hyperlink></w:p></w:body>
</w:document>"#;

        let document = parse_document_xml(xml, &resolver).unwrap().document;
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs.len(), 1);
        assert_eq!(paragraphs[0].runs[0].text(), Some("Rust"));
        assert_eq!(
            paragraphs[0].runs[0].hyperlink,
            Some(Hyperlink::External("https://www.rust-lang.org".to_string()))
        );
    }

    #[test]
    fn parses_an_internal_hyperlink_from_its_anchor_attribute() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:hyperlink w:anchor="Section1"><w:r><w:t>See above</w:t></w:r></w:hyperlink></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(
            paragraphs[0].runs[0].hyperlink,
            Some(Hyperlink::Internal("Section1".to_string()))
        );
    }

    #[test]
    fn a_hyperlink_id_with_no_matching_relationship_is_dropped_but_its_run_is_kept() {
        // A malformed document (r:id declared but not backed by a real relationship) — same
        // silent-drop policy as an unsupported field or an unresolvable image, rather than failing
        // the whole document.
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:hyperlink r:id="rId99"><w:r><w:t>Broken link</w:t></w:r></w:hyperlink></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs[0].text(), Some("Broken link"));
        assert_eq!(paragraphs[0].runs[0].hyperlink, None);
    }

    #[test]
    fn multiple_runs_inside_one_hyperlink_all_get_the_same_target() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:hyperlink w:anchor="Top"><w:r><w:rPr><w:b/></w:rPr><w:t>Back </w:t></w:r><w:r><w:t>to top</w:t></w:r></w:hyperlink></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let runs = &paragraphs[0].runs;

        assert_eq!(runs.len(), 2);
        assert_eq!(
            runs[0].hyperlink,
            Some(Hyperlink::Internal("Top".to_string()))
        );
        assert_eq!(
            runs[1].hyperlink,
            Some(Hyperlink::Internal("Top".to_string()))
        );
        assert!(runs[0].bold);
        assert!(!runs[1].bold);
    }

    #[test]
    fn a_run_outside_any_hyperlink_has_no_hyperlink() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:hyperlink w:anchor="Top"><w:r><w:t>link</w:t></w:r></w:hyperlink><w:r><w:t> plain</w:t></w:r></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();
        let runs = &paragraphs[0].runs;

        assert_eq!(runs.len(), 2);
        assert!(runs[0].hyperlink.is_some());
        assert_eq!(runs[1].hyperlink, None);
    }

    #[test]
    fn parses_a_paragraphs_numpr_into_numbering_id_and_level() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:pPr><w:numPr><w:ilvl w:val="1"/><w:numId w:val="7"/></w:numPr></w:pPr><w:r><w:t>Item</w:t></w:r></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].numbering_id, Some(7));
        assert_eq!(paragraphs[0].numbering_level, 1);
    }

    #[test]
    fn a_paragraph_without_numpr_has_no_numbering() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Not a list item</w:t></w:r></w:p></w:body>
</w:document>"#,
        );
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].numbering_id, None);
        assert_eq!(paragraphs[0].numbering_level, 0);
    }

    #[test]
    fn parses_numbering_xml_resolving_num_through_its_abstractnum() {
        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:abstractNum w:abstractNumId="0">
<w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="bullet"/><w:lvlText w:val="•"/><w:lvlJc w:val="left"/><w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr></w:lvl>
<w:lvl w:ilvl="1"><w:start w:val="1"/><w:numFmt w:val="bullet"/><w:lvlText w:val="◦"/><w:lvlJc w:val="left"/><w:pPr><w:ind w:left="1440" w:hanging="360"/></w:pPr></w:lvl>
</w:abstractNum>
<w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>
</w:numbering>"#;

        let definitions = parse_numbering_xml(xml).unwrap();

        assert_eq!(definitions.len(), 1);
        assert_eq!(definitions[0].id, 1);
        assert_eq!(definitions[0].levels.len(), 2);
        assert_eq!(definitions[0].levels[0].format, NumberFormat::Bullet);
        assert_eq!(definitions[0].levels[0].text, "•");
        assert_eq!(definitions[0].levels[0].indent_twips, 720);
        assert_eq!(definitions[0].levels[0].hanging_twips, 360);
        assert_eq!(definitions[0].levels[1].text, "◦");
    }

    #[test]
    fn numid_and_abstractnumid_can_differ_like_in_a_real_word_document() {
        // Real Word-authored documents commonly have several `w:num` entries with different
        // `numId`s all pointing at the same `w:abstractNum` (or at least not numerically matching
        // it) — unlike this crate's own writer, which always keeps them equal for simplicity. The
        // reader must not assume they match.
        let xml = r#"<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:abstractNum w:abstractNumId="4">
<w:lvl w:ilvl="0"><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/></w:lvl>
</w:abstractNum>
<w:num w:numId="2"><w:abstractNumId w:val="4"/></w:num>
</w:numbering>"#;

        let definitions = parse_numbering_xml(xml).unwrap();

        assert_eq!(definitions.len(), 1);
        assert_eq!(definitions[0].id, 2);
        assert_eq!(definitions[0].levels[0].format, NumberFormat::Decimal);
    }

    #[test]
    fn a_num_referencing_an_undeclared_abstractnum_gets_empty_levels() {
        let xml = r#"<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:num w:numId="1"><w:abstractNumId w:val="99"/></w:num>
</w:numbering>"#;

        let definitions = parse_numbering_xml(xml).unwrap();

        assert_eq!(definitions.len(), 1);
        assert_eq!(definitions[0].id, 1);
        assert!(definitions[0].levels.is_empty());
    }

    #[test]
    fn a_document_without_a_numbering_relationship_has_no_numbering_definitions() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Body</w:t></w:r></w:p></w:body>
</w:document>"#,
        );

        assert!(document.numbering_definitions.is_empty());
    }

    #[test]
    fn parses_a_footnote_reference_run_into_a_run_content_variant() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:rPr><w:rStyle w:val="FootnoteReference"/></w:rPr><w:footnoteReference w:id="1"/></w:r></w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        assert_eq!(paragraphs[0].runs.len(), 1);
        assert_eq!(
            paragraphs[0].runs[0].content,
            RunContent::NoteReference(NoteReference::Footnote(1))
        );
        assert_eq!(
            paragraphs[0].runs[0].style_id.as_deref(),
            Some("FootnoteReference")
        );
    }

    #[test]
    fn parses_an_endnote_reference_run() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:endnoteReference w:id="3"/></w:r></w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        assert_eq!(
            paragraphs[0].runs[0].content,
            RunContent::NoteReference(NoteReference::Endnote(3))
        );
    }

    #[test]
    fn parses_notes_xml_into_notes_with_their_blocks() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:footnotes xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:footnote w:id="1"><w:p><w:r><w:footnoteRef/></w:r><w:r><w:t xml:space="preserve"> </w:t></w:r><w:r><w:t>Some detail.</w:t></w:r></w:p></w:footnote>
</w:footnotes>"#;

        let notes = parse_notes_xml(xml, &resolver, b"footnote").unwrap();

        assert_eq!(notes.len(), 1);
        assert_eq!(notes[0].id, 1);
        let paragraph = notes[0].paragraphs().next().expect("missing paragraph");
        assert_eq!(paragraph.runs.len(), 3);
        assert_eq!(
            paragraph.runs[0].content,
            RunContent::NoteMarker(NoteKind::Footnote)
        );
        assert_eq!(paragraph.runs[2].text(), Some("Some detail."));
    }

    #[test]
    fn skips_separator_and_continuation_separator_notes() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        // Real Word-authored footnotes.xml files always carry these two boilerplate entries — they
        // must not show up as user-visible notes (see `Note`'s doc comment).
        let xml = r#"<w:footnotes xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:footnote w:type="separator" w:id="-1"><w:p><w:r><w:separator/></w:r></w:p></w:footnote>
<w:footnote w:type="continuationSeparator" w:id="0"><w:p><w:r><w:continuationSeparator/></w:r></w:p></w:footnote>
<w:footnote w:id="1"><w:p><w:r><w:t>Real footnote.</w:t></w:r></w:p></w:footnote>
</w:footnotes>"#;

        let notes = parse_notes_xml(xml, &resolver, b"footnote").unwrap();

        assert_eq!(notes.len(), 1);
        assert_eq!(notes[0].id, 1);
    }

    #[test]
    fn a_document_without_a_footnotes_or_endnotes_relationship_has_none() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Body</w:t></w:r></w:p></w:body>
</w:document>"#,
        );

        assert!(document.footnotes.is_empty());
        assert!(document.endnotes.is_empty());
    }

    #[test]
    fn parses_a_comment_range_into_the_covered_run_s_comment_ids() {
        // ECMA-376's own `commentRangeStart` example fragment, verbatim (see this project's own
        // copy of it in `model.rs`'s `Run.comment_ids` doc comment).
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p>
<w:r><w:t xml:space="preserve">Some </w:t></w:r>
<w:commentRangeStart w:id="0"/>
<w:r><w:t>text.</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:commentReference w:id="0"/></w:r>
</w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        let runs = &paragraphs[0].runs;
        // The reference run itself isn't inside the range (it comes after `commentRangeEnd`) and
        // carries no text — it's still a run in the model (matching what was actually in the XML),
        // just with no comment id of its own.
        assert_eq!(runs.len(), 3);
        assert_eq!(runs[0].text(), Some("Some "));
        assert!(runs[0].comment_ids.is_empty(), "{:?}", runs[0].comment_ids);
        assert_eq!(runs[1].text(), Some("text."));
        assert_eq!(runs[1].comment_ids, vec![0]);
        assert!(runs[2].comment_ids.is_empty(), "{:?}", runs[2].comment_ids);
    }

    #[test]
    fn overlapping_comment_ranges_parse_back_into_each_run_s_own_id_set() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p>
<w:commentRangeStart w:id="0"/>
<w:r><w:t>a</w:t></w:r>
<w:commentRangeStart w:id="1"/>
<w:r><w:t>b</w:t></w:r>
<w:commentRangeEnd w:id="1"/>
<w:r><w:commentReference w:id="1"/></w:r>
<w:r><w:t>c</w:t></w:r>
<w:commentRangeEnd w:id="0"/>
<w:r><w:commentReference w:id="0"/></w:r>
</w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        let text_runs: Vec<_> = paragraphs[0]
            .runs
            .iter()
            .filter(|run| run.text().is_some_and(|text| !text.is_empty()))
            .collect();
        assert_eq!(text_runs[0].text(), Some("a"));
        assert_eq!(text_runs[0].comment_ids, vec![0]);
        assert_eq!(text_runs[1].text(), Some("b"));
        assert_eq!(text_runs[1].comment_ids, vec![0, 1]);
        assert_eq!(text_runs[2].text(), Some("c"));
        assert_eq!(text_runs[2].comment_ids, vec![0]);
    }

    #[test]
    fn parses_a_bookmark_range_into_the_covered_run_s_bookmarks() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p>
<w:r><w:t xml:space="preserve">Some </w:t></w:r>
<w:bookmarkStart w:id="0" w:name="MyBookmark"/>
<w:r><w:t>text.</w:t></w:r>
<w:bookmarkEnd w:id="0"/>
</w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        let runs = &paragraphs[0].runs;
        assert_eq!(runs.len(), 2);
        assert_eq!(runs[0].text(), Some("Some "));
        assert!(runs[0].bookmarks.is_empty(), "{:?}", runs[0].bookmarks);
        assert_eq!(runs[1].text(), Some("text."));
        assert_eq!(runs[1].bookmarks, vec![Bookmark::new(0, "MyBookmark")]);
    }

    #[test]
    fn overlapping_bookmarks_parse_back_into_each_run_s_own_set() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p>
<w:bookmarkStart w:id="0" w:name="Outer"/>
<w:r><w:t>a</w:t></w:r>
<w:bookmarkStart w:id="1" w:name="Inner"/>
<w:r><w:t>b</w:t></w:r>
<w:bookmarkEnd w:id="1"/>
<w:r><w:t>c</w:t></w:r>
<w:bookmarkEnd w:id="0"/>
</w:p></w:body>
</w:document>"#,
        );

        let paragraphs: Vec<_> = document.paragraphs().collect();
        let runs = &paragraphs[0].runs;
        assert_eq!(runs[0].text(), Some("a"));
        assert_eq!(runs[0].bookmarks, vec![Bookmark::new(0, "Outer")]);
        assert_eq!(runs[1].text(), Some("b"));
        assert_eq!(
            runs[1].bookmarks,
            vec![Bookmark::new(0, "Outer"), Bookmark::new(1, "Inner")]
        );
        assert_eq!(runs[2].text(), Some("c"));
        assert_eq!(runs[2].bookmarks, vec![Bookmark::new(0, "Outer")]);
    }

    #[test]
    fn parses_comments_xml_into_comments_with_author_date_initials_and_blocks() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:comment w:id="0" w:author="Morgan" w:date="2026-07-16T12:00:00Z" w:initials="MR"><w:p><w:r><w:t>Please rephrase.</w:t></w:r></w:p></w:comment>
</w:comments>"#;

        let comments = parse_comments_xml(xml, &resolver).unwrap();

        assert_eq!(comments.len(), 1);
        assert_eq!(comments[0].id, 0);
        assert_eq!(comments[0].author.as_deref(), Some("Morgan"));
        assert_eq!(comments[0].date.as_deref(), Some("2026-07-16T12:00:00Z"));
        assert_eq!(comments[0].initials.as_deref(), Some("MR"));
        let paragraph = comments[0].paragraphs().next().expect("missing paragraph");
        assert_eq!(paragraph.text(), "Please rephrase.");
    }

    #[test]
    fn a_comment_with_no_id_is_skipped() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:comment w:author="No id"><w:p><w:r><w:t>Malformed.</w:t></w:r></w:p></w:comment>
<w:comment w:id="1"><w:p><w:r><w:t>Valid.</w:t></w:r></w:p></w:comment>
</w:comments>"#;

        let comments = parse_comments_xml(xml, &resolver).unwrap();

        assert_eq!(comments.len(), 1);
        assert_eq!(comments[0].id, 1);
    }

    #[test]
    fn a_document_without_a_comments_relationship_has_none() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Body</w:t></w:r></w:p></w:body>
</w:document>"#,
        );

        assert!(document.comments.is_empty());
    }

    #[test]
    fn parses_a_structured_document_tag_with_its_properties_and_content() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:sdt>
<w:sdtPr><w:alias w:val="Customer Name"/><w:tag w:val="CustomerName"/><w:id w:val="1"/></w:sdtPr>
<w:sdtContent><w:p><w:r><w:t>Acme Corp</w:t></w:r></w:p></w:sdtContent>
</w:sdt></w:body>
</w:document>"#,
        );

        assert_eq!(document.blocks.len(), 1);
        match &document.blocks[0] {
            Block::StructuredDocumentTag(sdt) => {
                assert_eq!(sdt.id, Some(1));
                assert_eq!(sdt.tag.as_deref(), Some("CustomerName"));
                assert_eq!(sdt.alias.as_deref(), Some("Customer Name"));
                assert_eq!(
                    sdt.paragraphs().next().expect("missing paragraph").text(),
                    "Acme Corp"
                );
            }
            other => panic!("expected a StructuredDocumentTag block, got {other:?}"),
        }
    }

    #[test]
    fn a_structured_document_tag_with_no_sdtpr_has_no_properties() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:sdt><w:sdtContent><w:p><w:r><w:t>Plain</w:t></w:r></w:p></w:sdtContent></w:sdt></w:body>
</w:document>"#,
        );

        match &document.blocks[0] {
            Block::StructuredDocumentTag(sdt) => {
                assert!(sdt.id.is_none());
                assert!(sdt.tag.is_none());
                assert!(sdt.alias.is_none());
                assert_eq!(sdt.paragraphs().next().unwrap().text(), "Plain");
            }
            other => panic!("expected a StructuredDocumentTag block, got {other:?}"),
        }
    }

    #[test]
    fn a_nested_structured_document_tag_parses_correctly() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:sdt>
<w:sdtPr><w:tag w:val="outer"/></w:sdtPr>
<w:sdtContent><w:sdt>
<w:sdtPr><w:tag w:val="inner"/></w:sdtPr>
<w:sdtContent><w:p><w:r><w:t>nested</w:t></w:r></w:p></w:sdtContent>
</w:sdt></w:sdtContent>
</w:sdt></w:body>
</w:document>"#,
        );

        match &document.blocks[0] {
            Block::StructuredDocumentTag(outer) => {
                assert_eq!(outer.tag.as_deref(), Some("outer"));
                assert_eq!(outer.blocks.len(), 1);
                match &outer.blocks[0] {
                    Block::StructuredDocumentTag(inner) => {
                        assert_eq!(inner.tag.as_deref(), Some("inner"));
                        assert_eq!(inner.paragraphs().next().unwrap().text(), "nested");
                    }
                    other => panic!("expected a nested StructuredDocumentTag block, got {other:?}"),
                }
            }
            other => panic!("expected a StructuredDocumentTag block, got {other:?}"),
        }
    }

    #[test]
    fn a_structured_document_tag_interleaved_with_paragraphs_keeps_reading_order() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Before</w:t></w:r></w:p>
<w:sdt><w:sdtContent><w:p><w:r><w:t>Inside</w:t></w:r></w:p></w:sdtContent></w:sdt>
<w:p><w:r><w:t>After</w:t></w:r></w:p>
</w:body>
</w:document>"#,
        );

        assert_eq!(document.blocks.len(), 3);
        assert!(matches!(&document.blocks[0], Block::Paragraph(p) if p.text() == "Before"));
        assert!(matches!(
            &document.blocks[1],
            Block::StructuredDocumentTag(_)
        ));
        assert!(matches!(&document.blocks[2], Block::Paragraph(p) if p.text() == "After"));
    }

    #[test]
    fn parses_a_theme_with_colors_and_fonts() {
        let theme = parse_theme_xml(
            r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Custom">
<a:themeElements>
<a:clrScheme name="Custom">
<a:dk1><a:srgbClr val="111111"/></a:dk1>
<a:lt1><a:srgbClr val="EEEEEE"/></a:lt1>
<a:dk2><a:srgbClr val="222222"/></a:dk2>
<a:lt2><a:srgbClr val="DDDDDD"/></a:lt2>
<a:accent1><a:srgbClr val="AA0000"/></a:accent1>
<a:accent2><a:srgbClr val="BB1100"/></a:accent2>
<a:accent3><a:srgbClr val="CC2200"/></a:accent3>
<a:accent4><a:srgbClr val="DD3300"/></a:accent4>
<a:accent5><a:srgbClr val="EE4400"/></a:accent5>
<a:accent6><a:srgbClr val="FF5500"/></a:accent6>
<a:hlink><a:srgbClr val="0000AA"/></a:hlink>
<a:folHlink><a:srgbClr val="AA00AA"/></a:folHlink>
</a:clrScheme>
<a:fontScheme name="Custom">
<a:majorFont><a:latin typeface="Georgia"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont>
<a:minorFont><a:latin typeface="Verdana"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont>
</a:fontScheme>
<a:fmtScheme name="Office"><a:fillStyleLst/><a:lnStyleLst/><a:effectStyleLst/><a:bgFillStyleLst/></a:fmtScheme>
</a:themeElements>
</a:theme>"#,
        )
        .unwrap();

        assert_eq!(theme.name, "Custom");
        assert_eq!(theme.colors.dark1, "111111");
        assert_eq!(theme.colors.light1, "EEEEEE");
        assert_eq!(theme.colors.accent6, "FF5500");
        assert_eq!(theme.colors.followed_hyperlink, "AA00AA");
        assert_eq!(theme.fonts.major_latin, "Georgia");
        assert_eq!(theme.fonts.minor_latin, "Verdana");
    }

    #[test]
    fn parses_trackrevisions_from_settings_xml() {
        let xml = r#"<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:trackRevisions/>
</w:settings>"#;

        let (track_changes, _protection) = parse_settings_xml(xml).unwrap();
        assert!(track_changes);
    }

    #[test]
    fn a_settings_xml_with_no_trackrevisions_parses_as_false() {
        let xml = r#"<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:evenAndOddHeaders/>
</w:settings>"#;

        let (track_changes, _protection) = parse_settings_xml(xml).unwrap();
        assert!(!track_changes);
    }

    #[test]
    fn an_explicit_trackrevisions_val_false_parses_as_false() {
        let xml = r#"<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:trackRevisions w:val="false"/>
</w:settings>"#;

        let (track_changes, _protection) = parse_settings_xml(xml).unwrap();
        assert!(!track_changes);
    }

    #[test]
    fn parses_documentprotection_edit_value_into_protectionkind() {
        let xml = r#"<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:documentProtection w:edit="readOnly" w:enforcement="1"/>
</w:settings>"#;

        let (_track_changes, protection) = parse_settings_xml(xml).unwrap();
        assert_eq!(protection, Some(ProtectionKind::ReadOnly));
    }

    #[test]
    fn a_settings_xml_with_no_documentprotection_parses_protection_as_none() {
        let xml = r#"<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:trackRevisions/>
</w:settings>"#;

        let (_track_changes, protection) = parse_settings_xml(xml).unwrap();
        assert_eq!(protection, None);
    }

    #[test]
    fn an_unrecognized_documentprotection_edit_value_parses_as_none() {
        let xml = r#"<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:documentProtection w:edit="none" w:enforcement="1"/>
</w:settings>"#;

        let (_track_changes, protection) = parse_settings_xml(xml).unwrap();
        assert_eq!(protection, None);
    }

    #[test]
    fn parses_core_properties_xml_into_documentproperties() {
        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<dc:title>Rapport trimestriel</dc:title>
<dc:subject>Finances</dc:subject>
<dc:creator>Morgan &amp; Associ&#233;s</dc:creator>
<cp:keywords>rapport, finances</cp:keywords>
<dc:description>Notes internes</dc:description>
<cp:lastModifiedBy>Morgan</cp:lastModifiedBy>
<cp:revision>3</cp:revision>
<dcterms:created xsi:type="dcterms:W3CDTF">2026-07-17T10:00:00Z</dcterms:created>
<dcterms:modified xsi:type="dcterms:W3CDTF">2026-07-17T11:30:00Z</dcterms:modified>
<cp:category>Interne</cp:category>
<cp:contentStatus>Draft</cp:contentStatus>
</cp:coreProperties>"#;

        let properties = parse_core_properties_xml(xml).unwrap();

        assert_eq!(properties.title.as_deref(), Some("Rapport trimestriel"));
        assert_eq!(properties.subject.as_deref(), Some("Finances"));
        // Confirms both a named entity (`&amp;`) and a numeric character reference (`&#233;`, "é")
        // survive `Event::GeneralRef` decoding — same class of bug already fixed once for run text
        // (see the CHANGELOG), now exercised here for core properties too.
        assert_eq!(properties.creator.as_deref(), Some("Morgan & Associés"));
        assert_eq!(properties.keywords.as_deref(), Some("rapport, finances"));
        assert_eq!(properties.description.as_deref(), Some("Notes internes"));
        assert_eq!(properties.last_modified_by.as_deref(), Some("Morgan"));
        assert_eq!(properties.revision.as_deref(), Some("3"));
        assert_eq!(properties.created.as_deref(), Some("2026-07-17T10:00:00Z"));
        assert_eq!(properties.modified.as_deref(), Some("2026-07-17T11:30:00Z"));
        assert_eq!(properties.category.as_deref(), Some("Interne"));
        assert_eq!(properties.content_status.as_deref(), Some("Draft"));
    }

    #[test]
    fn an_empty_core_properties_element_parses_as_all_none() {
        let xml = r#"<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>"#;

        let properties = parse_core_properties_xml(xml).unwrap();

        assert_eq!(properties, DocumentProperties::new());
    }

    #[test]
    fn a_sysclr_color_slot_uses_its_lastclr_fallback() {
        let theme = parse_theme_xml(
            r#"<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office">
<a:themeElements>
<a:clrScheme name="Office">
<a:dk1><a:sysClr val="windowText" lastClr="000000"/></a:dk1>
<a:lt1><a:sysClr val="window" lastClr="FFFFFF"/></a:lt1>
<a:dk2><a:srgbClr val="1F497D"/></a:dk2>
<a:lt2><a:srgbClr val="EEECE1"/></a:lt2>
<a:accent1><a:srgbClr val="4F81BD"/></a:accent1>
<a:accent2><a:srgbClr val="C0504D"/></a:accent2>
<a:accent3><a:srgbClr val="9BBB59"/></a:accent3>
<a:accent4><a:srgbClr val="8064A2"/></a:accent4>
<a:accent5><a:srgbClr val="4BACC6"/></a:accent5>
<a:accent6><a:srgbClr val="F79646"/></a:accent6>
<a:hlink><a:srgbClr val="0000FF"/></a:hlink>
<a:folHlink><a:srgbClr val="800080"/></a:folHlink>
</a:clrScheme>
</a:themeElements>
</a:theme>"#,
        )
        .unwrap();

        // `sysClr`'s live system-color binding (`val="windowText"`) isn't preserved — only its
        // `lastClr` fallback RGB is, see `ColorScheme`'s doc comment.
        assert_eq!(theme.colors.dark1, "000000");
        assert_eq!(theme.colors.light1, "FFFFFF");
    }

    #[test]
    fn a_theme_with_no_font_scheme_keeps_the_default_fonts() {
        let theme = parse_theme_xml(
            r#"<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="ColorsOnly">
<a:themeElements>
<a:clrScheme name="ColorsOnly">
<a:dk1><a:srgbClr val="000000"/></a:dk1>
<a:lt1><a:srgbClr val="FFFFFF"/></a:lt1>
<a:dk2><a:srgbClr val="1F497D"/></a:dk2>
<a:lt2><a:srgbClr val="EEECE1"/></a:lt2>
<a:accent1><a:srgbClr val="4F81BD"/></a:accent1>
<a:accent2><a:srgbClr val="C0504D"/></a:accent2>
<a:accent3><a:srgbClr val="9BBB59"/></a:accent3>
<a:accent4><a:srgbClr val="8064A2"/></a:accent4>
<a:accent5><a:srgbClr val="4BACC6"/></a:accent5>
<a:accent6><a:srgbClr val="F79646"/></a:accent6>
<a:hlink><a:srgbClr val="0000FF"/></a:hlink>
<a:folHlink><a:srgbClr val="800080"/></a:folHlink>
</a:clrScheme>
</a:themeElements>
</a:theme>"#,
        )
        .unwrap();

        assert_eq!(theme.fonts, FontScheme::office_default());
    }

    #[test]
    fn parses_page_size_margins_and_columns_from_sectpr() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Body</w:t></w:r></w:p>
<w:sectPr>
<w:pgSz w:w="16838" w:h="11906" w:orient="landscape"/>
<w:pgMar w:top="1000" w:right="1000" w:bottom="1000" w:left="1000" w:header="500" w:footer="500" w:gutter="0"/>
<w:cols w:num="2" w:space="720" w:equalWidth="true"/>
</w:sectPr>
</w:body>
</w:document>"#;

        let document = parse(xml);

        assert_eq!(document.page_setup.width_twips, 16838);
        assert_eq!(document.page_setup.height_twips, 11906);
        assert_eq!(document.page_setup.orientation, Orientation::Landscape);
        assert_eq!(document.page_setup.margin_top_twips, 1000);
        assert_eq!(document.page_setup.margin_right_twips, 1000);
        assert_eq!(document.page_setup.margin_bottom_twips, 1000);
        assert_eq!(document.page_setup.margin_left_twips, 1000);
        assert_eq!(document.page_setup.margin_header_twips, 500);
        assert_eq!(document.page_setup.margin_footer_twips, 500);
        assert_eq!(document.page_setup.columns, Some(2));
    }

    #[test]
    fn parses_an_a3_page_size_distinct_from_the_default_a4() {
        // Distinct from the test above, which only swaps A4's own width/height for landscape — this
        // proves `pgSz`'s `w`/`h` parse into genuinely arbitrary values, not just the two numbers
        // this crate's own default already uses.
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Body</w:t></w:r></w:p>
<w:sectPr>
<w:pgSz w:w="16838" w:h="23811"/>
</w:sectPr>
</w:body>
</w:document>"#;

        let document = parse(xml);

        assert_eq!(document.page_setup.width_twips, 16838);
        assert_eq!(document.page_setup.height_twips, 23811);
        assert_eq!(document.page_setup.orientation, Orientation::Portrait);
    }

    #[test]
    fn a_missing_pgsz_keeps_the_default_page_setup() {
        let document = parse(
            r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body><w:p><w:r><w:t>Body</w:t></w:r></w:p></w:body>
</w:document>"#,
        );

        assert_eq!(document.page_setup, PageSetup::default());
    }

    #[test]
    fn captures_first_and_even_header_footer_reference_ids_separately() {
        let package = Package::new();
        let relationships = Relationships::new();
        let resolver = ImageResolver {
            package: &package,
            part_relationships: &relationships,
        };

        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:r><w:t>Body</w:t></w:r></w:p>
<w:sectPr>
<w:headerReference w:type="default" r:id="rId2"/>
<w:headerReference w:type="first" r:id="rId4"/>
<w:footerReference w:type="first" r:id="rId5"/>
<w:headerReference w:type="even" r:id="rId6"/>
<w:footerReference w:type="even" r:id="rId7"/>
<w:pgSz w:w="11906" w:h="16838"/>
</w:sectPr>
</w:body>
</w:document>"#;

        let parsed = parse_document_xml(xml, &resolver).unwrap();

        assert_eq!(parsed.header_relationship_id.as_deref(), Some("rId2"));
        assert_eq!(parsed.header_first_relationship_id.as_deref(), Some("rId4"));
        assert_eq!(parsed.footer_first_relationship_id.as_deref(), Some("rId5"));
        assert_eq!(parsed.header_even_relationship_id.as_deref(), Some("rId6"));
        assert_eq!(parsed.footer_even_relationship_id.as_deref(), Some("rId7"));
    }

    #[test]
    fn parses_custom_tab_stops_in_order() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:pPr><w:tabs>
<w:tab w:val="left" w:pos="720"/>
<w:tab w:val="decimal" w:leader="dot" w:pos="-360"/>
</w:tabs></w:pPr><w:r><w:t>Tabbed</w:t></w:r></w:p>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].tabs.len(), 2);
        assert_eq!(paragraphs[0].tabs[0].position_twips, 720);
        assert_eq!(paragraphs[0].tabs[0].alignment, TabStopAlignment::Left);
        assert_eq!(paragraphs[0].tabs[0].leader, None);
        assert_eq!(paragraphs[0].tabs[1].position_twips, -360);
        assert_eq!(paragraphs[0].tabs[1].alignment, TabStopAlignment::Decimal);
        assert_eq!(paragraphs[0].tabs[1].leader, Some(TabLeader::Dot));
    }

    #[test]
    fn parses_keep_next_keep_lines_page_break_before_and_contextual_spacing() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p><w:pPr>
<w:keepNext/><w:keepLines/><w:pageBreakBefore/><w:contextualSpacing/>
</w:pPr><w:r><w:t>Heading</w:t></w:r></w:p>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert!(paragraphs[0].keep_with_next);
        assert!(paragraphs[0].keep_lines_together);
        assert!(paragraphs[0].page_break_before);
        assert!(paragraphs[0].contextual_spacing);
    }

    #[test]
    fn parses_page_and_column_breaks_and_a_carriage_return() {
        let xml = r#"<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
<w:body>
<w:p>
<w:r><w:br/></w:r>
<w:r><w:br w:type="page"/></w:r>
<w:r><w:br w:type="column"/></w:r>
<w:r><w:cr/></w:r>
</w:p>
</w:body>
</w:document>"#;

        let document = parse(xml);
        let paragraphs: Vec<_> = document.paragraphs().collect();

        assert_eq!(paragraphs[0].runs.len(), 4);
        assert_eq!(
            paragraphs[0].runs[0].content,
            RunContent::Break(BreakKind::TextWrapping)
        );
        assert_eq!(
            paragraphs[0].runs[1].content,
            RunContent::Break(BreakKind::Page)
        );
        assert_eq!(
            paragraphs[0].runs[2].content,
            RunContent::Break(BreakKind::Column)
        );
        assert_eq!(paragraphs[0].runs[3].content, RunContent::CarriageReturn);
    }
}