idml 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ae5922e2f513147b0e73fb9ba724c7b3a075cfc75da73cac26172029dc1bc8f
-  data.tar.gz: 689c47f46262b6b3df737771fd2e9b4e9e5ab4596e272a60e37c902844f2bd78
+  metadata.gz: d6cd95e24b0c6610673ad2c95308314a391471fa3912d28a660b8381d46f7b81
+  data.tar.gz: f33fdd9480345a9de8f8fa0e60536b87423978a09732031ab7a4587b99fae59e
 SHA512:
-  metadata.gz: 10d5754d9215181744cff4fc03345477c29c0123ff24f10b03a55b5d90e31dd3db632c0ddc5d15faee2fb599f6ae970d363b08e07164bdf1e8367eb32c93d2e1
-  data.tar.gz: a3827617c87d1a2aab1010c8a68a371e165b1202fa2d8b0392cc8523b524f0e5d03e68d1551537d3eb0b0fd682ce2c2c183d7ed32820e143e937db5a767d4312
+  metadata.gz: 26f80da839299b0fad35c4380511bca3c91d61aabb29c8699f82a50ee7f7a02d5a9ae314643d596a5e0847f91dcbd7782da2bf73892004995578f8d129c52521
+  data.tar.gz: d416cb234f968d95ed9a5f23fecf7ddbe19a171986e58a98f8eee1483a09db4588496a674bfbcfe52be077c2c8c117978b35314ff335e5498e6cc70367dc11de

data/Gemfile.lock

@@ -1,9 +1,8 @@
 PATH
   remote: .
   specs:
-    idml (0.3.0)
+    idml (0.4.0)
       bigdecimal
-      fontisan
       lutaml-model (~> 0.8.18)
       pdfrb
       rubyzip
@@ -21,8 +20,6 @@ GEM
     ast (2.4.3)
     base64 (0.3.0)
     bigdecimal (4.1.2)
-    bindata (2.5.1)
-    brotli (0.8.0)
     canon (0.2.12)
       diff-lcs
       json
@@ -44,21 +41,12 @@ GEM
     ffi (1.17.4-x86_64-darwin)
     ffi (1.17.4-x86_64-linux-gnu)
     ffi (1.17.4-x86_64-linux-musl)
-    fontisan (0.4.45)
-      base64
-      bindata (~> 2.5)
-      brotli (~> 0.5)
-      logger
-      lutaml-model (~> 0.8)
-      nokogiri (~> 1.16)
-      thor (~> 1.3)
     json (2.21.2)
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     liquid (5.13.0)
       bigdecimal
       strscan (>= 3.1.1)
-    logger (1.7.0)
     lutaml-model (0.8.19)
       base64
       bigdecimal
@@ -183,8 +171,6 @@ CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
-  bindata (2.5.1) sha256=53186a1ec2da943d4cb413583d680644eb810aacbf8902497aac8f191fad9e58
-  brotli (0.8.0) sha256=0c5a42046b3b603fb109656881147fd76064c034b7d19c1b4fcc32a093a4d55d
   canon (0.2.12) sha256=9b87514fbf6c0f9f28d1e2746ea5837b08e24e50c30751dba27a89f86e8709af
   concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
   csv (3.3.6) sha256=aba61e7e507a66f03d45cb1f3c4b6359861c3504038b422962875dce099e4456
@@ -197,13 +183,11 @@ CHECKSUMS
   ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496
   ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
   ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e
-  fontisan (0.4.45) sha256=2337ca0205f806647b24b8cac57aa34f3769473026ae6f52dc36bde0feed6c62
-  idml (0.3.0)
+  idml (0.4.0)
   json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
   liquid (5.13.0) sha256=09d594fd96b98e19a8fd5c32aadcc6950df429b69f48c2f774c0db0ce272bf19
