0008. Pages are an addressing layer, not the storage unit

• Status: Accepted
• Date: 2026-10-01 (recorded with @nextgensoftwares/folio-sync, commit 0544841)

Context

Users think in pages ("open at page 3,200", "the scrollbar should show 7,314 pages before anything loads"), and the previous system cached page boundaries. It is tempting to store and serve documents by page. But page boundaries move with every edit that changes a block's height, and with every theme or font change: storing by page would re-split and invalidate storage on each keystroke, and two clients with different fonts would disagree about what "page 12" holds.

Decision

Documents are stored and served by chunk (runs of top-level blocks starting at chapters, see 0006). Pages are an addressing layer computed by layout. After laying out, a client reports which page each chunk starts on (layoutReport); the server attaches those ranges to the next manifest (pageStart, pages, estimatedPages). Clients use them to size the scrollbar before loading and to open at any page (chunkForPage): because chunks start at chapters, the target chunk paginates on its own while the rest loads.

Consequences

• Storage and caching are independent of layout: a theme change invalidates no stored data.
• Page estimates can be stale (they come from the last reported layout) and are treated as hints; the real page numbers always come from the local layout.
• Opening at a page is exact for chapter-aligned chunks. A chapter longer than maxChunkBlocks is hard-cut, so its later chunks start mid-chapter and their standalone pagination is approximate until the full document is loaded.
• toPageBoundaries still exposes page → block ranges for hosts that need them (e.g. a legacy page index), derived from layout, never stored as truth.