arrolio 0.1.0

data/TODO.implementation/46-color-management.md

@@ -0,0 +1,47 @@
+---
+priority: P2
+phase: 14
+depends_on: [04, 22]
+layer: color
+est: 2d
+status: pending
+---
+
+## Problem
+
+Currently colours are Symbols (`:black`, `:red`) or hex strings.
+Production documents need RGB, CMYK, named spot colours, and ICC
+profile-based colours for accurate print reproduction.
+
+## Approach
+
+Files under `lib/arrolio/color/`:
+
+- `color.rb` — base + factory: `Color.parse("black")`, `Color.rgb(255,
+  128, 0)`, `Color.cmyk(0, 1, 1, 0)`, `Color.spot("PMS 200")`.
+
+- `rgb.rb` — `RGB = Struct.new(:r, :g, :b)`. Each 0..1 Float.
+
+- `cmyk.rb` — `CMYK = Struct.new(:c, :m, :y, :k)`.
+
+- `spot.rb` — `Spot = Struct.new(:name, :tint)`.
+
+- `icc.rb` — `ICC = Struct.new(:profile_ref, :components)`. Profile
+  loaded from `data/arrolio/icc/*.icc`.
+
+- `color_space_registry.rb` — registers ICC profiles; assigns
+  `/ColorSpace` objects in the PDF; caches by profile path.
+
+PDF rendering (TODO 22 extension):
+- RGB → `rg`/`RG` operators.
+- CMYK → `k`/`K` operators.
+- Spot → separation colour space with alternate colour.
+- ICC → ICCBased colour space with the embedded profile.
+
+## Done-When
+
+- [ ] `Color.parse("#FF8800")` returns an RGB instance.
+- [ ] CMYK colour renders correctly in the PDF.
+- [ ] Spot colour renders with a fallback alternate colour.
+- [ ] ICC profile embedded once per document, referenced by name.
+- [ ] Round-trip: re-read PDF has correct `/ColorSpace` entries.

data/TODO.implementation/47-metadata-and-xmp.md

@@ -0,0 +1,41 @@
+---
+priority: P2
+phase: 14
+depends_on: [22]
+layer: color
+est: 2d
+status: pending
+---
+
+## Problem
+
+Production PDFs carry metadata: title, author, subject, keywords,
+creation/modification dates, plus an XMP stream for ISO 19005-2
+(PDF/A) compliance. Arrolio currently writes nothing.
+
+## Approach
+
+Files:
+
+- `lib/arrolio/metadata/info.rb` — `Info` value object with the
+  classic `/Info` dict fields: `:Title`, `:Author`, `:Subject`,
+  `:Keywords`, `:Creator`, `:Producer`, `:CreationDate`,
+  `:ModDate`.
+
+- `lib/arrolio/metadata/xmp.rb` — builds an XMP packet (XML)
+  containing Dublin Core + PDF + PDF/A schemas. Stored as a
+  `/Metadata` stream on Catalog (`/Type /Metadata /Subtype /XML`).
+
+- Renderer (TODO 22) integration: after rendering pages, write
+  `/Info` to trailer and `/Metadata` to Catalog.
+
+Date format: PDF date strings `D:YYYYMMDDHHmmSSOHH'mm'`.
+
+## Done-When
+
+- [ ] A document rendered with `metadata: { title: "My Doc", author:
+      "Jane" }` has those fields in `/Info`.
+- [ ] `/CreationDate` and `/ModDate` are valid PDF date strings.
+- [ ] XMP packet is valid XML; parses with REXML.
+- [ ] XMP contains `dc:title`, `dc:creator`, `pdf:Producer`.
+- [ ] Round-trip: re-read PDF exposes the metadata via Pdfrb.

data/TODO.implementation/48-struct-tree-and-marked-content.md