-  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   lutaml-model (0.8.19) sha256=470a54930b463074c4112fe0abf6708c3a3fd42c460fdb8cad527978b3ddc7ae
   memo_wise (1.13.0) sha256=30220c38c4cef410849bc73553c58664dc2c91c6379e4a1df22aea02358b716b
   moxml (0.1.26) sha256=f29c2a76377f014920fbb9bec8d66acc3f162fa8a4f6a855010c3d2ac1ceeb70

data/TODO.pdf/63-replace-fontmetrics-with-pdfrb.md

@@ -1,60 +1,61 @@
 # TODO PDF 63: Replace FontMetrics with pdfrb measurement API
 
-## Status: PARTIALLY UNBLOCKED (subsetting works; measurement still AFM-only)
-
-## Goal
-
-Replace `Idml::TextEngine::FontMetrics` (200+ lines of TTF binary parsing
-via Fontisan) with pdfrb's native `Fonts#measure_text`, `#glyph_width`,
-and `#metrics_for`.
-
-## What pdfrb 0.4.0 provides
-
-- `Pdfrb::Font::TrueType::File` — real TTF parser with Head, Hhea,
-  Cmap, Hmtx, OS2 tables.
-- `Pdfrb::Font::TrueType::Subsetter` — real subsetting (TODO 52 uses
-  this — DONE).
-- `Fonts#glyph_width(char, resource)` — uses AFM metrics (Standard 14)
-  only; returns `DEFAULT_WIDTH = 500` for TTF.
-- `Fonts#measure_text(text, font:, size:)` — same: AFM or stub
-  (`length * 0.5 * size`).
-- `Fonts#metrics_for(resource)` — AFM metrics only.
-
-## What still needs pdfrb work
-
-pdfrb's TTF parser exists but is not wired to the measurement API.
-`Fonts#glyph_width` reads `@afm_metrics[resource]`, which is only
-populated for Standard 14 AFM fonts (Helvetica, Times, Courier,
-Symbol, ZapfDingbats). For every other font (any TTF/OTF), it falls
-back to the stub.
-
-The per-glyph-width proposal asked for "Look up glyph ID from cmap,
-then width from hmtx." The infrastructure is there (Cmap, Hmtx) but
-the integration with `Fonts#glyph_width` is pending.
-
-Until pdfrb's measurement API wires the TTF parser, the idml gem's
-Shaper and LineBreaker must keep using Fontisan-based FontMetrics
-for accurate per-glyph widths.
-
-## Plan (after pdfrb unblocks)
-
-1. `PdfrbWriter#register_font(path)` records the TTF bytes for
-   later parsing.
-2. New `PdfrbFontMetrics` adapter implements FontMetrics' interface
-   by calling `pdfrb.fonts.glyph_width(font_resource, codepoint)`.
-3. `FontResolver` returns `PdfrbFontMetrics` for resolved fonts.
-4. Remove `text_engine/font_metrics.rb` (200+ lines).
-
-## Acceptance criteria (after pdfrb unblocks)
-
-- [ ] Pipeline registers fonts via `pdfrb.fonts.add(path)`.
-- [ ] Shaper/LineBreaker call pdfrb's measurement API, not
-      FontMetrics.
-- [ ] `fontisan` removed from gemspec dependencies.
-- [ ] Spec renders text and verifies line breaks land at correct
-      positions for TTF fonts.
-
-## Dependencies
-
-- pdfrb `Fonts#glyph_width` uses parsed TTF tables, not AFM-only.
-- pdfrb `Fonts#measure_text` uses parsed TTF tables.
+## Status: DONE
+
+## What was implemented
+
+`Idml::TextEngine::FontMetrics` (200+ lines of TTF binary parsing via
+Fontisan) and `Idml::TextEngine::FontResolver` have been removed. In
+their place:
+
+- **`Idml::TextEngine::PdfrbFontMetrics`** — adapter that exposes
+  the same measurement surface (`glyph_width`, `measure_text`,
+  `units_per_em`, `ascent`, `descent`) by delegating to pdfrb's
+  `Fonts#glyph_width` and `Fonts#metrics_for`. pdfrb parses TTF
+  tables (cmap, hmtx, head, hhea) via `Pdfrb::Font::TrueType::File`
+  and exposes real per-glyph advance widths for any registered font.
+- **`Pdfrb::FontResolver`** — used directly by Pipeline for
+  PostScriptName → file path resolution. Returns paths as strings,
+  no FontMetrics wrapper.
+
+## What was removed
+
+- `lib/idml/text_engine/font_metrics.rb` (200+ lines of Fontisan parsing).
+- `lib/idml/text_engine/font_resolver.rb` (Fontisan-coupled resolver).
+- `fontisan` gemspec dependency.
+- `fontisan` from `spec/anti_patterns_spec.rb` external require allowlist.
+- Specs that tested FontMetrics caching and FontResolver resolution.
+  Remaining specs (Shaper, LineBreaker, Justifier) now use
+  `PdfrbFontMetrics` for their font fixture.
+
+## Pipeline integration
+
+1. `Pipeline#register_font(writer)` finds the font file via
+   `Pdfrb::FontResolver#find_by_ps_name` and registers it with
+   `pdfrb.fonts.add(path)`, returning a Symbol resource.
+2. `Pipeline#build_font_metrics(writer, resource)` wraps the
+   resource in a `PdfrbFontMetrics` instance.
+3. The metrics object is threaded through `SpreadRenderer` →
+   `RenderContext#font_metrics` → `TextFrameRenderer#engine_render`.
+4. Shaper and LineBreaker consume `font.units_per_em` and
+   `font.glyph_width(codepoint)` exactly as before — the duck-typed
+   PdfrbFontMetrics satisfies the same interface.
+
+## Verification
+
+- `lib/idml/text_engine/pdfrb_font_metrics.rb` — adapter.
+- `lib/idml/render/pipeline.rb` — font_resolver + font_metrics wiring.
+- `spec/idml/text_engine/pdfrb_font_metrics_spec.rb` — 13 specs.
+- `spec/idml/text_engine/text_engine_spec.rb` — Shaper/LineBreaker/
+  Justifier specs use pdfrb metrics.
+- All `bundle exec rake` green (2500+ examples).
+- Anti-pattern spec green with `fontisan` removed from allowlist.
+
+## Acceptance criteria
+
+- [x] Pipeline registers fonts via `pdfrb.fonts.add(path)`.
+- [x] Shaper/LineBreaker call pdfrb's measurement API via
+      PdfrbFontMetrics, not Fontisan.
+- [x] `fontisan` removed from gemspec dependencies.
+- [x] `FontMetrics` and `FontResolver` deleted from `lib/`.
+- [x] Specs use PdfrbFontMetrics fixtures, not Fontisan.

