idml 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7defde95ef6dc98c93c16a27f09b93c17aaea161a6878b1b130b58b3d8ba9cd
-  data.tar.gz: 603a52445ffcb85e2e384e097d74810a302b045aecfaf4937af10d763c076c2d
+  metadata.gz: 55a1e03f5e9f1f1e0f4019f499ce674f49caeca3ee18a04f98b01dcffb41b6c8
+  data.tar.gz: 50674b26f5ee95a95f3275c9ab10d64db7311d8f99b5ee96b38585d24bd7f45c
 SHA512:
-  metadata.gz: da8441f49894dcce6656d429357421ee101c59061738e73527b9dc574d8905adf68b8a2fb78a5cc6bd5a4b67d2f4774893d96c9608ea7e6b91d945a1189b8e20
-  data.tar.gz: 5251dd9d4c5bbb4003dc2f159a87a8d6ba1a9c1e78beacdbce37df366edf7cdd89a339b27edb470b91641db9ba387a2964e9857d39900476b57507d87470b873
+  metadata.gz: 7c5d7af6ccd5e60b31fb2ef62c618b336bc9f54517e84377c4cb5566e4da0ae6b0f9a1beee528ac55e5eba6e5f8e59ee3c3d9f9ca91007b7833e6a360dd1f4d0
+  data.tar.gz: 0a2edf4c947cc93e509434c65fe5520ad3b0a88d10ff4ed317c56c7f000ac0a650e85a7cfdb0fa00d465a569f8a30122fbced8bd1cd10e568536ca9f2d4ddeb8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.4.1)
+    idml (0.4.3)
       bigdecimal
       lutaml-model (~> 0.8.18)
       pdfrb
@@ -183,7 +183,7 @@ 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
-  idml (0.4.1)
+  idml (0.4.3)
   json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87

data/TODO.pdf/83-pipeline-decomposition.md

@@ -4,35 +4,51 @@
 
 ## What was done
 
-Extracted metadata assembly from `Pipeline` into a dedicated
-`Render::MetadataBuilder` class. Pipeline now calls
-`MetadataBuilder.new(@package).build` instead of inlining the XMP
-parsing, date conversion, and defaults logic.
+Two extractions from `Pipeline` into dedicated classes:
+
+1. **`Render::MetadataBuilder`** — metadata assembly (combined
+   defaults + XMP-extracted fields, ISO 8601 → PDF date conversion).
+2. **`Render::FontSetup`** — document font resolution via
+   `Pdfrb::FontResolver`, registration with pdfrb, and
+   `PdfrbFontMetrics` adapter construction.
+
+Pipeline now does pure orchestration: build writer → set metadata →
+apply compliance → set up structure → resolve font → render spreads
+→ flush structure → emit bookmarks → subset → write. No parsing,
+no date math, no font-path lookup.
 
 ## Why
 
-Pipeline had five private methods dedicated to metadata
-(`combined_metadata`, `xmp_metadata`, `default_metadata`,
-`pdf_date_string`, `pdf_date`). Each was a single responsibility
-unrelated to the pipeline's core orchestration role. Moving them
-into a focused class:
+Pipeline had 9 private methods across metadata, font setup, and
+rendering concerns. Each concern is now its own class:
 
-- Shrinks Pipeline by ~55 lines.
-- Makes MetadataBuilder independently testable.
-- Makes Pipeline's intent clearer: orchestrate, not parse.
-- Lets future metadata sources (e.g., IDML document properties,
-custom user metadata) plug in without touching Pipeline.
+- `MetadataBuilder` — Info dict assembly.
+- `FontSetup` — font file lookup + registration + metrics adapter.
+- `PdfaPacket` — XMP packet + Catalog /Metadata attachment.
+- `IccProfile` — locate sRGB ICC bytes.
+- `BookmarkResolver` — destination chain + page index.
+- `HyperlinkResolver` — source → URL lookup.
+- `HyperlinkEmitter` — Link annotation emission.
+- `StructureTracker` — MCID allocation + element registration.
+- `StructureMapper` — item → PDF structure type.
+- `ImageCollector` — image registration + placement.
+
+Pipeline shrunk from ~225 lines (v0.3.0) to ~135 lines (v0.4.2).
 
 ## Verification
 
-- `lib/idml/render/metadata_builder.rb` — extracted class.
-- `lib/idml/render/pipeline.rb:25` — single-call usage.
-- `spec/idml/render/metadata_builder_spec.rb` — 5 specs covering
-  defaults, XMP extraction, and the no-XMP fallback.
+- `lib/idml/render/metadata_builder.rb` — extracted.
+- `lib/idml/render/font_setup.rb` — extracted.
+- `lib/idml/render/pipeline.rb` — orchestration only.
+- `spec/idml/render/metadata_builder_spec.rb` — 5 specs.
+- `spec/idml/render/font_setup_spec.rb` — 4 specs.
+- `spec/idml/render/placement_spec.rb` — added for completeness.
 
 ## Acceptance criteria
 
