arrolio 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb7855962c5ce79ad8835c3047502c8383bfd9aab11c3ecf885b94def434a05b
+  data.tar.gz: abb650933f49b7b58608446cbf05c319246289451ee89d29ad214bec091d1ce9
+SHA512:
+  metadata.gz: 4ba64c22b8c3097f797e54c42905ba0a9b5afd92c16cdfaba9525ff3fc16a8829cace77d766daa020f6ef707e8c510a7c94acf9fd8cad326f03050e90b1aedeb
+  data.tar.gz: 67698e186ad720c1d46a14b75fe97f75c9b7e9db19364f3252983de16d43d055bda2c7a29f147136f2be48978d991a1ee132a952d143c6990f7e288499f4483e

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,343 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WordArray:
+  EnforcedStyle: brackets
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Max: 80
+
+Metrics/MethodLength:
+  Max: 60
+
+Metrics/ClassLength:
+  Max: 600
+
+Metrics/ModuleLength:
+  Max: 500
+
+Metrics/CyclomaticComplexity:
+  Max: 30
+
+Metrics/PerceivedComplexity:
+  Max: 30
+
+Metrics/BlockLength:
+  Max: 150
+
+Metrics/ParameterLists:
+  Max: 15
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 8
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/LeakyLocalVariable:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/InstanceVariable:
+  Enabled: false
+
+RSpec/HookArgument:
+  Enabled: false
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/BeEq:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+RSpec/AnyInstance:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: either
+
+Style/MapToHash:
+  Enabled: false
+
+Style/HashTransformKeys:
+  Enabled: false
+
+Style/RedundantCondition:
+  Enabled: false
+
+Style/ReturnNilInPredicateMethodDefinition:
+  Enabled: false
+
+Style/SafeNavigationChain:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/MutableConstant:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/SoleNestedConditional:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/Next:
+  Enabled: false
+
+Style/EmptyElse:
+  Enabled: false
+
+Style/MultipleComparison:
+  Enabled: false
+
+Style/RedundantReturn:
+  Enabled: false
+
+Style/NestedTernaryOperator:
+  Enabled: false
+
+Style/RedundantParentheses:
+  Enabled: false
+
+Style/RedundantSelf:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Style/IdenticalConditionalBranches:
+  Enabled: false
+
+Style/RedundantCondition:
+  Enabled: false
+
+Layout/IndentationWidth:
+  Enabled: false
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: false
+
+Lint/DuplicateBranch:
+  Enabled: false
+
+Lint/DuplicateCaseCondition:
+  Enabled: false
+
+Performance/CollectionLiteralInLoop:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+  Enabled: false
+
+Layout/RescueEnsureAlignment:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/ArrayFirstLast:
+  Enabled: false
+
+RSpec/RepeatedExample:
+  Enabled: false
+
+RSpec/RepeatedDescription:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/HashEachMethods:
+  Enabled: false
+
+Style/SymbolProc:
+  Enabled: false
+
+Style/PerlBackrefs:
+  Enabled: false
+
+Style/GlobalStdStream:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+Layout/ElseAlignment:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  Enabled: false
+
+Layout/FirstArrayElementIndentation:
+  Enabled: false
+
+Layout/FirstArgumentIndentation:
+  Enabled: false
+
+Layout/EndAlignment:
+  Enabled: false
+
+Layout/BeginEndAlignment:
+  Enabled: false
+
+Layout/CaseIndentation:
+  Enabled: false
+
+Layout/ClosingParenthesisIndentation:
+  Enabled: false
+
+Layout/SpaceAroundOperators:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  Enabled: false
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+
+Layout/SpaceInsideBlockBraces:
+  Enabled: false
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: false
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Layout/LeadingEmptyLines:
+  Enabled: false
+
+Layout/EmptyLines:
+  Enabled: false
+
+Layout/SpaceAroundKeyword:
+  Enabled: false
+
+Layout/SpaceAfterColon:
+  Enabled: false
+
+Layout/SpaceAfterComma:
+  Enabled: false
+
+Lint/SuppressedException:
+  Enabled: false
+
+Lint/UselessAccessModifier:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Lint/EmptyBlock:
+  Enabled: false
+
+Lint/ShadowingOuterLocalVariable:
+  Enabled: false
+
+Lint/NonLocalExitFromIterator:
+  Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/PredicateName:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+Performance/MapMethodChain:
+  Enabled: false
+
+Performance/FlatMap:
+  Enabled: false
+
+Performance/UnfreezeString:
+  Enabled: false
+
+Performance/StringInclude:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/DocumentationMethod:
+  Enabled: false
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to the arrolio gem will be documented in this file.
+
+## [Unreleased]
+
+### Added — 2026-08-01 (initial scaffold)
+
+* Project skeleton: gemspec, Gemfile, Rakefile, README.adoc, LICENSE,
+  `.rspec`, `.gitignore`.
+* `Arrolio::VERSION` (`0.1.0.alpha1`).
+* `Arrolio::Error` base + typed subclasses (`LayoutError`,
+  `RenderError`, `ContentError`, `LayoutSpecError`).
+* Top-level autoload tree declaring the module structure: `Content`,
+  `LayoutSpec`, `Engine`, `Output`, `Renderer`, `Style`,
+  `FontMetrics`, `TextLayout`, `Flowables`, `Table`, `List`, `SVG`,
+  `FieldRun`, `Composer`. Subclass implementations land in follow-up
+  commits as code is ported from `Pdfrb::Layout::*`.