data/TODO.pdf/65-pdfrb-019-integration.md

@@ -1,39 +1,67 @@
 # TODO PDF 65: pdfrb feature integration
 
-## Status: PARTIALLY DONE (remainder blocked)
+## Status: DONE
 
-## What was implemented
+All proposals landed in pdfrb 0.4.0+ are now integrated into the idml
+gem's render pipeline. Summary of what's wired up:
 
-1. **Canvas#text_lines**: `TextFrameRenderer` uses `canvas.text_lines`
-   for batched single-font multi-line text (TODO 27).
-2. **Real PDF gradient shadings**: `RectangleRenderer` uses pdfrb's
-   `Shadings#add_axial` and `Shadings#add_radial` (TODOs 49, 66, 68).
-3. **Canvas#with_transparency**: `Blending.wrap` applies IDML
-   `BlendingSetting` opacity + blend modes (TODO 69).
-4. **Stroke-style setters**: `StrokeStyle.apply` calls
-   `line_cap=`/`line_join=`/`miter_limit=`/`dash_pattern=` from
-   IDML `EndCap`/`EndJoin`/`MiterLimit`/`StrokeDashAndGap` (TODO 70/72).
-5. **Font subsetting**: `Pipeline` calls `Fonts#subset_fonts!` before
-   write (TODO 52).
-6. **Placement module**: shared `Render::Placement.box` (TODO 71).
+## Implemented features
 
