arrolio 0.1.0

data/TODO.implementation/21-output-tree.md

@@ -0,0 +1,56 @@
+---
+priority: P0
+phase: 6
+depends_on: [20]
+layer: output
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Engine produces laid-out pages but currently they're tied to Pdfrb's
+page object. The Output tree should be a medium-neutral representation
+of "what goes where" — separate from both the layout algorithm and
+the renderer. The PDF renderer walks the Output tree; future
+renderers (PostScript, PPML, an in-memory canvas for tests) walk the
+same tree.
+
+## Approach
+
+Files under `lib/arrolio/output/`:
+
+- `page.rb` — `Page` value object:
+  - `number` (Integer)
+  - `template_ref` (Symbol or PageTemplate reference)
+  - `regions` (Hash of region_name → Region)
+  - `static_content` (Array of StaticContent)
+  - `size` (Array `[w, h]`)
+
+- `region.rb` — `Region` value object:
+  - `name` (`:body`, `:before`, `:after`, ...)
+  - `frame` (the consumed Frame snapshot)
+  - `placed_boxes` (Array of PlacedBox)
+
+- `placed_box.rb` — `PlacedBox` value object:
+  - `x`, `y`, `width`, `height` (Float)
+  - `content_ref` (opaque reference to the source flowable or run)
+  - `style` (resolved Style::Definition snapshot)
+  - `kind` (`:text`, `:image`, `:shape`, ...)
+
+- `static_content.rb` — region name + a list of flowables (rendered
+  in pass 2 with resolved citations).
+
+The Output tree is fully reified before rendering — no lazy
+generation. This makes rendering straightforward and lets us diff
+Output trees between runs.
+
+## Done-When
+
+- [ ] Engine returns `[Output::Page]`.
+- [ ] Each Page has at least a body Region with placed_boxes.
+- [ ] StaticContent records region + flowables but doesn't render
+      until pass 2.
+- [ ] Output tree is fully frozen; no mutation after construction.
+- [ ] `Output::Dumper.to_yaml(page)` produces a stable, diffable
+      representation.

data/TODO.implementation/22-pdf-renderer.md

@@ -0,0 +1,77 @@
+---
+priority: P0
+phase: 6
+depends_on: [21]
+layer: render
+est: 3d
+status: in_progress
+---
+
+## Problem
+
+The PDF renderer walks `Output::Page[]` and emits PDF bytes via
+Pdfrb. This is where Arrolio stops being medium-neutral and becomes
+PDF-specific. The renderer must NOT make layout decisions — every
+position and style comes from the Output tree.
+
+## Approach
+
+File: `lib/arrolio/renderer/pdf.rb`.
+
+```ruby
+class Arrolio::Renderer::Pdf
+  def render(pages, io:)
+    pdfrb_doc = Pdfrb::Document.new
+    pages.each { |page| render_page(pdfrb_doc, page) }
+    pdfrb_doc.write(io: io)
+  end
+
+  private
+
+  def render_page(doc, output_page)
+    pdfrb_page = doc.pages.add(media_box: [0, 0, *output_page.size])
+    canvas = pdfrb_page.canvas
+    output_page.regions.each_value do |region|
+      render_region(canvas, region)
+    end
+    output_page.static_content.each { |sc| render_static(canvas, sc) }
+  end
+
+  def render_region(canvas, region)
+    region.placed_boxes.each { |box| render_box(canvas, box) }
+  end
+
+  def render_box(canvas, box)
+    case box.kind
+    when :text  then render_text(canvas, box)
+    when :image then render_image(canvas, box)
+    when :shape then render_shape(canvas, box)
+    end
+  end
+end
+```
+
+Mapping table from Arrolio Output concepts to Pdfrb primitives:
+
+| Arrolio | Pdfrb |
+|---|---|
+| `Output::Page` of size `[w,h]` | `doc.pages.add(media_box: [0,0,w,h])` |
+| `PlacedBox` kind `:text` | `canvas.text(content, at:, font:, size:, char_spacing:, word_spacing:)` |
+| `PlacedBox` kind `:image` | `name = doc.images.add(path); canvas.image(name, at:, width:, height:)` |
+| `PlacedBox` kind `:shape` (rectangle, line) | `canvas.rectangle/line + canvas.fill/stroke` |
+| `StaticContent` | render via the same path, but at region-specific coordinates |
+
+The renderer holds no state between pages — each page renders from
+the Output tree afresh.
+
+## Done-When
+
+- [ ] `Renderer::Pdf.new.render([Output::Page.new(...)], io: StringIO.new)`
+      produces bytes starting with `%PDF-`.
+- [ ] A single text page renders the text correctly.
+- [ ] Multi-page documents produce N pages with correct page numbers
+      in PDF metadata.
+- [ ] Round-trip: rendered PDF re-read by Pdfrb has the expected
+      number of pages and extractable text.
+- [ ] No layout decisions leak into the renderer (all coordinates
+      come from Output::PlacedBox).

