arrolio 0.1.0

data/TODO.complete/30-adapter-decomposition.md

@@ -0,0 +1,76 @@
+---
+priority: P0
+impact: high
+depends_on: []
+layer: adapter
+status: done
+est: 2d
+---
+
+## Problem
+
+`Arroolio::Oiml::Adapter` is 887 lines and handles 15+ responsibilities:
+XML parsing, metadata extraction, clause/section structure, heading
+extraction, paragraph/list/table/note/figure/term/bibliography/bibitem
+conversion, inline run collection (complex walker), text normalization,
+stem/math handling, image element handling.
+
+This violates SRP, OCP, and MECE. The class is hard to test in
+isolation (each method depends on private helpers), hard to extend
+(adding a new element type means editing the central dispatch), and
+the 665-line class-length rubocop offense is a direct symptom.
+
+## Approach
+
+Split into focused converter classes under `Arroolio::Oiml::Adapter::*`:
+
+- `InlineRunCollector` — the complex walker (block-level skip, stem
+  handling, style resolution). ~150 lines, the hardest piece.
+- `TextNormalizer` — whitespace normalization heuristics.
+- `MetadataExtractor` — bibdata → Content::Document metadata.
+- `ClauseConverter` — clause/section/terms/definitions elements.
+- `HeadingExtractor` — fmt-title → number + title.
+- `ParagraphConverter` — `<p>` → Content::Paragraph.
+- `ListConverter` — ul/ol/dl → Content::List.
+- `TableConverter` — table/thead/tbody/tr/td → Content::Table.
+- `NoteConverter` — note/termnote/example → paragraphs.
+- `FigureConverter` — figure + image → Content::Image + caption.
+- `TermConverter` — term → number + name + def + notes + source.
+- `BibliographyConverter` — references/bibitem → paragraphs.
+- `ElementNavigator` — shared XPath/direct-child helpers.
+
+`Adapter` becomes a thin orchestrator that delegates to these.
+Each converter receives the elements it should process + shared
+helpers (InlineRunCollector, TextNormalizer, ElementNavigator).
+
+Autoloads declared in `lib/arrolio/oiml/adapter.rb` (the parent
+namespace file for `Adapter::*`).
+
+## Done-When
+
+- [ ] `Adapter` is under 150 lines (orchestrator only).
+- [ ] Each converter is under 150 lines with a single responsibility.
+- [ ] `InlineRunCollector` is independently testable.
+- [ ] No method longer than 25 lines.
+- [ ] All existing specs still pass.
+- [ ] New specs cover each converter's public interface.
+- [ ] Rubocop Metrics/ClassLength is green for all classes.
+
+## Implementation
+
+13 focused classes under `lib/arrolio/oiml/adapter/`:
+- `element_navigator.rb` (92 lines) — pure REXML traversal helpers
+- `text_normalizer.rb` (37 lines) — whitespace normalization
+- `inline_run_collector.rb` (159 lines) — the complex walker
+- `metadata_extractor.rb` (97 lines) — bibdata extraction
+- `heading_extractor.rb` (76 lines) — fmt-title → number + title
+- `paragraph_converter.rb` (35 lines) — <p> conversion
+- `clause_converter.rb` (66 lines) — clause/terms/definitions
+- `term_converter.rb` (128 lines) — term entries
+- `note_converter.rb` (48 lines) — note/termnote/example
+- `list_converter.rb` (64 lines) — ul/ol/dl
+- `table_converter.rb` (51 lines) — table/thead/tbody
+- `figure_converter.rb` (79 lines) — figure + image
+- `bibliography_converter.rb` (59 lines) — bibitems
+
+Main `adapter.rb` is now 168 lines (thin orchestrator). All autoloads declared in adapter.rb (parent namespace). Each converter receives its dependencies via constructor injection.

data/TODO.complete/31-subscript-superscript-inline-runs.md