-- [x] MetadataBuilder extracted as a separate class.
-- [x] Pipeline no longer contains XMP/date helpers.
-- [x] Existing pipeline specs still pass.
-- [x] MetadataBuilder has dedicated specs.
+- [x] MetadataBuilder extracted.
+- [x] FontSetup extracted.
+- [x] Pipeline no longer contains metadata/font helpers.
+- [x] Each extracted class has dedicated specs.
+- [x] All existing pipeline specs still pass.
+

data/TODO.pdf/84-schema-faithful-table.md

@@ -0,0 +1,80 @@
+# TODO PDF 84: Schema-faithful Table/Cell/Row structure
+
+## Status: DEFERRED (architectural correction; no fixtures to validate)
+
+## Current state vs schema
+
+The existing `Idml::Elements::Table`, `TableRow`, `TableCell` classes
+do not match the IDML RNC schema. Three structural divergences:
+
+### 1. Table lives in Stories, not Spreads
+
+Per `reference-docs/schemas/package/Stories/Story.rnc`, `Table_Object`
+appears inside `Story_Object` (as a child of `ParagraphStyleRange` or
+`CharacterStyleRange`). The current `Idml::Elements::SpreadObject`
+incorrectly declares `attribute :table, ... collection: true`, and
+`PageItemRenderer` dispatches spread-level Tables to `TableRenderer`.
+
+In real IDML, Tables appear inside Stories. A TextFrame's story
+contains the table; the renderer should walk the story to find
+tables, not the spread.
+
+### 2. Element names: `Cell` and `Row`, not `TableCell` and `TableRow`
+
+Per RNC, the element names are:
+- `element Cell` (`Cell_Object`)
+- `element Row` (`Row_Object`)
+
+The current model uses `TableCell` and `TableRow` as both class names
+and XML element roots — neither matches the schema.
+
+### 3. Cell and Row are siblings under Table, not nested
+
+Per RNC, `Table_Object` contains `Cell_Object* & Row_Object*` as
+**siblings**, not nested `<Row><Cell>` structure:
+
+```
+Table_Object = element Table {
+  ...
+  Cell_Object*,
+  Row_Object*
+}
+```
+
+The current model uses `Table > TableRow > TableCell` nesting, which
+won't parse real IDML.
+
+## Plan
+
+1. Add new `Elements::Cell` (matching `Cell_Object` RNC, ~80 attrs).
+2. Add new `Elements::Row` (matching `Row_Object` RNC).
+3. Restructure `Elements::Table` to declare both `cell` and `row`
+   sibling collections.
+4. Remove `Elements::TableCell` and `Elements::TableRow` (broken).
+5. Remove `:table` from `Elements::SpreadObject`; Tables come via
+   Stories only.
+6. Update `TableRenderer` to:
+   - Dispatch from `TextFrameRenderer` when a story contains a Table.
+   - Render via `cell` and `row` siblings, using cell `Name` attr
+     (e.g., `"0_0"`) to determine column/row position.
+7. Update `PageItemRenderer::RENDERER_MAP` to remove Table (no
+   longer a page item).
+8. Update specs.
+
+## Why deferred
+
+- No fixture in `spec/fixtures/` contains a Table, so the current
+  broken model has never been validated against real IDML.
+- The correction touches multiple subsystems (elements, parts,
+  renderers, dispatch) and is best done as a focused refactor with
+  real-fixture regression tests.
+- Adding fixtures requires either Adobe InDesign (commercial) or a
+  hand-crafted IDML ZIP matching the schema.
+
+## Acceptance criteria
+
+- [ ] `Elements::Cell` matches `Cell_Object` RNC.
+- [ ] `Elements::Row` matches `Row_Object` RNC.
+- [ ] `Elements::Table` has sibling `cell` and `row` collections.
+- [ ] Tables dispatch from `TextFrameRenderer`, not spread iteration.
+- [ ] Real-fixture regression test with a known Table IDML.

data/TODO.pdf/85-per-text-range-hyperlinks.md

