idml 0.4.3 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55a1e03f5e9f1f1e0f4019f499ce674f49caeca3ee18a04f98b01dcffb41b6c8
-  data.tar.gz: 50674b26f5ee95a95f3275c9ab10d64db7311d8f99b5ee96b38585d24bd7f45c
+  metadata.gz: 73b6eace594144002b5d513bb823512ff44a018e90dffb83188167674e839975
+  data.tar.gz: bcdebe8d9ba4c525d0b9f0bb0c47e10dcb08edb15d22c145031bb0cdbb796b7d
 SHA512:
-  metadata.gz: 7c5d7af6ccd5e60b31fb2ef62c618b336bc9f54517e84377c4cb5566e4da0ae6b0f9a1beee528ac55e5eba6e5f8e59ee3c3d9f9ca91007b7833e6a360dd1f4d0
-  data.tar.gz: 0a2edf4c947cc93e509434c65fe5520ad3b0a88d10ff4ed317c56c7f000ac0a650e85a7cfdb0fa00d465a569f8a30122fbced8bd1cd10e568536ca9f2d4ddeb8
+  metadata.gz: d9637751e91a71db94cc5ab3ede0843eecde0aa35323a128309d21a4e4c3c0c7c88f08e887d7b9d67a081454747e14d85954b43b9e0e3429325f9e39c1bf0b17
+  data.tar.gz: d92faf74e08e0f82c9c4265ea0f1532a7d73c25b4195c992a984eedce7625f7cac1d51c367bb35fbcfa7563c77d701e0f7134438aea5bd3d0d2a359a47d1e639

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.4.3)
+    idml (0.4.5)
       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.5)
   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/84-schema-faithful-table.md

@@ -1,6 +1,35 @@
 # TODO PDF 84: Schema-faithful Table/Cell/Row structure
 
-## Status: DEFERRED (architectural correction; no fixtures to validate)
+## Status: PARTIAL — Cell and Row elements added; full restructure deferred
+
+## What was added
+
+Schema-faithful element classes alongside the legacy non-standard
+ones, so existing fixtures continue to work:
+
+- **`Elements::Cell`** — matches `Cell_Object` RNC. Captures Self,
+  Name, RowSpan, ColumnSpan, insets, FillColor, FillTint,
+  VerticalJustification, and inline `CharacterStyleRange` children.
+  `text_content` walks inline CSRs. `col_row` decodes the
+  `"col_row"` Name format.
+- **`Elements::Row`** — matches `Row_Object` RNC. Captures Self,
+  Name, insets, FillColor, height constraints.
+- **`Elements::Table`** now declares `cell` and `row` collections
+  alongside the legacy `table_row`. Both parse correctly from XML.
+
+## What remains deferred
+
+The full schema-faithful refactor — moving Table out of SpreadObject
+(per RNC, Tables live in Stories, not Spreads) and removing the
+legacy `Elements::TableRow`/`TableCell` classes — requires a real
+IDML fixture with tables to validate.
+
+Until then:
+- The legacy `Table > TableRow > TableCell` path handles the
+  existing synthetic test fixture.
+- The schema-faithful `Table > {Cell, Row}` path is available for
+  future fixtures.
+- `TableRenderer` still uses the legacy path.
 
 ## Current state vs schema
 

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/TODO.pdf/87-final-state-summary.md

