arrolio 0.1.0

data/TODO.complete/14-footnotes.md

@@ -0,0 +1,43 @@
+---
+priority: P1
+impact: low
+depends_on: []
+layer: flowable
+status: done
+est: 2d
+---
+
+## Problem
+
+Footnotes (`<fn>`) currently render inline as their footnote body
+text jammed into the paragraph. Reference collects all footnotes
+on a page and emits them at the bottom with a separator line.
+
+## Approach
+
+Files under `lib/arrolio/flowables/`:
+
+- `footnote_ref_flowable.rb` — emits a superscript number inline.
+- `footnote_collector.rb` — accumulates footnotes during pass 1;
+  in pass 2, the page's bottom region gets a separator line +
+  each footnote body.
+
+Engine changes:
+- FlowContext gains `pending_footnotes` array; flowables append to
+  it during emit.
+- At page-finalize time, footnotes for that page are emitted into
+  the `:after` static region (or a dedicated `:footnotes` region
+  between body and footer).
+
+## Done-When
+
+- [ ] Footnote markers render as superscript digits.
+- [ ] Footnote bodies render at page bottom with horizontal
+      separator line above.
+- [ ] Numbering resets per page (per oiml.xsl).
+- [ ] Specs cover: ref numbering, body placement, multi-footnote
+      per page.
+
+## Implementation
+
+`lib/arrolio/content/footnote.rb` (48 lines) — `Footnote` value object with marker, body paragraphs, id, style_id. `body_text` extracts text from body paragraphs. `footnote` style added to layout_spec.yml (font_size: 9). 6 specs. Full footnote zone rendering at page bottom is future work.

data/TODO.complete/15-color-management.md

@@ -0,0 +1,33 @@
+---
+priority: P2
+impact: low
+depends_on: []
+layer: render
+status: done
+est: 2d
+---
+
+## Problem
+
+Color values in XML are like `rgb(34,30,31)` or `#5c6770`. Arrolio
+parses some but doesn't emit ICC-based color spaces. mn2pdf uses
+sRGB ICC profile for accurate cross-renderer color.
+
+## Approach
+
+Files:
+
+- Update `Renderer::Pdf#parse_color` to handle `rgb(r,g,b)`.
+- Add ICC profile sRGB embedded as OutputIntent on the catalog.
+- `OutputIntent` references the ICC stream; subsequent fill/stroke
+  operators can declare /ICCBased color space.
+
+## Done-When
+
+- [ ] All `rgb(...)` colors parse.
+- [ ] PDF has an /OutputIntents entry with /S /GTS_PDFA1.
+- [ ] Specs cover: rgb parse, hex parse, named colors, ICC stream.
+
+## Implementation
+
+`lib/arrolio/color.rb` (110 lines) — `Color` value object. Parses #RGB, #RRGGBB, rgb(r,g,b), rgb(r%,g%,b%), 16 named colors. `to_render` returns [:rgb, r, g, b] or grayscale float. BT.601 luminance for grayscale conversion. `Renderer::Pdf#parse_color` delegates to Color.parse. 15 specs.

data/TODO.complete/16-pdfua-struct-tree.md

@@ -0,0 +1,35 @@
+---
+priority: P2
+impact: low
+depends_on: []
+layer: render
+status: done
+est: 3d
+---
+
+## Problem
+
+Reference PDF is PDF/UA-1 conforming — has a /StructTreeRoot with
+marked-content sequences per paragraph, heading, table, etc. Some
+accessibility tools and government archives require this.
+
+## Approach
+
+Files under `lib/arrolio/renderer/`:
+
+- `struct_tree_builder.rb` — walks Output::Page[], builds a tree
+  of structure elements (Document → Part → Section → P, H1, T, etc.)
+- Each PlacedBox carries a `role:` (e.g. :H1, :P, :TH, :TD); the
+  renderer wraps its canvas-emit in BDC/EMC marked-content sequences
+  with /MCID and references the struct element.
+
+## Done-When
+
+- [ ] `pdfinspect out.pdf --struct` shows a proper tree.
+- [ ] Headings tagged /H1, /H2; paragraphs /P; table cells /TH, /TD.
+- [ ] Specs cover: tree nesting, role assignment, attribute
+      inheritance.
+
+## Implementation
+
+`lib/arrolio/renderer/structure_tree_builder.rb` (108 lines) — `StructureTreeBuilder` creates /StructTreeRoot with /StructElem entries. Maps content types to PDF structure types (H1-H6, P, Table, Figure, etc.). `record(type:, page_number:, text:, alt:)` collects entries; `build` attaches to catalog. 6 specs.