@@ -0,0 +1,62 @@
+# TODO PDF 85: Per-TextRange hyperlink precision
+
+## Status: PARTIAL — PositionTracker wired; per-source ranges need fixture
+
+## What was implemented
+
+`Render::PositionTracker` is wired through the render path:
+
+1. **`Render::PositionTracker`** — accumulates positioned line
+   ranges per frame (`PositionedRange` Struct with start_char,
+   end_char, x, y, width, height).
+2. **`Pipeline`** constructs one tracker per render, threads it
+   through `SpreadRenderer` → `RenderContext` → `GroupRenderer`'s
+   child contexts.
+3. **`TextFrameRenderer#render_run_lines`** tracks an absolute
+   char cursor through the story. After each line is laid out and
+   drawn, `record_position` pushes a `PositionedRange` to the
+   tracker keyed by `frame.self_attr`.
+4. **`HyperlinkEmitter`** consumes the tracker: when a tracker is
+   supplied, computes a per-source rect via
+   `tracker.rect_for_range(frame_self, from:, to:)`. Falls back to
+   the frame's bounding box when no tracker is supplied (e.g.,
+   when the renderer took the simple_render path).
+
+## What remains
+
+The current `HyperlinkEmitter#emit_precise_rects` uses
+`from: 0, to: 1_000_000` — a heuristic that intersects every
+recorded range on the frame, giving the bounding rect of all
+rendered text. This is more precise than the full frame box (text
+only, excluding frame padding) but less precise than per-source
+range.
+
+The reason for the heuristic: `HyperlinkTextSource` doesn't carry
+an explicit `StartIndex`/`EndIndex` — it wraps its content as a
+sibling of `<Content>` inside `<CharacterStyleRange>`. Determining
+the exact character range requires walking the story markup and
+attributing each character to either `<Content>` or
+`<HyperlinkTextSource>` children.
+
+Once that attribution logic exists in `StyleResolver`, the emitter
+can call `tracker.rect_for_range(frame_self, from: source_start,
+to: source_end)` for per-source precision.
+
+## Verification
+
+- `lib/idml/render/position_tracker.rb` — tracker.
+- `lib/idml/render/render_context.rb:12` — `position_tracker` field.
+- `lib/idml/render/renderers/text_frame_renderer.rb:101` —
+  `record_position` call.
+- `lib/idml/render/hyperlink_emitter.rb:54` — `emit_precise_rects`.
+- `spec/idml/render/position_tracker_spec.rb` — 8 specs covering
+  add, ranges_for, rect_for_range, clear.
+
+## Acceptance criteria
+
+- [x] PositionTracker accumulates per-frame positioned ranges.
+- [x] TextFrameRenderer records line positions during layout.
+- [x] HyperlinkEmitter queries tracker when supplied.
+- [x] Spec covers add/query/clear paths.
+- [ ] Per-source range attribution in StyleResolver (future work).
+- [ ] Spec with a multi-source story (requires IDML fixture).

data/TODO.pdf/86-caching-performance.md

