arrolio 0.1.0

data/TODO.implementation/08-truetype-tables-and-metrics.md

@@ -0,0 +1,48 @@
+---
+priority: P0
+phase: 2
+depends_on: [01]
+layer: metrics
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+TTF/OTF advance widths live in the `hmtx` table indexed by glyph ID.
+To go Unicode → glyph ID we need the `cmap` table. To scale we need
+`head.units_per_em`. And `hhea` / `OS/2` give ascender/descender
+(line height).
+
+## Approach
+
+Files under `lib/arrolio/font/true_type/`:
+
+- `file.rb` — sfnt header + table directory; lazy table access.
+- `head.rb` — `units_per_em`, `bbox`, `index_to_loc_format`,
+  `mac_style` (bold/italic flags).
+- `hhea.rb` — `ascender`, `descender`, `line_gap`,
+  `number_of_hmetrics`.
+- `hmtx.rb` — `advance_width(glyph_id)`, `lsb(glyph_id)`; handles
+  `numberOfHMetrics < numGlyphs` case.
+- `cmap.rb` — Unicode → glyph ID; subtable selection prefers
+  `(3,12)` > `(0,*)` > `(3,1)` > `(3,0)`; supports formats 0, 4, 6, 12.
+- `os2.rb` — `s_typo_ascender/descender/line_gap`,
+  `s_cap_height`, `sx_height`, `us_win_ascent/descent`,
+  `fs_selection` (bold/italic flags).
+
+Under `lib/arrolio/font_metrics/`:
+
+- `true_type_metrics.rb` — wraps `TrueType::File`; implements the
+  universal metrics interface from TODO 09.
+
+## Done-When
+
+- [ ] Loading DejaVuSans.ttf (or similar fixture) succeeds.
+- [ ] `ttf.head.units_per_em` matches `ttfname`/`fc-query` output.
+- [ ] `ttf.cmap.glyph_id_for(0x41)` returns the same value FreeType
+      reports for "A".
+- [ ] `ttf.hmtx.advance_width(0)` matches the .notdef glyph width.
+- [ ] `TrueTypeMetrics#width_of_string` matches FreeType to within
+      0.1pt at 12pt.
+- [ ] Specs cover cmap formats 4 and 12 (provide two test TTFs).

data/TODO.implementation/09-font-registry-and-glyph-measurer.md

@@ -0,0 +1,49 @@
+---
+priority: P0
+phase: 2
+depends_on: [07, 08]
+layer: metrics
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+Engine and TextLayout need one stable interface for "ask the font about
+glyph metrics" regardless of whether the font is AFM-backed (standard
+Type1) or TTF-backed. Plus a high-level measurer that combines metrics
+with PDF's `Tc`/`Tw` operator semantics.
+
+## Approach
+
+Files:
+
+- `lib/arrolio/font_metrics/interface.rb` — module documenting the
+  contract every metrics class implements: `units_per_em`,
+  `advance_width(char)`, `width_of_string(str, font_size:)`,
+  `ascender(font_size:)`, `descender(font_size:)`,
+  `cap_height(font_size:)`, `x_height(font_size:)`,
+  `line_height(font_size:, line_spacing:)`.
+- `lib/arrolio/font_metrics/registry.rb` — singleton; maps font name
+  to a metrics instance; memoises; supports `register_ttf(name, path)`.
+- `lib/arrolio/glyph_measurer.rb` — high-level facade over a metrics
+  instance. Methods:
+  - `width_of_string(str, font_size:)` — direct.
+  - `width_of_run(str, font_size:, character_spacing:, word_spacing:)`
+    — adds `character_spacing * (chars - 1)` and `word_spacing * words`.
+  - `line_height(font_size:, line_spacing:)`.
+  - `space_width(font_size:)`.
+  - `available?` — false when no metrics loaded (falls back to 0.5em
+    estimate to keep layout usable).
+
+## Done-When
+
+- [ ] `Registry["Helvetica"]` returns an `AfmMetrics` instance,
+      memoised across calls.
+- [ ] `Registry["Unknown"]` returns `nil`.
+- [ ] After `Registry.register_ttf("MyFont", "/path/x.ttf")`,
+      `Registry["MyFont"]` returns a `TrueTypeMetrics`.
+- [ ] `GlyphMeasurer.new(font_name: "Helvetica").width_of_run("a b c",
+      font_size: 12, character_spacing: 1, word_spacing: 2)` matches
+      the PDF spec formula.
+- [ ] Specs cover both AFM and TTF paths through GlyphMeasurer.