@@ -0,0 +1,97 @@
+# TODO PDF 87: IDML → PDF render — final state summary
+
+## Status: COMPLETE (architecture); fixture-validation work bounded
+
+## What was built
+
+A complete IDML → PDF renderer in pure Ruby, using:
+- `lutaml-model` for XML (no Nokogiri/REXML).
+- `pdfrb` for PDF assembly (no hand-rolled PDF operators).
+- `Pdfrb::Font::TrueType` for TTF measurement (no Fontisan).
+
+## Feature coverage
+
+| Feature | Status |
+|---------|--------|
+| Text frames with paragraph alignment | DONE (TODO 80) |
+| Word-wrap via Shaper + LineBreaker + Justifier | DONE |
+| Real TTF font measurement via pdfrb | DONE (TODO 63) |
+| Font subsetting | DONE (TODO 52) |
+| Rectangle/Polygon/GraphicLine shapes | DONE |
+| Linear and radial gradient shadings | DONE (TODOs 49, 66, 68) |
+| Transparency and blend modes | DONE (TODO 69) |
+| Stroke styling (cap, join, miter, dash) | DONE (TODO 70/72) |
+| Image embedding with clipping | DONE |
+| XMP metadata extraction | DONE (TODO 75) |
+| Tagged PDF structure tree | DONE (TODO 76) |
+| PDF/A-2a XMP packet | DONE (TODO 77) |
+| sRGB ICC output intent | DONE (TODO 81) |
+| Bookmarks / outline | DONE (TODO 79) |
+| Hyperlinks (per-source rects) | DONE (TODOs 78, 85) |
+| Basic table cell text | DONE (TODO 82) |
+| Layer filtering | DONE |
+| Master spread rendering | DONE |
+| Pipeline decomposition (MetadataBuilder + FontSetup) | DONE (TODO 83) |
+| geometric_bounds memoisation | DONE (TODO 86) |
+| PositionTracker for per-source hyperlink rects | DONE (TODO 85) |
+
+## Architecture
+
+Pipeline (orchestrator) → Render helpers (one per concern):
+- `Placement` — item to PDF-rect bridge.
+- `Blending` — transparency/blend mode wrapper.
+- `StrokeStyle` — stroke cap/join/miter/dash.
+- `ColorResolver` / `ColorHelper` — IDML color → PDF.
+- `ImageCollector` — image registration + placement.
+- `MetadataBuilder` — Info dict from XMP.
+- `FontSetup` — pdfrb font registration + metrics adapter.
+- `PdfaPacket` / `IccProfile` — PDF/A compliance.
+- `StructureTracker` / `StructureMapper` — tagged PDF.
+- `PositionTracker` — per-line text positions.
+- `BookmarkResolver` — outline entries.
+- `HyperlinkResolver` / `HyperlinkEmitter` — link annotations.
+
+Renderers (OCP registry dispatch via `PageItemRenderer::RENDERER_MAP`):
+- RectangleRenderer, PolygonRenderer, GraphicLineRenderer.
+- TextFrameRenderer, GroupRenderer, TableRenderer.
+
+Text engine (`TextEngine` namespace):
+- Shaper, LineBreaker, Justifier, VerticalLayout, CjkLayout.
+- PdfrbFontMetrics (adapter from Fontisan legacy to pdfrb).
+
+## Quality
+
+- 2614 examples, 0 failures, 8 pending.
+- 98.12% line coverage.
+- 211 lib files, 52 spec files.
+- 0 anti-pattern violations (`.send`, `instance_variable_*`, `respond_to?`,
+  `require_relative`, internal `require`, `double()`, Nokogiri, REXML).
+- 0 rubocop offenses.
+
+## Deferred (TODOs 84 + 85 fixture validation)
+
+Two TODOs are documented as architecture-complete but fixture-deferred:
+
+- **TODO 84** — Schema-faithful Table/Cell/Row structure. The current
+  `Elements::Table`/`TableRow`/`TableCell` classes don't match the RNC
+  schema (real IDML has `<Cell>` and `<Row>` as siblings under `<Table>`,
+  and Tables live in Stories not Spreads). The architectural correction
+  requires a real IDML fixture with tables to validate. The current
+  synthetic test continues to pass.
+
+- **TODO 85** — Per-source hyperlink rect precision. The architecture
+  is in place (PositionTracker + CSR#attributed_text +
+  HyperlinkEmitter source-range lookup) but no fixture has hyperlinks
+  to validate end-to-end.
+
+## Path forward for the deferred work
+
+1. Acquire a real IDML fixture (from Adobe InDesign or hand-crafted
+   per the RNC) with tables and hyperlinks.
+2. Add to `spec/fixtures/`.
+3. Implement TODO 84 schema correction; verify with fixture.
+4. Verify TODO 85 emits precise per-source rects against the fixture.
+
+Until then, the gem renders the existing fixtures correctly and
+emits valid PDF/A, tagged PDF, and PDF/UA-adjacent structure for
+the supported feature set.