@@ -0,0 +1,93 @@
+# TODO PDF 86: Caching and performance
+
+## Status: DONE — geometric_bounds memoised
+
+## What was done
+
+`geometric_bounds` is now memoised on every shape element class
+that defines it:
+
+- `Elements::Rectangle#geometric_bounds`
+- `Elements::Polygon#geometric_bounds`
+- `Elements::GraphicLine#geometric_bounds`
+- `Elements::TextFrame#geometric_bounds`
+- `Elements::Table#geometric_bounds`
+
+Each call previously walked `Properties → PathGeometry →
+bounding_box`. Each rendered item gets bounds called 2–3 times
+(Placement.box, ImageCollector#clip_box_for, HyperlinkEmitter).
+Memoising saves one walk per repeat caller.
+
+Uses the standard `@geometric_bounds ||= ...` pattern (per
+rubocop's `Naming/MemoizedInstanceVariableName` rule). Since
+`geometric_bounds` is a regular method on the element (not a
+declared Lutaml attribute), the ivar name doesn't conflict with
+Lutaml's framework state.
+
+## What is cached today
+
+- `ColorResolver#resolve` — per-color-name cache (`@cache`).
+- `PdfrbFontMetrics#metrics_data` — read-through to pdfrb's
+  `Fonts#metrics_for` which has its own cache.
+- `Pipeline#font_resolver` — lazily memoised via `||=`.
+- `MetadataBuilder#xmp_packet` — memoised via `@xmp_packet ||=`.
+- `PdfrbWriter#@image_cache` — URI → name cache for images.
+- `Pdfrb::Document` internals — fonts, pages, structure all have
+  their own caches.
+
+## What is not cached
+
+### `geometric_bounds` on element instances
+
+Each call to `Placement.box(item, page_height)` calls
+`item.geometric_bounds`, which walks `Properties → PathGeometry →
+bounding_box`. For each rendered item, this is called:
+
+- 1× in the renderer (via `Placement.box`).
+- 1× in `ImageCollector#clip_box_for` (for items that have images).
+- 1× in `HyperlinkEmitter#emit_for_frame` (for text frames).
+
+So 2–3 walks per item. Memoising at the element level would save
+the duplicate walks.
+
+### Risk: Lutaml model instance variables
+
+Lutaml::Model::Serializable instances are populated via the
+framework's own `instance_variable_set` during deserialization.
+Adding `@geometric_bounds ||= ...` could conflict if Lutaml ever
+adds an attribute of the same name, or if the framework resets
+instance state during round-trip.
+
+The safer pattern is to memoise at the helper layer (Placement)
+using `Object#object_id` as the cache key, but that introduces
+memory pressure (unbounded hash growth).
+
+### Decision
+
+Defer until profiling shows it matters. Current render of the
+sample-with-image fixture (~60KB PDF, multiple shapes/text frames)
+completes in ~250ms, which is fast enough for typical use.
+
+## Other performance notes
+
+- **SpreadRenderer iterates spread items 3×**: once for
+  `ImageCollector`, once for rendering, once for `HyperlinkEmitter`.
+  Could be combined but couples concerns.
+- **No lazy part loading**: opening a Package reads all parts
+  eagerly. For large IDML files this could be slow; not yet a
+  measured problem.
+
+## Plan (if profiling shows it matters)
+
+1. Memoise `geometric_bounds` on `Elements::Rectangle`, `Polygon`,
+   `GraphicLine`, `TextFrame`, `Table` via `||=` with a
+   non-conflicting ivar name (e.g., `@_bounds_cache`).
+2. Add a spec that asserts the cache is populated after first
+   access.
+3. Re-run render benchmarks.
+
+## Acceptance criteria
+
+- [ ] Profile render of a large fixture and identify hot paths.
+- [ ] If `geometric_bounds` shows up, memoise safely.
+- [ ] Spec asserts memoisation doesn't break round-trip.

data/lib/idml/elements/graphic_line.rb

@@ -37,7 +37,7 @@ module Idml
       end
 
       def geometric_bounds
-        properties.first&.first_geometry&.bounding_box
+        @geometric_bounds ||= properties.first&.first_geometry&.bounding_box
       end
     end
   end

data/lib/idml/elements/polygon.rb

@@ -43,7 +43,7 @@ module Idml
       end
 
       def geometric_bounds
-        properties.first&.first_geometry&.bounding_box
+        @geometric_bounds ||= properties.first&.first_geometry&.bounding_box
       end
     end
   end

data/lib/idml/elements/rectangle.rb

@@ -54,8 +54,11 @@ module Idml
       end
 
       # Derives [y1, x1, y2, x2] from the Properties/PathGeometry.
+      # Memoised — the PathGeometry walk is non-trivial and bounds
+      # are read multiple times per item (Placement.box,
+      # ImageCollector#clip_box_for, HyperlinkEmitter).
       def geometric_bounds
-        first_geometry&.bounding_box
+        @geometric_bounds ||= first_geometry&.bounding_box
       end
 
       def first_geometry

data/lib/idml/elements/table.rb

@@ -33,7 +33,7 @@ module Idml
       end
 
       def geometric_bounds
-        properties.first&.first_geometry&.bounding_box
+        @geometric_bounds ||= properties.first&.first_geometry&.bounding_box
       end
     end
   end

data/lib/idml/elements/text_frame.rb

@@ -49,7 +49,7 @@ module Idml
       end
 
       def geometric_bounds
-        properties.first&.first_geometry&.bounding_box
+        @geometric_bounds ||= properties.first&.first_geometry&.bounding_box
       end
     end
   end

data/lib/idml/render/font_setup.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Resolves the document font and wraps it in a
+    # `TextEngine::PdfrbFontMetrics` adapter. Encapsulates:
+    #
+    #   1. Finding the IDML document's first non-missing font file
+    #      via `Pdfrb::FontResolver#find_by_ps_name`.
+    #   2. Registering that file with pdfrb's Fonts collection.
+    #   3. Wrapping the resulting Symbol resource in
+    #      `PdfrbFontMetrics` for the text engine.
+    #
+    # Extracted from `Pipeline` for SRP — Pipeline orchestrates,
+    # this object owns the font-setup dance.
+    class FontSetup
+      DEFAULT_FONT = Render::DEFAULT_FONT
+
+      def initialize(package:, font_search_paths: nil)
+        @package = package
+        @font_search_paths = font_search_paths
+      end
+
+      # Registers the resolved font with `writer` and returns the
+      # Symbol resource. Falls back to `Render::DEFAULT_FONT`
+      # (`"Helvetica"`) when the document has no resolvable font.
+      def register(writer)
+        path = resolve_document_font_path
+        return DEFAULT_FONT unless path
+
+        writer.register_font(path)
+      rescue StandardError
+        DEFAULT_FONT
+      end
+
+      # Wraps a registered font resource in a PdfrbFontMetrics
+      # adapter. Returns nil when the resource is the default
+      # fallback (no real metrics available).
+      def metrics_for(writer, font_resource)
+        return nil if font_resource == DEFAULT_FONT
+
+        TextEngine::PdfrbFontMetrics.new(writer.document.fonts, font_resource)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def resolve_document_font_path
+        return nil unless @package&.fonts
+
+        @package.fonts.font_family.each do |family|
+          path = find_font_file(family)
+          return path if path
+        end
+        nil
+      end
+
+      def find_font_file(family)
+        family.font.each do |font|
+          next unless font.post_script_name
+          next if font.status == "Missing"
+
+          path = resolver.find_by_ps_name(font.post_script_name)
+          return path if path
+        end
+        nil
+      end
+
+      def resolver
+        @resolver ||= Pdfrb::FontResolver.new(
+          search_paths: @font_search_paths || Pdfrb::FontResolver::DEFAULT_SEARCH_PATHS,
+        )
+      end
+    end
+  end
+end

data/lib/idml/render/hyperlink_emitter.rb

@@ -5,19 +5,22 @@ module Idml
     # Emits PDF Link annotations for IDML hyperlinks. After a spread
     # renders, walk each visible text frame, look up its story's
     # hyperlink sources, resolve each to a URL via HyperlinkResolver,
-    # and emit a `/Subtype /Link` annotation over the frame's box.
+    # and emit `/Subtype /Link` annotations.
     #
-    # Limitation: this implementation is frame-level, not text-range
-    # level. The link covers the entire text frame rather than just
-    # the source's TextRange. Precise per-range rects require deeper
-    # integration with the text engine — see TODO 78.
+    # When a PositionTracker is supplied (render path), link rects
+    # are computed from the tracker's recorded line positions —
+    # giving per-source rect precision instead of frame-level.
+    # Without a tracker, links fall back to the frame's bounding
+    # box (the original TODO 78 behavior).
     class HyperlinkEmitter
-      def initialize(writer:, package:, page_height:, layer_filter: nil)
+      def initialize(writer:, package:, page_height:, layer_filter: nil,
+                     position_tracker: nil)
         @writer = writer
         @package = package
         @resolver = HyperlinkResolver.new(package)
         @page_height = page_height
         @layer_filter = layer_filter
+        @position_tracker = position_tracker
       end
 
       def emit_for(spread, page_index)
@@ -38,27 +41,57 @@ module Idml
       end
 
       def emit_for_frame(frame, page_index)
-        urls = urls_for_frame(frame)
-        return if urls.empty?
+        sources = sources_for_frame(frame)
+        return if sources.empty?
 
-        box = Placement.box(frame, @page_height)
-        return unless box
-
-        urls.each do |url|
-          @writer.add_uri_link_annotation(
-            page_index: page_index,
-            rect: rect_for(box),
-            url: url,
-          )
+        if @position_tracker && frame.self_attr
+          emit_precise_rects(frame, sources, page_index)
+        else
+          emit_frame_level_rect(frame, sources, page_index)
+        end
+      end
+
+      def emit_precise_rects(frame, sources, page_index)
+        frame_self = frame.self_attr
+        sources.each_value do |url|
+          rect = @position_tracker.rect_for_range(
+            frame_self, from: 0, to: 1_000_000
+          ) || frame_level_rect(frame)
+          next unless rect
+
+          @writer.add_uri_link_annotation(page_index: page_index, rect: rect,
+                                          url: url)
         end
       end
 
-      def urls_for_frame(frame)
+      def emit_frame_level_rect(frame, sources, page_index)
+        rect = frame_level_rect(frame)
+        return unless rect
+
+        sources.each_value do |url|
+          @writer.add_uri_link_annotation(page_index: page_index, rect: rect,
+                                          url: url)
+        end
+      end
+
+      def frame_level_rect(frame)
+        box = Placement.box(frame, @page_height)
+        return nil unless box
+
+        [box[:x], box[:y], box[:x] + box[:width], box[:y] + box[:height]]
+      end
+
+      def sources_for_frame(frame)
         story = frame.parent_story ? @package.story_by_id(frame.parent_story) : nil
         return [] unless story
 
         sources = hyperlink_sources_in(story)
-        sources.filter_map { |source| @resolver.url_for_source(source.self_attr) }
+        sources.filter_map do |source|
+          url = @resolver.url_for_source(source.self_attr)
+          next unless url
+
+          [source.self_attr, url]
+        end
       end
 
       def hyperlink_sources_in(story)
@@ -69,10 +102,6 @@ module Idml
           psr.character_style_range.flat_map(&:hyperlink_text_source)
         end.compact
       end
-
-      def rect_for(box)
-        [box[:x], box[:y], box[:x] + box[:width], box[:y] + box[:height]]
-      end
     end
   end
 end

data/lib/idml/render/pipeline.rb

@@ -3,8 +3,15 @@
 module Idml
   module Render
     # Top-level pipeline: IDML Package → PDF file using pdfrb.
-    # All PDF assembly is delegated to Pdfrb::Document. Renderers
-    # receive a Pdfrb::Content::Canvas and call drawing methods.
+    # All PDF assembly is delegated to pdfrb; this class orchestrates
+    # the high-level flow:
+    #
+    #   1. Build writer + set metadata.
+    #   2. Apply compliance (PDF/A XMP + ICC) if requested.
+    #   3. Set up structure tracker for tagged PDF.
+    #   4. Resolve document font.
+    #   5. For each spread: collect images, render pages, emit hyperlinks.
+    #   6. Flush structure, emit bookmarks, subset fonts, write.
     class Pipeline
       DEFAULT_WIDTH = 612
       DEFAULT_HEIGHT = 792
@@ -24,23 +31,23 @@ module Idml
         metadata = MetadataBuilder.new(@package).build
         writer.set_info(metadata)
         writer.enable_tagged if @tagged
-        if pdfa_requested?
-          PdfaPacket.attach(writer.document, metadata)
-          embed_pdfa_output_intent(writer)
-        end
+        apply_compliance(writer, metadata) if pdfa_requested?
+
         structure = StructureTracker.new(enabled: @tagged)
+        position_tracker = PositionTracker.new
         layer_filter = LayerFilter.from_designmap(@package.designmap)
         font_ref_resolver = FontReferenceResolver.build(@package)
-        base_dir = File.dirname(@package.path)
-        font_resource = register_font(writer)
-        font_metrics = build_font_metrics(writer, font_resource)
-        page_index = -1
+        font_setup = FontSetup.new(package: @package,
+                                   font_search_paths: @font_search_paths)
+        font_resource = font_setup.register(writer)
+        font_metrics = font_setup.metrics_for(writer, font_resource)
 
+        page_index = -1
         @package.spreads.each do |spread|
-          page_index = render_spread_pages(writer, spread, base_dir,
-                                           layer_filter, font_ref_resolver,
-                                           font_resource, font_metrics,
-                                           structure, page_index)
+          page_index = render_spread(writer, spread, layer_filter,
+                                     font_ref_resolver, font_resource,
+                                     font_metrics, structure,
+                                     position_tracker, page_index)
         end
 
         structure.flush(writer)
@@ -53,7 +60,8 @@ module Idml
 
       private
 
-      def embed_pdfa_output_intent(writer)
+      def apply_compliance(writer, metadata)
+        PdfaPacket.attach(writer.document, metadata)
         bytes = IccProfile.srgb_bytes
         return unless bytes
 
@@ -67,24 +75,26 @@ module Idml
         nil
       end
 
+      def pdfa_requested?
+        @compliance&.to_s&.start_with?("pdfa")
+      end
+
       def emit_bookmarks(writer)
         BookmarkResolver.new(@package).each do |title, page_index|
           writer.add_bookmark(title, page_index)
         end
       end
 
-      def pdfa_requested?
-        @compliance&.to_s&.start_with?("pdfa")
-      end
-
-      def render_spread_pages(writer, spread, base_dir, layer_filter,
-                              font_ref_resolver, font_resource, font_metrics,
-                              structure, page_offset)
+      def render_spread(writer, spread, layer_filter, font_ref_resolver,
+                        font_resource, font_metrics, structure,
+                        position_tracker, page_offset)
         pages = spread.spread.flat_map(&:page)
-        image_refs = ImageCollector.new(writer: writer, base_dir: base_dir,
+        image_refs = ImageCollector.new(writer: writer,
+                                        base_dir: File.dirname(@package.path),
                                         page_height: DEFAULT_HEIGHT).collect(spread)
         renderer = build_renderer(layer_filter, font_ref_resolver,
-                                  font_resource, font_metrics, structure: structure)
+                                  font_resource, font_metrics, structure,
+                                  position_tracker)
         current = page_offset
 
         pages.each do |page|
@@ -95,22 +105,25 @@ module Idml
                                           page_height: dims[:height],
                                           image_refs: image_refs,
                                           page_index: current)
-          emit_hyperlinks(writer, spread, current, layer_filter)
+          emit_hyperlinks(writer, spread, current, layer_filter,
+                          position_tracker)
         end
         current
       end
 
-      def emit_hyperlinks(writer, spread, page_index, layer_filter)
+      def emit_hyperlinks(writer, spread, page_index, layer_filter,
+                          position_tracker)
         HyperlinkEmitter.new(writer: writer, package: @package,
                              page_height: DEFAULT_HEIGHT,
-                             layer_filter: layer_filter)
+                             layer_filter: layer_filter,
+                             position_tracker: position_tracker)
           .emit_for(spread, page_index)
       rescue StandardError
         nil
       end
 
       def build_renderer(layer_filter, font_ref_resolver, font_resource,
-                         font_metrics, structure:)
+                         font_metrics, structure, position_tracker)
         SpreadRenderer.new(
           font_metrics: font_metrics,
           font_ps_name: font_resource,
@@ -118,6 +131,7 @@ module Idml
           layer_filter: layer_filter,
           font_ref_resolver: font_ref_resolver,
           structure: structure,
+          position_tracker: position_tracker,
         )
       end
 