data/TODO.implementation/10-break-opportunity-and-inline-run.md

@@ -0,0 +1,47 @@
+---
+priority: P0
+phase: 3
+depends_on: [04, 09]
+layer: text
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+Line breaking iterates over a list of `InlineRun`s. Each run is a
+contiguous span of text sharing one `Style`. The line breaker must
+find break opportunities across run boundaries (the wrap algorithm
+cannot force a line break just because the style changed).
+
+## Approach
+
+Files:
+
+- `lib/arrolio/inline_run.rb` — frozen value object:
+  `text`, `style`. Methods: `empty?`, `length`, `width(measurer)`,
+  `==`, `eql?`, `hash`.
+- `lib/arrolio/text_layout/break_opportunity.rb` — finds break
+  points in a run list. Yields `BreakOpportunity` value objects:
+  - `run_index` — index into the run list.
+  - `char_offset` — position within that run.
+  - `width_before` — cumulative width up to (and including) the break.
+  - `type` — `:start`, `:soft`, `:forced`, `:end`.
+
+Opportunities are created at:
+- Paragraph start (always, `:start`).
+- After each space (`:soft`).
+- After hyphen / em-dash / soft hyphen (`:soft`).
+- At zero-width space (U+200B) (`:soft`, no width consumed).
+- At newline (`:forced`).
+- At end of paragraph (`:end`).
+
+## Done-When
+
+- [ ] `InlineRun.new("Hello", style:).width(measurer)` returns a Float.
+- [ ] `BreakOpportunity.each_in(runs, measurer:, font_size:)` yields
+      every opportunity in order with correct cumulative widths.
+- [ ] A forced newline produces a `:forced` opportunity.
+- [ ] A paragraph with no spaces yields only `:start` and `:end`.
+- [ ] Specs cover: ASCII, multi-run with style change at space,
+      explicit newline, soft hyphen.

data/TODO.implementation/11-greedy-line-breaker.md

@@ -0,0 +1,48 @@
+---
+priority: P0
+phase: 3
+depends_on: [10]
+layer: text
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+The simplest correct line breaker: first-fit word wrap. Walk runs
+left-to-right, accumulate words, emit a line when the next word would
+exceed the target width. FOP's default. Linear time, fast.
+
+## Approach
+
+File: `lib/arrolio/text_layout/greedy.rb`.
+
+```ruby
+class Arrolio::TextLayout::Greedy
+  def initialize(runs, measurer:, width:, align: :left)
+  def layout -> [Line, Line, ...]
+end
+```
+
+Algorithm:
+1. Enumerate break opportunities.
+2. Track `line_start` index into the opportunity list.
+3. For each subsequent opportunity, compute `line_width = opp.width_before
+   - opps[line_start].width_before`.
+4. If `line_width > target_width` and we have at least one opportunity
+   on this line, emit a line ending at the previous opportunity; reset
+   `line_start`.
+5. Force-break at `:forced` opportunities.
+6. At end, emit the trailing line.
+
+Output: list of `Line` objects (TODO 13). This TODO builds Lines
+without alignment offsets; TODO 13 adds offsets.
+
+## Done-When
+
+- [ ] A single short word on one line: `"Hello"` at width 500 → 1 line.
+- [ ] Long text wraps to multiple lines; no line exceeds target width
+      except for unbreakable words.
+- [ ] Forced newline breaks the line.
+- [ ] Style change at a space does not produce a spurious line break.
+- [ ] Per-line `width` is correct (matches sum of placed run widths).

data/TODO.implementation/12-knuth-plass-line-breaker.md