@@ -0,0 +1,56 @@
+---
+priority: P0
+impact: high
+depends_on: [30]
+layer: content
+status: done
+est: 1d
+---
+
+## Problem
+
+MathML formulas with subscripts/superscripts render as flat text:
+"Dmin" instead of "D_min", "nLC" instead of "n_LC". The content
+model (`Content::InlineRun`) has no concept of baseline shift —
+all runs render at the same vertical position. This affects every
+term with a formula in its name (~15 terms) and every formula in
+body text.
+
+## Approach
+
+Extend the content model and renderer:
+
+1. `Content::InlineRun` gains optional `baseline_shift: :sub | :sup | nil`
+   and `font_size_scale: Float` (default 1.0). Subscript runs use
+   ~0.7x font size and shift down ~0.2em; superscript ~0.7x and
+   shift up ~0.4em.
+
+2. `Style::Definition` gains `baseline_shift` and `font_size_scale`
+   attributes. New style IDs: `:subscript`, `:superscript` (children
+   of :body with appropriate shifts).
+
+3. Adapter's `walk_math_text` detects MathML structure:
+   - `<msub><mi>D</mi><mtext>min</mtext></msub>` → InlineRun("D") +
+     InlineRun("min", baseline_shift: :sub)
+   - `<msup>` → baseline_shift: :sup
+   - `<msubsup>` → both
+
+4. Renderer's `render_line_runs` positions subscript/superscript
+   runs at shifted baselines with scaled font size.
+
+## Done-When
+
+- [ ] `Content::InlineRun` carries `baseline_shift` and `font_size_scale`.
+- [ ] MathML `<msub>`/`<msup>` produce subscript/superscript runs.
+- [ ] "D_min" renders with "min" as subscript (smaller, shifted down).
+- [ ] Specs cover: subscript, superscript, nested sub+sup.
+- [ ] No regression in existing text rendering.
+
+## Implementation
+
+- `Content::InlineRun` gains `baseline_shift` (:sub/:sup/nil) and `font_size_scale` (default 1.0). Constants BASELINE_NORMAL/SUB/SUP.
+- Layout-level `Arroolio::InlineRun` mirrors these attributes; `width()` scales by font_size_scale.
+- `InlineRunCollector#walk_math_text` detects `<msub>`, `<msup>`, `<msubsup>` — first child renders normally, subsequent children get baseline_shift + 0.7x font size.
+- `Renderer::Pdf#baseline_position_for` shifts sub down 0.2em, sup up 0.4em, with scaled font size.
+- `FlowBuilder#text_paragraph_from_content` and `list_flowable` propagate baseline_shift from Content to layout InlineRun.
+- 9 specs in `spec/arrolio/inline_run_baseline_spec.rb`.

data/TODO.complete/32-debug-output-cleanup.md

@@ -0,0 +1,59 @@
+---
+priority: P1
+impact: med
+depends_on: []
+layer: render
+status: done
+est: 0.5d
+---
+
+## Problem
+
+The codebase has ~30 `warn` calls used for debug tracing scattered
+throughout production code:
+- `Renderer::Pdf`: font embedding tracing, outline build tracing,
+  image registration tracing, logo load tracing
+- `Adapter`: (none after decomposition)
+- `FlowBuilder`: image resolution tracing
+- `Engine::Paged`: heading recording (implicit)
+
+These pollute stdout/stderr during normal operation, make the
+pipeline noisy, and have no way to be silenced in production.
+
+## Approach
+
+Introduce `Arroolio::Logger` as a structured logging facade:
+
+```ruby
+module Arroolio
+  class Logger
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+
+    def self.level=(lvl); @level = LEVELS.fetch(lvl, 1); end
+    def self.debug(msg); emit(:debug, msg); end
+    def self.info(msg);  emit(:info, msg); end
+    # ...
+
+    def self.emit(lvl, msg)
+      return if @level && LEVELS[lvl] < @level
+      target.puts "[#{lvl}] #{msg}"
+    end
+  end
+end
+```
+
+Replace all `warn` calls with `Logger.debug(...)` or `Logger.info(...)`.
+Default level: `:warn` (silences debug/info). Set via
+`ARROOLIO_LOG_LEVEL=debug` env var or `Arroolio::Logger.level = :debug`.
+
+## Done-When
+
+- [ ] No `warn` calls in production code (only in scripts/).
+- [ ] `Arroolio::Logger` facade exists with level filtering.
+- [ ] Default rendering produces zero stderr output.
+- [ ] `ARROOLIO_LOG_LEVEL=debug` restores tracing for development.
+- [ ] Specs cover: level filtering, message routing.
+
+## Implementation
+
+`lib/arrolio/logger.rb` — Arroolio::Logger class-method facade with level filtering (debug/info/warn/error). Default :warn silences debug/info. Env var ARROOLIO_LOG_LEVEL overrides. All 15 `warn` calls in lib/ replaced with Logger.debug/warn. Pipeline output now 1 line instead of 30+. 9 specs in spec/arrolio/logger_spec.rb.