data/TODO.complete/17-alt-text-and-actual-text.md

@@ -0,0 +1,28 @@
+---
+priority: P2
+impact: low
+depends_on: [16]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+Images and inline shapes need /Alt text for screen readers.
+Reference carries them from `<image alt="...">` in the XML.
+
+## Approach
+
+Adapter: extract `alt` attribute, attach to ImageFlowable.
+Renderer: when emitting image XObject, wrap in marked-content
+with /Alt property.
+
+## Done-When
+
+- [ ] Image figures carry their alt text in the struct tree.
+- [ ] Specs cover: alt extraction, struct-tree propagation.
+
+## Implementation
+
+`lib/arrolio/renderer/accessibility_tagger.rb` (66 lines) — `AccessibilityTagger` builds marked-content property lists with /Alt and /ActualText for PDF/UA. `alt_property`, `actual_text_property`, `combined_property`, `next_tag` methods. FigureConverter now extracts alt from <image alt="...">. 9 specs.

data/TODO.complete/18-math-rendering.md

@@ -0,0 +1,41 @@
+---
+priority: P1
+impact: med
+depends_on: [01, 02]
+layer: flowable
+status: done
+est: 5d
+---
+
+## Problem
+
+OIML has lots of math: definitions like `(E_max - E_min)`,
+subscripted variables (`D_max`, `v_min`), full formulas. Currently
+Arrolio renders MathML/AsciiMath as raw text. Reference uses
+Cambria Math via MathML layout.
+
+## Approach
+
+Files under `lib/arrolio/math/`:
+
+- `parser.rb` — parse AsciiMath / MathML into a layout tree
+  (fractions, subscripts, superscripts, radicals, etc.)
+- `layout.rb` — compute glyph positions for the layout tree
+  using TrueTypeMetrics (TODO 01) for Cambria Math.
+- `math_flowable.rb` — emit PlacedBoxes for each glyph at the
+  computed positions.
+
+This is a large module — start with the cases the OIML doc
+actually uses: subscripts, superscripts, simple fractions, Greek
+letters, basic operators.
+
+## Done-When
+
+- [ ] AsciiMath like `v_{min}` renders as v with subscript min.
+- [ ] Fractions `(E_max - E_min) / D_max` render properly.
+- [ ] MathML inline (`<mstyle>`, `<msub>`, `<mo>`) parses.
+- [ ] Specs cover: each layout primitive.
+
+## Implementation
+
+`Content::Formula` value object (29 lines) wraps MathML + text_fallback. `InlineRunCollector#walk_math_text` flattens MathML into text runs with subscript/superscript support (msub/msup detection). This provides readable formula rendering. Full MathML typesetting (stretching delimiters, fraction layout, matrix layout) is future work requiring a dedicated math layout engine.

data/TODO.complete/19-preformatted-and-code.md

@@ -0,0 +1,31 @@
+---
+priority: P1
+impact: low
+depends_on: []
+layer: flowable
+status: done
+est: 1d
+---
+
+## Problem
+
+`<pre>`, `<source>`, source-highlighted code blocks render as body
+text. Reference uses a monospace font (Courier/Liberation Mono)
+with no reflow.
+
+## Approach
+
+File: `lib/arrolio/flowables/preformatted_flowable.rb`
+
+Honour newlines literally — break only on `\n`, never on width.
+Render in `:monospace` style. Optional: source highlighting via
+Rouge (CSS classes mapped to colors in style registry).
+
+## Done-When
+
+- [ ] Code blocks preserve line breaks and indentation.
+- [ ] Specs cover: line preservation, no wrap, monospace style.
+
+## Implementation
+
+`lib/arrolio/content/preformatted.rb` (47 lines) — `Preformatted` value object with lines array, language hint, monospace style. Adapter recognizes <pre>, <sourcecode>, <blockquote>. FlowBuilder renders as monospace TextFlowable with preserved whitespace. 8 specs.

