Sprint 5: PAGE XML serializer and dual export

Complete the second native export format, achieving the architecture's
core goal of dual ALTO + PAGE XML output from a single CanonicalDocument.

PAGE XML serializer (lxml):
- Namespace: http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15
- Mapping: TextRegion→TextRegion, TextLine→TextLine, Word→Word
- <Coords points="x,y ..."> uses polygon when available, falls back to
rectangle from bbox — preserves PaddleOCR's original quadrilateral
- <ReadingOrder>/<OrderedGroup>/<RegionRefIndexed> from page.reading_order
- <TextEquiv><Unicode> at region, line, and word levels
- BlockRole→PAGE type mapping (heading, paragraph, footnote, etc.)
- Confidence as @conf attribute on Word elements
- <Metadata> with Creator, Created, LastChange

Integration test validates:
- Same canonical doc → both ALTO and PAGE produce correct output
- Same word count and text content in both formats
- ALTO uses HPOS/VPOS/WIDTH/HEIGHT, PAGE uses Coords/points
- PAGE preserves polygon geometry, ALTO uses axis-aligned bbox
- Export eligibility checks pass before serialization

22 new tests (PAGE serializer: 19, dual export integration: 3)
353 total tests passing.

https://claude.ai/code/session_01Cuzvc9Pjfo5u46eT3ta2Cg

src/app/serializers/page_xml.py