@@ -0,0 +1,49 @@
+---
+priority: P2
+phase: 15
+depends_on: [22, 21]
+layer: a11y
+est: 3d
+status: pending
+---
+
+## Problem
+
+PDF/UA (ISO 14289-1) requires a structure tree: every visible
+element on the page maps to a structure element (H1, P, Table, TR,
+TD, Figure, etc.). The structure tree is the screen-reader path
+through the document. Without it, the PDF is unreadable to
+assistive technology.
+
+## Approach
+
+Files:
+
+- `lib/arrolio/structure/element.rb` — `StructElement` value
+  object: `type` (`:H1`, `:P`, `:Table`, `:Figure`, etc.),
+  `content_ref` (link to the PlacedBox that materialises this),
+  `children`, `attributes`.
+
+- `lib/arrolio/structure/tree.rb` — `StructTreeRoot` builder.
+  Walks the Output tree; for each PlacedBox with a `struct_role`
+  attribute, emits a StructElement.
+
+- Marked content in the content stream: every visible drawing
+  operation is wrapped in `BDC`/`EMC` operators with a `/MC`
+  property list referencing the StructElement.
+
+- `lib/arrolio/renderer/pdf/struct_emitter.rb` — emits:
+  - `/StructTreeRoot` on Catalog.
+  - `/Type /StructElem` entries.
+  - `/ParentTree` mapping content-stream MCIDs to StructElems.
+  - `/MarkInfo /true` on Catalog.
+
+## Done-When
+
+- [ ] A simple paragraph emits `<P>` structure element.
+- [ ] A heading emits `<H1>` with correct heading level.
+- [ ] A table emits `<Table><TR><TH>...</TH></TR></Table>`.
+- [ ] An image emits `<Figure>` with `/Alt` text.
+- [ ] `/MarkInfo /true` is present on Catalog.
+- [ ] Round-trip: re-read PDF has a `/StructTreeRoot`.
+- [ ] A screen reader (NVDA or similar) can navigate the document.

data/TODO.implementation/49-alt-text-and-actual-text.md

@@ -0,0 +1,43 @@
+---
+priority: P2
+phase: 15
+depends_on: [48, 33]
+layer: a11y
+est: 1d
+status: pending
+---
+
+## Problem
+
+PDF/UA mandates alt text on every image (`/Alt` on the Figure
+structure element) and supports `/ActualText` on any element (for
+cases where the visible text isn't the accessible text — e.g.
+mathematical equations rendered as glyphs).
+
+## Approach
+
+Extend `Arrolio::Content::Image` (TODO 02) with `alt` (String).
+Extend `Arrolio::Flowables::ImageFlowable` (TODO 33) to propagate
+`alt` to the PlacedBox.
+
+Extend `Arrolio::Output::PlacedBox` with `alt_text` and
+`actual_text` fields.
+
+Renderer integration (TODO 48 StructElement):
+- When emitting a `<Figure>` StructElement for an image, include
+  `/Alt (alt text)` if `alt_text` is set.
+- When emitting any StructElement, include `/ActualText` if the
+  PlacedBox carries it.
+
+Validation:
+- A `Content::Image` without `alt` produces a warning (configurable:
+  error in strict mode).
+- A `Content::Equation` without `actual_text` produces a warning.
+
+## Done-When
+
+- [ ] Image with `alt: "Diagram of the system"` emits `/Alt` on its
+      Figure element.
+- [ ] Equation with `actual_text: "E = mc^2"` emits `/ActualText`.
+- [ ] Missing alt text raises a warning (or error in strict mode).
+- [ ] Screen reader reads the alt text when navigating to an image.

data/TODO.implementation/50-composer-facade.md