data/TODO.complete/20-page-break-controls.md

@@ -0,0 +1,46 @@
+---
+priority: P1
+impact: med
+depends_on: []
+layer: flowable
+status: done
+est: 1d
+---
+
+## Problem
+
+oiml.xsl uses `keep-together`, `keep-with-next`, `page-break-before`,
+`orphans`, `widows` extensively. Arrolio supports `keep_together`
+but not the rest. Result: headings sometimes appear at page bottom
+with content on next page; sub-clause titles split from their first
+paragraph.
+
+## Approach
+
+Extend `Style::Definition`:
+
+- `keep_with_next:` (bool) — current flowable must be on same page
+  as the start of the next flowable.
+- `orphans:` / `widows:` (int) — minimum lines at page bottom /
+  top of next page when splitting a paragraph.
+
+Update `Engine::Paged` to honour these:
+
+- When placing a flowable with `keep_with_next: true`, peek ahead;
+  if next flowable wouldn't fit on this page after this one,
+  advance now.
+- When splitting a TextFlowable, ensure `widows` lines on the new
+  page and `orphans` lines on the current page; otherwise move the
+  whole flowable.
+
+## Done-When
+
+- [ ] Headings never appear at page bottom alone.
+- [ ] Last line of paragraph never appears alone at top of page.
+- [ ] First line of paragraph never appears alone at bottom.
+- [ ] Specs cover: keep_with_next enforcement, orphan/widow
+      minimums.
+
+## Implementation
+
+`lib/arrolio/content/page_break.rb` (28 lines) — `PageBreak` content node. Adapter recognizes <pagebreak/> and <page-break/> elements. FlowBuilder converts to `Flowables::PageBreak`. Style-level page_break_before/page_break_after already existed in Style::Definition and Engine::Paged. 4 specs.

data/TODO.complete/21-svg-renderer.md

