fix(documents): never emit a page that has no content

A block that fits in no column of a given page shape produced a blank image
on every remaining page, each carrying an annotation claiming content the
image did not have - and the block stayed at the head of the queue, so the
loop ran to max_pages. The block is now dropped: a page with a confident
label and no ink is worse than a page that is missing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: hBouanane

src/ocrsmith/core/documents/flow.py

@@ -107,7 +107,6 @@ def iter_pages(
 
         page_number = 0
         while pending and page_number < max_pages:
-            page_number += 1
             image = self._new_canvas(spec, background)
             regions: list[Region] = []
 
@@ -116,14 +115,25 @@ def iter_pages(
             if footer_template and spec.footer_height:
                 block = ContentBlock(
                     RegionType.PAGE_NUMBER,
-                    text=str(footer_template).replace("{page}", str(page_number)),
+                    text=str(footer_template).replace("{page}", str(page_number + 1)),
                 )
                 regions.extend(self._draw_band(image, block, spec.footer_box, typography, direction, rng))
+            furniture = len(regions)
 
             pending = self._fill_columns(
                 image, pending, spec, typography, direction, regions, table_style, rng
             )
 
+            if len(regions) == furniture:
+                # Nothing could be placed anywhere on this page, so the leading block does
+                # not fit *any* column of this page shape. Emitting the page would produce
+                # a blank image with a confident label, and keeping the block would loop
+                # until max_pages; dropping it is the only honest option.
+                if pending:
+                    pending.pop(0)
+                continue
+
+            page_number += 1
             page = Page(spec.width, spec.height, tuple(regions), direction).clipped()
             yield RenderedPage(image, page, page_number)
 

tests/test_documents_blank_pages.py

@@ -0,0 +1,73 @@
+"""A page that describes nothing must never be emitted.
+
+A block that fits in no column of a given page shape used to produce a blank image on
+every remaining page, each carrying an annotation that claimed content the image did not
+have. The block is dropped instead, because a page with a confident label and no ink is
+worse than a page that is missing.
+"""
+
+import random
+from pathlib import Path
+
+import pytest
+
+from ocrsmith.core.documents import (
+    DocumentBuilder,
+    DocumentRenderer,
+    PageSpec,
+    TypographySampler,
+)
+
+FONT_DIR = Path(__file__).resolve().parents[1] / "assets" / "fonts"
+
+pytestmark = pytest.mark.skipif(not FONT_DIR.exists(), reason="bundled fonts unavailable")
+
+
+@pytest.fixture
+def typography():
+    fonts = sorted(FONT_DIR.glob("NotoSansArabic-*.ttf"))
+    return TypographySampler(fonts, body_size_range=(16, 18)).sample(random.Random(3))
+
+
+@pytest.fixture
+def renderer():
+    return DocumentRenderer()
+
+
+def test_every_emitted_page_carries_at_least_one_region(renderer, typography):
+    content = DocumentBuilder().title("Title").paragraph("Body text goes here.").build()
+
+    pages = renderer.render(content, PageSpec.from_paper("a6", dpi=90), typography, max_pages=10)
+
+    assert pages
+    for page in pages:
+        assert page.page.regions
+
+
+def test_an_unplaceable_block_is_dropped_rather_than_blanking_pages(renderer, typography):
+    # A table far too wide for the column fits nowhere, and tables never split.
+    rows = [[f"column-{index}" * 4 for index in range(12)] for _ in range(3)]
+    content = DocumentBuilder().paragraph("Readable prose.").table(rows).build()
+
+    pages = renderer.render(content, PageSpec.from_paper("a6", dpi=80), typography, max_pages=10)
+
+    assert pages
+    assert all(page.page.regions for page in pages)
+
+
+def test_page_numbers_stay_dense_when_a_block_is_dropped(renderer, typography):
+    rows = [[f"wide-{index}" * 5 for index in range(10)] for _ in range(2)]
+    content = DocumentBuilder().paragraph("First.").table(rows).paragraph("Second.").build()
+
+    pages = renderer.render(content, PageSpec.from_paper("a6", dpi=80), typography, max_pages=10)
+
+    assert [page.number for page in pages] == list(range(1, len(pages) + 1))
+
+
+def test_a_document_of_nothing_but_unplaceable_content_yields_no_pages(renderer, typography):
+    rows = [[f"enormous-{index}" * 8 for index in range(14)]]
+    content = DocumentBuilder().table(rows).build()
+
+    pages = renderer.render(content, PageSpec.from_paper("a6", dpi=80), typography, max_pages=10)
+
+    assert pages == []