@@ -0,0 +1,59 @@
+---
+priority: P2
+phase: 16
+depends_on: [02, 03, 20, 22]
+layer: composer
+est: 3d
+status: in_progress
+---
+
+## Problem
+
+Building Content + LayoutSpec by hand for every document is verbose.
+The Composer facade provides a streaming "write a report" API:
+`composer.heading("Intro"); composer.paragraph("...")`. It builds
+Content + uses a default LayoutSpec under the hood.
+
+## Approach
+
+File: `lib/arrolio/composer.rb`.
+
+```ruby
+class Arrolio::Composer
+  def initialize(page_size: :A4, margins: 25.mm, preset: :technical_report)
+    @document = Arrolio::Content::Document.new
+    @layout_spec = Arrolio::Presets.load(preset, page_size:, margins:)
+    @current_section = @document
+  end
+
+  def heading(text, level: 1); ... end
+  def paragraph(text, **style); ... end
+  def table(headers:, rows:); ... end
+  def list(items, marker: :bullet); ... end
+  def image(path, **opts); ... end
+  def page_break; ... end
+
+  def write(path_or_io)
+    pages = Arrolio::Engine::Paged.new(layout_spec: @layout_spec,
+                                         flowables: build_flowables).layout
+    Arrolio::Renderer::Pdf.new.render(pages, io: path_or_io)
+  end
+
+  private
+  def build_flowables
+    # Walk @document, produce Flowable[] per content node.
+  end
+end
+```
+
+Top-level convenience: `Arrolio.compose("out.pdf") { |c| ... }`.
+
+## Done-When
+
+- [ ] `Arrolio.compose("out.pdf") { |c| c.heading "Hi"; c.paragraph "World" }`
+      produces a valid PDF.
+- [ ] Heading uses the preset's heading style.
+- [ ] Multiple paragraphs flow across pages.
+- [ ] Tables and lists integrate.
+- [ ] Image integration.
+- [ ] Specs cover the public API surface.

data/TODO.implementation/51-style-presets.md

@@ -0,0 +1,44 @@
+---
+priority: P2
+phase: 16
+depends_on: [04]
+layer: composer
+est: 1d
+status: pending
+---
+
+## Problem
+
+Composer needs default LayoutSpecs that look professional without
+requiring the user to specify everything. Built-in presets: technical
+report, book, article, manual. Each preset is a LayoutSpec factory.
+
+## Approach
+
+File: `lib/arrolio/presets.rb` (namespace) + files under
+`lib/arrolio/presets/`:
+
+- `technical_report.rb` — A4, 25mm margins, single column, Times body,
+  Helvetica headings, page number bottom-center, section title in
+  header. Reads like an ISO/IEC standard.
+
+- `book.rb` — Letter, 1in margins, single column with optional
+  header, running header with chapter title, page number outside
+  (left on even, right on odd). Two-page sequence (odd/even templates).
+
+- `article.rb` — A4, 20mm margins, single column, no headers, simple
+  footer. Compact.
+
+- `manual.rb` — Letter, 0.75in margins, two-column body, sidebar
+  notes. Uses multi-column (TODO 44).
+
+Each preset is a `LayoutSpec.build { ... }` block, returned by
+`Presets.load(:technical_report, page_size:, margins:)`.
+
+## Done-When
+
+- [ ] `Presets.load(:technical_report)` returns a valid LayoutSpec.
+- [ ] Each preset has documented font + page geometry choices.
+- [ ] Each preset renders a sample document end-to-end.
+- [ ] Presets can be subclassed/extended.
+- [ ] Specs cover loading + structure of each preset.

data/TODO.implementation/52-oiml-adapter-and-e2e-pipeline.md