data/TODO.implementation/23-end-to-end-smoke.md

@@ -0,0 +1,53 @@
+---
+priority: P0
+phase: 6
+depends_on: [22]
+layer: output
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+Need a single test that proves the full pipeline works end-to-end:
+Content → LayoutSpec → Engine → Output → Renderer → PDF bytes that
+read back correctly. This is the MVP milestone.
+
+## Approach
+
+File: `spec/arrolio/end_to_end_smoke_spec.rb`.
+
+Build the simplest non-trivial document:
+- A4 page, 25mm margins.
+- One section with a heading and two paragraphs of body text.
+- Use the standard 14 Type1 fonts (Helvetica + Times).
+
+Run it through the pipeline:
+```ruby
+content = Arrolio::Content::Document.build { ... }
+layout  = Arrolio::LayoutSpec.build { ... }
+pages   = Arrolio::Engine::Paged.new(layout_spec: layout,
+                                       flowables: FlowBuilder.(content, layout)).layout
+out     = StringIO.new
+Arrolio::Renderer::Pdf.new.render(pages, io: out)
+
+# Assertions
+reopened = Pdfrb::Document.new(io: StringIO.new(out.string))
+expect(reopened.pages.count).to eq(1)
+extracted = Pdfrb::Task::ExtractText.(reopened).first
+expect(extracted).to include("Hello, World!")
+```
+
+Also a multi-page variant: 50 paragraphs that overflow to 2+ pages.
+
+This spec becomes the regression canary — any breaking change in
+any layer fails it.
+
+## Done-When
+
+- [ ] Single-page smoke spec passes.
+- [ ] Multi-page overflow spec passes (≥ 2 pages, text extractable).
+- [ ] Round-trip: write → read → re-write → re-read produces same
+      text extraction.
+- [ ] The spec runs in < 2 seconds.
+- [ ] Spec is marked `:e2e` so it can be excluded from fast unit runs.

data/TODO.implementation/24-page-template-and-region.md

@@ -0,0 +1,51 @@
+---
+priority: P0
+phase: 7
+depends_on: [03, 20]
+layer: template
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Documents need more than one page geometry: cover pages differ from
+body pages, running headers/footers vary, odd/even pages mirror each
+other. The PageTemplate + Region types define static geometry; the
+engine instantiates them per output page.
+
+## Approach
+
+Files under `lib/arrolio/layout_spec/`:
+
+- `page_template.rb` (extended from TODO 03):
+  - `name` (Symbol).
+  - `page_size` (`[w, h]` or named like `:A4`, `:Letter`).
+  - `margins` (Hash with `:top`, `:right`, `:bottom`, `:left`).
+  - `region_extents` (Hash `:before => 15mm`, etc.).
+  - Computed `regions` (Hash of name → Region with absolute geometry).
+
+- `region.rb`:
+  - `name`, `x`, `y`, `width`, `height`.
+  - `flow_ref` (optional — names the Flow that fills this region).
+  - `to_frame` → returns a fresh `Frame` for runtime use.
+
+Helper: `PageSizes` constant mapping `:A4` → `[595, 842]`, `:Letter`
+→ `[612, 792]`, `:Legal` → `[612, 1008]`, etc.
+
+Region geometry computed from page size + margins + region extents:
+```
+body = Region(x: left_margin, y: bottom_margin,
+              width: page_w - L - R,
+              height: page_h - T - B - before_extent - after_extent)
+```
+
+## Done-When
+
+- [ ] `PageTemplate.new(page_size: :A4, margins: 25)` produces a
+      template with body region of 545×743pt.
+- [ ] Asymmetric margins honoured.
+- [ ] `Region#to_frame` returns a Frame with `remaining_height ==
+      height`.
+- [ ] All 14 standard page sizes supported.
+- [ ] Specs cover A4, Letter, asymmetric margins, with-header-footer.