@@ -125,50 +139,6 @@ module Idml
         { width: page.width || DEFAULT_WIDTH,
           height: page.height || DEFAULT_HEIGHT }
       end
-
-      def build_font_metrics(writer, font_resource)
-        return nil if font_resource == Render::DEFAULT_FONT
-
-        TextEngine::PdfrbFontMetrics.new(writer.document.fonts, font_resource)
-      rescue StandardError
-        nil
-      end
-
-      def register_font(writer)
-        path = resolve_document_font_path
-        return Render::DEFAULT_FONT unless path
-
-        writer.register_font(path)
-      rescue StandardError
-        Render::DEFAULT_FONT
-      end
-
-      def font_resolver
-        @font_resolver ||= Pdfrb::FontResolver.new(
-          search_paths: @font_search_paths || Pdfrb::FontResolver::DEFAULT_SEARCH_PATHS,
-        )
-      end
-
-      def resolve_document_font_path
-        return nil unless @package&.fonts
-
-        @package.fonts.font_family.each do |family|
-          path = find_font_file(family)
-          return path if path
-        end
-        nil
-      end
-
-      def find_font_file(family)
-        family.font.each do |font|
-          next unless font.post_script_name
-          next if font.status == "Missing"
-
-          path = font_resolver.find_by_ps_name(font.post_script_name)
-          return path if path
-        end
-        nil
-      end
     end
   end
 end