@@ -0,0 +1,120 @@
+---
+priority: P0
+phase: 17
+depends_on: [23, 30, 32, 33, 39, 42]
+layer: harness
+est: 3d
+status: pending
+---
+
+## Problem
+
+**This is Arrolio's primary end-to-end correctness test.** The user's
+requirement: define OIML PDF output (from the existing `oiml.xsl`),
+use the `metanorma-document` gem to parse real OIML presentation XML,
+convert that into Arrolio's content model, apply an OIML LayoutSpec,
+and render via Pdfrb. If Arrolio can produce FOP-equivalent PDFs for
+real OIML documents, the engine is correct.
+
+This TODO sets up the **adapter gem** (or namespace) that bridges
+metanorma-document → Arrolio. Phase-17 TODOs 53–55 build the OIML
+LayoutSpec and the diff harness around this.
+
+## Approach
+
+The bridge has three parts:
+
+### 1. OIML fixture corpus
+
+Live in `spec/fixtures/oiml/` (gitignored if licensing requires):
+- 3–5 real OIML presentation XML files at varying complexity
+  (cover + TOC + 5 sections + tables; multi-section with figures;
+  full 50-page reference doc).
+- For each, a FOP-rendered reference PDF (the ground truth).
+
+A rake task `rake fixtures:refresh_oiml` regenerates the reference
+PDFs by running `xsltproc oiml.xsl + fop` if the user has FOP
+installed; otherwise fetches pre-rendered ones from a private repo.
+
+### 2. `Arrolio::Oiml` adapter (in this gem, spec-only initially)
+
+Files under `lib/arrolio/oiml/`:
+
+- `content_adapter.rb` — converts
+  `Metanorma::Oiml::Document::Root` → `Arrolio::Content::Document`.
+  Walks the typed model, dispatches per node class via
+  `BlockDispatcher` (mirrors the STS transformer pattern):
+
+  ```ruby
+  class ContentAdapter
+    def convert(oiml_root) -> Arrolio::Content::Document
+    def convert_clause(clause) -> Arrolio::Content::Section
+    def convert_paragraph(p) -> Arrolio::Content::Paragraph
+    def convert_table(t) -> Arrolio::Content::Table
+    def convert_list(l) -> Arrolio::Content::List
+    def convert_image(i) -> Arrolio::Content::Image
+    # etc.
+  end
+  ```
+
+  Inline content (text + spans + cross-references) maps to
+  `Arrolio::InlineRun[]`.
+
+- `layout_spec_loader.rb` — loads the OIML LayoutSpec (TODO 53).
+
+- `pipeline.rb` — orchestrates:
+  ```ruby
+  oiml_root = Metanorma::Oiml::Document::Root.parse(xml)
+  content   = ContentAdapter.new.convert(oiml_root)
+  layout    = LayoutSpecLoader.load("oiml.layout_spec.rb")
+  flowables = FlowBuilder.(content, layout)
+  pages     = Arrolio::Engine::Paged.new(layout_spec: layout,
+                                           flowables:).layout
+  Arrolio::Renderer::Pdf.new.render(pages, io:)
+  ```
+
+### 3. End-to-end spec
+
+`spec/arrolio/oiml_e2e_spec.rb` (tagged `:e2e`):
+
+```ruby
+RSpec.describe "OIML → PDF end-to-end", :e2e do
+  Dir.glob("spec/fixtures/oiml/*.presentation.xml").each do |xml_path|
+    it "renders #{File.basename(xml_path)} to a valid PDF" do
+      out = StringIO.new
+      Arrolio::Oiml::Pipeline.(File.read(xml_path), io: out)
+
+      # Sanity: valid PDF
+      expect(out.string).to start_with("%PDF-")
+      expect(out.string).to include("%%EOF")
+
+      # Re-readable
+      reopened = Pdfrb::Document.new(io: StringIO.new(out.string))
+      expect(reopened.pages.count).to be > 0
+
+      # Diff vs FOP reference (TODO 55)
+      ref_path = xml_path.sub(".presentation.xml", ".fop.pdf")
+      if File.exist?(ref_path)
+        diff = Arrolio::Harness::TextDiff.(
+          ours: out.string,
+          reference: File.binread(ref_path)
+        )
+        expect(diff.page_count_delta).to be <= 1   # tolerate off-by-one
+        expect(diff.text_similarity).to be > 0.95
+      end
+    end
+  end
+end
+```
+
+## Done-When
+
+- [ ] `Metanorma::Oiml::Document::Root` (or its base class) loads
+      fixture XMLs without error.
+- [ ] `ContentAdapter` converts every fixture without raising.
+- [ ] `Pipeline` produces bytes starting with `%PDF-` for every fixture.
+- [ ] Each rendered PDF re-reads via Pdfrb with the expected page count.
+- [ ] Adapter covers at minimum: clause, paragraph, table, list,
+      image, heading (sections 1, 1.1, 1.1.1), footnote, basic-link.
+- [ ] Each adapter method is unit-tested with a minimal input.
+- [ ] `rake oiml:render[xml_path]` CLI command renders a single doc.