data/TODO.implementation/25-page-sequence-master.md

@@ -0,0 +1,54 @@
+---
+priority: P0
+phase: 7
+depends_on: [24]
+layer: template
+est: 2d
+status: pending
+---
+
+## Problem
+
+The engine needs to know which PageTemplate to use for each output
+page. FOP's `fo:page-sequence-master` solves this with rules: first,
+odd, even, blank, last. Same model in Ruby.
+
+## Approach
+
+File: `lib/arrolio/layout_spec/page_sequence_master.rb`.
+
+```ruby
+class Arrolio::LayoutSpec::PageSequenceMaster
+  attr_reader :rules, :fallback
+
+  def initialize(rules: {}, fallback: nil)
+    # rules: { first: template_name, odd: ..., even: ..., blank: ..., last: ... }
+    # All values are Symbol template names.
+  end
+
+  def template_name_for(page_number:, total: nil, blank: false)
+    # Returns a Symbol template name. Selection order:
+    #   1. first page (page_number == 1) && rules[:first]
+    #   2. blank page && rules[:blank]
+    #   3. last page (page_number == total) && rules[:last]
+    #   4. odd/even by parity
+    #   5. fallback or rules[:default]
+  end
+end
+```
+
+Engine integration:
+- Track page_number, total (set in pass 1), and "is this a blank page"
+  (page with no body content, only static).
+- On each new page, query the master for the template name.
+- Look up the actual PageTemplate in the LayoutSpec.
+
+## Done-When
+
+- [ ] `template_name_for(page_number: 1)` returns `rules[:first]` if set.
+- [ ] `template_name_for(page_number: 4, total: 4)` returns
+      `rules[:last]` if set.
+- [ ] `template_name_for(page_number: 2)` returns `rules[:even]`.
+- [ ] `template_name_for(page_number: 3)` returns `rules[:odd]`.
+- [ ] Falls through to fallback when no rule matches.
+- [ ] Engine uses the selected template to size each new page.

data/TODO.implementation/26-two-pass-layout.md

@@ -0,0 +1,66 @@
+---
+priority: P0
+phase: 7
+depends_on: [25]
+layer: template
+est: 2d
+status: pending
+---
+
+## Problem
+
+Cross-references (`fo:page-number-citation`, "Page X of Y") need to
+know page numbers that aren't decided until layout completes. The
+engine runs two passes:
+
+1. **Pass 1**: lay out everything with placeholder field values.
+   Record which page each citation target lands on.
+2. **Pass 2**: re-render the static-content regions (headers/footers)
+   with resolved citation values.
+
+Body content is NOT re-rendered in pass 2 — its layout is stable.
+Only the static regions need field resolution.
+
+## Approach
+
+Modify `Arrolio::Engine::Paged` (TODO 20):
+
+```ruby
+def layout
+  pass1_result = layout_pass1
+  context.page_count = pass1_result.pages.length
+  pass2(pass1_result.pages)
+end
+
+def pass2(pages)
+  pages.each_with_index do |page, i|
+    context.page_number = i + 1
+    page.render_static_content(context)
+  end
+  pages
+end
+```
+
+The `Output::Page#render_static_content(context)` method:
+- For each `StaticContent` entry, resolve its flowables' field runs.
+- Rebuild the placed boxes for the static region only.
+- Replace the region's `placed_boxes` with the new ones.
+
+Field runs (TODO 39) implement `resolve(context)` returning a String.
+The static-content flow is built once during pass 1, but its field
+runs are evaluated against `context` each time the region is
+re-rendered.
+
+Citation recording: when the engine places a flowable that has a
+`citation_target_id`, it records
+`context.record_citation(target_id, current_page_number)`.
+
+## Done-When
+
+- [ ] A document with "Page X of Y" in the footer renders correctly
+      (X = current page, Y = total).
+- [ ] A `page-number-citation` to a section heading on page 5
+      resolves to "5" in static content.
+- [ ] Body layout is identical between pass 1 and pass 2 (no relayout).
+- [ ] Pass 2 only re-evaluates field runs; no other work.
+- [ ] 100-page document: pass 2 completes in < 1 second.

