idml 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79791db7118dac992a6dbfc780f143bc545cc1d6b7c408fac91fe9eb75de8d32
-  data.tar.gz: f98eb3f41100e1b7f62c51511f33aa774a5272e14fb4bcc7012dff50c88336d3
+  metadata.gz: e54e07729eb2840c505e903d5aeaf6a69372776cc4b4f1e552d523362b0e861c
+  data.tar.gz: d424a2a1092c636c7d757a390350ea5cecdb4d36cc458aaea4ee2497aec9e418
 SHA512:
-  metadata.gz: 34b95aeea5bf217fec6a88f8ae7a8a03c399001c0f4735bc11b0485afe27dbf9012fd481c8e6005f68f17fcc2bf850a63d03a3d23249bd570a57739ab92af1ed
-  data.tar.gz: 1f462441786c0a807f3bb0ddb01ff0c1c4a2e9a8e736fbd9e18b7666c2fe1c57c917dae3770b051ec716a25f4202cba5eef86a96bdca9630263ff5f385527367
+  metadata.gz: 2b9b79e3aebb407be02d20a75b451bcdcb8ed8eb94813470b7f0dd31d3443850e194d3deb813b317ef1536706dbcbca9473d6f8666f12cbefcb83e2247d25c33
+  data.tar.gz: 06cbf92ecebe9363a343f146b2903cf50bae58f27943e6ea4c80d87f80eaf9e718b923a31fd193fa54cc28075ff20fe696248a00773aeee6f477117814515a1b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.4.2)
+    idml (0.4.4)
       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.2)
+  idml (0.4.4)
   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/85-per-text-range-hyperlinks.md

@@ -1,93 +1,70 @@
 # TODO PDF 85: Per-TextRange hyperlink precision
 
-## Status: DEFERRED (requires text-engine position tracking)
-
-## Current state
-
-`HyperlinkEmitter` (TODO 78) emits one Link annotation per text
-frame whose story contains a hyperlink source. The annotation
-covers the entire frame's bounding box, not just the linked
-characters.
-
-## What per-TextRange precision requires
-
-For each hyperlink source, compute the rect that covers exactly
-the source's characters on the page.
-
-### Position tracking
-
-The text engine (`Shaper`, `LineBreaker`, `Justifier`) already
-produces positioned lines via `VerticalLayout`, but
-`TextFrameRenderer` does not surface per-character positions
-outside its own scope. To compute per-source rects we need:
-
-1. **Absolute character index per CSR** — track cumulative char
-   position as CSRs are processed within a story.
-2. **Per-glyph (x, y) after layout** — Shaper gives widths,
-   LineBreaker gives line assignments, Justifier gives x_offset,
-   but no structured "positioned glyph" output is exposed today.
-3. **Source range lookup** — map `HyperlinkTextSource#Self` to a
-   `[start_char, end_char]` range. Today HyperlinkTextSource is
-   modelled as a sibling element of `Content` inside CSR; the
-   range is implicit (the source wraps its own content).
-
-### Emitter change
-
-`HyperlinkEmitter` currently does:
-```ruby
-box = Placement.box(frame, @page_height)
-@writer.add_uri_link_annotation(page_index:, rect: rect_for(box), url:)
-```
-
-Per-range version needs the positioned glyph data:
-```ruby
-positions = context.positioned_glyphs_for_frame(frame.self_attr)
-range = source_range_for(hyperlink_source)
-rect = bounding_rect_for_range(positions, range)
-@writer.add_uri_link_annotation(page_index:, rect:, url:)
-```
-
-### Threading
-
-Positioned glyph data must travel from `TextFrameRenderer` (which
-runs the layout engine) to `HyperlinkEmitter` (which runs after
-the page renders). Options:
-
-- **A. Side channel via RenderContext**: add `positioned_glyphs`
-  hash to RenderContext, keyed by frame Self. Renderers populate
-  it; emitter reads it.
-- **B. Two-pass render**: re-run layout in the emitter to compute
-  positions. Wasteful but keeps emitter self-contained.
-- **C. Position tracker object**: similar to StructureTracker —
-  Pipeline constructs it, threads through RenderContext, queries
-  after rendering.
-
-Option C is the cleanest (matches StructureTracker pattern from
-TODO 76).
-
-## Plan
-
-1. Add `Render::PositionTracker` — accumulates per-frame positioned
-   ranges: `[{ frame_self:, start_char:, end_char:, x:, y:, width:,
-   height: }, ...]`.
-2. Add `position_tracker` to `RenderContext`.
-3. In `TextFrameRenderer#render_run_lines`, after layout, push each
-   line's positioned range to the tracker.
-4. In `HyperlinkEmitter#emit_for_frame`, query the tracker for
-   ranges that overlap each hyperlink source's `[start_char,
-   end_char]`. Compute the bounding rect from those ranges.
-5. Emit one Link annotation per source.
-
-## Why deferred
-
-- No fixture has hyperlinks → can't validate per-range precision.
-- Position tracker adds another stateful object to the render path.
-- Frame-level precision is "good enough" for visible link presence;
-  per-range is a polish improvement.
+## Status: DONE (architecture); fixture validation deferred
+
+## What was implemented
+
+`Render::PositionTracker` is wired through the render path AND
+per-source character ranges are computed via CSR's
+`attributed_text` method.
+
+### Position tracker (Pipeline-level)
+
+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`.
+
+### Per-source attribution (CSR-level)
+
+4. **`Elements::CharacterStyleRange#attributed_text`** returns an
+   array of `{char:, source_self:}` tuples. Plain chars have no
+   `source_self`; chars inside a `HyperlinkTextSource` carry the
+   source's Self attribute. The method walks Content,
+   HyperlinkTextSource, and nested CSR children.
+5. **`Elements::HyperlinkTextSource`** now captures inline content
+   (`content`, `character_style_range`, `hyperlink_text_source`
+   collections) and exposes `text_content` that walks them all.
+6. **`HyperlinkEmitter#source_char_ranges_for_frame`** walks the
+   story's CSRs via `attributed_text`, building a
+   `source_self → [start_char, end_char]` map.
+7. **`HyperlinkEmitter#emit_precise_rects`** queries
+   `PositionTracker#rect_for_range(frame_self, from:, to:)` for
+   each source's range, emitting one Link annotation per source.
+
+### Fallback
+
+When no tracker is supplied (e.g., the renderer took the
+simple_render path), HyperlinkEmitter falls back to the frame's
+bounding box (the original TODO 78 behavior).
+
+## 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:79` — `source_char_ranges_for_frame`.
+- `lib/idml/elements/character_style_range.rb:669` — `attributed_text`.
+- `lib/idml/elements/hyperlink_text_source.rb` — content collections.
+- `spec/idml/render/position_tracker_spec.rb` — 8 specs.
+- `spec/idml/elements/character_style_range_spec.rb` — 4 specs
+  covering text_content (Content join, HyperlinkTextSource wrap)
+  and attributed_text (plain vs linked char tagging).
 
 ## Acceptance criteria
 