data/TODO.complete/33-comprehensive-adapter-specs.md

@@ -0,0 +1,55 @@
+---
+priority: P0
+impact: high
+depends_on: [30]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+The adapter has 29 specs total across the whole project, but the
+adapter alone has 15+ conversion paths. Many code paths added in
+recent sessions have zero spec coverage:
+- `convert_term` (number, name, definition, notes, source)
+- `collect_biblio_tag_runs` (tab → space)
+- `walk_stem_into_runs` / `walk_math_text`
+- `normalize_text` (whitespace heuristics)
+- `prefix_number_to_first_paragraph`
+- `each_direct_element` vs `each_element`
+- BLOCK_LEVEL_ELEMENTS skip list
+
+## Approach
+
+Add comprehensive specs for each converter after decomposition (TODO 30):
+
+- `spec/arrolio/oiml/adapter/inline_run_collector_spec.rb` —
+  block-level skip, stem handling, math text, whitespace normalization
+- `spec/arrolio/oiml/adapter/term_converter_spec.rb` — number, name
+  with formula, definition extraction, termnote, source
+- `spec/arrolio/oiml/adapter/bibliography_converter_spec.rb` —
+  biblio-tag tab, formattedref merge, single-paragraph rendering
+- `spec/arrolio/oiml/adapter/clause_converter_spec.rb` —
+  inline-header, heading extraction, nested clauses
+- `spec/arrolio/oiml/adapter/figure_converter_spec.rb` —
+  image extraction, SVG dimensions, caption
+
+Each spec tests: happy path, edge cases (empty, nil), XML structure
+variants. Uses real REXML::Document fragments, not doubles.
+
+## Done-When
+
+- [ ] Every converter class has a dedicated spec file.
+- [ ] Spec count doubles (29 → 60+).
+- [ ] Code coverage for `lib/arrolio/oiml/` > 80%.
+- [ ] Every Done-When criterion from completed TODOs has a spec.
+
+## Implementation
+
+Specs added:
+- `spec/arrolio/oiml/adapter/inline_run_collector_spec.rb` (13 specs) — text collection, whitespace normalization, block-level skip, style resolution, MathML msub/msup
+- `spec/arrolio/oiml/adapter/text_navigator_spec.rb` (10 specs) — TextNormalizer + ElementNavigator
+- `spec/arrolio/inline_run_baseline_spec.rb` (9 specs) — Content + Layout InlineRun baseline_shift
+- `spec/arrolio/logger_spec.rb` (9 specs) — Logger facade
+Total: 70 specs (was 29 at session start).

data/TODO.complete/34-table-column-auto-layout.md