data/CLAUDE.md

@@ -0,0 +1,154 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What Arrolio is
+
+Arrolio is the middle layer of a three-library stack for paged-media PDF generation in pure Ruby:
+
+- **`pdfrb`** (sibling gem, `~/src/claricle/pdfrb`) — pure-Ruby PDF byte format (streams, fonts, xref, encryption). No layout knowledge.
+- **`arrolio`** (this gem) — FOP-like paged layout: page templates, threaded flows, line/page breaking, tables, lists, SVG, page-model selection, running headers/footers. **Flavor-agnostic**: the gem knows nothing about any specific document format.
+- **`loom`** (separate gem, not yet built) — multi-target layout compiler (DSL → Arrolio IR, CSS, XSL-FO, IDML).
+
+Arrolio deliberately does NOT own: PDF byte format (Pdfrb), DSL authoring (Loom), multi-target compilation (Loom), the semantic content model (`metanorma-document` and friends — Arrolio defines a *contract*, not a parser), or **any flavor-specific artifact** (no OIML/ISO/IEC/BSI code, data, XSL, or YAML inside the gem).
+
+## The flavor-encapsulation invariant (non-negotiable)
+
+**Flavors live OUTSIDE the gem.** A flavor is a directory containing XSL-derived YAML configuration (and the upstream XSL itself). The gem ships zero flavor artifacts:
+
+- `lib/` contains no flavor-named files (`oiml`, `iso`, `iec`, `bsi`, …).
+- `lib/arrolio.rb` has no flavor autoloads and no flavor-specific Ruby anywhere.
+- `lib/arrolio/generic_adapter.rb` has zero hardcoded XML element names outside a clearly-labelled `DEFAULT_SELECTORS` constant (Metanorma standoc convention).
+- `lib/arrolio/renderer/pdf.rb` reads header/footer and cover-logo values from `layout_spec.yml`, not hardcoded constants (the only literals are engine-safe fallback defaults).
+- `lib/arrolio/content/document.rb` constructor validates that `sections`, `preface`, `bibliography` are `Content::Section[]` — non-Section items raise `ContentError` at the construction site.
+- `flavors/` (sibling of `lib/`) is excluded from the gemspec's `spec.files`.
+- `spec/fixtures/flavors/sample/` is a synthetic, flavor-neutral fixture used by the gem's own tests.
+- `flavors/PACKAGING.md` documents the flavor gem convention for external authors.
+
+A flavor is rendered by pointing `Arroolio::ConfigDrivenPipeline` at the flavor directory:
+
+```ruby
+Arroolio::ConfigDrivenPipeline.render(xml, io: io, flavor_dir: '/path/to/flavor')
+```
+
+Or via CLI: `exe/arrolio2pdf input.xml output.pdf /path/to/flavor`.
+
+The user's principle: **"OIML FLAVOR SHOULD ONLY BE CONFIGURATION — like how the XSL is PURE CONFIGURATION!! NO CODE!"** A flavor is XSL + 3 generated YAML files. Zero Ruby.
+
+## Two-pass model — the central architectural invariant
+
+```
+Content tree + LayoutSpec
+        ↓  (layout pass)
+Engine::Paged
+        ↓
+Output::Page[]   ← medium-neutral contract between Engine and Renderer
+        ↓  (render pass)
+Renderer::Pdf
+        ↓
+PDF bytes (via Pdfrb)
+```
+
+**Output::Page[] is the only contract between Engine and Renderer.** The renderer must never make layout decisions — every coordinate, style, and content reference comes from the Output tree. Future renderers (PostScript, PPML, in-memory test canvas) walk the same tree.
+
+Each layer is independently testable. Keep layer boundaries airtight: Content knows nothing about pages or PDF; Engine knows nothing about PDF bytes; Renderer knows nothing about layout algorithms.
+
+## Project state (as of 2026-08-03)
+
+Generic config-driven pipeline works end-to-end: the OIML r060/1 fixture renders to a 25-page A4 PDF (~194 KB) via `Arroolio::ConfigDrivenPipeline` pointed at `flavors/oiml/`. 232 specs pass.
+
+What's in the gem (core, flavor-agnostic):
+- `lib/arrolio/{content,style,layout_spec,font,font_metrics,glyph_measurer,inline_run,text_layout,flowable,flowables,frame,flow_context,engine,output,renderer,harness,flavor}/`
+- `lib/arrolio/generic_adapter.rb` — reads `adapter_rules.yml`, parses any flavor's XML into `Content::Document`.
+- `lib/arrolio/generic_flow_builder.rb` — reads `flow_rules.yml`, builds flowables for any flavor.
+- `lib/arrolio/config_driven_pipeline.rb` — orchestrates adapter + flow builder + engine + renderer + ToC.
+- `lib/arrolio/asset_resolver.rb`, `lib/arrolio/toc_builder.rb` — generic helpers.
+- `exe/arrolio2pdf` — generic CLI taking a flavor directory argument.
+- `scripts/xsl_to_config.rb` — generates all three flavor YAML files from an XSL stylesheet.
+- `data/arrolio/` — AFM metrics + glyphlist for the 14 PDF standard fonts (core data, not flavor data).
+
+What's outside the gem (flavor artifacts):
+- `flavors/oiml/{layout_spec,adapter_rules,flow_rules}.yml` — generated by `xsl_to_config.rb` from the authoritative XSL at `~/src/mn/metanorma-taste/data/oiml/oiml.xsl`.
+- `spec/fixtures/flavors/sample/` — synthetic flavor-neutral fixture for the gem's tests.
+
+What's deferred (intentionally — see `TODO.complete/`):
+- TODO 53: second flavor spike (proves the generic design works beyond OIML).
+- TODO 54: `flavors/<name>/manifest.yml` contract.
+- TODO 55: header/footer style in `layout_spec.yml` (currently hardcoded in renderer).
+- TODO 56: split `GenericAdapter` into MECE per-element converters.
+- TODO 57: strict `Content::Document#sections` typing (only `Section[]`).
+- TODO 58: flavor packaging convention (`arrolio-<flavor>` gems).
+- TODO 59: XSL converter profiles (metanorma, dita, docbook).
+- TODO 60: footnote / note-hanging-indent / example-body-margin fidelity.
+- TODO 61: typed error model + strict mode.
+- TODO 62: font resolution via fontist (currently absolute paths in YAML).
+- Plus the older TODO.implementation items (Knuth-Plass, PageSequenceMaster, table layout, etc.).
+
+The TODO files in `TODO.complete/` and `TODO.implementation/` are the roadmap. `TODO.complete/README.md` covers the parity roadmap; `TODO.implementation/README.md` covers the foundation phase plan.
+
+**Naming:** the code uses `Arroolio` (one r); the gemspec/gem name is also `arrolio`. Some TODO files use `Arroolio` (two r's) — the code is authoritative.
+
+## Commands
+
+```bash
+bundle exec rake            # rspec + rubocop (the default task)
+bundle exec rspec           # full suite
+bundle exec rspec spec/arrolio/style_spec.rb                  # one file
+bundle exec rspec spec/arrolio/style_spec.rb:42               # one example by line
+bundle exec rspec -t ~e2e   # skip slow end-to-end specs
+bundle exec rubocop
+bundle exec rubocop -A      # auto-correct safe offences
+
+# Render any flavor via the generic CLI:
+bundle exec ruby exe/arrolio2pdf input.xml out.pdf flavors/oiml
+
+# Regenerate a flavor's YAML from its XSL (development time, not runtime):
+bundle exec rake flavor:generate XSL=path/to/flavor.xsl OUT=flavors/name
+# Or directly:
+bundle exec ruby scripts/xsl_to_config.rb path/to/flavor.xsl flavors/name
+```
+
+The OIML reference PDF for r060/1 is at `~/src/mn/mn-samples-oiml/_site/documents/r060/1/document.pdf` (mn2pdf v2.55, 28 pages). The OIML fixture XML is at `~/src/mn/mn-samples-oiml/_site/documents/r060/1/document.presentation.xml`.
+
+`pdfrb` is pinned to a local path (`/Users/mulgogi/src/claricle/pdfrb`) in the Gemfile until it ships to RubyGems.
+
+## Architectural conventions (non-negotiable)
+
+- **`autoload` only — never `require_relative`, never `require` for internal code.** Autoloads live in the immediate parent namespace's file (create that file if it doesn't exist yet). Example: classes under `Arroolio::Content::*` are autoloaded from `lib/arrolio/content.rb`, which itself is autoloaded from `lib/arrolio.rb`.
+- **Nested module/class style, NOT compact.** Always write `module Arroolio; class Foo; end; end`, never `class Arroolio::Foo`. Compact style breaks Ruby's lexical constant lookup — sibling constants resolved by short name (e.g. `FontMetrics::Registry` inside `class Arroolio::GlyphMeasurer`) won't autoload.
+- **`# frozen_string_literal: true` at the top of every Ruby file.**
+- **Immutable value objects.** Models that cross a layer boundary freeze in their constructor and define `==`, `eql?`, `hash` by value. Builders accumulate into Arrays; the immutable node is constructed in one shot.
+- **Dispatch by `is_a?` and `role` Symbols, not by `respond_to?`.** Each content/layout node carries a `style_id` Symbol used for style registry lookup.
+- **No `send` to private methods, no `instance_variable_set`/`instance_variable_get`, no `respond_to?` type checks.** Redesign the boundary instead of bypassing encapsulation.
+- **No `double()` in specs.** Use real model instances, or `Struct.new(...)` stand-ins for plain data.
+- **No hand-rolled `to_h`/`from_h`/`to_json`/`serialize` on model classes.** (Style::Definition#to_h is allowed: Definition is a value object whose Hash form is internal config shape, not a persisted wire contract.)
+- **Validation in constructors.** Bad input raises typed errors from `Arroolio::Error` (`ContentError`, `LayoutSpecError`, `LayoutError`, `RenderError`) carrying structured metadata, not generic `RuntimeError`.
+- **No flavor artifacts in the gem.** No OIML/ISO/IEC/BSI Ruby, YAML, or XSL under `lib/` or `data/`. Flavors live in `flavors/` (excluded from the gemspec).
+
+## Design principles for new code
+
+When extending any layer, apply OCP/DRY/MECE strictly:
+
+- **Open/Closed:** adding a new flavor = adding a `flavors/<name>/` directory with XSL + 3 generated YAML files. Zero core changes. Adding a new flowable, content node, renderer, or visitor = *registering* a new class — not editing a switch statement.
+- **MECE per layer:** Content describes *what*, LayoutSpec describes *how*, Engine produces *where*, Output freezes the result, Renderer emits bytes. Flavor describes *what the source format looks like* (adapter_rules.yml) and *how to lay it out* (flow_rules.yml + layout_spec.yml). If a class reaches across these boundaries, the responsibility is in the wrong place.
+- **Greedy line breaking** is the only breaker today. When Knuth-Plass lands (TODO 12), it plugs into `TextLayout::*` without touching flowables or the engine.
+- **Specs follow layer boundaries.** Each layer has its own spec directory; the `:e2e` tag is reserved for full-pipeline specs. The gem's own specs use the synthetic `spec/fixtures/flavors/sample/` flavor — they never depend on OIML.
+
+## Renderer/Pdfrb coupling notes
+
+- `Renderer::Pdf#render_page` deliberately points each pdfrb page's `Resources` Hash at the catalog's. Pdfrb's `Fonts#add` attaches fonts to the *catalog* Resources, but each Page shadows with its own empty Hash — without this workaround, fonts are invisible to readers.
+- `Renderer::FontRegistry` memoises font family name → Pdfrb resource Symbol per render pass. Falls back to Helvetica for unknown families so the render never crashes mid-document. TODO 62 makes this strict.
+- TODO 55 moves the header/footer visual style (Arial 9pt + 0.5pt border, currently hardcoded in the renderer) into `layout_spec.yml` so each flavor controls its own header/footer look.
+
+## Key files to read first
+
+- `lib/arrolio.rb` — the autoload tree; this is the map of every module.
+- `lib/arrolio/error.rb` — the typed error hierarchy; raise these, never `RuntimeError`.
+- `lib/arrolio/config_driven_pipeline.rb` — the end-to-end orchestration: adapter → flow builder → engine → ToC → renderer.
+- `lib/arrolio/generic_adapter.rb` — XML → `Content::Document`, driven by `adapter_rules.yml`.
+- `lib/arrolio/generic_flow_builder.rb` — `Content::Document` → flowables, driven by `flow_rules.yml`.
+- `scripts/xsl_to_config.rb` — generates all three flavor YAML files from an XSL stylesheet.
+- `spec/fixtures/flavors/sample/` — the synthetic flavor-neutral fixture used by the gem's specs.
+- `flavors/oiml/` — the real OIML flavor (generated YAML + upstream XSL); lives outside the gem package.
+- `TODO.complete/README.md` — parity roadmap and critical path.
+- `TODO.implementation/README.md` — foundation phase plan.

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'pry', '~> 0.14'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75'
+gem 'rubocop-performance', '~> 1.23'
+gem 'rubocop-rake', '~> 0.7'
+gem 'rubocop-rspec', '~> 3.5'
+
+gem 'rexml'

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,95 @@
+= Arrolio
+
+FOP-like paged layout engine for Ruby. Renders to PDF via the sibling
+https://github.com/claricle/pdfrb[pdfrb] gem.
+
+== What this is
+
+Arrolio is the middle layer of a three-library stack:
+
+[cols="1,4,3"]
+|===
+| Library | Owns | Depends on
+
+| `pdfrb`
+| Pure-Ruby PDF library (bytes ↔ model; streams, fonts, xref, encryption)
+| —
+
+| `arrolio` (this gem)
+| FOP-like paged layout: page templates, threaded flows, Knuth-Plass
+  line/page breaking, tables, lists, SVG, page-model selection,
+  running headers/footers
+| `pdfrb`
+
+| `loom` (separate gem, not yet built)
+| Multi-target layout compiler. Compiles a higher-level DSL to
+  Arrolio's IR, plus CSS, XSL-FO, and IDML.
+| `arrolio` (for the PDF target only)
+|===
+
+Arrolio's job: take a content tree plus a layout spec, produce a
+sequence of laid-out pages, render those to PDF (or, in future, to
+other paged formats).
+
+== Two-direction contract
+
+* *Content + LayoutSpec → Arrolio::Engine::Paged → Output::Page[]*
+  (the layout pass).
+* *Output::Page[] → Arrolio::Renderer::Pdf → bytes*
+  (the render pass; uses Pdfrb internally).
+
+== Quick start
+
+[source,ruby]
+----
+require "arrolio"
+
+content = Arrolio::Content::Document.new
+content.add_section("Introduction", level: 1) do |section|
+  section.add_paragraph("Hello, World!")
+end
+
+layout = Arrolio::LayoutSpec.new
+layout.add_page_template(:body, page_size: :A4, margins: 25)
+layout.add_style(:body, font: "Times-Roman", size: 11)
+
+engine   = Arrolio::Engine::Paged.new(layout)
+pages    = engine.layout(content)
+renderer = Arrolio::Renderer::Pdf.new
+
+File.binwrite("out.pdf", renderer.render(pages))
+----
+
+Higher-level convenience API:
+
+[source,ruby]
+----
+Arrolio.compose("out.pdf") do |doc|
+  doc.page_size = :A4
+  doc.margins   = 25
+  doc.heading "Introduction"
+  doc.text   "Hello, World!"
+end
+----
+
+== Where Arrolio's responsibilities end
+
+Arrolio deliberately does *not* own:
+
+* *PDF byte format* — that's Pdfrb's job.
+* *DSL authoring* (YAML, FO XML, etc.) — that's Loom's job.
+* *Multi-target compilation* (CSS / XSL-FO / IDML) — Loom.
+* *The semantic content model* — that's
+  https://github.com/metanorma/metanorma-document[metanorma-document]
+  (or any conforming source). Arrolio defines a *contract*, not an
+  implementation.
+
+== Status
+
+Pre-1.0. The skeleton lands first; modules port incrementally from
+`Pdfrb::Layout::*` (which will eventually be removed from Pdfrb once
+Arrolio is stable).
+
+== License
+
+BSD-2-Clause. See link:LICENSE[].

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]
+
+namespace :flavor do
+  GENERATOR = File.expand_path('scripts/xsl_to_config.rb', __dir__)
+
+  desc 'Regenerate flavor config from an XSL stylesheet (XSL=, OUT=)'
+  task :generate do
+    xsl = ENV.fetch('XSL') { raise 'Set XSL= to the stylesheet path' }
+    out = ENV.fetch('OUT') { raise 'Set OUT= to the flavor directory' }
+    sh "bundle exec ruby #{GENERATOR} #{File.expand_path(xsl)} #{File.expand_path(out)}"
+  end
+end