The page is our atomic unit, but it isn't the unit of meaning

[gbergengruen]

The page is our atomic unit, but it isn't the unit of meaning

TL;DR

I set out to check whether page-sectioning sends one page or several to the LLM. It sends one. Rather than argue from the code, we measured a real book end to end.

In a real Spanish novel, 1 in 3 page boundaries splits a sentence — and the resulting fragments are translated and simplified independently, by design.

• Easy Read is the worst affected step, not translation. It fabricates content to close fragments it cannot resolve. At one boundary it turned "Dá-lhe o" into the invented sentence "Diga."
• Translation breaks in 3 of 20 split boundaries, in two specific mechanisms: preposition+article contractions, and idioms split mid-phrase.
• Merging the two pages fixes it. We proved this with a controlled second run.
• One hypothesis I started with is not supported and I'm retracting it: split activities are not a real problem in our workbooks. Zero real cases in 115 boundaries.

Everything below is measured on real books. Method and caveats are in §7.

---

1. What we measured, and how

Script: scripts/measure-page-boundaries.mjs (read-only, no LLM calls). For every pair of consecutive pages it takes the last text leaf of page N and the first of page N+1 and scores:

Signal	Test
S1 sentence split	the pipeline's own isContinuation heuristic, ported verbatim from packages/pdf/src/positioned-text.ts:918-923 — previous page ends with a hyphen, or the next starts with a lowercase letter
S2 open sentence	previous page's last prose leaf has no terminal punctuation
S4 orphan activity	an activity_* section on both sides, where the continuation has no activity_instruction but the previous side does

Pruned sections, pruned nodes, and page furniture (header / footer / page_number) are excluded — without that, running headers make every boundary look broken.

Books. The prose case is Uruguay_Ceibal_1930-el-viaje — a Ceibal educational novel, Spanish (es-UY), mode: dynamic. We ran pages 147-208, a 62-page span chosen because it contains no chapter breaks, so every boundary is genuine mid-narrative. Translation target pt-BR. Two workbooks (cuaderno3, cuaderno5) serve as controls.

---

2. For prose, the chunk is the page

prompts/page_sectioning.liquid:161-164, in dynamic mode:

Do NOT split in any of these cases:
- A page with a SINGLE MECHANIC, regardless of how many questions/items it contains.
- A page with no activities — always one section.
- Separation by visual whitespace, headings, or topic alone — not a reason to split.

Both split conditions concern activity mechanics (:148, :157). A prose page has neither. Chapter breaks, scene breaks and blank-line separators are explicit non-reasons.

Measured, on the narrative window:

Book	pages	sections
1930 pages 147-208, unmerged	61	61
1930 pages 147-208, merged run	50	50

Exactly one section per page, no exceptions. In the packaged bundle of the original 25-page run, 18 of 19 files are pgNNN_sec001 (page 23 is the sole page that produced two sections).

So the section boundary is the page boundary, and the page boundary is wherever the typesetter's text happened to run out.

And below sectioning there is nothing durable

Leaves are sentences (page_sectioning.liquid:122). Paragraphs exist only as an LLM-chosen container (config.yaml:8-9) that no code reads — grep finds "paragraph" only as a font scope. Containers don't even carry an id (_render_node.liquid:25; only leaves get data-id).

A continuation heuristic exists (positioned-text.ts:918-923) but is confined within a block, within a page (:201), and on spreads deliberately per-side (:262-265). Its only consumer is fixed-layout-rendering.ts:126-136, and no book uses fixed layout.

The page boundary is then re-hardened at every layer below: one HTML file per section (packaging/web.ts:355), one XHTML spine item per page (packaging/epub.ts:171-234), one SMIL overlay per page (smil.ts:58-98), and audio that stops and resets at page end (useAudioPlayer.ts:249-257 — the code comment says "a TTS index from page N has no meaning on page N+1").

---

3. How often it happens

20 of 60 boundaries (33%) split a sentence. 19 of 60 (32%) leave an open sentence.

Examples, verbatim:

Boundary	Page ends	Next page starts
201→202	"Por"	"lo que leí, se trata de alguien…"
186→187	"Le da lo"	"mismo cómo se llame esa jovencita…"
155→156	"…su camarada le"	"dio un puñetazo…"
163→164	"…cantando en el"	"puente del Sena."
205→206	"Sí, hay"	"varias anotaciones de abril…"

A page whose last word is "Por" is not an edge case we can wave away — it is 1 of 20 in a 62-page sample.

---

4. What it costs — measured, not predicted

4a. Translation: 3 of 20 broken

Translation gets one call per page and its entire context is {...languageContext, texts} (translation.ts:75-78). prompts/translation.liquid rule 1 says "Translate each text segment independently" and rule 7 "Do not add, remove, or merge text segments". There is no context field to fix this with.