@@ -0,0 +1,245 @@
+"""PAGE XML serializer — deterministic conversion from CanonicalDocument to PAGE XML.
+
+This serializer follows the same rules as the ALTO serializer (see AGENTS.md §6):
+  - No model calls, no segmentation reconstruction, no text correction
+  - No coordinate invention, no export eligibility decisions
+  - Pure deterministic mapping from validated CanonicalDocument
+
+PAGE XML mapping:
+  Page         → <Page>
+  TextRegion   → <TextRegion>
+  TextLine     → <TextLine>
+  Word         → <Word>
+
+Coordinate mapping:
+  Uses <Coords points="x1,y1 x2,y2 x3,y3 x4,y4"/> — polygon if available,
+  otherwise constructs a rectangle from the bbox.
+
+Reading order:
+  <ReadingOrder> / <OrderedGroup> / <RegionRefIndexed>
+
+Text content:
+  <TextEquiv><Unicode>text</Unicode></TextEquiv> at each level.
+
+Namespace: http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from lxml import etree
+
+from src.app.domain.models import (
+    CanonicalDocument,
+    Page,
+    TextLine,
+    TextRegion,
+    Word,
+)
+from src.app.domain.models.status import BlockRole
+from src.app.geometry.polygon import bbox_to_polygon
+from src.app.geometry.quantization import RoundingStrategy, quantize_value
+
+PAGE_NS = "http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15"
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+SCHEMA_LOCATION = (
+    "http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15 "
+    "http://schema.primaresearch.org/PAGE/gts/pagecontent/2019-07-15/pagecontent.xsd"
+)
+
+NSMAP = {
+    None: PAGE_NS,
+    "xsi": XSI_NS,
+}
+
+# Mapping from canonical BlockRole to PAGE region type
+_ROLE_TO_TYPE: dict[BlockRole | None, str] = {
+    BlockRole.BODY: "paragraph",
+    BlockRole.HEADING: "heading",
+    BlockRole.FOOTNOTE: "footnote",
+    BlockRole.CAPTION: "caption",
+    BlockRole.MARGIN: "marginalia",
+    BlockRole.PAGE_NUMBER: "page-number",
+    BlockRole.HEADER: "header",
+    BlockRole.FOOTER: "footer",
+    BlockRole.OTHER: "other",
+    None: "paragraph",
+}
+
+
+def serialize_page_xml(
+    doc: CanonicalDocument,
+    *,
+    rounding: RoundingStrategy = RoundingStrategy.ROUND,
+    pretty_print: bool = True,
+    encoding: str = "UTF-8",
+) -> bytes:
+    """Serialize a CanonicalDocument to PAGE XML bytes.
+
+    Args:
+        doc: The validated canonical document.
+        rounding: Strategy for coordinate rounding.
+        pretty_print: Whether to indent output.
+        encoding: Output encoding.
+
+    Returns:
+        PAGE XML as bytes.
+    """
+    root = _build_page_tree(doc, rounding)
+    return etree.tostring(
+        root,
+        pretty_print=pretty_print,
+        xml_declaration=True,
+        encoding=encoding,
+    )
+
+
+def serialize_page_xml_to_string(
+    doc: CanonicalDocument,
+    *,
+    rounding: RoundingStrategy = RoundingStrategy.ROUND,
+) -> str:
+    """Serialize to a UTF-8 string (convenience for tests)."""
+    return serialize_page_xml(doc, rounding=rounding).decode("utf-8")
+
+
+# -- Tree construction --------------------------------------------------------
+
+
+def _build_page_tree(
+    doc: CanonicalDocument, rounding: RoundingStrategy
+) -> etree._Element:
+    root = etree.Element(f"{{{PAGE_NS}}}PcGts", nsmap=NSMAP)
+    root.set(f"{{{XSI_NS}}}schemaLocation", SCHEMA_LOCATION)
+    root.set("pcGtsId", doc.document_id)
+
+    # <Metadata>
+    metadata = etree.SubElement(root, f"{{{PAGE_NS}}}Metadata")
+    creator = etree.SubElement(metadata, f"{{{PAGE_NS}}}Creator")
+    creator.text = "XmLLM"
+    created = etree.SubElement(metadata, f"{{{PAGE_NS}}}Created")
+    created.text = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+    last_change = etree.SubElement(metadata, f"{{{PAGE_NS}}}LastChange")
+    last_change.text = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S")
+
+    # One <Page> per canonical page (PAGE XML is per-page, but we handle multi-page)
+    for page in doc.pages:
+        _add_page(root, page, rounding)
+
+    return root
+
+
+def _add_page(
+    parent: etree._Element, page: Page, rounding: RoundingStrategy
+) -> None:
+    page_el = etree.SubElement(parent, f"{{{PAGE_NS}}}Page")
+    page_el.set("imageFilename", page.metadata.get("image_ref", "") if page.metadata else "")
+    page_el.set("imageWidth", str(int(page.width)))
+    page_el.set("imageHeight", str(int(page.height)))
+
+    # <ReadingOrder>
+    if page.reading_order:
+        _add_reading_order(page_el, page)
+
+    # <TextRegion> elements
+    for region in page.text_regions:
+        _add_text_region(page_el, region, rounding)
+
+    # Non-text regions are not in PAGE TextRegion — could add as ImageRegion etc.
+    # For now we skip them (Sprint scope).
+
+
+def _add_reading_order(page_el: etree._Element, page: Page) -> None:
+    ro = etree.SubElement(page_el, f"{{{PAGE_NS}}}ReadingOrder")
+    og = etree.SubElement(ro, f"{{{PAGE_NS}}}OrderedGroup")
+    og.set("id", f"ro_{page.id}")
+    for idx, region_id in enumerate(page.reading_order):
+        ref = etree.SubElement(og, f"{{{PAGE_NS}}}RegionRefIndexed")
+        ref.set("index", str(idx))
+        ref.set("regionRef", region_id)
+
+
+def _add_text_region(
+    parent: etree._Element, region: TextRegion, rounding: RoundingStrategy
+) -> None:
+    tr = etree.SubElement(parent, f"{{{PAGE_NS}}}TextRegion")
+    tr.set("id", region.id)
+    tr.set("type", _ROLE_TO_TYPE.get(region.role, "paragraph"))
+
+    # <Coords>
+    _add_coords(tr, region.geometry.bbox, region.geometry.polygon, rounding)
+
+    # <TextLine> elements
+    for line in region.lines:
+        _add_text_line(tr, line, rounding)
+
+    # Region-level <TextEquiv>
+    _add_text_equiv(tr, region.text)
+
+
+def _add_text_line(
+    parent: etree._Element, line: TextLine, rounding: RoundingStrategy
+) -> None:
+    tl = etree.SubElement(parent, f"{{{PAGE_NS}}}TextLine")
+    tl.set("id", line.id)
+
+    # <Coords>
+    _add_coords(tl, line.geometry.bbox, line.geometry.polygon, rounding)
+
+    # <Word> elements
+    for word in line.words:
+        _add_word(tl, word, rounding)
+
+    # Line-level <TextEquiv>
+    _add_text_equiv(tl, line.text)
+
+
+def _add_word(
+    parent: etree._Element, word: Word, rounding: RoundingStrategy
+) -> None:
+    w = etree.SubElement(parent, f"{{{PAGE_NS}}}Word")
+    w.set("id", word.id)
+
+    if word.confidence is not None:
+        w.set("conf", f"{word.confidence:.2f}")
+
+    # <Coords>
+    _add_coords(w, word.geometry.bbox, word.geometry.polygon, rounding)
+
+    # <TextEquiv>
+    _add_text_equiv(w, word.text)
+
+
+# -- Helpers ------------------------------------------------------------------
+
+
+def _add_coords(
+    parent: etree._Element,
+    bbox: tuple[float, float, float, float],
+    polygon: list[tuple[float, float]] | None,
+    rounding: RoundingStrategy,
+) -> None:
+    """Add a <Coords> element with points attribute.
+
+    Uses the polygon if available, otherwise constructs a rectangle from bbox.
+    """
+    coords = etree.SubElement(parent, f"{{{PAGE_NS}}}Coords")
+
+    if polygon and len(polygon) >= 3:
+        points = polygon
+    else:
+        points = bbox_to_polygon(bbox)
+
+    points_str = " ".join(
+        f"{quantize_value(x, rounding)},{quantize_value(y, rounding)}"
+        for x, y in points
+    )
+    coords.set("points", points_str)
+
+
+def _add_text_equiv(parent: etree._Element, text: str) -> None:
+    """Add <TextEquiv><Unicode>text</Unicode></TextEquiv>."""
+    te = etree.SubElement(parent, f"{{{PAGE_NS}}}TextEquiv")
+    unicode_el = etree.SubElement(te, f"{{{PAGE_NS}}}Unicode")
+    unicode_el.text = text

tests/integration/test_dual_export.py

@@ -0,0 +1,144 @@
+"""Integration test: PaddleOCR → CanonicalDocument → ALTO + PAGE (dual export).
+
+Validates that the same canonical document can be serialized to both
+ALTO XML and PAGE XML, and that both outputs are structurally correct.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from lxml import etree
+
+from src.app.domain.models import RawProviderPayload
+from src.app.domain.models.geometry import GeometryContext
+from src.app.normalization.pipeline import normalize
+from src.app.policies.document_policy import DocumentPolicy
+from src.app.policies.export_policy import check_alto_export, check_page_export
+from src.app.serializers.alto_xml import ALTO_NS, serialize_alto
+from src.app.serializers.page_xml import PAGE_NS, serialize_page_xml
+from src.app.validators.export_eligibility_validator import compute_export_eligibility
+
+
+class TestDualExport:
+    """Full pipeline: raw → canon → validate → ALTO + PAGE."""
+
+    def test_both_exports_from_same_document(self, fixtures_dir: Path) -> None:
+        # 1. Load and normalize
+        with open(fixtures_dir / "paddle_ocr_sample.json") as f:
+            paddle_output = json.load(f)
+
+        raw = RawProviderPayload(
+            provider_id="paddleocr",
+            adapter_id="adapter.word_box_json.v1",
+            runtime_type="local",
+            payload=paddle_output,
+            image_width=2480, image_height=3508,
+        )
+        geo_ctx = GeometryContext(source_width=2480, source_height=3508)
+
+        doc = normalize(
+            raw, family="word_box_json", geometry_context=geo_ctx,
+            document_id="dual_export_test", source_filename="page.png",
+        )
+
+        # 2. Check export eligibility
+        policy = DocumentPolicy()
+        eligibility = compute_export_eligibility(doc, policy)
+
+        alto_decision = check_alto_export(eligibility, policy)
+        page_decision = check_page_export(eligibility, policy)
+
+        assert alto_decision.allowed
+        assert page_decision.allowed
+
+        # 3. Serialize both
+        alto_bytes = serialize_alto(doc)
+        page_bytes = serialize_page_xml(doc)
+
+        assert alto_bytes
+        assert page_bytes
+
+        # 4. Parse both
+        alto_root = etree.fromstring(alto_bytes)
+        page_root = etree.fromstring(page_bytes)
+
+        # 5. Validate ALTO structure
+        alto_strings = alto_root.findall(f".//{{{ALTO_NS}}}String")
+        assert len(alto_strings) == 5
+        assert alto_strings[0].get("CONTENT") == "Bonjour"
+
+        # 6. Validate PAGE structure
+        page_words = page_root.findall(f".//{{{PAGE_NS}}}Word")
+        assert len(page_words) == 5
+        w1_te = page_words[0].find(f".//{{{PAGE_NS}}}Unicode")
+        assert w1_te.text == "Bonjour"
+
+        # 7. Verify same word count in both
+        assert len(alto_strings) == len(page_words)
+
+        # 8. Verify same text content in both
+        alto_texts = [s.get("CONTENT") for s in alto_strings]
+        page_texts = [
+            w.find(f".//{{{PAGE_NS}}}Unicode").text for w in page_words
+        ]
+        assert alto_texts == page_texts
+
+    def test_page_has_coords_alto_has_hpos(self, fixtures_dir: Path) -> None:
+        """PAGE uses Coords/points, ALTO uses HPOS/VPOS/WIDTH/HEIGHT."""
+        with open(fixtures_dir / "paddle_ocr_sample.json") as f:
+            paddle_output = json.load(f)
+
+        raw = RawProviderPayload(
+            provider_id="paddleocr", adapter_id="v1", runtime_type="local",
+            payload=paddle_output, image_width=2480, image_height=3508,
+        )
+        geo_ctx = GeometryContext(source_width=2480, source_height=3508)
+
+        doc = normalize(
+            raw, family="word_box_json", geometry_context=geo_ctx,
+            document_id="coord_test",
+        )
+
+        alto_root = etree.fromstring(serialize_alto(doc))
+        page_root = etree.fromstring(serialize_page_xml(doc))
+
+        # ALTO: String has HPOS, VPOS, WIDTH, HEIGHT
+        alto_s = alto_root.find(f".//{{{ALTO_NS}}}String")
+        assert alto_s.get("HPOS") is not None
+        assert alto_s.get("VPOS") is not None
+        assert alto_s.get("WIDTH") is not None
+        assert alto_s.get("HEIGHT") is not None
+
+        # PAGE: Word has Coords with points
+        page_w = page_root.find(f".//{{{PAGE_NS}}}Word")
+        coords = page_w.find(f"{{{PAGE_NS}}}Coords")
+        assert coords is not None
+        points = coords.get("points")
+        assert points is not None
+        # Points should be polygon (4 vertices from PaddleOCR)
+        parts = points.split()
+        assert len(parts) == 4
+
+    def test_page_has_reading_order(self, fixtures_dir: Path) -> None:
+        with open(fixtures_dir / "paddle_ocr_sample.json") as f:
+            paddle_output = json.load(f)
+
+        raw = RawProviderPayload(
+            provider_id="paddleocr", adapter_id="v1", runtime_type="local",
+            payload=paddle_output, image_width=2480, image_height=3508,
+        )
+        geo_ctx = GeometryContext(source_width=2480, source_height=3508)
+
+        doc = normalize(
+            raw, family="word_box_json", geometry_context=geo_ctx,
+            document_id="ro_test",
+        )
+
+        page_root = etree.fromstring(serialize_page_xml(doc))
+        ro = page_root.find(f".//{{{PAGE_NS}}}ReadingOrder")
+        assert ro is not None
+        refs = ro.findall(f".//{{{PAGE_NS}}}RegionRefIndexed")
+        assert len(refs) >= 1
+        assert refs[0].get("regionRef") == "tb1"