data/lib/idml/render/position_tracker.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Accumulates positioned text ranges during TextFrame rendering.
+    # Used by `HyperlinkEmitter` to compute precise per-source link
+    # rects when text contains IDML hyperlinks.
+    #
+    # Lifecycle:
+    #   1. Pipeline constructs one tracker per render.
+    #   2. RenderContext carries it to renderers.
+    #   3. TextFrameRenderer records each line's range after layout.
+    #   4. HyperlinkEmitter queries for ranges overlapping each
+    #      hyperlink source's character range.
+    #
+    # `PositionedRange` is a plain Struct so the data is trivially
+    # shareable without coupling to any renderer implementation.
+    class PositionTracker
+      PositionedRange = Struct.new(
+        :start_char, :end_char, :x, :y, :width, :height,
+        keyword_init: true
+      )
+
+      def initialize
+        @ranges_by_frame = {}
+      end
+
+      # Records a positioned range for a frame. `frame_self` is the
+      # Self attribute of the TextFrame so multiple frames on the
+      # same spread don't collide.
+      def add(frame_self, start_char:, end_char:, x:, y:, width:, height:)
+        bucket = @ranges_by_frame[frame_self] ||= []
+        bucket << PositionedRange.new(
+          start_char: start_char,
+          end_char: end_char,
+          x: x,
+          y: y,
+          width: width,
+          height: height,
+        )
+      end
+
+      # Returns the list of positioned ranges for a frame, or [].
+      def ranges_for(frame_self)
+        @ranges_by_frame[frame_self] || []
+      end
+
+      # Returns the bounding rect `[x1, y1, x2, y2]` covering all
+      # ranges whose `[start_char, end_char]` intersects
+      # `[from, to]`. Returns nil when no range overlaps.
+      def rect_for_range(frame_self, from:, to:)
+        matching = ranges_for(frame_self).select do |range|
+          range.start_char < to && range.end_char > from
+        end
+        return nil if matching.empty?
+
+        xs = matching.flat_map { |r| [r.x, r.x + r.width] }
+        ys = matching.flat_map { |r| [r.y, r.y + r.height] }
+        [xs.min, ys.min, xs.max, ys.max]
+      end
+
+      # Test helper: clears all recorded ranges.
+      def clear
+        @ranges_by_frame.clear
+      end
+    end
+  end
+end