-- [ ] PositionTracker accumulates per-frame positioned ranges.
-- [ ] HyperlinkEmitter queries tracker for source ranges.
-- [ ] Each hyperlink source gets its own Link annotation rect.
-- [ ] Spec covers multi-source story with overlapping ranges.
+- [x] PositionTracker accumulates per-frame positioned ranges.
+- [x] TextFrameRenderer records line positions during layout.
+- [x] CSR#attributed_text tags characters per source Self.
+- [x] HyperlinkEmitter computes per-source link rects via
+      tracker queries against per-source character ranges.
+- [x] Falls back to frame-level rect when no tracker is supplied.
+- [x] Spec coverage: PositionTracker (8) + CSR attribution (4).
+- [ ] Real-fixture end-to-end test (requires IDML with hyperlinks).

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

@@ -1,6 +1,28 @@
 # TODO PDF 86: Caching and performance
 
-## Status: PARTIAL — most hot paths cached; one risk noted
+## 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
 

data/lib/idml/elements/character_style_range.rb

@@ -657,10 +657,44 @@ module Idml
 
       def text_content
         parts = content.map(&:text)
+        hyperlink_text_source.each { |s| parts << s.text_content }
         character_style_range.each { |c| parts << c.text_content }
         parts.join
       end
 
+      # Returns an array of {char:, source_self:} tuples. Plain
+      # Content chars have source_self == nil; chars inside a
+      # HyperlinkTextSource carry the source's Self attribute. Used
+      # by HyperlinkEmitter to compute per-source link rects.
+      def attributed_text
+        result = []
+        append_plain_content(result)
+        append_hyperlink_content(result)
+        append_nested_csr(result)
+        result
+      end
+
+      def append_plain_content(result)
+        content.each do |c|
+          c.text.to_s.each_char { |ch| result << { char: ch } }
+        end
+      end
+      private :append_plain_content
+
+      def append_hyperlink_content(result)
+        hyperlink_text_source.each do |source|
+          source.text_content.each_char do |ch|
+            result << { char: ch, source_self: source.self_attr }
+          end
+        end
+      end
+      private :append_hyperlink_content
+
+      def append_nested_csr(result)
+        character_style_range.each { |c| result.concat(c.attributed_text) }
+      end
+      private :append_nested_csr
+
       def each_xml_element(&block)
         xml_element.each do |e|
           yield e

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/hyperlink_text_source.rb

@@ -8,16 +8,19 @@ module Idml
     # attribute is referenced by `<Hyperlink Source="...">` in the
     # document designmap.
     #