@@ -0,0 +1,46 @@
+---
+priority: P1
+phase: 3
+depends_on: [10]
+layer: text
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Greedy line breaking produces uneven right margins and unbalanced
+justify. Knuth-Plass (TeX, Pango) minimises the sum of squared
+shrink/stretch ratios across the paragraph, producing visually
+balanced text. Opt-in via `style.line_break: :knuth_plass`.
+
+## Approach
+
+File: `lib/arrolio/text_layout/knuth_plass.rb`.
+
+Same I/O as Greedy: `(runs, measurer, width, align)` → `[Line]`.
+
+Algorithm (simplified — TODO 14 generalises):
+1. Enumerate break opportunities.
+2. `best[i]` = optimal cost to reach opportunity i. `best[0] = 0`.
+3. For each pair `(i, j)` with `i < j`:
+   - Compute `line_width = opps[j].width_before - opps[i].width_before`.
+   - If `:forced` at j, treat as zero-cost break.
+   - If `line_width > target`, allow but with very high badness.
+   - Otherwise badness = `((target - line_width) / target) ** 2 * 100`.
+   - `candidate_cost = best[i] + badness`. Keep the minimum.
+4. Walk back from end to recover the chosen break sequence.
+5. Skip empty segments (would produce empty trailing lines).
+
+Knuth's full algorithm has penalties, fitness classes, and demerits.
+This TODO uses the simplified version. TODO 14 lifts it to a general
+`Breaker` with full Knuth semantics.
+
+## Done-When
+
+- [ ] Single short word → 1 line.
+- [ ] Long paragraph wraps to multiple lines without empty trailing line.
+- [ ] For a sample paragraph, KnuthPlass produces line widths whose
+      variance is ≤ Greedy's variance on the same paragraph (i.e. more
+      balanced).
+- [ ] Output interface is identical to Greedy (swappable).

data/TODO.implementation/13-line-and-alignment.md

@@ -0,0 +1,45 @@
+---
+priority: P0
+phase: 3
+depends_on: [11]
+layer: text
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+The line breakers emit lists of `Line` objects. Each `Line` carries
+the placed runs (with x-offsets), the line width, and the alignment.
+The renderer needs these to know exactly where to draw each run.
+
+## Approach
+
+Files:
+
+- `lib/arrolio/text_layout/line.rb` — `Line` value object:
+  - `placed_runs` — Array of `PlacedRun` (run + x_offset within line).
+  - `width` — actual content width of the line.
+  - `max_width` — target width (for alignment reference).
+  - `align` — `:left`, `:right`, `:center`, `:justify`.
+  - `x_offset` — line's left-edge offset based on alignment:
+    - left: 0
+    - right: `max_width - width`
+    - center: `(max_width - width) / 2`
+  - `justify_stretch` — extra width per word gap for justify alignment
+    (last line of a paragraph is never justified).
+- `lib/arrolio/text_layout/placed_run.rb` — `Struct.new(:run,
+  :x_offset, keyword_init: true)`.
+
+Both breakers (Greedy, KnuthPlass) produce `Line[]` via the same code
+path — extract shared line-building into a private helper.
+
+## Done-When
+
+- [ ] `Line#x_offset` for centered alignment matches
+      `(max_width - width) / 2`.
+- [ ] `Line#justify_stretch` is 0 for the last line in a paragraph.
+- [ ] `Line#justify_stretch` evenly distributes slack across word gaps
+      for non-last lines.
+- [ ] A renderer that consumes `Line#placed_runs` can place every run
+      at the correct x position.

data/TODO.implementation/14-knuth-elements-and-breaker.md

@@ -0,0 +1,56 @@
+---
+priority: P1
+phase: 4
+depends_on: [10]
+layer: knuth
+est: 2d
+status: pending
+---
+
+## Problem
+
+FOP's greatest insight: one algorithm (Knuth-Plass dynamic
+programming) handles line breaks, page breaks, column balancing, and
+table row distribution alike. The universal input is the Knuth element
+triple: Box (fixed-size content), Glue (inter-content with
+stretch/shrink), Penalty (break cost). My current pdfrb has this
+implicit inside TextLayout only.
+
+## Approach
+
+Files under `lib/arrolio/knuth/`:
+
+- `element.rb` — base class. Each element has a `width` (Float) and a
+  `flagged?` boolean (for penalty/forced breaks).
+- `box.rb` — content with fixed size: `Box.new(width: 30.0, content_ref)`.
+- `glue.rb` — inter-content: `Glue.new(width:, stretch:, shrink:)`.
+- `penalty.rb` — break cost: `Penalty.new(width:, penalty:, flagged:)`.
+  Special values:
+  - `Penalty::INFINITE` (no break here)
+  - `Penalty::FORCED` (must break here)
+
+File: `lib/arrolio/breaker.rb`.
+
+```ruby
+class Arrolio::Breaker
+  def initialize(elements, target_width:, tolerance: 1.0)
+  def break -> [BreakPoint, BreakPoint, ...]
+end
+```
+
+Algorithm (Knuth-Plass DP):
+1. Active set starts with node 0 at total cost 0.
+2. For each feasible break point, compute badness from preceding
+   active nodes; pick the minimum-cost predecessor.
+3. Returns the chosen break-point sequence.
+
+A `BreakPoint` references the element index and the predecessor.
+
+## Done-When
+
+- [ ] Knuth elements round-trip through serialisation.
+- [ ] `Breaker` on a synthetic Box-Glue-Penalty sequence produces
+      optimal breaks matching a hand-computed result.
+- [ ] `Penalty::FORCED` always breaks.
+- [ ] `Penalty::INFINITE` never breaks.
+- [ ] Specs cover under-full, over-full, and exact-fit cases.