data/TODO.implementation/53-oiml-layout-spec.md

@@ -0,0 +1,121 @@
+---
+priority: P0
+phase: 17
+depends_on: [52]
+layer: harness
+est: 5d
+status: pending
+---
+
+## Problem
+
+The OIML stylesheet (`oiml.xsl`) encodes OIML's house style:
+specific page geometry, section-numbering format, running headers
+with chapter title + doc number, table styling, TOC layout, etc.
+We need to encode the *intent* of `oiml.xsl` as a Ruby
+`Arrolio::LayoutSpec` — not by translating the XSL element-for-
+element, but by reading what it produces visually and reproducing
+that in Ruby.
+
+## Approach
+
+Read these sources of truth (in order):
+
+1. **`~/src/mn/metanorma-taste/data/oiml/oiml.xsl`** — the XSL itself.
+2. **Sample FOP-rendered OIML PDFs** — `~/src/mn/mn-samples-oiml/_site/documents/*/*.pdf`.
+   Open in a viewer; measure geometry with a PDF inspector.
+3. **The OIML document model** — `~/src/mn/metanorma-oiml/lib/metanorma/oiml/document/`
+   to know what elements exist.
+
+File: `lib/arrolio/oiml/layout_spec.rb` (Ruby-encoded OIML house style).
+
+```ruby
+module Arrolio::Oiml
+  module LayoutSpec
+    OIML_A4 = [595.28, 841.89].freeze  # A4 in pt
+
+    def self.build
+      Arrolio::LayoutSpec.build do
+        # Page templates: cover, body (with running header + footer)
+        page_template(:cover) do
+          page_size OIML_A4
+          margins top: 50, bottom: 50, left: 30, right: 30
+        end
+
+        page_template(:body) do
+          page_size OIML_A4
+          margins top: 35, bottom: 30, left: 25, right: 25
+          region_extents before: 15, after: 15
+        end
+
+        # Page sequences: cover (single page) + body (odd/even differ)
+        page_sequence(:front_matter, first: :cover, next: :cover)
+        page_sequence(:main,
+                      first: :body, odd: :body, even: :body,
+                      page_numbering: { format: :arabic, start: 1 })
+
+        # Styles (excerpt)
+        style(:title,           font: "Helvetica-Bold", size: 24)
+        style(:subtitle,        font: "Helvetica",      size: 14)
+        style(:heading_1,       font: "Helvetica-Bold", size: 14,
+                                space_before: 18, keep_with_next: true)
+        style(:heading_2,       font: "Helvetica-Bold", size: 12)
+        style(:body,            font: "Times-Roman",    size: 11,
+                                align: :justify, line_spacing: 1.2)
+        style(:table_header,    font: "Helvetica-Bold", size: 10,
+                                background_color: "#EEEEEE")
+        style(:table_cell,      font: "Times-Roman",    size: 10)
+        style(:running_header,  font: "Helvetica",      size: 9)
+        style(:footer,          font: "Helvetica",      size: 9, align: :center)
+
+        # Static content bindings (running header + footer)
+        static_content(:body, :before) do
+          [
+            # Left frame: current top-level section title
+            Arrolio::PlacedText.new(
+              content: ->(ctx) { ctx.current_section.numbered_title },
+              style: :running_header,
+              position: [0, 0, 80.mm, 15]
+            ),
+            # Right frame: doc reference
+            Arrolio::PlacedText.new(
+              content: ->(ctx) { ctx.metadata[:doc_reference] },
+              style: :running_header,
+              position: [100.mm, 0, 30.mm, 15]
+            )
+          ]
+        end
+
+        static_content(:body, :after) do
+          [
+            Arrolio::PlacedField.new(
+              field: :page_number,
+              style: :footer,
+              position: [90.mm, 0, 10.mm, 15]
+            )
+          ]
+        end
+      end
+    end
+  end
+end
+```
+
+This file is the **single source of truth** for OIML styling. To
+change a colour, edit this file. To change page geometry, edit this
+file. The XSL becomes irrelevant.
+
+## Done-When
+
+- [ ] `LayoutSpec.build` produces a valid Arrolio::LayoutSpec.
+- [ ] Page geometry matches the OIML sample PDFs (measured to 1pt).
+- [ ] Section numbering format matches OIML convention (`1`, `1.1`,
+      `1.1.1`).
+- [ ] Running header on a body page shows the current section title +
+      doc reference.
+- [ ] Footer shows page number centered.
+- [ ] Tables in the OIML sample render with the right header styling.
+- [ ] Cover page matches the OIML sample layout (title block, doc
+      reference, etc.).
+- [ ] Style is documented: every property choice cites the OIML
+      sample PDF or the XSL line it was derived from.

