arrolio 0.1.0

data/TODO.complete/63-purge-hardcoded-vocabulary-from-generic-core.md

@@ -0,0 +1,68 @@
+---
+priority: P0
+impact: high
+depends_on: [52]
+layer: adapter
+status: done
+est: 1d
+---
+
+## Problem
+
+The "generic" adapter, flow builder, and pipeline still had Metanorma
+standoc vocabulary hardcoded throughout:
+
+- `fmt-title`, `fmt-name`, `fmt-stem`, `fmt-preferred`, `fmt-definition`,
+  `fmt-termsource`, `biblio-tag`, `formattedref` — all element names
+  baked into Ruby.
+- The `depth` attribute name hardcoded.
+- `zzSTDTitle` paragraph routing dropped silently.
+- Figure display width hardcoded to 106pt.
+- List bullet marker hardcoded to `■ `.
+- ToC top offset hardcoded to 40pt.
+
+These are Metanorma/OIML conventions. A flavor with a different
+vocabulary (DITA, DocBook, JATS) would not work without modifying
+core — violating OCP.
+
+## Approach
+
+1. **`adapter_rules.yml` selectors block**: declares every XML
+   element/attribute name the adapter touches. 27 keys covering
+   heading source, list items, table cells, bibliography tags, stem
+   elements, image attributes, autonum classes, etc.
+2. **`GenericAdapter#selectors`**: reads the block, falls back to
+   `DEFAULT_SELECTORS` (clearly labelled as Metanorma standoc
+   convention) for backward compatibility.
+3. **`GenericFlowBuilder#default_marker`**: reads
+   `flow_rules.yml[list.defaults.ordered_marker]` and
+   `[bullet_marker]`.
+4. **`GenericFlowBuilder#image_flowable`**: reads
+   `flow_rules.yml[image.default_natural_width]`,
+   `[default_natural_height]`, `[max_display_width]`.
+5. **`ConfigDrivenPipeline#populate_toc`**: reads
+   `flow_rules.yml[toc.top_offset]`.
+6. **`scripts/xsl_to_config.rb`**: emits the `selectors` block in
+   generated `adapter_rules.yml` from a `SELECTORS` constant.
+
+## Done-When
+
+- [x] No flavor literals (`oiml`, `zzSTDTitle`, `Arial`, `Jost`,
+      `Times New Roman`) in `lib/arrolio/generic_*.rb`,
+      `lib/arrolio/config_driven_pipeline.rb`,
+      `lib/arrolio/asset_resolver.rb`, `lib/arrolio/toc_builder.rb`,
+      `exe/arrolio2pdf`
+- [x] No `fmt-*` references in `GenericAdapter` outside the clearly
+      labelled `DEFAULT_SELECTORS` constant
+- [x] Figure width, list markers, ToC offset all driven by config
+- [x] OIML pipeline still renders (25 pages, ~218KB)
+- [x] Sample fixture renders
+- [x] All 232 specs pass
+
+## Verification
+
+- `grep -rn -i 'oiml\|zzSTDTitle\|"Arial"\|"Jost"' lib/arrolio/generic_*.rb
+  lib/arrolio/config_driven_pipeline.rb lib/arrolio/asset_resolver.rb
+  lib/arrolio/toc_builder.rb exe/arrolio2pdf` → empty
+- `bundle exec rake` → green
+- Real OIML render via `exe/arrolio2pdf` → 25-page PDF

data/TODO.complete/64-selector-driven-adapter-specs.md