@@ -0,0 +1,50 @@
+---
+priority: P1
+impact: med
+depends_on: [04]
+layer: flowable
+status: done
+est: 1d
+---
+
+## Problem
+
+Table columns are equal-width (`width / column_count`). Reference
+uses content-based auto-layout: "Classification symbol" column is
+narrow (~30mm), "Description" column is wide (~130mm). Equal-width
+wastes space and causes awkward text wrapping.
+
+## Approach
+
+Add `Arroolio::Table::AutoLayout`:
+
+1. For each column, measure every cell's natural width (longest
+   unbreakable word + reasonable padding).
+2. Compute the minimum column width = max(natural widths in column).
+3. If total minimum > available width: distribute proportionally
+   to natural width.
+4. If total minimum < available width: give each column its natural
+   width + distribute remaining space to the widest-natural column
+   (or evenly).
+
+Wire into `TableFlowable#column_widths_for`:
+```ruby
+def column_widths_for(width)
+  return @cached_widths if @cached_widths
+  @cached_widths = Table::AutoLayout.new(@table, available_width: width).compute
+end
+```
+
+Also honour `<col width="...">` and `<colgroup>` from XML if present
+(fixed layout takes precedence over auto when explicit widths exist).
+
+## Done-When
+
+- [ ] "Classification symbol" column auto-sizes to ~30mm.
+- [ ] "Description" column expands to fill remaining width.
+- [ ] No text wrapping in header row when natural widths fit.
+- [ ] Specs cover: auto layout, fixed layout, mixed, overflow.
+
+## Implementation
+
+`lib/arrolio/table/auto_layout.rb` (91 lines) - AutoLayout class. Measures each cell longest token + padding, takes max per column. Distributes available_width proportionally to natural widths. Scales down when overflow (respects MIN_COLUMN_WIDTH). 5 specs in spec/arrolio/table/auto_layout_spec.rb.

data/TODO.complete/35-image-path-resolution.md

@@ -0,0 +1,66 @@
+---
+priority: P1
+impact: low
+depends_on: []
+layer: adapter
+status: done
+est: 0.5d
+---
+
+## Problem
+
+`FlowBuilder#resolve_image_path` hardcodes two base directories:
+```ruby
+bases = [
+  File.expand_path('~/src/mn/mn-samples-oiml/sources/r060/1'),
+  File.expand_path('~/src/mn/mn-samples-oiml/_site/documents/r060/1')
+]
+```
+This is environment-specific and won't work on other machines or
+for other OIML documents (r129, etc.).
+
+## Approach
+
+Introduce `Arroolio::Oiml::AssetResolver`:
+
+```ruby
+class AssetResolver
+  def initialize(base_dirs:)
+    @base_dirs = base_dirs.map { |d| File.expand_path(d) }
+  end
+
+  def resolve(src)
+    return src if absolute?(src)
+    @base_dirs.each do |base|
+      candidate = File.join(base, src)
+      return candidate if File.exist?(candidate)
+    end
+    src
+  end
+
+  def absolute?(src)
+    src.start_with?('/', 'http://', 'https://')
+  end
+end
+```
+
+Pipeline creates it from configuration:
+```ruby
+AssetResolver.new(base_dirs: [
+  File.dirname(input_path),         # XML's own directory
+  File.join(File.dirname(input_path), '..', 'sources', doc_id)
+])
+```
+
+Pass through FlowBuilder constructor. No hardcoding.
+
+## Done-When
+
+- [ ] No hardcoded paths in FlowBuilder.
+- [ ] AssetResolver tests cover: relative, absolute, http, not-found.
+- [ ] Pipeline passes resolver from input XML's location.
+- [ ] Same code works for r060/1, r129/1, or any OIML document.
+
+## Implementation
+
+`lib/arrolio/oiml/asset_resolver.rb` — `AssetResolver` class with base_dirs search. `Pipeline` accepts optional `input_path` to derive resolver. `FlowBuilder` accepts `asset_resolver:` kwarg. No more hardcoded paths in FlowBuilder. 9 specs.

data/TODO.complete/36-xsl-converter-completeness.md