data/TODO.implementation/27-table-model.md

@@ -0,0 +1,48 @@
+---
+priority: P0
+phase: 8
+depends_on: [02, 16]
+layer: table
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Tables are the hardest layout primitive. Need typed Row/Cell/Column
+model that the layout algorithms (TODO 28) and renderer (TODO 29)
+operate on. Cells can span multiple columns or rows. Header rows
+repeat across page breaks.
+
+## Approach
+
+Files under `lib/arrolio/table/`:
+
+- `table.rb` — value object holding `rows` (Array of Row),
+  `column_specs` (Array of ColumnSpec), `style` (TableStyle).
+  Methods: `num_columns`, `num_rows`, `header_rows`, `body_rows`.
+
+- `row.rb` — `Row = Struct.new(:cells, :header, :style,
+  keyword_init: true)`. `header?` alias. Cells is an Array of Cell.
+
+- `cell.rb` — `Cell = Struct.new(:content, :colspan, :rowspan,
+  :style, keyword_init: true)`. `content` is a Flowable or String
+  (Strings auto-wrapped in TextFlowable). `colspan?`, `rowspan?`
+  predicates.
+
+- `column_spec.rb` — `ColumnSpec = Struct.new(:width, :min, :max,
+  :auto, keyword_init: true)`. Class methods: `.fixed(width)`,
+  `.auto(min:, max:)`. `fixed?` predicate.
+
+Cell flowables: `Cell#flowables` normalises content into a list of
+`Flowable` instances. Strings become `TextFlowable` with the cell's
+style.
+
+## Done-When
+
+- [ ] Construct a 3-row × 3-column table; verify `num_rows == 3`,
+      `num_columns == 3`.
+- [ ] A row marked `header: true` appears in `header_rows`.
+- [ ] A cell with `colspan: 2` reports `colspan? == true`.
+- [ ] String cell content auto-wraps in TextFlowable.
+- [ ] Specs cover construction, header detection, span predicates.

data/TODO.implementation/28-table-layouts.md