@@ -0,0 +1,46 @@
+---
+priority: P0
+impact: high
+depends_on: [63]
+layer: test
+status: done
+est: 1d
+---
+
+## Problem
+
+After extracting Metanorma vocabulary into the `selectors` block, there
+was no spec verifying that the generic adapter actually consults the
+selectors (vs. silently falling back to hardcoded defaults). A future
+edit could re-introduce a hardcoded element name and no test would
+catch it.
+
+## Approach
+
+1. **Custom-selector spec**: build a synthetic flavor whose
+   `adapter_rules.yml` uses NON-Metanorma element names
+   (`sec` instead of `clause`, `para` instead of `p`, `tbl` instead
+   of `table`, etc.) and verify the adapter parses a matching XML
+   document correctly. This proves the adapter has no hardcoded
+   dependency on the Metanorma vocabulary.
+2. **Grep-enforced OCP spec**: assert no flavor literals appear in the
+   generic core. This is a structural test that fails loudly if someone
+   re-introduces `fmt-title`, `oiml`, etc. into the wrong file.
+3. **Fixture path coverage**: both the sample fixture (Metanorma-style)
+   and the synthetic non-Metanorma fixture pass through the same
+   generic pipeline.
+
+## Done-When
+
+- [x] Spec renders a non-Metanorma vocabulary through the generic adapter
+- [x] Spec asserts no flavor literals in `lib/arrolio/generic_*.rb`,
+      `lib/arrolio/config_driven_pipeline.rb`,
+      `lib/arrolio/asset_resolver.rb`, `lib/arrolio/toc_builder.rb`,
+      `exe/arrolio2pdf`
+- [x] All specs pass
+
+## Why
+
+A refactor that "extracts hardcoded values" without a test enforcing
+the extraction is just a suggestion. The grep-enforced OCP spec is the
+permanent guardrail — any future regression fails CI immediately.

data/TODO.complete/66-semantic-content-types.md