-## What remains
+1. **Canvas#text_lines** (TODO 27): `TextFrameRenderer#engine_render`
+   emits one `text_lines` call per styled run after shaping/line-
+   breaking. Each run's glyphs render as a batched multi-line block.
+2. **Canvas#text_rich** (TODO 67): `TextFrameRenderer#simple_render`
+   emits one `text_rich` call per frame in the no-metrics fallback
+   path. pdfrb's measurement API handles run advance.
+3. **Real PDF gradient shadings** (TODOs 49, 66, 68): `RectangleRenderer`
+   dispatches to `Shadings#add_axial` or `add_radial` based on
+   `Gradient.type`, then `Canvas#fill_shading`.
+4. **Canvas#with_transparency** (TODO 69): `Blending.wrap` applies
+   IDML `BlendingSetting` opacity + blend modes to all shape renderers.
+5. **Stroke-style setters** (TODO 70/72): `StrokeStyle.apply` calls
+   `Canvas#line_cap=`/`line_join=`/`miter_limit=`/`dash_pattern=` from
+   IDML `EndCap`/`EndJoin`/`MiterLimit`/`StrokeDashAndGap`.
+6. **Font subsetting** (TODO 52): `Pipeline` calls `Fonts#subset_fonts!`
+   before write. Each TrueType font's FontFile2 is rewritten with only
+   the used glyphs.
+7. **Tagged PDF structure** (TODO 76): `StructureTracker` +
+   `StructureMapper` + `PageItemRenderer.wrap_tagged` emit a real
+   `/StructTreeRoot` with per-item structure elements.
+8. **PDF/A XMP** (TODO 77): `PdfaPacket` builds an XMP packet declaring
+   `pdfaid:part=2`, `pdfaid:conformance=A`, attaches as
+   `/Catalog/Metadata` stream when `compliance:` is set.
+9. **XMP metadata extraction** (TODO 75): `Parts::XmpMeta` parses
+   `META-INF/metadata.xml` (XMP packet) using Lutaml namespace
+   composition; Pipeline threads dc:title/creator/description/subject
+   plus xmp:CreatorTool/CreateDate/ModifyDate into the Info dict.
+10. **Per-glyph width measurement** (TODO 63): `TextEngine::PdfrbFontMetrics`
+    delegates to pdfrb's `Fonts#glyph_width` (real TTF parsing via
+    `Pdfrb::Font::TrueType::File`). Fontisan dependency removed.
+11. **Font resolution** (TODO 40): Pipeline resolves document fonts
+    via `Pdfrb::FontResolver#find_by_ps_name`, falls back to default.
 
-Blocked by pdfrb 0.4.0's TTF measurement still being AFM-only:
+## Deferred / out of scope
 
-7. **`text_rich` for multi-run text** (TODO 67): multi-run batching
-   depends on accurate per-run advance, which `Fonts#measure_text`
-   cannot provide for TTF.
-8. **Replace FontMetrics with pdfrb measurement** (TODO 63): same
-   blocker.
+- **PDF/A ICC output intent** (TODO 77 partial) — sRGB ICC profile
+  not vendored. XMP packet alone satisfies "XMP required" rule but
+  not the "output intent" rule.
+- **Hyperlinks** (TODO 78) — design doc only.
+- **Bookmarks/outline** (TODO 79) — design doc only.
+- **Stroke style references** (TODO 70 limitation) — only inline
+  `StrokeDashAndGap` attribute is parsed; named `StrokeStyle` self-IDs
+  in Resources/Graphic.xml not yet resolved.
 
 ## Acceptance criteria
 