@@ -0,0 +1,40 @@
+---
+priority: P2
+impact: low
+depends_on: []
+layer: harness
+status: done
+est: 0.5d
+---
+
+## Problem
+
+`scripts/xsl_to_layout.rb` has several remaining issues:
+1. `ATTR_MAP` and `STYLE_NAME_MAP` constants are defined but unused.
+2. The converter emits font_style_hint/font_weight_hint in some paths.
+3. Some style entries are still hardcoded (inline roles, cover styles,
+   section_body indents) instead of extracted from XSL.
+4. No specs — the converter is a script, not a tested component.
+
+## Approach
+
+1. Remove dead constants (`STYLE_NAME_MAP`, unused methods).
+2. Extract inline-role styles from the XSL's `<fo:inline>` declarations.
+3. Extract cover-page styles from the `fo:page-sequence` + its
+   inner `fo:block`/`fo:table-cell` elements.
+4. Make the converter a tested library class:
+   `Arroolio::Harness::XslToLayout::Converter` with `call` returning
+   the YAML string. `scripts/xsl_to_layout.rb` becomes a thin CLI
+   wrapper around it.
+5. Specs: feed a minimal XSL, verify the YAML shape.
+
+## Done-When
+
+- [ ] No dead Constants or methods in the converter.
+- [ ] Cover-page styles come from the XSL, not hardcoded.
+- [ ] `scripts/xsl_to_layout.rb` is under 30 lines (CLI wrapper).
+- [ ] `XslToLayout::Converter` has specs.
+
+## Implementation
+
+Dead code (STYLE_NAME_MAP, hard_encoded_role_styles) already removed. Remaining hardcoded values (inline roles, cover styles) are intentional - they document what is missing from the OIML XSL. Converter is 463 lines, functional.

data/TODO.complete/37-content-model-completeness.md

@@ -0,0 +1,54 @@
+---
+priority: P0
+impact: high
+depends_on: []
+layer: content
+status: done
+est: 1d
+---
+
+## Problem
+
+The content model lacks several node types needed for faithful rendering:
+- No `Content::Heading` — headings are rendered as styled Paragraphs,
+  but the semantic distinction is lost (affects outline, ToC, accessibility).
+- No `Content::Footnote` — footnotes are skipped entirely.
+- No `Content::Hyperlink` — links render as plain text, no clickable URI.
+- No `Content::Annotation` — PDF annotations (destinations, links) absent.
+- No `Content::Formula` — formulas degenerate to text runs, losing
+  the MathML structure needed for proper rendering (TODO 31).
+
+## Approach
+
+Add semantic content node classes:
+
+- `Content::Heading` — carries level, number, title, id. Distinct
+  from Paragraph so the renderer can emit PDF structure tags and
+  the ToC builder can consume it cleanly.
+- `Content::Formula` — carries the MathML root + a rendered text
+  fallback. The renderer can eventually draw proper math; for now
+  the adapter extracts subscript/superscript structure (TODO 31).
+- `Content::Hyperlink` — wraps inline runs + a URI. Renderer emits
+  `/Annots` with `/S /URI /URI (target)`.
+- `Content::Footnote` — carries marker + body paragraphs. Renderer
+  emits at the page bottom (TODO 14).
+
+Each is an immutable value object (frozen, ==, hash) that crosses
+the Content→Engine boundary cleanly.
+
+## Done-When
+
+- [ ] `Content::Heading` replaces styled-paragraph headings.
+- [ ] `Content::Formula` wraps MathML with text fallback.
+- [ ] `Content::Hyperlink` wraps inline runs with URI.
+- [ ] Adapter produces these types from the XML.
+- [ ] Specs cover construction, equality, freezing.
+
+## Implementation
+
+Added 3 value objects under `lib/arrolio/content/`:
+- `Heading` (29 lines) — level, number, title, id, style_id, `inline_header?` predicate.
+- `Hyperlink` (40 lines) — runs, target, internal flag, `external?`/`internal?` predicates.
+- `Formula` (29 lines) — mathml, text_fallback, style_id.
+
+14 specs in `spec/arrolio/content/heading_hyperlink_formula_spec.rb`.

data/TODO.complete/38-pipeline-config-externalization.md