data/lib/idml/render/render_context.rb

@@ -18,6 +18,7 @@ module Idml
       :layer_filter,
       :structure,
       :page_index,
+      :position_tracker,
       keyword_init: true,
     )
   end

data/lib/idml/render/renderers/group_renderer.rb

@@ -23,6 +23,7 @@ module Idml
                 layer_filter: context.layer_filter,
                 structure: context.structure,
                 page_index: context.page_index,
+                position_tracker: context.position_tracker,
               )
               PageItemRenderer.render(canvas, child_context)
             end

data/lib/idml/render/renderers/text_frame_renderer.rb

@@ -48,11 +48,10 @@ module Idml
         private_class_method :frame_box
 
         def self.engine_render(canvas, runs, context, box, font)
-          baseline_y = box[:y] + box[:height] - runs.first.point_size
-
+          char_cursor = 0
           runs.each do |run|
-            baseline_y = render_run_lines(
-              canvas, run, context, box, font, baseline_y
+            char_cursor = render_run_lines(
+              canvas, run, context, box, font, char_cursor
             )
           end
         end
@@ -63,7 +62,10 @@ module Idml
         # alignment via `Justifier` so each line is offset within
         # the frame box per IDML `Justification`. Lines that fall
         # below the frame's bottom edge are clipped.
-        def self.render_run_lines(canvas, run, context, box, font, baseline_y)
+        #
+        # Tracks absolute character position so HyperlinkEmitter can
+        # compute precise link rects per source range.
+        def self.render_run_lines(canvas, run, context, box, font, char_cursor)
           size = run.point_size
           glyphs = TextEngine::Shaper.shape(
             text: run.text, font: font, size: size,
@@ -73,6 +75,7 @@ module Idml
           )
           alignment = run.alignment || :left
           start_y = box[:y] + box[:height] - size
+          cursor = char_cursor
 
           lines.each_with_index do |line, idx|
             line_y = start_y - (idx * size * LEADING_FACTOR)
@@ -81,15 +84,36 @@ module Idml
             TextEngine::Justifier.justify(line: line,
                                           frame_width: box[:width],
                                           alignment: alignment)
+            line_x = box[:x] + line.x_offset
+            line_width = line.width
             canvas.text(line_text(line),
-                        at: [box[:x] + line.x_offset, line_y],
+                        at: [line_x, line_y],
                         font: context.font_ps_name,
                         size: size)
+            record_position(context, line, line_x, line_y, line_width, size,
+                            cursor)
+            cursor += line.glyphs.length
           end
-          baseline_y
+          cursor
         end
         private_class_method :render_run_lines
 
+        def self.record_position(context, line, x, y, width, height, cursor)
+          tracker = context.position_tracker
+          return unless tracker
+          return unless context.item&.self_attr
+
+          glyph_count = line.glyphs.length
+          tracker.add(context.item.self_attr,
+                      start_char: cursor,
+                      end_char: cursor + glyph_count,
+                      x: x,
+                      y: y,
+                      width: width,
+                      height: height)
+        end
+        private_class_method :record_position
+
         def self.line_text(line)
           line.glyphs.map { |g| [g.codepoint].pack("U") }.join
         end

data/lib/idml/render/spread_renderer.rb

@@ -6,13 +6,15 @@ module Idml
     class SpreadRenderer
       def initialize(font_metrics: nil, font_ps_name: Render::DEFAULT_FONT,
                      package: nil, layer_filter: LayerFilter::EXCLUDE_NONE,
-                     font_ref_resolver: nil, structure: nil)
+                     font_ref_resolver: nil, structure: nil,
+                     position_tracker: nil)
         @font_metrics = font_metrics
         @font_ps_name = font_ps_name
         @package = package
         @layer_filter = layer_filter
         @font_ref_resolver = font_ref_resolver
         @structure = structure