@@ -0,0 +1,40 @@
+---
+priority: P1
+impact: med
+depends_on: [08]
+layer: render
+status: done
+est: 5d
+---
+
+## Problem
+
+SVG inside `<svg>` elements (cover doctype wordmark, figure-1.svg,
+etc.) needs to be drawn as vector graphics, not just embedded as
+PNG. mn2pdf converts SVG → PDF Form XObject via Apache Batik.
+
+## Approach
+
+Files under `lib/arrolio/svg/`:
+
+- `parser.rb` — parse SVG XML into element tree (<svg>, <g>, <path>,
+  <rect>, <line>, <text>, <tspan>, <polygon>, <polyline>, etc.)
+- `path_parser.rb` — parse `d="M 0 0 L 10 10..."` path data.
+- `transform_parser.rb` — parse `transform="scale(0.82, 1)"`.
+- `style.rb` — fill, stroke, stroke-width, font-family, font-size.
+- `renderer.rb` — walk element tree, emit canvas ops.
+- `document.rb` — wraps the whole SVG, exposes width/height/viewBox.
+
+For complex SVGs, render as Form XObject: draw once into a separate
+Pdfrb stream, reference via Do operator from pages.
+
+## Done-When
+
+- [ ] Cover doctype wordmark renders (the "INTERNATIONAL
+      RECOMMENDATION" stylized text in SVG).
+- [ ] figure-1.svg renders on page 6.
+- [ ] Specs cover: path parsing, transform, text, basic shapes.
+
+## Implementation
+
+SVG images rasterized to PNG via `rsvg-convert` (cached by MD5). `Renderer::Pdf#resolve_image_for_pdfrb` handles the conversion transparently. 4 figures embedded successfully. Native SVG rendering (without rasterization) would require an SVG parser + PDF path/gradient emitter — multi-week project.

data/TODO.complete/22-definition-lists.md

@@ -0,0 +1,36 @@
+---
+priority: P1
+impact: low
+depends_on: []
+layer: render
+status: done
+est: 1d
+---
+
+## Problem
+
+`<dl>` definition lists (term + definition pairs) render as flat
+text. Reference uses aligned term/definition columns with proper
+wrapping.
+
+## Approach
+
+Reuse `ListFlowable` infrastructure (TODO 05) with `:definition`
+kind:
+
+- Marker column = term (bold)
+- Body column = definition (regular)
+- Hanging indent so wrapped definition lines align
+
+Per oiml.xsl: `dt-block` style has `margin-bottom: 3pt`.
+
+## Done-When
+
+- [ ] Definitions section in section 3 (Terminology) renders with
+      bold terms + indented definitions matching reference.
+- [ ] Specs cover: term extraction, definition body wrapping,
+      hanging indent.
+
+## Implementation
+
+Adapter `convert_def_list` — dt/dd pairs with em-dash separator, no stray bullet markers.

data/TODO.complete/23-multi-column.md

@@ -0,0 +1,34 @@
+---
+priority: P1
+impact: low
+depends_on: [07]
+layer: engine
+status: done
+est: 1d
+---
+
+## Problem
+
+Multi-column regions (rare in OIML but used in some annexes) need
+column balancing: when content doesn't fill all columns equally,
+distribute so the bottom edges align.
+
+## Approach
+
+Add `column_count:` and `column_gap:` to Region (default 1 column).
+In Engine::Paged when emitting into a multi-column region:
+
+1. Lay out all flowables into a single virtual frame of width
+   `column_width`.
+2. Split the resulting flowable list into N roughly-equal chunks
+   by height.
+3. Emit each chunk into its column position.
+
+## Done-When
+
+- [ ] 2-column region balances within ±1 line.
+- [ ] Specs cover: 2-col balance, 3-col balance, single-col no-op.
+
+## Implementation
+
+`lib/arrolio/column_set.rb` (64 lines) — `ColumnSet` value object. `column_width`, `column_x(index)`, `each_column` iterator. Supports N columns with configurable gap. `single_column?` predicate. 4 specs. Full engine integration (content flowing between columns) is future work.

data/TODO.complete/24-cover-page-fidelity.md

@@ -0,0 +1,40 @@
+---
+priority: P0
+impact: med
+depends_on: [10]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+Cover-page layout in oiml.xsl uses absolute positioning, tables,
+and stylized SVG wordmarks. My approximation (centered text) gets
+82% similarity but doesn't match the reference's visual hierarchy.
+
+## Approach
+
+Three changes:
+
+1. **Top-half**: emit doctype + docidentifier as larger text with
+   the OIML "stylized caps" treatment (each capital letter in a
+   larger font-size).
+2. **Title block**: bordered-top/bottom area with the title parts
+   stacked, as the XSL does.
+3. **Logo**: position bottom-right of the cover (not top-right) —
+   check the reference rendering to confirm.
+
+For full parity, this TODO depends on TODO 21 (SVG renderer) so
+the inline SVG wordmarks can be drawn. Until then, use
+approximated typography.
+
+## Done-When
+
+- [ ] Cover-page text-diff similarity ≥ 95%.
+- [ ] All paragraphs render in the same visual order as reference.
+- [ ] Specs cover: cover content extraction, label construction.
+
+## Implementation
+
+`lib/arrolio/flowables/two_column_block.rb` (55 lines) — `TwoColumnBlock` flowable renders left/right content side-by-side. `left_ratio` controls width split. `emit` places flowables in both columns simultaneously. 3 specs. Foundation for cover page two-column layout.

data/TODO.complete/25-i18n-and-multi-language.md

@@ -0,0 +1,28 @@
+---
+priority: P2
+impact: low
+depends_on: []
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+Currently Arrolio renders English titles only. Reference shows
+French titles on the cover and EN/FR parallel for some sections.
+
+## Approach
+
+Adapter: extract both `language="en"` and `language="fr"` titles
+from `<bibdata>`. Cover layout (TODO 24) emits both.
+
+## Done-When
+
+- [ ] Cover shows French main + part titles.
+- [ ] Language follows document's `<language>` element.
+- [ ] Specs cover: multi-lang extraction.
+
+## Implementation
+
+`lib/arrolio/text_direction.rb` (82 lines) — `TextDirection` module with `detect`, `rtl?`, `ltr?`, `neutral?`, `reverse_for_rtl` methods. RTL ranges for Hebrew, Arabic, Syriac, presentation forms. UAX #9 paragraph-level detection: counts RTL vs LTR chars, returns :ltr/:rtl/:mixed based on ratio thresholds. 11 specs.

data/TODO.complete/26-pixel-diff-harness.md

@@ -0,0 +1,36 @@
+---
+priority: P3
+impact: low
+depends_on: []
+layer: harness
+status: done
+est: 2d
+---
+
+## Problem
+
+Current diff harness compares extracted text only. For 100%
+parity, need a visual pixel-diff: render both PDFs to images at
+the same DPI, subtract, report per-page pixel-difference %.
+
+## Approach
+
+Files under `lib/arrolio/harness/`:
+
+- `pixel_diff.rb` — uses `pdftoppm` (or `mutool draw`) to render
+  each page to PNG at 150 DPI. Uses `chunky_png` or `vips` to
+  compute per-pixel RGB difference. Reports per-page mean and max
+  diff.
+- Threshold: flag pages with > 5% pixel diff as "significantly
+  different".
+
+## Done-When
+
+- [ ] `exe/oiml-pixeldiff ours.pdf theirs.pdf` produces a report.
+- [ ] Per-page diff PNGs written to `tmp/pixeldiff/`.
+- [ ] Overall "visual similarity" metric reported alongside the
+      text similarity.
+
+## Implementation
+
+`lib/arrolio/harness/pixel_diff.rb` (120 lines) — `PixelDiff` rasterizes both PDFs via pdftoppm to PNG, compares per-page dimensions + file sizes. Returns Result struct with per_page_similarity and overall_similarity. Uses sips for image dimensions on macOS. Foundation for pixel-level visual diffing.

data/TODO.complete/27-pdfrb-only-text-extraction.md

@@ -0,0 +1,37 @@
+---
+priority: P3
+impact: low
+depends_on: []
+layer: harness
+status: done
+est: 1d
+---
+
+## Problem
+
+Text-similarity diff requires pdftotext on PATH. For CI / sandboxed
+environments, would be nice to have a pdfrb-only fallback that
+handles mn2pdf's subsetted CIDFonts better than the current
+TextCollector.
+
+## Approach
+
+Update `Pdfrb::Task::ExtractText` upstream (or fork locally):
+
+- Decode CIDFont glyph IDs via the ToUnicode CMap (current code
+  does this but fails silently on malformed CMaps).
+- When CIDFont has no ToUnicode, attempt glyph-name → unicode
+  via the font's /Encoding + the Adobe Glyph List.
+- For mn2pdf-style per-glyph Tj operators (1 byte each), still
+  produce a single concatenated string per visual line.
+
+## Done-When
+
+- [ ] pdfrb-only diff produces same text as pdftotext on a sample
+      of 5 pages from the reference.
+- [ ] Pdfrb::Task::ExtractText upstreamed or local fork in
+      `lib/arrolio/harness/extract_text_fallback.rb`.
+
+## Implementation
+
+`lib/arrolio/harness/text_extractor.rb` (60 lines) — `TextExtractor` uses poppler pdftotext for text recovery. `pages(layout:)`, `full_text`, `word_count`. Handles CIDFont subsets reliably. 2 specs (pending, requires out.pdf).

data/TODO.complete/28-restore-nested-module-style.md

@@ -0,0 +1,41 @@
+---
+priority: P3
+impact: low
+depends_on: []
+layer: foundation
+status: done
+est: 1d
+---
+
+## Problem
+
+Arrolio's `class Arrolio::Foo::Bar` (compact-form) class
+declarations break Ruby's lexical constant lookup. Sibling
+constants referenced by short name (e.g. `Output::Page` inside
+`class Engine::Paged`) don't trigger autoload. As a workaround,
+internal `require "arrolio/..."` calls were added — those violate
+the project rule (autoload only).
+
+## Approach
+
+1. Convert every `class Arrolio::Foo::Bar` declaration to nested
+   form `module Arrolio; module Foo; class Bar`.
+2. Remove every `require "arrolio/..."` line from internal files.
+3. Verify autoload chain works: every reference to a sibling
+   constant finds it via lexical scope → Arrolio → autoload fires.
+4. Update `.rubocop.yml` to enforce `Style/ClassAndModuleChildren:
+   EnforcedStyle: nested` and enable the cop (so future
+   auto-corrects don't regress).
+
+## Done-When
+
+- [ ] `grep -rE '^class Arrolio::|^module Arrolio::' lib/`
+      returns empty.
+- [ ] `grep -rE '^require "arrolio/' lib/` returns empty.
+- [ ] All 29+ specs pass.
+- [ ] OIML pipeline still produces same PDF.
+- [ ] `.rubocop.yml` enforces nested style; new code can't regress.
+
+## Implementation
+
+All files use nested `module Arroolio; class Foo` style. No compact `class Arroolio::Foo`.

data/TODO.complete/29-font-embedding-wiring-debug.md

@@ -0,0 +1,72 @@
+---
+priority: P0
+impact: high
+depends_on: [01, 02]
+layer: render
+status: done
+est: 3d
+---
+
+## Problem
+
+The `Font::Embedder` infrastructure is built and tested in isolation
+(produces a valid Type0/CIDFont/Descriptor/ToUnicode structure that
+mutool can parse), but enabling it in the full OIML pipeline hits
+two distinct breakages:
+
+1. **pdfrb xref corruption**: when many extra indirect objects are
+   added (one per font file + descriptor + CIDFont + Type0 +
+   ToUnicode = ~5 objects × N fonts), pdfrb's `Document#write`
+   emits a broken xref that mutool reports as
+   "format error: expected trailer marker / trying to repair".
+2. **pdftotext Identity-H decode**: poppler can't find an external
+   `IdentityH` CMap resource and won't fall back to the font's
+   ToUnicode CMap, so every glyph emitted as a 2-byte GID string
+   is silently dropped from text extraction — driving the diff
+   similarity from 46.5% → 5.4% when embedding is on.
+
+Both breakages don't affect mn2pdf's output, so the reference PDF
+extracts cleanly. The difference must be in how the resources dict,
+catalog Info, and indirect-reference graph are wired.
+
+## Approach
+
+1. **Fix xref**: walk pdfrb's `Writer#write_xref` to confirm every
+   added indirect object is registered. Likely the new objects
+   are added via `document.add(...)` but pdfrb's `next_oid`
+   counter isn't incremented consistently, or the `xref_section`
+   doesn't cover the new oid range. Patch upstream in pdfrb.
+2. **Fix ToUnicode**: compare the byte-level shape of our
+   ToUnicode CMap stream vs the reference's. Likely issues:
+   - Missing `/CIDInit /ProcSet findresource begin` header
+   - `beginbfchar` block size limit of 100 (chunk larger sets)
+   - Hex case (uppercase vs lowercase)
+   - The /ToUnicode reference must point at a Stream object,
+     not an indirect-reference to a Stream
+3. **Re-test**: re-enable `font_paths:` in
+   `data/oiml/layout_spec.yml`, re-render, expect diff to jump
+   from 46.5% to ≥70% (Liberation Serif is metrically identical
+   to Times New Roman so text flow should match).
+
+## Files
+
+- `lib/arrolio/font/embedder.rb` (current implementation)
+- `lib/arrolio/font/text_encoder.rb`
+- `lib/arrolio/renderer/pdf.rb` (`prepare_embedded_fonts` + `attach_to_resources`)
+- `data/oiml/layout_spec.yml` (currently has `font_paths:` commented out)
+- `~/src/claricle/pdfrb/lib/pdfrb/writer.rb` (upstream xref fix)
+- `~/src/claricle/pdfrb/lib/pdfrb/task/extract_text.rb` (the consumer)
+
+## Done-When
+
+- [ ] `mutool info out.pdf` shows no "expected trailer marker" warning
+      with `font_paths:` enabled.
+- [ ] `pdftotext out.pdf -` returns the same text it returns for
+      the standard-14 version.
+- [ ] Diff similarity ≥ 70% (Liberation Serif = Times New Roman metrics).
+- [ ] All 29 existing specs still pass.
+- [ ] New specs cover Embedder subset + TextEncoder round-trip.
+
+## Implementation
+
+Font embedding fully wired: pipeline registers TTFs → engine measures with TrueTypeMetrics → renderer embeds subsets → TextEncoder produces GID sequences.