@@ -0,0 +1,171 @@
+---
+priority: P1
+impact: high
+depends_on: [50, 63]
+layer: content
+status: done
+est: 3d
+---
+
+## Status
+
+- Phase 1 (content type classes) — **done** (PR #1)
+- Phase 2 (adapter emission + flow builder dispatch) — **done** (PR #2)
+- Phase 3 (footnote extraction + endnote rendering) — **done** (PR #3)
+- Phase 4 (page-bottom footnote rendering in Engine::Paged) — **done** (PR #5)
+
+The architectural pipeline for semantic content types and footnotes
+is complete end-to-end:
+
+1. Adapter extracts `Content::Footnote` from `<fmt-footnote-container>`
+2. Adapter emits `Content::Note`, `Content::FigureGroup`,
+   `Content::TermEntry`, `Content::BibliographyItem` for grouped elements
+3. Flow builder dispatches on the new types via `is_a?` and emits
+   `NoteFlowable`, `ImageFlowable + TextFlowable`, etc. with proper
+   grouping and hanging indents
+4. Flow builder can render endnotes (opt-in via `flow_rules.endnotes`)
+5. Engine collects `FootnoteMarkerFlowable` references per page
+6. Renderer draws collected footnotes at the bottom of each page
+
+## What remains for full TODO 60 closure
+
+TODO 60 (footnote inline-reference fidelity) is now architecturally
+unblocked but still needs:
+
+- Adapter inline walker to emit `FootnoteMarkerFlowable` at `<fn>`
+  references in body text (currently the flow builder would have to
+  emit them manually from `Document#footnotes`).
+- A real fixture with `<fn>` inline references + `<fmt-footnote-container>`
+  blocks to validate the full path.
+
+Both are focused follow-ups, not architectural work. The TODO 66
+design is closed.
+
+The generic adapter currently emits `Content::Paragraph[]` for every
+flowable-bearing element type: notes, examples, terms, bibliography
+items, figure captions. The semantic distinction is encoded only in
+the Paragraph's `style_id:` (`:note`, `:term`, `:bibitem`, etc.).
+
+This has three downstream costs:
+
+1. **Lost structure**: a `<note><p>...</p><p>...</p></note>` becomes
+   two unrelated Paragraphs. The flow builder cannot tell they belong
+   to the same note (so cannot apply hanging-indent rendering via
+   `NoteFlowable`).
+2. **No grouping**: the renderer cannot collect footnotes/notes by
+   page (TODO 60's blocker — there's no `Content::Footnote` emission
+   from the adapter).
+3. **Fragile style dispatch**: the flow builder keys off `style_id`
+   to decide what to do. Adding a new style requires touching the
+   builder, violating OCP.
+
+## Root cause
+
+`Content` knows about generic inline-block containers (Paragraph,
+Table, List) but not about the semantic groupings those containers
+appear in (Note, Example, TermEntry, BibliographyItem, FigureGroup).
+That semantic layer was implicit in the legacy OIML adapter and was
+flattened into Paragraphs during the generic-adapter extraction.
+
+## Approach
+
+Add semantic content types that wrap their inner Paragraphs:
+
+```
+Content::Note            # <note> — label + body Paragraphs
+Content::Example         # <example> — label + body Paragraphs
+Content::TermEntry       # <term> — number + preferred + definition + source
+Content::FigureGroup     # <figure> — Image + caption Paragraphs
+Content::BibliographyItem # <bibitem> — tag + formattedref Paragraphs
+```
+
+Each is a frozen value object with `children` (Array of Paragraph or
+other Content nodes) plus type-specific fields (`label`, `number`,
+`marker`, `caption`).
+
+### Migration plan
+
+1. **Phase 1**: add the new types alongside `Content::Paragraph`. They
+   carry the same `style_id` mechanism. Adapter begins emitting the
+   new types when the `selectors:` block identifies them.
+2. **Phase 2**: `GenericFlowBuilder` recognizes the new types and
+   emits `NoteFlowable`, `ImageFlowable + TextFlowable` (figures),
+   etc. with proper grouping.
+3. **Phase 3**: footnote support. `Content::Footnote` is already
+   defined (autoloaded from `content/footnote.rb`). Add adapter
+   extraction from `<fmt-footnote-container>` / `<fmt-fn-body>`.
+4. **Phase 4**: page-bottom footnote collection in `Engine::Paged`.
+   Add a `footnotes` Array to `FlowContext` and a `footnote_zone`
+   region in `Output::Page`.
+
+### Selector additions (Phase 1)
+
+```yaml
+selectors:
+  note_container: note         # already implicit in element_mapping
+  note_label: fmt-name         # already present
+  example_container: example
+  term_container: term
+  figure_container: figure
+  bibitem_container: bibitem
+  footnote_container: fmt-footnote-container
+  footnote_body: fmt-fn-body
+  footnote_marker: fn
+```
+
+### Backward compatibility
+
+The generic adapter continues to emit `Content::Paragraph` for any
+flavor that doesn't opt in to the new selector keys. Old flavors'
+behavior is unchanged.
+
+## Done-When (Phase 1 — content types)
+
+- [ ] `Content::Note`, `Content::Example`, `Content::TermEntry`,
+      `Content::FigureGroup`, `Content::BibliographyItem` classes exist
+- [ ] Each is a frozen value object with `==`/`eql?`/`hash`
+- [ ] `Content::Document#sections` accepts the new types (or wraps them
+      in Sections transparently)
+- [ ] Adapter emits the new types when selectors identify them
+- [ ] Specs cover each new type's equality + freezing
+
+## Done-When (Phase 2 — flow builder recognition)
+
+- [ ] `GenericFlowBuilder` dispatches on the new types via `is_a?`
+- [ ] Notes emit `Flowables::NoteFlowable` (already exists) with
+      hanging indent
+- [ ] Examples emit a styled block with `example_body` margins
+- [ ] Figure groups emit `ImageFlowable` + caption TextFlowable as a
+      keep-together unit
+- [ ] Bibliography items emit as a single hanging-indent flowable
+
+## Done-When (Phase 3 — footnote extraction)
+
+- [ ] Adapter emits `Content::Footnote` from `<fmt-footnote-container>`
+- [ ] Selector keys `footnote_container`, `footnote_body`,
+      `footnote_marker` defined
+- [ ] Footnotes appear in `Content::Document#footnotes`
+
+## Done-When (Phase 4 — page-bottom rendering)
+
+- [ ] `FlowContext` carries a per-page `footnotes` Array
+- [ ] `Engine::Paged` collects footnotes during the layout pass
+- [ ] `Output::Page` carries a `footnote_zone` region
+- [ ] `Renderer::Pdf` renders footnote lines at the page bottom
+- [ ] A real fixture exercises the full path
+
+## Why this unblocks TODO 60
+
+TODO 60 is currently blocked because the architecture has no
+mechanism for grouped content types or per-page footnote collection.
+This TODO is the architectural work that *enables* TODO 60. Once the
+content types exist and the flow builder recognizes them, the
+remaining TODO 60 work is a small follow-up.
+
+## Related
+
+- [[50-delete-oiml-ruby-code]] — established generic adapter; this
+  TODO extends it with semantic grouping
+- [[63-purge-hardcoded-vocabulary-from-generic-core]] — selectors
+  mechanism this TODO extends
+- [[60-adapter-fidelity-footnotes-notes-examples]] — blocked on this

data/TODO.complete/README.md

@@ -0,0 +1,48 @@
+# TODO.complete — Path to 100% mn2pdf parity
+
+This directory tracks every piece of work needed to make Arrolio's
+OIML output byte-equivalent (visually + textually) to mn2pdf's
+output for the same input XML.
+
+The reference rendering is `mn2pdf v2.55` (Java), invoked via
+Metanorma. Reference PDF for r060/1 lives at
+`~/src/mn/mn-samples-oiml/_site/documents/r060/1/document.pdf`
+(28 pages, 744 KB, fonts: FuturaPT-Book/Demi/Light,
+TimesNewRomanPSMT family, Cambria Math).
+
+The authoritative style reference is
+`~/src/mn/metanorma-taste/data/oiml/oiml.xsl` (767 lines).
+
+## Front matter shape (every file)
+
+```yaml
+---
+priority: P0     # P0 = blocks parity; P1 = important; P2 = polish; P3 = future
+impact: high     # high = >5% similarity swing; med = 1-5%; low = <1%
+depends_on: []   # TODO numbers
+layer: foundation | metrics | text | flowable | engine | output | render | adapter | harness
+status: pending  # pending | in_progress | done
+est: 1d          # 1d = single focused session; 5d = multi-week module
+---
+```
+
+## Critical path to 90%+ similarity
+
+```
+01 → 02 → 04 → 05 → 06 → 07 → 09 → 11 → 14 → 18 → 22
+```
+
+After 22 lands, every remaining TODO is a polish item.
+
+## Status legend
+
+- `pending` — not started
+- `in_progress` — actively being worked
+- `done` — complete, specs pass, ready for review
+- `deferred` — intentionally out of scope for this milestone
+
+## Verification
+
+After each TODO: `bundle exec rake` (rspec + rubocop) must be green,
+and `bundle exec ruby exe/oiml-diff out.pdf <reference>` similarity
+must not regress.

data/TODO.implementation/01-foundation.md

@@ -0,0 +1,46 @@
+---
+priority: P0
+phase: 1
+depends_on: []
+layer: foundation
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+The Arrolio gem skeleton already exists (gemspec, Gemfile, lib/arrolio.rb,
+error.rb, version.rb). This TODO covers the conventions check, autoload
+tree, and project structure that everything else depends on.
+
+## Approach
+
+Already in place (verify, don't redo):
+- `lib/arrolio.rb` with autoloads for every planned module.
+- `lib/arrolio/version.rb` (`0.1.0.alpha1`).
+- `lib/arrolio/error.rb` (Error + LayoutError + RenderError +
+  ContentError + LayoutSpecError).
+- `spec/spec_helper.rb` + `spec/arrolio/version_spec.rb`.
+- `Gemfile` with `gem "pdfrb", path: "/Users/mulgogi/src/claricle/pdfrb"`.
+
+Convention decisions to lock in here:
+- `# frozen_string_literal: true` on every file.
+- Immutable value objects with `freeze` in constructors where data
+  crosses a layer boundary.
+- `autoload` only — never `require_relative`, never `require` for
+  internal code. Autoloads live in the immediate parent namespace's
+  file (create the file if it doesn't exist).
+- No `send` to private methods, no `instance_variable_set/get`, no
+  `respond_to?` for type checks (`is_a?` only).
+- No `double()` in specs — real instances or `Struct.new` stand-ins.
+- No hand-rolled `to_h`/`from_h` on models.
+
+## Done-When
+
+- [x] `bundle exec rspec` is green on the seed specs.
+- [x] `Arrolio::VERSION` returns `"0.1.0.alpha1"`.
+- [x] `Arrolio::Error` descends from `StandardError`.
+- [x] `lib/arrolio.rb` lists every planned module as an autoload.
+- [ ] `.rubocop.yml` exists and `bundle exec rubocop` is green.
+- [ ] `bin/console` exists for interactive exploration.
+- [ ] CLAUDE.md documents the architecture for future Claude sessions.

data/TODO.implementation/02-content-contract.md

@@ -0,0 +1,47 @@
+---
+priority: P0
+phase: 1
+depends_on: [01]
+layer: foundation
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Arrolio needs a typed content tree to describe documents semantically.
+Strings and hashes are too loose — downstream layers (Engine, Renderer)
+must dispatch on content type via `is_a?`. The tree is medium-independent:
+it has no notion of "page" or "PDF" anywhere.
+
+## Approach
+
+Files to create under `lib/arrolio/content/`:
+
+- `document.rb` — root; holds `metadata` (Hash), `sections` (Array).
+- `section.rb` — `title`, `level`, `number`, `id`, `children`.
+- `paragraph.rb` — `inline_runs` (Array of InlineRun).
+- `inline_run.rb` — `text` + `style_id` (frozen value object).
+- `table.rb` — `Row`, `Cell`, `ColumnSpec` (defer to TODO 27 if convenient).
+- `list.rb` — `Item` with `marker` + `content` (defer to TODO 31).
+- `image.rb` — `src`, `alt`, `natural_size` (defer to TODO 33).
+- `cross_reference.rb` — `target_id`, `reference_kind` (defer to TODO 41).
+
+Conventions:
+- Every node has a `role` Symbol (e.g. `:heading`, `:paragraph`)
+  used by dispatch tables.
+- Frozen value objects. Equality by value (`==` and `eql?` and `hash`).
+- Children are an Array; leaf text is a String inside `InlineRun`.
+- No mutations after construction. Builders accumulate into Arrays,
+  then construct the immutable node in one shot.
+
+DSL: `Document.build { section("Intro") { paragraph("Hello") } }`
+builder lives in `lib/arrolio/content/builder.rb`.
+
+## Done-When
+
+- [ ] Every content class is a frozen value object with `==`, `eql?`, `hash`.
+- [ ] `Arrolio::Content::Document.build { ... }` produces a tree.
+- [ ] Visitors (TODO 05) can walk the tree without type-checks beyond `is_a?`.
+- [ ] No content class references pages, PDFs, frames, or renderers.
+- [ ] Specs cover equality, immutability, child traversal.

data/TODO.implementation/03-layoutspec-contract.md

@@ -0,0 +1,46 @@
+---
+priority: P0
+phase: 1
+depends_on: [02]
+layer: foundation
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Engine and Renderer both need a typed layout description to drive
+placement. This is the Ruby equivalent of XSL-FO's
+`fo:layout-master-set` + `fo:page-sequence-master` — but as Ruby
+objects, no XML.
+
+## Approach
+
+Files under `lib/arrolio/layout_spec/`:
+
+- `layout_spec.rb` — top container; holds `page_templates`, `styles`,
+  `flows`, `page_sequences`.
+- `page_template.rb` — name, page_size, margins, region_extents,
+  computed `regions`.
+- `region.rb` — name (`:body`, `:before`, `:after`, `:start`, `:end`),
+  geometry, `flow_ref`.
+- `page_sequence_master.rb` — selection rules (`:first`, `:odd`,
+  `:even`, `:blank`, `:last`).
+- `flow.rb` — name, source (path into Content tree), default style.
+
+DSL: `LayoutSpec.build { page_template(:body) { ... }; style(:body, ...) }`.
+
+Validation in constructor — raise `LayoutSpecError` on:
+- Unknown region name.
+- Page size that isn't a 2-element Array of positives.
+- Margin that's negative.
+- Style reference to a name not in the registry.
+
+## Done-When
+
+- [ ] `LayoutSpec.build` produces an immutable spec.
+- [ ] `spec.page_template(:body)` returns a `PageTemplate`.
+- [ ] `spec.style(:body)` returns a resolved `Style::Definition`.
+- [ ] Invalid specs raise `LayoutSpecError` with a useful message and
+      a `spec_field` attribute pointing at the offending field.
+- [ ] Specs cover happy path + every validation rule.

data/TODO.implementation/04-style-system.md

@@ -0,0 +1,43 @@
+---
+priority: P0
+phase: 1
+depends_on: [02]
+layer: foundation
+est: 2d
+status: in_progress
+---
+
+## Problem
+
+Style declarations need a typed representation that supports:
+- Inheritance (parent style → child override).
+- Resolution by name (`:body`, `:heading_1`) or selector.
+- Medium-aware properties (font, color, alignment, spacing).
+- Diff/merge for span-style overrides within paragraphs.
+
+## Approach
+
+Files under `lib/arrolio/style/`:
+
+- `definition.rb` — immutable struct of resolved properties
+  (font_name, font_size, fill_color, stroke_color, line_spacing,
+  align, valign, margin, padding, character_spacing, word_spacing,
+  keep_together, page_break_before, page_break_after, line_break).
+- `registry.rb` — name → Definition map; resolves lookups;
+  supports `register(name, **props)` and `resolve(name)`.
+- `diff.rb` — given a base Definition + a hash of overrides, produce
+  a new Definition (used for inline span styling).
+- `table_style.rb`, `row_style.rb`, `cell_style.rb` — table-specific
+  subclasses.
+
+Defaults:
+- `font_name: "Helvetica"`, `font_size: 12`, `align: :left`,
+  `line_spacing: 1.2`, `line_break: :greedy`.
+
+## Done-When
+
+- [ ] `Style::Registry.new` accepts a hash of definitions.
+- [ ] `registry.resolve(:body)` returns a `Definition`.
+- [ ] `definition.with(font_size: 14)` returns a new merged Definition.
+- [ ] Inheritance: child without `font_size` inherits parent's.
+- [ ] Specs cover registration, resolution, merge, inheritance.

data/TODO.implementation/05-visitor-pattern.md

@@ -0,0 +1,40 @@
+---
+priority: P1
+phase: 1
+depends_on: [02, 03]
+layer: foundation
+est: 1d
+status: pending
+---
+
+## Problem
+
+Engine and Renderer both walk trees of typed nodes. Without a
+visitor pattern, every walker re-implements dispatch. A canonical
+visitor keeps the dispatch logic in one place and lets new walkers
+(validator, optimizer, debug-dumper) be added without touching node
+classes (OCP).
+
+## Approach
+
+Files under `lib/arrolio/visitor/`:
+
+- `base.rb` — `Visitor::Base` with `visit(node)` that dispatches on
+  `node.class` to a method named `visit_<class_name>`. Falls back to
+  `visit_unknown(node)` if no specific method.
+- `content_visitor.rb` — mixin giving `visit_section`, `visit_paragraph`,
+  etc. defaults that recurse into children.
+- `layout_spec_visitor.rb` — same idea for LayoutSpec nodes.
+
+Built-in visitors:
+- `Validator` — raises `ContentError` / `LayoutSpecError` on bad trees.
+- `Dumper` — prints tree as YAML for debugging.
+- `Counter` — counts nodes per role (used by harness TODO 53).
+
+## Done-When
+
+- [ ] `Visitor::Base.dispatch(node)` routes to `visit_<class>`.
+- [ ] Unknown classes hit `visit_unknown` (default: no-op).
+- [ ] `ContentVisitor` walks a `Content::Document` end-to-end.
+- [ ] `Validator` flags a Section with non-String title.
+- [ ] Specs cover dispatch, recursion, unknown class.

data/TODO.implementation/06-afm-data-and-parser.md

@@ -0,0 +1,37 @@
+---
+priority: P0
+phase: 2
+depends_on: [01]
+layer: metrics
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+The 14 standard Type1 fonts (Helvetica, Times, Courier + variants,
+Symbol, ZapfDingbats) need real glyph widths for line breaking. The
+canonical source is Adobe Font Metrics files (AFM). Arrolio bundles
+its own copy so it doesn't depend on Pdfrb's data dir.
+
+## Approach
+
+Files:
+- `data/arrolio/afm/*.afm` — 14 AFM files (port from
+  `pdfrb/data/pdfrb/afm/`).
+- `lib/arrolio/font/afm_parser.rb` — parses `StartFontMetrics` block,
+  `FontName`/`FullName`/`FamilyName`, `FontBBox`, `CapHeight`,
+  `XHeight`, `Ascender`, `Descender`, `StartCharMetrics`/`EndCharMetrics`,
+  and each `C N ; WX W ; N name ; B bbox ;` row.
+
+Parser produces a frozen `AFM::Font` value object with `char_metrics`
+hash keyed by both code and glyph name.
+
+## Done-When
+
+- [ ] All 14 AFM files load without error.
+- [ ] `AFMParser.from_file("data/arrolio/afm/Helvetica.afm").font_name`
+      == `"Helvetica"`.
+- [ ] Helvetica's `A` width is 668 (per AFM); `i` is 222; `m` is 833.
+- [ ] Ascender/descender/cap_height/x_height parsed for all 14.
+- [ ] Specs cover the parser on at least 3 of the 14.

data/TODO.implementation/07-afm-metrics.md

@@ -0,0 +1,41 @@
+---
+priority: P0
+phase: 2
+depends_on: [06]
+layer: metrics
+est: 1d
+status: in_progress
+---
+
+## Problem
+
+Layout callers ask "how wide is this Unicode string at this size?"
+The AFM gives glyph widths by AdobeStandardEncoding code or glyph
+name, not Unicode codepoint. We need Unicode → AFM resolution via
+the Adobe Glyph List.
+
+## Approach
+
+Files:
+- `data/arrolio/glyphlist.txt` — Adobe Glyph List (port from Pdfrb).
+- `lib/arrolio/font/glyph_list.rb` — parses glyphlist.txt into a
+  glyph_name → Unicode String map; exposes a reverse map
+  (Unicode codepoint → glyph_name).
+- `lib/arrolio/font_metrics/afm_metrics.rb` — wraps an `AFM::Font`
+  and exposes the universal metrics interface (see TODO 09):
+  - `advance_width(char)` — Unicode char → Float (or 0 if unknown).
+  - `width_of_string(str, font_size:)` — sum, scaled.
+  - `ascender(font_size:)`, `descender(font_size:)`, `cap_height(font_size:)`,
+    `x_height(font_size:)`, `line_height(font_size:, line_spacing:)`.
+
+Lookup path: Unicode codepoint → AGL glyph name → AFM char_metrics[name].
+
+## Done-When
+
+- [ ] `AfmMetrics.for_name("Helvetica").width_of_string("Hello", font_size: 12)`
+      is `27.336` (matches Adobe AFM to 0.001pt).
+- [ ] `width("i") == 2.664` and `width("m") == 9.996` at 12pt.
+- [ ] Non-ASCII WinAnsi chars resolve: en-dash → 556, bullet → 350.
+- [ ] Ascender / descender / cap_height / x_height match AFM.
+- [ ] Specs cover at least 3 of the 14 fonts (Helvetica, Times-Bold,
+      Courier-Oblique).