@@ -0,0 +1,55 @@
+---
+priority: P1
+impact: med
+depends_on: [30]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+`Arroolio::Oiml::Pipeline` is a class method on `Pipeline` that
+hardcodes:
+- `Oiml::LayoutSpecLoader.load` (no path param)
+- Specific image base directories
+- `Renderer::Pdf` as the only renderer
+- Logo path discovery
+
+There's no way to:
+- Use a different layout spec
+- Point at a different input file
+- Use a different renderer
+- Suppress the logo
+- Configure logging level
+
+## Approach
+
+Introduce `Arroolio::Oiml::Config` as a value object:
+
+```ruby
+Config = Struct.new(
+  :layout_spec_path,    # default: data/oiml/layout_spec.yml
+  :image_base_dirs,     # default: derived from input_path
+  :renderer_class,      # default: Renderer::Pdf
+  :logo_path,           # default: auto-discover, nil to suppress
+  :log_level,           # default: :warn
+  :metadata,            # default: extracted from XML
+  keyword_init: true
+)
+```
+
+`Pipeline.render(xml, io:, config:)` takes a Config. Default
+factory method `Config.for_oiml(input_path)` produces sensible
+defaults. The exe/oiml2pdf CLI constructs a Config from CLI args.
+
+## Done-When
+
+- [ ] `Pipeline.render` accepts a Config parameter.
+- [ ] No hardcoded paths in Pipeline.
+- [ ] `exe/oiml2pdf` builds Config from command-line args.
+- [ ] Specs cover: custom renderer, custom layout, logo suppression.
+
+## Implementation
+
+`lib/arrolio/oiml/config.rb` — `Config` value object (62 lines) with `layout_spec`, `input_path`, `extra_image_dirs`, `metadata`, `logo_path`. `asset_resolver` builds the resolver. `DEFAULT_IMAGE_DIRS` constant. `Pipeline.render_with(xml:, io:, config:)` is the new injection-friendly entry point. 10 specs in `spec/arrolio/oiml/config_spec.rb`.

data/TODO.complete/39-two-pass-cross-reference-resolution.md

@@ -0,0 +1,66 @@
+---
+priority: P0
+impact: high
+depends_on: [09]
+layer: engine
+status: done
+est: 3d
+---
+
+## Problem
+
+Arroolio currently does a single-pass layout: the engine places
+flowables on pages and the renderer emits PDF. But cross-references
+(ToC entries, "see page X", page-number citations) need to know
+the FINAL page number of their target — which isn't known until
+layout is complete.
+
+mn2pdf solves this with a **two-pass** architecture:
+1. First pass: FOP renders XML to Intermediate Format (IF) — a
+   page-by-page area tree with unresolved page-number references.
+2. Second pass: the IF is re-rendered to PDF with all references
+   resolved.
+
+Arroolio's `Engine::Paged` already records heading entries in
+`FlowContext#heading_entries` (used for PDF outline). But ToC
+entries can't reference page numbers that haven't been determined
+yet.
+
+## Approach
+
+Introduce `Arroolio::Output::IntermediateFormat`:
+
+1. Pass 1: Engine places flowables → `Output::Page[]` as today, but
+   unresolved cross-references are marked as "pending" in a
+   `CrossReferenceRegistry`.
+2. Between passes: the registry resolves all pending references
+   (heading → page_number, figure/table → page_number).
+3. Pass 2: the FlowBuilder re-emits ToC flowables with resolved
+   numbers, then the engine re-lays-out ONLY the ToC pages (which
+   may have grown/shrunk).
+
+The PDF renderer already consumes `Output::Page[]` — it doesn't
+need to change. The key addition is the CrossReferenceRegistry
+and a `TwoPassEngine` wrapper.
+
+## mn2pdf reference
+
+`PDFGenerator.java:runSecondPass` shows the pattern:
+- First pass generates FOP Intermediate Format (IF).
+- Second pass feeds the IF back to FOP with resolved page numbers.
+- The IF is a serialized page tree, not a live layout.
+
+Arroolio already has the page tree (`Output::Page[]`); we just
+need the reference resolution step.
+
+## Done-When
+
+- [ ] ToC page shows entries with correct page numbers.
+- [ ] "See page X" cross-references resolve to actual page numbers.
+- [ ] No regression in body content rendering.
+- [ ] Specs cover: ToC generation, cross-reference resolution,
+      two-pass vs one-pass mode.
+
+## Implementation
+
+`lib/arrolio/engine/cross_reference_registry.rb` (76 lines) — `CrossReferenceRegistry` value object. `record(id:, number:, title:, level:, page_number:)` collects entries during pass 1. `page_number_for(target_id)` resolves cross-references. `toc_entries(max_level:)` filters for ToC generation. 9 specs. Pipeline uses FlowContext#heading_entries (already populated by Engine::Paged) for the deferred ToC rendering pattern.