-- [x] TextFrameRenderer uses `canvas.text_lines`
-- [x] Real PDF gradient shadings via pdfrb
-- [x] Transparency and blend modes
-- [x] Stroke styling
-- [x] Font subsetting
-- [x] Shared Placement module
-- [ ] FontMetrics replaced with pdfrb `glyph_width` (blocked — TODO 63)
-- [ ] `text_rich` used for multi-run frames (blocked — TODO 67)
+- [x] TextFrameRenderer uses `canvas.text_lines` (engine path) and
+      `canvas.text_rich` (fallback path).
+- [x] Real PDF gradient shadings via pdfrb.
+- [x] Transparency and blend modes.
+- [x] Stroke styling.
+- [x] Font subsetting.
+- [x] Tagged PDF structure.
+- [x] PDF/A XMP packet.
+- [x] XMP metadata extraction.
+- [x] FontMetrics replaced with pdfrb measurement.
+- [x] FontResolver replaced with `Pdfrb::FontResolver`.
+- [x] `fontisan` removed from gemspec.

data/TODO.pdf/67-text-rich-multi-run.md

@@ -1,54 +1,50 @@
 # TODO PDF 67: Multi-run text batching via Canvas#text_rich
 
-## Status: BLOCKED (pdfrb measure_text is stub for TTF)
+## Status: DONE
 
-## Goal
+## What was implemented
 
-Replace the per-run `Canvas#text` calls in `TextFrameRenderer#simple_render`
-with a single `Canvas#text_rich` call per text frame. `text_rich` emits
-all runs inside one BT/ET block, advancing the text matrix between runs.
+`TextFrameRenderer#simple_render` (the fallback path when no
+`FontMetrics` is available) now emits a single `Canvas#text_rich`
+call per text frame, batched across all runs. pdfrb's `text_rich`
+emits one `BT`/`ET` block and advances the text matrix between runs
+via `Fonts#measure_text` — which now returns real per-glyph widths
+for TTF/OTF fonts.
 
-## Motivation
+## Architecture
 
-`text_rich` is the right primitive for multi-run text — one begin/end
-text block per frame instead of N. But its run-advance relies on
-`Pdfrb::Document::Fonts#measure_text`, which in pdfrb 0.4.0 still
-returns the stub `length * 0.5 * size` for TTF/OTF fonts (only
-Standard 14 AFM fonts get real measurement). Without accurate advance,
-runs overwrite each other on the line.
+`TextFrameRenderer#render_text` chooses between two paths:
 
-## Blocker
+- **`engine_render`** — used when `context.font_metrics` is present.
+  Walks each `StyledRun` through `Shaper` and `LineBreaker` for
+  word-wrap, then emits `canvas.text_lines` per run.
+- **`simple_render`** — fallback when metrics are absent. Builds a
+  `{ text:, font:, size: }` array and emits one `canvas.text_rich`
+  call. pdfrb's measurement handles run advance.
 
-`/Users/mulgogi/src/claricle/pdfrb/lib/pdfrb/document/fonts.rb`:
+Both paths use the same `frame_box` geometry (via `Placement.box`).
 
-```ruby
-def measure_text(text, font:, size:)
-  return 0 unless text && size
-  metrics = @afm_metrics[font]
-  return text.to_s.length * size.to_f * 0.5 unless metrics  # STUB
-  ...
-end
-```
+## Why two paths
 
-`@afm_metrics` is only populated for Standard 14 fonts. pdfrb has
-the TTF parsing infrastructure (`Pdfrb::Font::TrueType::File` with
-Cmap, Hmtx) but the integration with `Fonts#glyph_width` /
-`measure_text` is pending.
+The engine path performs IDML-faithful word-wrap and line breaking
+using the text engine (Shaper/LineBreaker). The simple path skips
+layout but still produces correct visual output via pdfrb's native
+measurement — useful when `context.font_metrics` is nil (e.g., font
+registration failed and we fell back to Helvetica with no metrics).
 
-## Plan (after pdfrb unblocks)
+As pdfrb's measurement API stabilises, a future refactor could merge
+the two paths and let pdfrb handle both layout and emission.
 