data/lib/idml/elements/cell.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<Cell>` — a single cell in an IDML Table. Per `Cell_Object`
+    # in `reference-docs/schemas/package/Stories/Story.rnc`.
+    #
+    # Schema note: real IDML has `<Cell>` and `<Row>` as **siblings**
+    # inside `<Table>`, not nested `<TableRow><TableCell>`. This
+    # class is the schema-faithful model. The legacy
+    # `Idml::Elements::TableCell` (which models the non-standard
+    # `<TableCell>` element) is preserved for back-compat with the
+    # existing synthetic test fixture — see TODO 84.
+    #
+    # The cell's `Name` attribute encodes its column/row position
+    # (e.g., `"0_0"` for column 0, row 0). Carries text content via
+    # inline `<CharacterStyleRange>` children.
+    class Cell < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :row_span, :integer
+      attribute :column_span, :integer
+      attribute :top_inset, :float
+      attribute :left_inset, :float
+      attribute :bottom_inset, :float
+      attribute :right_inset, :float
+      attribute :fill_color, :string
+      attribute :fill_tint, :float
+      attribute :overprint_fill, :boolean
+      attribute :clip_content_to_cell, :boolean
+      attribute :vertical_justification, :string
+      attribute :paragraph_spacing_limit, :float
+      attribute :rotation_angle, :float
+      attribute :character_style_range, Idml::Elements::CharacterStyleRange,
+                collection: true
+
+      xml do
+        root "Cell"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "RowSpan", to: :row_span
+        map_attribute "ColumnSpan", to: :column_span
+        map_attribute "TopInset", to: :top_inset
+        map_attribute "LeftInset", to: :left_inset
+        map_attribute "BottomInset", to: :bottom_inset
+        map_attribute "RightInset", to: :right_inset
+        map_attribute "FillColor", to: :fill_color
+        map_attribute "FillTint", to: :fill_tint
+        map_attribute "OverprintFill", to: :overprint_fill
+        map_attribute "ClipContentToCell", to: :clip_content_to_cell
+        map_attribute "VerticalJustification", to: :vertical_justification
+        map_attribute "ParagraphSpacingLimit", to: :paragraph_spacing_limit
+        map_attribute "RotationAngle", to: :rotation_angle
+        map_element "CharacterStyleRange", to: :character_style_range
+      end
+
+      def text_content
+        character_style_range.filter_map(&:text_content).join
+      end
+
+      # Cell name format is "column_row" (e.g., "0_0", "1_2").
+      # Returns [col, row] integers or nil if Name is malformed.
+      def col_row
+        return nil unless name
+
+        parts = name.split("_")
+        return nil unless parts.length == 2
+
+        [parts[0].to_i, parts[1].to_i]
+      end
+    end
+  end
+end

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/elements/row.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<Row>` — a row definition in an IDML Table. Per `Row_Object`
+    # in `reference-docs/schemas/package/Stories/Story.rnc`.
+    #
+    # Schema note: real IDML has `<Cell>` and `<Row>` as siblings
+    # inside `<Table>`. This class is the schema-faithful model.
+    # The legacy `Idml::Elements::TableRow` (which models the
+    # non-standard `<TableRow>` element) is preserved for back-compat
+    # with the existing synthetic test fixture — see TODO 84.
+    #
+    # Rows carry visual properties (fill, insets, minimum height)
+    # but not cell content — cells live as `<Cell>` siblings.
+    class Row < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :top_inset, :float
+      attribute :left_inset, :float
+      attribute :bottom_inset, :float
+      attribute :right_inset, :float
+      attribute :fill_color, :string
+      attribute :fill_tint, :float
+      attribute :overprint_fill, :boolean
+      attribute :single_row_height, :float
+      attribute :minimum_height, :float
+      attribute :maximum_height, :float
+
+      xml do
+        root "Row"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "TopInset", to: :top_inset
+        map_attribute "LeftInset", to: :left_inset
+        map_attribute "BottomInset", to: :bottom_inset
+        map_attribute "RightInset", to: :right_inset
+        map_attribute "FillColor", to: :fill_color
+        map_attribute "FillTint", to: :fill_tint
+        map_attribute "OverprintFill", to: :overprint_fill
+        map_attribute "SingleRowHeight", to: :single_row_height
+        map_attribute "MinimumHeight", to: :minimum_height
+        map_attribute "MaximumHeight", to: :maximum_height
+      end
+    end
+  end
+end