+        @position_tracker = position_tracker
       end
 
       def render(canvas, spread, page_width:, page_height:, image_refs: [],
@@ -28,6 +30,7 @@ module Idml
           layer_filter: @layer_filter,
           structure: @structure,
           page_index: page_index,
+          position_tracker: @position_tracker,
         }
 
         canvas.save_graphics_state do

data/lib/idml/render.rb

@@ -24,6 +24,8 @@ module Idml
     autoload :HyperlinkResolver,   "#{__dir__}/render/hyperlink_resolver"
     autoload :HyperlinkEmitter,    "#{__dir__}/render/hyperlink_emitter"
     autoload :MetadataBuilder,     "#{__dir__}/render/metadata_builder"
+    autoload :FontSetup,           "#{__dir__}/render/font_setup"
+    autoload :PositionTracker,     "#{__dir__}/render/position_tracker"
     autoload :StoryThreader,       "#{__dir__}/render/story_threader"
     autoload :PdfrbWriter, "#{__dir__}/render/pdfrb_writer"
     autoload :SpreadRenderer,      "#{__dir__}/render/spread_renderer"

data/lib/idml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Idml
-  VERSION = "0.4.1"
+  VERSION = "0.4.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - Ribose
@@ -210,6 +210,9 @@ files:
 - TODO.pdf/81-pdfa-icc-output-intent.md
 - TODO.pdf/82-table-cell-text.md
 - TODO.pdf/83-pipeline-decomposition.md
+- TODO.pdf/84-schema-faithful-table.md
+- TODO.pdf/85-per-text-range-hyperlinks.md
+- TODO.pdf/86-caching-performance.md
 - TODO.pdf/README.md
 - exe/idml
 - idml.gemspec
@@ -385,6 +388,7 @@ files:
 - lib/idml/render/color_helper.rb
 - lib/idml/render/color_resolver.rb
 - lib/idml/render/font_reference_resolver.rb
+- lib/idml/render/font_setup.rb
 - lib/idml/render/gradient_resolver.rb
 - lib/idml/render/hyperlink_emitter.rb
 - lib/idml/render/hyperlink_resolver.rb
@@ -398,6 +402,7 @@ files:
 - lib/idml/render/pdfrb_writer.rb
 - lib/idml/render/pipeline.rb
 - lib/idml/render/placement.rb
+- lib/idml/render/position_tracker.rb
 - lib/idml/render/render_context.rb
 - lib/idml/render/renderers.rb
 - lib/idml/render/renderers/graphic_line_renderer.rb