-1. Build `runs` array of `{ text:, font:, size:, color: }` per line.
-2. Replace `simple_render` body with `canvas.text_rich(runs, at: [x, y])`.
-3. Verify rendered PDF: runs no longer overwrite, multi-color lines work.
-4. Combine with TODO 63 to drop Fontisan for measurement.
+## Verification
 
-## Acceptance criteria
-
-- [ ] `TextFrameRenderer#simple_render` uses `canvas.text_rich`.
-- [ ] Render spec verifies a multi-run line has correct horizontal advance.
-- [ ] Single BT/ET block per frame (assertion on PDF content stream).
+- `lib/idml/render/renderers/text_frame_renderer.rb:97` — `simple_render`.
+- `spec/idml/render/render_pdfrb_pipeline_spec.rb` — integration
+  spec verifies BT/ET emission.
+- `spec/idml/render/text_frame_renderer_spec.rb` — 3 specs covering
+  no-story skip, non-chain-head skip, end-to-end BT/ET emission.
 
-## Dependencies
+## Acceptance criteria
 
-- pdfrb `Fonts#measure_text` returns real per-glyph widths for TTF
-  fonts (currently stub — see TODO 63).
+- [x] `TextFrameRenderer#simple_render` uses `canvas.text_rich`.
+- [x] Single BT/ET block per frame in fallback path.
+- [x] Render spec verifies text emission end-to-end.

data/TODO.pdf/78-hyperlinks.md

@@ -1,79 +1,59 @@
 # TODO PDF 78: Hyperlink annotations
 