data/TODO.implementation/54-oiml-pipeline.md

@@ -0,0 +1,97 @@
+---
+priority: P0
+phase: 17
+depends_on: [52, 53]
+layer: harness
+est: 2d
+status: pending
+---
+
+## Problem
+
+End-to-end pipeline that ties together:
+1. metanorma-document parses OIML presentation XML.
+2. `Oiml::ContentAdapter` converts to `Arrolio::Content::Document`.
+3. `Oiml::LayoutSpec.build` (TODO 53) supplies the OIML house style.
+4. `Engine::Paged` lays out.
+5. `Renderer::Pdf` produces bytes.
+
+The PDF **diff** against FOP's reference is a separate concern —
+covered by the comparator subsystem (TODOs 55–59). This TODO only
+ships the pipeline and a minimal sanity-check spec.
+
+## Approach
+
+### Pipeline entry point
+
+File: `lib/arrolio/oiml/pipeline.rb`.
+
+```ruby
+module Arrolio::Oiml
+  module Pipeline
+    module_function
+
+    def call(presentation_xml_or_path, io:, **opts)
+      require "metanorma/oiml/document"   # lazy-load heavy dep
+
+      oiml_root = Metanorma::Oiml::Document::Root.parse(
+        presentation_xml_or_path
+      )
+      content = ContentAdapter.new.convert(oiml_root)
+      layout  = LayoutSpec.build
+      flowables = FlowBuilder.(content, layout)
+      pages = Arrolio::Engine::Paged.new(
+        layout_spec: layout,
+        flowables: flowables
+      ).layout
+      Arrolio::Renderer::Pdf.new.render(pages, io: io)
+    end
+  end
+end
+```
+
+### CLI
+
+File: `exe/arrolio-oiml` (executable).
+
+```sh
+arrolio-oiml render document.presentation.xml > document.pdf
+arrolio-oiml diff   document.presentation.xml \
+                    --reference=document.fop.pdf
+```
+
+The `diff` subcommand shells out to the comparator subsystem
+(TODO 55) — this TODO only delivers `render`.
+
+### Minimal sanity spec
+
+`spec/arrolio/oiml/pipeline_spec.rb`:
+
+```ruby
+RSpec.describe "OIML → PDF pipeline", :e2e do
+  Dir.glob("spec/fixtures/oiml/*.presentation.xml").each do |xml|
+    it "#{File.basename(xml)} renders a valid PDF" do
+      out = StringIO.new
+      Arrolio::Oiml::Pipeline.(xml, io: out)
+      expect(out.string).to start_with("%PDF-")
+      expect(out.string).to include("%%EOF")
+
+      reopened = Pdfrb::Document.new(io: StringIO.new(out.string))
+      expect(reopened.pages.count).to be > 0
+    end
+  end
+end
+```
+
+This is intentionally weak — no comparison vs FOP. The diff
+subsystem (TODO 55–59) layers comparison on top.
+
+## Done-When
+
+- [ ] `Arrolio::Oiml::Pipeline.(xml, io:)` produces PDF bytes from
+      every fixture.
+- [ ] `exe/arrolio-oiml render doc.presentation.xml > out.pdf`
+      produces a readable PDF.
+- [ ] Pipeline spec runs against all fixtures without raising.
+- [ ] Pipeline accepts either a path or a raw XML string.
+- [ ] No FOP/diff code lives in this TODO — that's TODOs 55–59.