Lazy loading: render the visible window and fetch the rest over HTTP as the reader scrolls

[andiwand]

Translation is all-or-nothing today: html::translate builds a service whose every view writes its whole content in one write_html pass, and that pass is what a big file dies in — #762 is a 1.4 MB ods taking 1.2 GB before any view exists. The html limits do not help, because spreadsheet_limit / spreadsheet_cell_limit bound what is written, not what is read to get there, and cutting content is a compromise anyway (#740, #757).

For anything large — a spreadsheet with 100k rows, a 900 page pdf, a deck of 200 slides, a 50 MB log file — the reader only ever looks at a screenful. We already ship an HTTP server (odr::HttpServer, cli/src/server.cpp) that serves a connected HtmlService by path, and the views already ship their own scripts (viewport, search). That is most of the substrate for rendering the visible window plus a safety margin up front, and fetching the rest on the fly as the reader scrolls.

What exists to build on

• HtmlConfig::page_range_begin / page_range_end — the only partial render there is: static, whole-service, honored only by the pdf pipeline.
• HtmlFragmentView (internal/html/document.cpp) — a document is already cut into fragments, one per sheet / slide / drawing page, each its own view and its own file, with document.html writing all of them. Coarse laziness at view granularity, and the place a finer one attaches.
• HtmlView::sheet_cut() — a view already reports content vs rendered extent, i.e. the vocabulary for "what is there" vs "what I gave you".
• HttpServer routes /file/<prefix>/<path> into HtmlService::exists / mimetype / write / write_html, so a fragment route is an addition rather than a new server.
• internal/html/frontend.* writes the shipped css/js and can locate them as resources instead of embedding — where a loader script would go.

Which content, and on what axis

Every format wants this eventually; they differ in how much structure is already there to cut along.

content	today	region axis
text files (internal/html/text_file.cpp)	one text.html, the whole text held as a std::string and streamed twice — once for the line-number gutter, once for the body	line ranges. Closest thing to a sheet's rows, and the only shape here with no element tree in the way at all
spreadsheets (ods/xlsx/xls/csv)	one fragment per sheet; each writes every cell in one pass	row ranges, possibly column ranges too for very wide sheets
pdf	one view per page, page_range_* already renders a subset	page ranges
presentations (odp/pptx/ppt) and drawings (odg)	already one fragment per slide / page, so a view is already a screenful	slide / page index — the split exists, but building any one fragment still parses the whole document, and a host scrolling a deck continuously still pulls every fragment
text documents (odt/docx/doc/rtf/md)	a single document.html for the whole thing, no split at all	block index, or page ranges when text_document_margin renders pages. The hardest: reflowing content has no coordinate before it is laid out

Text files are the cheapest end-to-end proof — trivial region axis, no engine work — while spreadsheets and pdf are where the pain actually is, and text documents are where the geometry problem below has no easy answer.

Sketch

Three layers, roughly in this order:

1. Translation engine — render a region without parsing the whole document.
A view needs to be able to write rows [a, b), lines [a, b), or pages [a, b) at a cost proportional to the region rather than the document. Today every engine builds its full element registry up front, so this is the deep part of the work: the sheet path in particular needs the row/cell parse to be skippable and resumable, and the element adapters need to admit random access into a sheet or page without walking everything before it. For presentations and drawings the fragment split already gives the axis, and the work is that building one fragment must stop parsing the other 199. Whatever bounds memory here also fixes #762 as a side effect.

2. HtmlService / HtmlView API — ask a view for a piece of itself.
Something like a region descriptor (line / row / block / page range) plus a write_html variant that takes one, and metadata for the whole extent so a client knows what it may ask for. The skeleton written up front has to carry stable anchors the fragments splice into, and enough geometry (row heights, page boxes) that scroll position is stable before a fragment arrives — a lazily grown document that resizes under the reader is worse than a cut one. bring_offline must keep meaning "materialize all of it".

3. HTTP + JS — a loader.
A fragment route on the server, and a shipped script that watches the viewport, requests the regions it needs with a margin ahead of the scroll direction, splices them in, and evicts what is far away. It should degrade to today's behaviour when nothing serves it, since the same output is written to disk and opened as a file.

Things to decide