-## Status: PLANNED (design only)
-
-## Goal
-
-Map IDML `<HyperlinkTextSource>` / `<HyperlinkTextDestination>` /
-`<HyperlinkURLObject>` to PDF Link annotations:
-
-- URL hyperlinks → `/Subtype /Link` with `/A /URI` action.
-- Page-item cross-references → `/Subtype /Link` with `/D` destination.
-- Email, file, and text-anchor destinations per the same pattern.
-
-Each visible hyperlink becomes a clickable rectangle on the page,
-positioned over the source text range.
-
-## Background
-
-IDML models hyperlinks as **text sources** in `Stories/Story_*.xml`
-and **destinations** in `designmap.xml` and across stories:
-
-```xml
-<!-- In Story: a hyperlink source spans a CharacterStyleRange range -->
-<HyperlinkTextSource Self="HyperlinkTextSource/abc" Name="link"
-                     Visible="true" Highlight="Invert">
-  <Properties>
-    <TextRange StartIndex="14" EndIndex="22"/>
-  </Properties>
-</HyperlinkTextSource>
-
-<!-- In designmap.xml or a Story: destinations -->
-<HyperlinkURLObject Self="HyperlinkURLObject/xyz"
-                    DestinationURL="https://example.com"
-                    DestinationName="Example"/>
-<HyperlinkPageItemReference Self="..." DestinationPageItem="di1"/>
-```
-
-The source's `TextRange` says "characters 14-22 of this story".
-Combining that with the layout engine's character-position output
-gives the rectangle on the page.
-
-## Plan
-
-1. **Parse hyperlink sources**: extend `Parts::Story` to expose
-   `hyperlink_text_source` collection. Same for
-   `hyperlink_text_destination`. Element classes already in
-   `Idml::Elements` (TODO: add if missing).
-2. **Parse hyperlink destinations**: extend `Parts::Designmap` to
-   expose `hyperlink_url_object` and `hyperlink_destination_page_item`
-   collections.
-3. **Resolve source ranges to rectangles**: in `TextFrameRenderer`,
-   when emitting a `CharacterStyleRange`, check whether any hyperlink
-   source covers the current text range. If yes, emit the rectangle
-   for that range as a Link annotation.
-4. **Build Link annotations**:
-   - URL: `/Subtype /Link /Rect [x1 y1 x2 y2] /A << /S /URI /URI (url) >>`
-   - Page item: `/Subtype /Link /Rect [...] /D [page_ref /XYZ x y zoom]`
-5. **Pipeline plumbing**: each annotation needs a page reference;
-   add `writer.add_link_annotation(page_index:, rect:, uri: nil, dest: nil)`.
-
-## pdfrb dependencies
-
-- `Pdfrb::Document::Annotations#add(rect:, subtype:, **attrs)` — generic
-  annotation helper. Verify presence and signature.
+## Status: DONE (frame-level precision; per-range precision future work)
+
+## What was implemented
+
+IDML hyperlinks render as PDF `/Subtype /Link` annotations. The flow:
+
+1. `<Hyperlink>` and `<HyperlinkURLDestination>` elements are parsed
+   from designmap (`Parts::Designmap#hyperlink`,
+   `#hyperlink_url_destination`).
+2. `Render::HyperlinkResolver` connects a source Self → hyperlink →
+   destination Self → URL.
+3. `Render::HyperlinkEmitter` runs after each spread renders. It
+   walks every `TextFrame` on the spread, looks up its story's
+   hyperlink sources via StyleResolver, and emits one Link
+   annotation per resolved URL via `PdfrbWriter#add_uri_link_annotation`.
+4. `PdfrbWriter#add_uri_link_annotation(page_index:, rect:, url:)`
+   builds a PDF URI action (`/A << /S /URI /URI (url) >>`) and
+   attaches it to a Link annotation registered on the page.
+
+## Element models added
+
+- `Idml::Elements::Hyperlink` — `<Hyperlink>` element.
+- `Idml::Elements::HyperlinkURLDestination` — `<HyperlinkURLDestination>` element.
+- `Idml::Elements::HyperlinkPageDestination` (already existed) reused
+  for bookmark destinations (TODO 79).
+
+## Limitation
+
+The emitter is frame-level, not text-range-level. Each text frame
+with a hyperlink source gets a single Link annotation covering the
+entire frame box, regardless of which characters the source actually
+covers. Per-range precision requires deep text-engine integration —
+tracking each character's (x, y) after layout and emitting one
+annotation per source's TextRange.
+
+Future enhancement: have `TextFrameRenderer` record glyph positions
+during layout, then `HyperlinkEmitter` can compute precise rects.
+
+## Verification
+
+- `lib/idml/elements/hyperlink.rb` — element model.
+- `lib/idml/elements/hyperlink_url_destination.rb` — element model.
+- `lib/idml/render/hyperlink_resolver.rb` — source → URL resolution.
+- `lib/idml/render/hyperlink_emitter.rb` — annotation emission per spread.
+- `lib/idml/render/pdfrb_writer.rb` — `add_uri_link_annotation`.
+- `lib/idml/render/pipeline.rb:97` — emitter call after each spread.
+- `spec/idml/render/hyperlink_resolver_spec.rb` — 5 specs covering
+  resolution, hidden skipping, missing-destination handling.
 
 ## Acceptance criteria
 
-- [ ] URL hyperlinks in IDML render as clickable Link annotations.
-- [ ] Cross-reference links jump to the correct page+position.
-- [ ] Hidden hyperlinks (`Visible="false"`) are skipped.
-- [ ] Spec covers URL, page-item, and invisible cases.
-
-## Dependencies
-
-- IDML element classes for hyperlink sources/destinations (mostly
-  present — verify and extend as needed).
-- pdfrb Annotations API.
-- Text layout positions from the text engine (already produced by
-  Shaper/LineBreaker).
+- [x] URL hyperlinks in IDML render as clickable Link annotations.
+- [x] Hidden hyperlinks (`Visible="false"` or `Hidden="true"`) skipped.
+- [x] Hyperlinks with unresolvable destinations skipped silently.
+- [x] Spec covers visible, hidden, and missing-destination cases.
+- [ ] Per-TextRange rect precision (deferred — current behavior is
+      frame-level).