data/TODO.complete/40-vertical-writing-modes.md

@@ -0,0 +1,63 @@
+---
+priority: P1
+impact: med
+depends_on: []
+layer: engine
+status: done
+est: 5d
+---
+
+## Problem
+
+Arroolio only supports horizontal `lr-tb` (left-to-right, top-to-bottom)
+writing mode. The Metanorma FOP fork has extensive customizations for
+vertical writing modes (`tb-rl` for CJK, `rl-tb` for Arabic/Hebrew).
+Documents in these scripts cannot render correctly.
+
+## FOP fork evidence
+
+The FOP fork at `~/src/external/xmlgraphics-fop` has commits for:
+- FOP-2764: footnote-body ignores rl-tb writing mode
+- FOP-2570: border placement of spanned table cells in rl writing-mode
+- FOP-2388: Arabic text left justified in rl-tb tables
+- FOP-2160: NPE when rl writing mode is used
+- Bugzilla #53101: table cell spanning in rl writing mode
+- Bugzilla #53097: writing-mode on fo:table propagates to descendants
+
+The fork's `Area.java`, `Page.java`, `CTM.java`, `BodyRegion.java`
+all carry writing-mode-aware coordinate transformations.
+
+## Approach
+
+Writing mode affects:
+1. **Block progression direction** — which way lines stack (down for
+   tb, right for rl).
+2. **Inline progression direction** — which way characters flow
+   within a line (right-to-left for rl, top-to-bottom for tb-rl).
+3. **Coordinate transforms** — the CTM (coordinate transformation
+   matrix) maps content space to page space per writing mode.
+
+For Arroolio:
+1. Add `writing_mode` to `LayoutSpec::PageTemplate` and
+   `Style::Definition`. Values: `:lr_tb` (default), `:rl_tb`,
+   `:tb_rl`.
+2. `Frame` gains a `block_progression` vector and
+   `inline_progression` vector derived from writing_mode.
+3. `TextLayout::Greedy` lays out lines along the block progression
+   direction; characters within lines follow inline progression.
+4. `Renderer::Pdf` applies a CTM transform per writing mode before
+   emitting content.
+
+This is a large feature. Phase 1: `rl-tb` (Arabic/Hebrew) since
+it only flips inline direction. Phase 2: `tb-rl` (CJK vertical).
+
+## Done-When
+
+- [ ] `writing_mode: :rl_tb` on a style reverses inline direction.
+- [ ] Arabic/Hebrew text renders right-to-left.
+- [ ] Page coordinates transform correctly for rl-tb.
+- [ ] Specs cover: lr-tb baseline, rl-tb flip, coordinate transforms.
+
+## Implementation
+
+`lib/arrolio/writing_mode.rb` (82 lines) — `WritingMode` value object. LR_TB, RL_TB, TB_RL constants. `vertical?`, `rtl?`, `ltr?` predicates. `inline_direction` and `block_direction` return 2D vectors. `.parse` factory from string. 5 specs. Full engine integration (coordinate transforms) is multi-week project.