• Region vocabulary. Lines, rows, pages, slides and blocks are five axes; is one generic descriptor right, or a per-shape one?
• Geometry of reflowing content. Rows, lines and pages can be sized before they are rendered, so a placeholder holds the right space. A text document's blocks cannot — the placeholder is a guess, and correcting it moves the reader. May mean text documents only lazy-load in the text_document_margin page shape, at least at first.
• Where the state lives. A service holding a partially parsed document across requests is a cache with a lifetime and an eviction policy, and HtmlService is currently stateless per request beyond warmup().
• Hosts without an HTTP server. The bindings (wasm, jni, apple) render into a web view, and only some of them will want to run a server; a fragment fetch may need to go through a host-supplied callback instead, which argues for the fragment API being the primitive and HTTP being one transport over it.
• Editing / back-translation. editable output and generateDiff() assume the whole document is in the page; a lazily loaded one is not.
• Search. odr.search() searches the DOM, which will no longer hold everything.

Scope

Big, and worth splitting. Text files are the smallest thing that exercises all three layers and could go first as the shape of the API. Layer 1 then lands per engine, starting with ods/xlsx and pdf (the formats that hurt), with presentations and drawings following as "parse one fragment, not the deck". Text documents last, once the geometry question has an answer.

[andiwand]

Naming: region for the request, fragment for the payload

Picking up "Region vocabulary" under Things to decide, plus a collision the issue text walks into: it uses fragment for both the existing per-sheet/slide split and the new lazily-fetched piece, sometimes in the same paragraph ("a fragment route", "building one fragment must stop parsing the other 199").

shard was considered and rejected. A shard is a horizontal partition that is the canonical storage form of the data, keyed and distributed, with no inherent ordering — you look up the shard holding a key. These pieces are the opposite on the axes that matter: contiguous ranges along one ordered dimension, derived on demand from a document that still exists whole, fetched precisely because they neighbour what is on screen ("a margin ahead of the scroll direction"). Adjacency and ordering are the mechanism, and shard carries neither. It also cannot express the row × column case noted for very wide sheets.

fragment is available, contrary to first appearances

• HtmlResourceType::html_fragment (src/odr/html.hpp:30) is declared but never constructed. The only resource types actually produced in src/ are css, js, image, media, file. It is bound in python/src/bind_html.cpp:20 and wasm/src/wasm_core.cpp:95 and nowhere else. It arrived with the header merge (1dd0231, 2025-06-09) and has had no producer since — a placeholder that reads as reserved for approximately this.
• HtmlFragmentBase (internal/html/document.cpp:203) is internal, and is not a view: it is the body writer that HtmlFragmentView wraps and HtmlDocumentView concatenates. Its own doc comment already calls it "this one view". Free to rename.

Proposal

Two words, split along a line the design already has — the descriptor and the thing it returns are not the same object:

• region — what a client asks for. A range on an axis (line / row / page / slide / block), the parameter to the write_html variant in layer 2, and the query the layer-3 route carries. Already the issue's own prose ("a region descriptor", "render a region without parsing the whole document").
• fragment — what comes back. HTML spliced at a stable anchor; the HTTP response body; the word the loader script is written in, since DocumentFragment / createContextualFragment is the web platform's own term for "markup of any size that you splice in". This finally gives HtmlResourceType::html_fragment a producer.

Consequence: rename the existing HtmlFragmentBase / HtmlFragmentView to say view (or a view's body), which is what they are, freeing fragment for the granularity that actually crosses the wire.

Notes on the runners-up: tile would be the pick if the pieces turn out to be a fixed pre-cut grid rather than arbitrary client-chosen ranges — it is the established word for fetch-visible-plus-margin-and-evict in map and PDF viewers, and it survives 2D. chunk is already spoken for at the byte layer (rtf_tokenizer, byte_stream_util, iwork snappy). region collides mildly with the geometric sense in the pdf internals (pdf_graphics_state.hpp, pdf_jbig2.*), and the two meet in internal/html/pdf_file.cpp — different layers, but worth knowing.

Whichever words win, they land in four places at once and one of them is public: the C++ API, the HTTP route, the shipped JS, and HtmlResourceType, which the bindings mirror by ordinal. Worth settling before layer 2 rather than after. They should also sit beside the vocabulary already there for this exact distinction — HtmlSheetCut{content, rendered} and sheet_cut(). "The region a view rendered of the sheet's content extent" composes.