Boundary	Portuguese produced	Why it's wrong
163→164	"…cantando no" / "ponte do Sena."	Must be na ponte. Spanish puente is masculine, Portuguese ponte is feminine. The model contracted en el → no without knowing the noun overleaf changes gender between the two languages.
186→187	"Dá-lhe o" / "mesmo como…"	The idiom Le da lo mismo ("he couldn't care less") became word-salad reading as an imperative "give him the".
201→202	"Por" / "o que li…"	Por o que li is ungrammatical — Portuguese requires the contraction Pelo que li.

17 of 20 survived, and that matters: Spanish→Portuguese is the most forgiving pair we could have picked. Adjectives already carry gender and number, so "não são questões" / "ocas." came out correct. 15% is a floor, not a typical rate. A more distant target (English, Albanian) would break considerably more.

4b. Easy Read: the worst affected step

Easy Read runs after translation on the Portuguese text. Its prompt promises context it structurally cannot have — easy_read.liquid:55-58 says "You will also receive the full text of the section as context. Use the context to understand references, omitted subjects, continuity…", but section_text is built only from that block's own entries (easy-read.ts:217), and a block is one section of one page. Set against :64 ("Inventing new information… is forbidden") and :69 ("use the context to deduce the exact referent"), a page boundary is an instruction collision with no valid resolution.

The model resolves it by inventing. Roughly 8-11 of 19 page-final fragments show visible damage, in three categories:

Fabrication

Page	Original	Easy Read produced
186	"Dá-lhe o"	"Diga." — an invented imperative, from nothing
184	"Conta até dez e se põe"	"Ele conta até 10 e começa." — invents "starts", loses "stands up"
172	"Terá tempo para pensar no que o espera"	invents "o senhor" as a subject

False termination — pg205 "Sim, há" → "Sim, há.", pg189 → "exatamente." Adding a full stop asserts the sentence is complete when it continues overleaf.

Pass-through — pg155, pg163, pg174, pg191 and pg201 are left as dangling fragments. On page 201 the entire Easy Read content is the word "Por".

This is the feature built for readers least able to recover from incoherence, and it is the one most affected.

4c. Read-aloud and SMIL — derivable without running TTS

The TTS unit is one data-id leaf (text-catalog.ts:45-71), there is no terminal-punctuation check and no SSML in speech.ts, and the page-batched path explicitly joins entries with \n\n so the model treats each as its own sentence (speech-batch.ts:194-199). Because the split sentence is two leaves and the merged one is a single leaf, the unmerged book necessarily produces two clips with a falling cadence on "Por", and the merged book one. SMIL highlighting terminates at the fragment (smil.ts:58); playback stops at page end.

4d. Pruning creates adjacencies that never existed

The original 25-page run packages to 19 files — separator pages are dropped — so the reader goes straight from page 011's text to page 013's with no cue. Measuring raw page order rather than reading order would have understated the split rate (21% vs 29% on that sample).

---

5. Proof that merging fixes it

We re-ran the identical page range with spread_pairs set at the flagged boundaries, so both halves arrive in a single sectioning call and a single translation call — the condition any "give the model neighbour context" fix would create.

	Unmerged	Merged
Sectioning	two leaves on two pages	one leaf: "Le da lo mismo cómo se llame esa jovencita ni lo que puede estar pensando Tomassino."
Translation	"Dá-lhe o" + "mesmo como…"	"Tanto faz para ele como se chama essa mocinha…" — correct idiom
Easy Read	"Diga." + "nem como essa mocinha se chama…"	"Para o Romeno, tanto faz como essa moça se chama…"
Translation (201/202)	"Por" + "o que li"	"Pelo que li, trata-se de alguém muito conhecido…"

Both covered cases fixed, at every stage.

Two things worth noticing. First, the merged Easy Read is better than its source — it resolved the pronoun to "Para o Romeno", which is exactly what its prompt promises and what it could actually do once the sentence was intact. Second, and more important for choosing a fix: the repair happened at the leaf. Sectioning emitted the whole sentence as one leaf, and everything downstream inherited that. The defect was never only "translation lacked context" — the leaf boundary itself was wrong.

---

6. What is not a problem — a retraction

I began this review believing split activities were the headline problem, because the code path is alarming: an orphan half-activity gets its own answer key from a second LLM call seeing only that section, and activity_multiple_choice_answers.liquid:35 instructs it to emit all-false when undeterminable. With an all-false key, allCorrect is unreachable (activity-quiz.ts:565-575), so Submit can never become Next — a learner stranded on a page of instruction-less questions.

The data does not support this happening. Across cuaderno3 and cuaderno5, S4 fired on 2 of 115 boundaries and both are false positives — the continuation began with its own heading ("¿Cuáles son los sucesos?", "Apuntes"). Activities in our workbooks do not span page breaks; each page's activity carries its own instruction.

Related: the workbooks show no prose problem either — S1 was 0 of 20 in cuaderno3 and 1 of 95 in cuaderno5. This is a narrative-prose issue specifically.

The broken-Submit path remains real code and worth hardening cheaply, but it is a latent risk, not an observed defect. I had it as a headline; that was reasoning from what the code permits rather than what the books contain.

---

7. Limits of this measurement