@@ -0,0 +1,53 @@
+---
+priority: P0
+phase: 8
+depends_on: [27, 16]
+layer: table
+est: 3d
+status: pending
+---
+
+## Problem
+
+Given a Table + target width, compute the column widths and row
+heights. Two strategies: Fixed (caller-specified widths) and Auto
+(CSS 2.1 §17.5.2.2 — distribute surplus by content).
+
+## Approach
+
+Files under `lib/arrolio/table_layout/`:
+
+- `resolved_grid.rb` — value object: `column_widths`, `row_heights`,
+  `cell_rects` (per-cell { x, y, width, height }). `total_width`,
+  `total_height`.
+
+- `fixed.rb` — Fixed strategy:
+  - Take column widths from specs.
+  - Scale proportionally if sum != target_width.
+  - Compute each row's height as the max cell content height at the
+    cell's resolved width.
+
+- `auto.rb` — Auto strategy (CSS 2.1):
+  1. For each cell, measure min-content width (longest unbreakable
+     word) and max-content width (single line).
+  2. Aggregate to per-column min/max (respecting colspan: distribute
+     spanned cell's min/max evenly across spanned columns).
+  3. Distribute target_width:
+     - If surplus over max: distribute by max-content ratio.
+     - If between min and max: distribute by max ratio of the slack.
+     - If less than min: each column gets its min (may overflow).
+  4. Compute row heights same as Fixed.
+
+Both strategies return a `ResolvedGrid`.
+
+## Done-When
+
+- [ ] Fixed layout: `Fixed.new(table, target_width: 300).layout`
+      honours the spec widths.
+- [ ] Fixed layout scales when target_width != sum(specs).
+- [ ] Auto layout: a column containing "antidisestablishmentarianism"
+      gets at least the word's width.
+- [ ] Auto layout: narrow column for short content, wide for long.
+- [ ] ResolvedGrid.cell_rects respects colspan (cell spans 2 columns'
+      combined width) and rowspan.
+- [ ] Specs cover both strategies + colspan/rowspan.

data/TODO.implementation/29-table-renderer.md

@@ -0,0 +1,55 @@
+---
+priority: P0
+phase: 8
+depends_on: [28, 22]
+layer: table
+est: 2d
+status: pending
+---
+
+## Problem
+
+Given a resolved grid (column widths + cell rects), render the table:
+draw borders as a single-line grid (border-collapse model), fill
+backgrounds, place each cell's content via its flowables. The
+renderer must produce `PlacedBox[]` entries that the PDF renderer
+(TODO 22) consumes.
+
+## Approach
+
+File: `lib/arrolio/table_renderer.rb`.
+
+```ruby
+class Arrolio::TableRenderer
+  def initialize(table, grid)
+  def render(canvas, x_origin, y_origin, context) -> Float (total height)
+end
+```
+
+Steps:
+1. **Backgrounds**: for each row, fill the row's rect with the row's
+   `background_color` (or table's `header_background` for header rows).
+2. **Borders**: border-collapse grid.
+   - Vertical lines: at each column boundary (including outer left/right).
+   - Horizontal lines: at each row boundary (including outer top/bottom).
+   - Stroke colour from `table.style.border_color`; width from
+     `table.style.border_width`.
+3. **Content**: for each cell, stack its flowables vertically inside
+   the cell rect (accounting for `cell_padding`).
+
+Output: emits `canvas` operations directly OR returns PlacedBox[]
+(we'll do canvas operations directly for simplicity; the PlacedBox
+indirection is for non-PDF renderers, deferred).
+
+PDF coordinate flip: PDF y grows up; table y grows down. Convert via
+`y_origin - rect.y - rect.height`.
+
+## Done-When
+
+- [ ] A 2×2 table renders as a visible grid with content in each cell.
+- [ ] Header row background differs from body rows when
+      `header_background` is set.
+- [ ] Border-collapse: adjacent cells share a single 1pt line, not
+      doubled.
+- [ ] Cell content respects `cell_padding`.
+- [ ] Colspan cell spans the combined width visually.

data/TODO.implementation/30-table-flowable.md

@@ -0,0 +1,53 @@
+---
+priority: P0
+phase: 8
+depends_on: [29, 16]
+layer: table
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Tables longer than a single page must split between rows (never
+mid-cell). Header rows repeat on every fragment. The TableFlowable
+wraps a Table so it integrates with the page-flow engine like any
+other Flowable.
+
+## Approach
+
+File: `lib/arrolio/flowables/table_flowable.rb`.
+
+```ruby
+class Arrolio::Flowables::TableFlowable < Arrolio::Flowable
+  def initialize(table, algorithm: :auto)
+  def height(width, context)
+  def render(canvas, x, y, width, context)
+  def splittable?; true; end
+  def do_split(width, remaining_height, context) -> [head, tail]
+end
+```
+
+`do_split` algorithm:
+1. Layout the table at `width` to get the resolved grid.
+2. Walk rows; cumulate heights.
+3. Header rows always go in the head.
+4. Body rows: include in head if `cum_height + row_h <= remaining_height`;
+   otherwise include in tail.
+5. If no body rows fit (`head_rows == header_rows`), return
+   `[nil, self]` so the engine advances to a new page.
+6. Build two tables: `head_table` (header + first N body rows),
+   `tail_table` (header + remaining body rows — header repeats!).
+7. Return `[TableFlowable.new(head_table), TableFlowable.new(tail_table)]`.
+
+`render` uses TableRenderer.
+
+## Done-When
+
+- [ ] A short table (fits on one page) renders without splitting.
+- [ ] A 30-row table on a single-page frame splits into multiple
+      pages, header row repeated on each.
+- [ ] Split is between rows, never mid-cell.
+- [ ] `do_split` with insufficient remaining returns `[nil, self]`.
+- [ ] Engine then advances and renders the table on the next page.
+- [ ] Colspan/rowspan preserved across splits.

data/TODO.implementation/31-list-model.md

@@ -0,0 +1,45 @@
+---
+priority: P1
+phase: 9
+depends_on: [02, 16]
+layer: list
+est: 1d
+status: pending
+---
+
+## Problem
+
+Lists (bullet, numbered, definition) need a typed model: items with
+markers, nested lists, marker schemes (decimal, alpha, roman, bullet
+variants).
+
+## Approach
+
+Files under `lib/arrolio/list/`:
+
+- `list.rb` — value object: `items` (Array of Item), `marker_scheme`
+  (Symbol), `style`. Methods: `nested?`, `level`.
+
+- `item.rb` — `Item = Struct.new(:marker, :content, :sublists,
+  keyword_init: true)`. `marker` may be a String (explicit) or nil
+  (use scheme). `content` is a Flowable or Array. `sublists` is
+  Array of List (for nesting).
+
+- `marker_scheme.rb` — module of constants:
+  - `BULLET` ("•")
+  - `DASH` ("—")
+  - `DECIMAL` (Proc: `->(i) { "#{i}." }`)
+  - `LOWER_ALPHA`, `UPPER_ALPHA`
+  - `LOWER_ROMAN`, `UPPER_ROMAN`
+  - Custom schemes via Proc.
+
+Nested lists indent and may use different schemes at different
+levels (decimal at level 0, lower-alpha at level 1, etc.).
+
+## Done-When
+
+- [ ] A 3-item bullet list has `marker_scheme == :bullet`.
+- [ ] `MarkerScheme::DECIMAL.call(3) == "3."`.
+- [ ] `MarkerScheme::LOWER_ROMAN.call(4) == "iv."`.
+- [ ] A nested list (`item.sublists`) reports `level == 1`.
+- [ ] Specs cover all built-in schemes + nesting.

data/TODO.implementation/32-list-flowable.md

@@ -0,0 +1,54 @@
+---
+priority: P1
+phase: 9
+depends_on: [31, 18]
+layer: list
+est: 2d
+status: pending
+---
+
+## Problem
+
+A list flowable must:
+- Render items as a two-column layout (label gutter + body).
+- Auto-size the gutter to the widest marker.
+- Apply hanging indent so wrapped lines align with the first line.
+- Support nested lists (deeper indent).
+- Be splittable between items (one item per page minimum).
+
+## Approach
+
+File: `lib/arrolio/flowables/list_flowable.rb`.
+
+```ruby
+class Arrolio::Flowables::ListFlowable < Arrolio::Flowable
+  def initialize(list, level: 0)
+  def height(width, context)
+  def render(canvas, x, y, width, context)
+  def splittable?; true; end
+  def do_split(width, remaining_height, context)
+end
+```
+
+Layout algorithm:
+1. For each item, compute the marker text (from scheme or explicit).
+2. Label column width = max marker width + small gap (e.g. 6pt).
+3. Body column width = `width - label_column - indent`.
+4. Render item:
+   - Place marker in label column (right-aligned to body column).
+   - Place content flowable in body column.
+   - Hanging indent: if content wraps, subsequent paragraphs in the
+     item align with the body column's left edge.
+5. Nested lists: render as a sub-ListFlowable indented further.
+
+Splitting: between items only. If first item doesn't fit on the
+current frame, advance page.
+
+## Done-When
+
+- [ ] A 3-item bullet list renders with "•" markers in the left gutter.
+- [ ] Decimal-numbered list auto-sizes gutter to "12." or wider.
+- [ ] Wrapped content lines align with the first line (hanging indent).
+- [ ] Nested list indents further and uses different marker scheme.
+- [ ] A list longer than the page splits between items.
+- [ ] Specs cover all of the above.