tests/unit/test_page_xml_serializer.py

@@ -0,0 +1,340 @@
+"""Tests for the PAGE XML serializer."""
+
+from __future__ import annotations
+
+from lxml import etree
+
+from src.app.domain.models import (
+    AltoReadiness,
+    CanonicalDocument,
+    EvidenceType,
+    Geometry,
+    GeometryStatus,
+    Hyphenation,
+    Page,
+    PageXmlReadiness,
+    Provenance,
+    ReadinessLevel,
+    Source,
+    TextLine,
+    TextRegion,
+    Word,
+)
+from src.app.domain.models.status import BlockRole, InputType
+from src.app.serializers.page_xml import PAGE_NS, serialize_page_xml, serialize_page_xml_to_string
+
+
+def _prov(ref: str = "$.test") -> Provenance:
+    return Provenance(
+        provider="test", adapter="test.v1", source_ref=ref,
+        evidence_type=EvidenceType.PROVIDER_NATIVE,
+    )
+
+
+def _geo(x: float = 100, y: float = 200, w: float = 300, h: float = 50) -> Geometry:
+    return Geometry(bbox=(x, y, w, h), status=GeometryStatus.EXACT)
+
+
+def _geo_with_polygon() -> Geometry:
+    return Geometry(
+        bbox=(100, 200, 300, 50),
+        polygon=[(98, 205), (402, 195), (404, 245), (100, 255)],
+        status=GeometryStatus.EXACT,
+    )
+
+
+def _simple_doc() -> CanonicalDocument:
+    """One-page doc with one region, one line, two words."""
+    return CanonicalDocument(
+        document_id="doc_page_test",
+        source=Source(input_type=InputType.IMAGE, filename="test.png"),
+        pages=[
+            Page(
+                id="p1", page_index=0, width=2480, height=3508,
+                alto_readiness=AltoReadiness(level=ReadinessLevel.FULL),
+                page_readiness=PageXmlReadiness(level=ReadinessLevel.FULL),
+                reading_order=["tb1"],
+                text_regions=[
+                    TextRegion(
+                        id="tb1", role=BlockRole.BODY,
+                        geometry=_geo(100, 200, 1200, 900),
+                        lang="fra", provenance=_prov(),
+                        lines=[
+                            TextLine(
+                                id="tl1",
+                                geometry=_geo(110, 220, 1100, 42),
+                                lang="fra", provenance=_prov(),
+                                words=[
+                                    Word(id="w1", text="Bonjour",
+                                         geometry=_geo(110, 220, 90, 40),
+                                         lang="fra", confidence=0.96,
+                                         provenance=_prov()),
+                                    Word(id="w2", text="monde",
+                                         geometry=_geo(220, 220, 80, 40),
+                                         lang="fra", confidence=0.94,
+                                         provenance=_prov()),
+                                ],
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+        ],
+    )
+
+
+class TestPageXmlSerialization:
+    def test_produces_valid_xml(self) -> None:
+        doc = _simple_doc()
+        xml_bytes = serialize_page_xml(doc)
+        root = etree.fromstring(xml_bytes)
+        assert root.tag == f"{{{PAGE_NS}}}PcGts"
+
+    def test_has_metadata(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        meta = root.find(f"{{{PAGE_NS}}}Metadata")
+        assert meta is not None
+        creator = meta.find(f"{{{PAGE_NS}}}Creator")
+        assert creator is not None
+        assert creator.text == "XmLLM"
+
+    def test_pcgts_id(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        assert root.get("pcGtsId") == "doc_page_test"
+
+    def test_page_dimensions(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        page = root.find(f"{{{PAGE_NS}}}Page")
+        assert page is not None
+        assert page.get("imageWidth") == "2480"
+        assert page.get("imageHeight") == "3508"
+
+    def test_reading_order(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        ro = root.find(f".//{{{PAGE_NS}}}ReadingOrder")
+        assert ro is not None
+        og = ro.find(f"{{{PAGE_NS}}}OrderedGroup")
+        assert og is not None
+        refs = og.findall(f"{{{PAGE_NS}}}RegionRefIndexed")
+        assert len(refs) == 1
+        assert refs[0].get("index") == "0"
+        assert refs[0].get("regionRef") == "tb1"
+
+    def test_text_region_exists(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        tr = root.find(f".//{{{PAGE_NS}}}TextRegion")
+        assert tr is not None
+        assert tr.get("id") == "tb1"
+        assert tr.get("type") == "paragraph"
+
+    def test_text_region_coords(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        tr = root.find(f".//{{{PAGE_NS}}}TextRegion")
+        coords = tr.find(f"{{{PAGE_NS}}}Coords")
+        assert coords is not None
+        points = coords.get("points")
+        assert points is not None
+        # bbox (100,200,1200,900) → rectangle 4 points
+        parts = points.split()
+        assert len(parts) == 4
+        assert parts[0] == "100,200"  # top-left
+
+    def test_text_line_exists(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        tl = root.find(f".//{{{PAGE_NS}}}TextLine")
+        assert tl is not None
+        assert tl.get("id") == "tl1"
+
+    def test_words_exist(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        words = root.findall(f".//{{{PAGE_NS}}}Word")
+        assert len(words) == 2
+
+    def test_word_text_equiv(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        words = root.findall(f".//{{{PAGE_NS}}}Word")
+        te = words[0].find(f"{{{PAGE_NS}}}TextEquiv")
+        assert te is not None
+        unicode_el = te.find(f"{{{PAGE_NS}}}Unicode")
+        assert unicode_el is not None
+        assert unicode_el.text == "Bonjour"
+
+    def test_word_confidence(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        words = root.findall(f".//{{{PAGE_NS}}}Word")
+        assert words[0].get("conf") == "0.96"
+
+    def test_line_text_equiv(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        tl = root.find(f".//{{{PAGE_NS}}}TextLine")
+        te = tl.find(f"{{{PAGE_NS}}}TextEquiv")
+        unicode_el = te.find(f"{{{PAGE_NS}}}Unicode")
+        assert unicode_el.text == "Bonjour monde"
+
+    def test_region_text_equiv(self) -> None:
+        doc = _simple_doc()
+        root = etree.fromstring(serialize_page_xml(doc))
+        tr = root.find(f".//{{{PAGE_NS}}}TextRegion")
+        # Region TextEquiv is after lines
+        te_all = tr.findall(f"{{{PAGE_NS}}}TextEquiv")
+        assert len(te_all) == 1
+        unicode_el = te_all[0].find(f"{{{PAGE_NS}}}Unicode")
+        assert unicode_el.text == "Bonjour monde"
+
+    def test_string_output(self) -> None:
+        doc = _simple_doc()
+        xml_str = serialize_page_xml_to_string(doc)
+        assert "<?xml version=" in xml_str
+        assert "Bonjour" in xml_str
+        assert "PcGts" in xml_str
+
+
+class TestPageXmlPolygon:
+    def test_uses_polygon_when_available(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc_poly",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[Page(
+                id="p1", page_index=0, width=2480, height=3508,
+                text_regions=[TextRegion(
+                    id="tb1", geometry=_geo_with_polygon(), provenance=_prov(),
+                    lines=[TextLine(
+                        id="tl1", geometry=_geo_with_polygon(), provenance=_prov(),
+                        words=[Word(
+                            id="w1", text="test",
+                            geometry=_geo_with_polygon(), provenance=_prov(),
+                        )],
+                    )],
+                )],
+            )],
+        )
+        root = etree.fromstring(serialize_page_xml(doc))
+        word = root.find(f".//{{{PAGE_NS}}}Word")
+        coords = word.find(f"{{{PAGE_NS}}}Coords")
+        points = coords.get("points")
+        # Should use the polygon, not a rectangle from bbox
+        parts = points.split()
+        assert len(parts) == 4
+        assert parts[0] == "98,205"  # first polygon point
+
+    def test_falls_back_to_bbox_rectangle(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc_rect",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[Page(
+                id="p1", page_index=0, width=1000, height=1000,
+                text_regions=[TextRegion(
+                    id="tb1", geometry=_geo(10, 20, 100, 50), provenance=_prov(),
+                    lines=[TextLine(
+                        id="tl1", geometry=_geo(10, 20, 100, 50), provenance=_prov(),
+                        words=[Word(
+                            id="w1", text="test",
+                            geometry=_geo(10, 20, 100, 50), provenance=_prov(),
+                        )],
+                    )],
+                )],
+            )],
+        )
+        root = etree.fromstring(serialize_page_xml(doc))
+        word = root.find(f".//{{{PAGE_NS}}}Word")
+        coords = word.find(f"{{{PAGE_NS}}}Coords")
+        points = coords.get("points")
+        parts = points.split()
+        assert len(parts) == 4
+        # bbox (10,20,100,50) → rectangle: top-left, top-right, bottom-right, bottom-left
+        assert parts[0] == "10,20"
+        assert parts[1] == "110,20"
+        assert parts[2] == "110,70"
+        assert parts[3] == "10,70"
+
+
+class TestPageXmlRoles:
+    def test_heading_role(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc_roles",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[Page(
+                id="p1", page_index=0, width=1000, height=1000,
+                text_regions=[TextRegion(
+                    id="tb1", role=BlockRole.HEADING,
+                    geometry=_geo(), provenance=_prov(),
+                    lines=[TextLine(
+                        id="tl1", geometry=_geo(), provenance=_prov(),
+                        words=[Word(id="w1", text="Title", geometry=_geo(), provenance=_prov())],
+                    )],
+                )],
+            )],
+        )
+        root = etree.fromstring(serialize_page_xml(doc))
+        tr = root.find(f".//{{{PAGE_NS}}}TextRegion")
+        assert tr.get("type") == "heading"
+
+    def test_footnote_role(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc_fn",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[Page(
+                id="p1", page_index=0, width=1000, height=1000,
+                text_regions=[TextRegion(
+                    id="tb1", role=BlockRole.FOOTNOTE,
+                    geometry=_geo(), provenance=_prov(),
+                    lines=[TextLine(
+                        id="tl1", geometry=_geo(), provenance=_prov(),
+                        words=[Word(id="w1", text="Note", geometry=_geo(), provenance=_prov())],
+                    )],
+                )],
+            )],
+        )
+        root = etree.fromstring(serialize_page_xml(doc))
+        tr = root.find(f".//{{{PAGE_NS}}}TextRegion")
+        assert tr.get("type") == "footnote"
+
+
+class TestPageXmlMultipleRegions:
+    def test_reading_order_multiple(self) -> None:
+        doc = CanonicalDocument(
+            document_id="doc_multi",
+            source=Source(input_type=InputType.IMAGE),
+            pages=[Page(
+                id="p1", page_index=0, width=2000, height=3000,
+                reading_order=["tb1", "tb2"],
+                text_regions=[
+                    TextRegion(
+                        id="tb1", role=BlockRole.HEADING,
+                        geometry=_geo(0, 0, 2000, 200), provenance=_prov(),
+                        lines=[TextLine(id="tl1", geometry=_geo(0, 0, 2000, 40), provenance=_prov(),
+                            words=[Word(id="w1", text="Title", geometry=_geo(0, 0, 200, 40), provenance=_prov())])],
+                    ),
+                    TextRegion(
+                        id="tb2", role=BlockRole.BODY,
+                        geometry=_geo(0, 250, 2000, 2500), provenance=_prov(),
+                        lines=[TextLine(id="tl2", geometry=_geo(0, 250, 2000, 40), provenance=_prov(),
+                            words=[Word(id="w2", text="Body", geometry=_geo(0, 250, 200, 40), provenance=_prov())])],
+                    ),
+                ],
+            )],
+        )
+        root = etree.fromstring(serialize_page_xml(doc))
+
+        # Two text regions
+        regions = root.findall(f".//{{{PAGE_NS}}}TextRegion")
+        assert len(regions) == 2
+
+        # Reading order with 2 refs
+        refs = root.findall(f".//{{{PAGE_NS}}}RegionRefIndexed")
+        assert len(refs) == 2
+        assert refs[0].get("regionRef") == "tb1"
+        assert refs[0].get("index") == "0"
+        assert refs[1].get("regionRef") == "tb2"
+        assert refs[1].get("index") == "1"