Stated plainly, because the numbers are only as good as these:

• One book, one language pair. 62 pages of one Spanish novel, es→pt-BR. The 33% split rate is that book's typesetting; other books will differ.
• es→pt is the most forgiving pair. 15% translation breakage is a floor.
• Portuguese grammaticality judgements are mine. The three translation breaks and the "Diga." fabrication I'm confident about; the fuller Easy Read tally should be checked by a Portuguese speaker.
• S1 has known misfires — drop caps and chapter openings — and misses continuations starting with a capitalised word, so it under-counts in one direction and over-counts in the other. One of the 20 (pg009→010 in the earlier sample) was ambiguous.
• The counterfactual covers 2 of the 3 broken translations. The no ponte case wasn't covered: the pairs were chosen on predicted severity before we knew which boundaries actually broke, and page 163 got consumed by a different pair.
• The spread proxy moves more than one variable — it also stitches page images. For translation that's harmless (translation never sees images); for any claim about sectioning quality it is a confound.
• cuaderno5 has no PDF text layer; all its text came from the vision model, so OCR fidelity is a confound unique to it.

---

8. Options

Re-ranked after the measurement. This reverses my earlier instinct, which put the cheap context-only fix first.

Structural — fixes the leaf

C. Cross-page continuity in sectioning. Neighbour page text in the sectioning prompt plus continuesFromPrev / continuesToNext flags (C1), then an automatic merge post-pass reusing the existing sourcePageIds machinery (C2).
For: this is what the counterfactual actually did. The render side already honours sourcePageIds (web-rendering.ts:194-212), and the manual merge-cross-page endpoint (pages.ts:2022) already implements the merge and renumber.
Against: C2 changes section counts and IDs — the keys for web-rendering, quizzes, text-catalog, TTS ids, SMIL and packaged filenames. Needs a consumer-by-consumer audit. A false-positive merge is worse than a miss.

D. Sentence-level stitching. Extend isContinuation across the page boundary and join the two fragments into one leaf.
For: narrower blast radius than C2 — it moves text between two leaves rather than sections between pages — and it is the only option that also fixes TTS prosody and SMIL, because it fixes the unit those consume.
Against: a leaf lives in exactly one document, so the joined sentence either disappears from one page or is duplicated. Neither is obviously right, and it interacts with data-id stability and word timestamps.

Context-only — partial

B. Give translation, easy-read and glossary a read-only prev_text / next_text.
For: no ID churn, no packaging or runtime change; and it makes the Easy Read prompt honest about the context it already claims to receive.
Against — and this is new information: it is a partial fix. It would plausibly repair the contraction case (emitting "Pelo" + "que li"), but probably not the idiom, because translation.liquid rule 7 forbids redistributing content across segments and "Tanto faz para ele" does not split cleanly across the original fragments. It leaves two leaves, so TTS and SMIL stay broken.

Independent of page boundaries

A. Distribute book context we already compute. book-summary runs over the whole book and reaches exactly two prompts — image-captioning and font-assignment (a typography decision). Not sectioning, rendering, quizzes, glossary, easy-read or translation. metadata is read back only for language_code; grade level and subject never reach a prompt. toc-generation's output is consumed by no prompt at all. Cheap to fix — the plumbing pattern is already in production (image-captioning.ts:127).

E. Structure-aware batching. Quizzes are built from fixed 3-page slices of tag-stripped text (quiz-generation.ts:117-127); the sectioning tree is used only as a filter and discarded. toc-generation's unused output is the obvious input.

Small and unrelated

F. activity_multiple_choice_answers.liquid:35 should emit an explicit "undeterminable" the runtime treats as ungraded, rather than all-false. Latent per §6, but it converts a silent trap into a visible gap.

G. A real bug found along the way, nothing to do with page boundaries: Easy Read's numeral-simplification converted the indefinite article um into the numeral 1 — "tem um profundo significado" → "tem 1 profundo". Worth its own issue.

---

9. Proposal, for debate

1. G now — it's a plain bug.
2. C1 next (neighbour context + continuation flags). It is useful on its own, it is what the counterfactual validated, and it unblocks either C2 or D.
3. Then choose C2 or D on the basis of the consumer audit. D is narrower and fixes read-aloud too; C2 reuses machinery that already exists.
4. A alongside — cheap, independent, helps classification everywhere.
5. B only if C/D prove too invasive. It is a partial fix, not the fix.
6. F and E when convenient.

Where I'd most like pushback

• Is the page the right chunk for prose at all? mode: page is set deliberately on all four narrative books. Considered decision about reading experience, or a default nobody revisited? If we want meaningful chunks, the honest answer may be chunking by paragraph or scene and giving up page fidelity for reflowable books — a much bigger conversation than any option above.
• Is C2's ID churn affordable, given how many consumers key off section ids?
• Should the runtime persist reading state across documents? Everything is ephemeral today. Even a perfect merge leaves cross-document audio continuity unsolved.
• Is dropping pruned pages from reading order intended? It silently joins content that was never adjacent.