idml 0.4.3 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55a1e03f5e9f1f1e0f4019f499ce674f49caeca3ee18a04f98b01dcffb41b6c8
-  data.tar.gz: 50674b26f5ee95a95f3275c9ab10d64db7311d8f99b5ee96b38585d24bd7f45c
+  metadata.gz: e54e07729eb2840c505e903d5aeaf6a69372776cc4b4f1e552d523362b0e861c
+  data.tar.gz: d424a2a1092c636c7d757a390350ea5cecdb4d36cc458aaea4ee2497aec9e418
 SHA512:
-  metadata.gz: 7c5d7af6ccd5e60b31fb2ef62c618b336bc9f54517e84377c4cb5566e4da0ae6b0f9a1beee528ac55e5eba6e5f8e59ee3c3d9f9ca91007b7833e6a360dd1f4d0
-  data.tar.gz: 0a2edf4c947cc93e509434c65fe5520ad3b0a88d10ff4ed317c56c7f000ac0a650e85a7cfdb0fa00d465a569f8a30122fbced8bd1cd10e568536ca9f2d4ddeb8
+  metadata.gz: 2b9b79e3aebb407be02d20a75b451bcdcb8ed8eb94813470b7f0dd31d3443850e194d3deb813b317ef1536706dbcbca9473d6f8666f12cbefcb83e2247d25c33
+  data.tar.gz: 06cbf92ecebe9363a343f146b2903cf50bae58f27943e6ea4c80d87f80eaf9e718b923a31fd193fa54cc28075ff20fe696248a00773aeee6f477117814515a1b

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.4.3)
+    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.3)
+  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,10 +1,14 @@
 # TODO PDF 85: Per-TextRange hyperlink precision
 
-## Status: PARTIAL — PositionTracker wired; per-source ranges need fixture
+## Status: DONE (architecture); fixture validation deferred
 
 ## What was implemented
 
-`Render::PositionTracker` is wired through the render path:
+`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,
@@ -16,31 +20,29 @@
    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.
+
+### 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
 
@@ -48,15 +50,21 @@ to: source_end)` for per-source precision.
 - `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.
+- `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
 
 - [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).
+- [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/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/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/render/hyperlink_emitter.rb

@@ -53,10 +53,19 @@ module Idml
 
       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)
+        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,
@@ -64,6 +73,39 @@ module Idml
         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

data/lib/idml/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.4
 platform: ruby
 authors:
 - Ribose