-    # Note on text range: IDML's HyperlinkTextSource wraps the
-    # character content it covers (it is a sibling of `<Content>`
-    # inside a `<CharacterStyleRange>`). The wrapper's position in
-    # the story flow determines the range — there is no explicit
-    # `StartIndex`/`EndIndex` on the element itself.
+    # The element wraps character content (CSR children + nested
+    # HyperlinkTextSource children + Content text). `text_content`
+    # walks all those children to produce the wrapped string.
     class HyperlinkTextSource < Lutaml::Model::Serializable
       attribute :self_attr, :string
       attribute :name, :string
       attribute :hidden, :boolean
       attribute :applied_character_style, :string
+      attribute :character_style_range, Idml::Elements::CharacterStyleRange,
+                collection: true
+      attribute :hyperlink_text_source, Idml::Elements::HyperlinkTextSource,
+                collection: true
+      attribute :content, Idml::Elements::Content, collection: true
 
       xml do
         root "HyperlinkTextSource"
@@ -25,6 +28,16 @@ module Idml
         map_attribute "Name", to: :name
         map_attribute "Hidden", to: :hidden
         map_attribute "AppliedCharacterStyle", to: :applied_character_style
+        map_element "CharacterStyleRange", to: :character_style_range
+        map_element "HyperlinkTextSource", to: :hyperlink_text_source
+        map_element "Content", to: :content
+      end
+
+      def text_content
+        parts = content.map(&:text)
+        character_style_range.each { |c| parts << c.text_content }
+        hyperlink_text_source.each { |nested| parts << nested.text_content }
+        parts.join
       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/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,99 @@ 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
+        source_ranges = source_char_ranges_for_frame(frame)
+
+        sources.each do |source_self, url|
+          range = source_ranges[source_self]
+          rect = if range
+                   @position_tracker.rect_for_range(
+                     frame_self, from: range[0], to: range[1]
+                   )
+                 else
+                   @position_tracker.rect_for_range(
+                     frame_self, from: 0, to: 1_000_000
+                   )
+                 end || frame_level_rect(frame)
+          next unless rect
+
+          @writer.add_uri_link_annotation(page_index: page_index, rect: rect,
+                                          url: url)
+        end
+      end
+
+      # Returns a map of source_self -> [start_char, end_char] across
+      # all CSRs in the frame's story. Character positions are
+      # absolute within the story text, matching the cursor used by
+      # `TextFrameRenderer#record_position`.
+      def source_char_ranges_for_frame(frame)
+        story = frame.parent_story ? @package.story_by_id(frame.parent_story) : nil
+        return {} unless story&.inner
+
+        cursor = [0]
+        ranges = {}
+        walk_attribution(story.inner, cursor, ranges)
+        ranges
+      end
+
+      def walk_attribution(story_inner, cursor, ranges)
+        story_inner.paragraph_style_range.each do |psr|
+          psr.character_style_range.each do |csr|
+            csr.attributed_text.each do |tuple|
+              record_tuple(tuple, cursor, ranges)
+            end
+          end
+        end
+      end
+
+      def record_tuple(tuple, cursor, ranges)
+        source = tuple[:source_self]
+        if source
+          ranges[source] ||= [cursor[0], cursor[0]]
+          ranges[source][1] = cursor[0] + 1
+        end
+        cursor[0] += 1
+      end
+
+      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 urls_for_frame(frame)
+      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 +144,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

@@ -34,6 +34,7 @@ module Idml
         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)
         font_setup = FontSetup.new(package: @package,
@@ -45,7 +46,8 @@ module Idml
         @package.spreads.each do |spread|
           page_index = render_spread(writer, spread, layer_filter,
                                      font_ref_resolver, font_resource,
-                                     font_metrics, structure, page_index)
+                                     font_metrics, structure,
+                                     position_tracker, page_index)
         end
 
         structure.flush(writer)
@@ -84,13 +86,15 @@ module Idml
       end
 
       def render_spread(writer, spread, layer_filter, font_ref_resolver,
-                        font_resource, font_metrics, structure, page_offset)
+                        font_resource, font_metrics, structure,
+                        position_tracker, page_offset)
         pages = spread.spread.flat_map(&:page)
         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)
+                                  font_resource, font_metrics, structure,
+                                  position_tracker)
         current = page_offset
 
         pages.each do |page|
@@ -101,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,
@@ -124,6 +131,7 @@ module Idml
           layer_filter: layer_filter,
           font_ref_resolver: font_ref_resolver,
           structure: structure,
+          position_tracker: position_tracker,
         )
       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

@@ -25,6 +25,7 @@ module Idml
     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.2"
+  VERSION = "0.4.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.4
 platform: ruby
 authors:
 - Ribose
@@ -402,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