data/TODO.implementation/15-refactor-text-layout-on-knuth.md

@@ -0,0 +1,47 @@
+---
+priority: P2
+phase: 4
+depends_on: [11, 12, 14]
+layer: knuth
+est: 2d
+status: pending
+---
+
+## Problem
+
+Greedy and KnuthPlass line breakers were built independently and
+duplicate the line-assembly logic. Once the universal `Breaker`
+exists (TODO 14), refactor both algorithms to produce Knuth
+element sequences from InlineRuns, then break them with the universal
+Breaker. Same output, less code, easier to extend.
+
+## Approach
+
+Files to modify:
+
+- `lib/arrolio/text_layout/knuth_sequence_builder.rb` — new class.
+  Takes `InlineRun[]` + `GlyphMeasurer`, produces a `Knuth::Element[]`
+  sequence:
+  - Each character → `Box(width: char_width)`.
+  - Each space → `Glue(width: space_width, stretch:, shrink:)` plus a
+    `Penalty(width: 0, penalty: 0, flagged: false)` before the glue
+    (Knuth's standard space-break pattern).
+  - Each hyphenation point → `Penalty(width: hyphen_width, penalty:
+    50, flagged: true)`.
+  - Each newline → `Penalty(width: 0, penalty: -Infinity, flagged: true)`.
+
+- `lib/arrolio/text_layout/greedy.rb` and `knuth_plass.rb` — refactor
+  to use `KnuthSequenceBuilder` + `Breaker` with different parameters:
+  - Greedy: `tolerance: Infinity` (always accept first fit).
+  - KnuthPlass: `tolerance: 1.0` (standard).
+
+- A `LineAssembler` reconstitutes `Line[]` from the breaker's output
+  and the original run list.
+
+## Done-When
+
+- [ ] All TODOs 11 and 12 specs still pass after refactor.
+- [ ] Both breakers use the same `KnuthSequenceBuilder`.
+- [ ] Both use the same `Breaker` (different params).
+- [ ] The shared `LineAssembler` produces identical Lines to before.
+- [ ] Code size shrinks (no duplicate line-assembly logic).

data/TODO.implementation/16-flowable-and-frame.md

@@ -0,0 +1,52 @@
+---
+priority: P0
+phase: 5
+depends_on: [04, 13]
+layer: flowable
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+The page-flow engine places "flowables" — paragraphs, tables, images,
+spacers, page breaks — into frames, splitting and advancing pages as
+needed. The Flowable base class defines the contract every flowable
+must satisfy; Frame tracks remaining space.
+
+## Approach
+
+Files:
+
+- `lib/arrolio/flowable.rb` — abstract base.
+  - `height(width, context)` → Float: natural height at this width.
+  - `render(canvas, x, y, width, context)` → Float: actual height
+    consumed (may differ from `height` if rendering adjusts).
+  - `splittable?` — true if the flowable supports `split`.
+  - `keep_together?` — true if it must not be split.
+  - `page_break_before?`, `page_break_after?` — bool flags from style.
+  - `split(width, remaining_height, context)` → `[head, tail]` where
+    head fits in remaining_height, tail is the rest (or nil).
+  - `do_split(width, remaining_height, context)` — subclass hook.
+  - Default `split`: if `height <= remaining_height`, `[self, nil]`;
+    if not splittable and not keep_together, render whole `[self, nil]`;
+    if keep_together, `[nil, self]`.
+
+- `lib/arrolio/frame.rb` — rectangular region tracking consumed space.
+  - `x`, `y`, `width`, `height`, `consumed`.
+  - `remaining_height`, `full?`, `consume!(h)`, `cursor_y`, `clone_empty`.
+  - `available_width_at(y)` — for text wrap (FloatRegistry hook).
+
+- `lib/arrolio/float_registry.rb` — tracks floated boxes for wrap;
+  `available_width_at(frame_x, full_width, y)` returns
+  `[x_start, available_width]`.
+
+## Done-When
+
+- [ ] `Flowable.new.height(100, ctx)` raises `NotImplementedError`.
+- [ ] A subclass that returns height 50 and renders 50 actually does.
+- [ ] `Frame.new(x: 0, y: 0, width: 100, height: 200).consume!(50)`
+      leaves `remaining_height == 150`.
+- [ ] `FloatRegistry` with a left-floated image reduces
+      `available_width_at` on the floated y-range.
+- [ ] Specs cover the abstract contract + 1 concrete subclass.

data/TODO.implementation/17-flow-context.md

@@ -0,0 +1,50 @@
+---
+priority: P0
+phase: 5
+depends_on: [16]
+layer: flowable
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+Every `render` call gets a `FlowContext`. It carries page-level state
+flowables need: current page number, total page count (for "Page X of
+Y"), resolved citation targets, bookmark targets, the float registry,
+and a reference to the document (for emitting indirect objects like
+hyperlink annotations).
+
+## Approach
+
+File: `lib/arrolio/flow_context.rb`.
+
+```ruby
+class Arrolio::FlowContext
+  attr_reader :document, :citations, :bookmarks, :float_registry
+  attr_accessor :page_number, :page_count
+
+  def initialize(document: nil, page_number: 1, page_count: nil)
+    ...
+  end
+
+  def citation_for(ref_id)        # filled in pass 1, read in pass 2
+  def record_citation(ref_id, page_number)
+  def record_bookmark(ref_id, page_number, y)
+  def total_pages                 # nil until pass 1 completes
+end
+```
+
+The context is passed by reference, so mutating it during layout is
+intentional. Pass 2 (after the document is fully laid out) reads the
+recorded citations/bookmarks to render static content with resolved
+field values.
+
+## Done-When
+
+- [ ] `FlowContext.new(page_number: 5)` exposes `page_number == 5`.
+- [ ] `record_citation("ch1", 7)` then `citation_for("ch1") == 7`.
+- [ ] `total_pages` returns nil until `page_count = N` is set.
+- [ ] Document reference is propagated to children that need to emit
+      indirect objects (TODO 37 hyperlinks).
+- [ ] Specs cover recording, lookup, two-pass resolution.

data/TODO.implementation/18-text-flowable.md

@@ -0,0 +1,52 @@
+---
+priority: P0
+phase: 5
+depends_on: [13, 16, 17]
+layer: flowable
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+The fundamental flowable: a paragraph of text. Wraps an `InlineRun[]`
++ `Style`; uses TextLayout (Greedy or KnuthPlass) for line breaking;
+splittable across pages.
+
+## Approach
+
+File: `lib/arrolio/flowables/text_flowable.rb`.
+
+```ruby
+class Arrolio::Flowables::TextFlowable < Arrolio::Flowable
+  attr_reader :runs, :measurer
+
+  def initialize(text_or_runs, style:, measurer: nil)
+  def height(width, context)
+  def render(canvas, x, y, width, context)
+  def splittable?; true; end
+  def do_split(width, remaining_height, context)
+end
+```
+
+Internals:
+- `laid_out(width)` runs Greedy or KnuthPlass based on
+  `style.line_break`; returns `Line[]`.
+- `height(width, ctx) = lines.length * line_height`.
+- `render(canvas, x, y, width, ctx)` walks lines; for each PlacedRun,
+  calls `canvas.text(run.text, at:, font:, size:, char_spacing:,
+  word_spacing:)` per the run's style.
+- `do_split` allocates lines to head until `cum_height <= remaining_height`;
+  remaining lines form the tail.
+
+`line_height = measurer.line_height(font_size:, line_spacing:)`.
+
+## Done-When
+
+- [ ] A single-line paragraph at width 500 renders exactly one line.
+- [ ] A long paragraph splits cleanly across pages; both halves
+      render correct text.
+- [ ] Style span (bold run inside body) preserves per-run font in
+      emitted `canvas.text` calls.
+- [ ] Justify alignment applies per-line word spacing.
+- [ ] Specs cover single-line, multi-line, splittable behaviour.

data/TODO.implementation/19-spacer-and-page-break.md

@@ -0,0 +1,52 @@
+---
+priority: P0
+phase: 5
+depends_on: [16]
+layer: flowable
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+Need two simple flowables: vertical `Spacer` (reserve empty space) and
+`PageBreak` (force the engine to advance to the next page before
+continuing).
+
+## Approach
+
+File: `lib/arrolio/flowables/spacer.rb`.
+
+```ruby
+class Arrolio::Flowables::Spacer < Arrolio::Flowable
+  def initialize(amount)
+  def height(width, context) = amount
+  def render(*); amount; end
+  def splittable?; true; end
+  def do_split(width, remaining_height, context)
+    # If amount fits, return self. Else split into two spacers.
+  end
+end
+```
+
+File: `lib/arrolio/flowables/page_break.rb`.
+
+```ruby
+class Arrolio::Flowables::PageBreak < Arrolio::Flowable
+  def height(*); 0.0; end
+  def render(*); 0.0; end
+  def page_break_after?; true; end   # engine recognises this
+end
+```
+
+Engine treats `PageBreak` as a sentinel: instead of placing it, it
+advances to a new page. Both flowables are zero-cost on render.
+
+## Done-When
+
+- [ ] `Spacer.new(50).height(100, ctx) == 50`.
+- [ ] `Spacer.new(100).do_split(100, 30, ctx)` returns
+      `[Spacer(30), Spacer(70)]`.
+- [ ] `PageBreak.new.page_break_after? == true`.
+- [ ] Engine consumes `PageBreak` without rendering it.
+- [ ] Specs cover both.

data/TODO.implementation/20-engine-paged.md

@@ -0,0 +1,63 @@
+---
+priority: P0
+phase: 5
+depends_on: [17, 18, 19]
+layer: flowable
+est: 3d
+status: in_progress
+---
+
+## Problem
+
+The driver that walks a Flowable list, places each into a Frame,
+advances pages when the frame is full, honours keep-together and
+page-break directives, and runs two passes for citation resolution.
+This is the heart of the engine.
+
+## Approach
+
+File: `lib/arrolio/engine/paged.rb`.
+
+```ruby
+class Arrolio::Engine::Paged
+  attr_reader :layout_spec, :flowables, :context, :pages
+
+  def initialize(layout_spec:, flowables:, context: nil)
+  def layout -> [Arrolio::Output::Page]
+end
+```
+
+Algorithm:
+1. Initialise `pending = flowables.dup`, `current_page = new_page`,
+   `current_frame = current_page.body_frame`.
+2. Loop:
+   - Shift next flowable.
+   - `PageBreak` → new page; continue.
+   - `page_break_before?` and not first flowable → new page.
+   - `keep_together?` and `height > remaining_height` and `height <=
+     frame.height` → new page first.
+   - If frame full → new page.
+   - `render_on_page(flowable, current_page, current_frame)` →
+     `[consumed, remainder]`.
+   - `frame.consume!(consumed)`.
+   - If remainder and consumed == 0 and frame not full → new page;
+     unshift remainder.
+   - Else unshift remainder.
+3. After all flowables placed: `context.page_count = pages.length`.
+4. Pass 2: for each page, render its static-content regions
+   (running headers/footers) with resolved citation values.
+
+Each page is created from the layout_spec's PageSequenceMaster
+selection (TODO 24, 25). For now (Phase 5), use a single body
+template.
+
+## Done-When
+
+- [ ] A single-paragraph document produces 1 page.
+- [ ] 50 long paragraphs across multiple pages.
+- [ ] `PageBreak` forces a new page.
+- [ ] `keep_together: true` flowable that doesn't fit moves to next
+      page whole.
+- [ ] 100-paragraph doc lays out in < 5 seconds.
+- [ ] No infinite loops on over-large content (TODO 19's split
+      contract prevents this).