data/lib/idml/elements/table.rb

@@ -16,6 +16,8 @@ module Idml
       attribute :stroke_color, :string
       attribute :stroke_weight, :float
       attribute :table_row, Idml::Elements::TableRow, collection: true
+      attribute :cell, Idml::Elements::Cell, collection: true
+      attribute :row, Idml::Elements::Row, collection: true
       attribute :properties, Idml::Elements::Properties, collection: true
 
       xml do
@@ -29,6 +31,8 @@ module Idml
         map_attribute "StrokeColor", to: :stroke_color
         map_attribute "StrokeWeight", to: :stroke_weight
         map_element "TableRow", to: :table_row
+        map_element "Cell", to: :cell
+        map_element "Row", to: :row
         map_element "Properties", to: :properties
       end
 

data/lib/idml/elements.rb

@@ -16,6 +16,7 @@ module Idml
     autoload :BlendingSetting, "idml/elements/blending_setting"
     autoload :ButtonPreference, "idml/elements/pref_button_preference"
     autoload :Bookmark, "idml/elements/bookmark"
+    autoload :Cell, "idml/elements/cell"
     autoload :CellStyle, "idml/elements/cell_style"
     autoload :CellStyleGroup, "idml/elements/cell_style_group"
     autoload :ChapterNumberPreference,
@@ -118,6 +119,7 @@ module Idml
     autoload :Properties, "idml/elements/properties"
     autoload :GeometryPathType, "idml/elements/geometry_path_type"
     autoload :Rectangle, "idml/elements/rectangle"
+    autoload :Row, "idml/elements/row"
     autoload :RootCellStyleGroup, "idml/elements/root_cell_style_group"
     autoload :RootCharacterStyleGroup,
              "idml/elements/root_character_style_group"

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.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.5
 platform: ruby
 authors:
 - Ribose
@@ -213,6 +213,7 @@ files:
 - TODO.pdf/84-schema-faithful-table.md
 - TODO.pdf/85-per-text-range-hyperlinks.md
 - TODO.pdf/86-caching-performance.md
+- TODO.pdf/87-final-state-summary.md
 - TODO.pdf/README.md
 - exe/idml
 - idml.gemspec
@@ -231,6 +232,7 @@ files:
 - lib/idml/elements/bevel_and_emboss_setting.rb
 - lib/idml/elements/blending_setting.rb
 - lib/idml/elements/bookmark.rb
+- lib/idml/elements/cell.rb
 - lib/idml/elements/cell_style.rb
 - lib/idml/elements/cell_style_group.rb
 - lib/idml/elements/character_style.rb
@@ -333,6 +335,7 @@ files:
 - lib/idml/elements/root_object_style_group.rb
 - lib/idml/elements/root_paragraph_style_group.rb
 - lib/idml/elements/root_table_style_group.rb
+- lib/idml/elements/row.rb
 - lib/idml/elements/satin_setting.rb
 - lib/idml/elements/spread_object.rb
 - lib/idml/elements/story_inner.rb