idml 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6cd95e24b0c6610673ad2c95308314a391471fa3912d28a660b8381d46f7b81
-  data.tar.gz: f33fdd9480345a9de8f8fa0e60536b87423978a09732031ab7a4587b99fae59e
+  metadata.gz: 79791db7118dac992a6dbfc780f143bc545cc1d6b7c408fac91fe9eb75de8d32
+  data.tar.gz: f98eb3f41100e1b7f62c51511f33aa774a5272e14fb4bcc7012dff50c88336d3
 SHA512:
-  metadata.gz: 26f80da839299b0fad35c4380511bca3c91d61aabb29c8699f82a50ee7f7a02d5a9ae314643d596a5e0847f91dcbd7782da2bf73892004995578f8d129c52521
-  data.tar.gz: d416cb234f968d95ed9a5f23fecf7ddbe19a171986e58a98f8eee1483a09db4588496a674bfbcfe52be077c2c8c117978b35314ff335e5498e6cc70367dc11de
+  metadata.gz: 34b95aeea5bf217fec6a88f8ae7a8a03c399001c0f4735bc11b0485afe27dbf9012fd481c8e6005f68f17fcc2bf850a63d03a3d23249bd570a57739ab92af1ed
+  data.tar.gz: 1f462441786c0a807f3bb0ddb01ff0c1c4a2e9a8e736fbd9e18b7666c2fe1c57c917dae3770b051ec716a25f4202cba5eef86a96bdca9630263ff5f385527367

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.4.0)
+    idml (0.4.2)
       bigdecimal
       lutaml-model (~> 0.8.18)
       pdfrb
@@ -11,7 +11,7 @@ PATH
 PATH
   remote: /Users/mulgogi/src/claricle/pdfrb
   specs:
-    pdfrb (0.5.0)
+    pdfrb (0.6.0)
       thor
 
 GEM
@@ -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.0)
+  idml (0.4.2)
   json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
@@ -203,7 +203,7 @@ CHECKSUMS
   paint (2.3.0) sha256=327d623e4038619d5bd99ae5db07973859cd78400c7f0329eea283cef8e83be5
   parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
   parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
-  pdfrb (0.5.0)
+  pdfrb (0.6.0)
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a

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

@@ -0,0 +1,54 @@
+# TODO PDF 83: Pipeline decomposition
+
+## Status: DONE
+
+## What was done
+
+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 9 private methods across metadata, font setup, and
+rendering concerns. Each concern is now its own class:
+
+- `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.
+- `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.
+- [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,93 @@
+# 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.
+
+## 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.

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

@@ -0,0 +1,71 @@
+# TODO PDF 86: Caching and performance
+
+## Status: PARTIAL — most hot paths cached; one risk noted
+
+## 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/character_style_range.rb

@@ -296,6 +296,8 @@ module Idml
       attribute :character_style_range, Idml::Elements::CharacterStyleRange,
                 collection: true
       attribute :content, Idml::Elements::Content, collection: true
+      attribute :hyperlink_text_source, Idml::Elements::HyperlinkTextSource,
+                collection: true
       attribute :xml_element, Idml::Elements::XmlElement, collection: true
 
       xml do
@@ -649,6 +651,7 @@ module Idml
         map_attribute "UpperLevel", to: :upper_level
         map_element "CharacterStyleRange", to: :character_style_range
         map_element "Content", to: :content
+        map_element "HyperlinkTextSource", to: :hyperlink_text_source
         map_element "XMLElement", to: :xml_element
       end
 

data/lib/idml/elements/hyperlink_text_source.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<HyperlinkTextSource>` — source anchor of a hyperlink in a
+    # story. Per `HyperlinkTextSource_Object` in
+    # `reference-docs/schemas/package/Stories/Story.rnc`. The `Self`
+    # 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.
+    class HyperlinkTextSource < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :hidden, :boolean
+      attribute :applied_character_style, :string
+
+      xml do
+        root "HyperlinkTextSource"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "Hidden", to: :hidden
+        map_attribute "AppliedCharacterStyle", to: :applied_character_style
+      end
+    end
+  end
+end

data/lib/idml/elements.rb

@@ -64,6 +64,8 @@ module Idml
     autoload :Hyperlink, "idml/elements/hyperlink"
     autoload :HyperlinkPageDestination,
              "idml/elements/hyperlink_page_destination"
+    autoload :HyperlinkTextSource,
+             "idml/elements/hyperlink_text_source"
     autoload :HyperlinkURLDestination,
              "idml/elements/hyperlink_url_destination"
     autoload :Image, "idml/elements/image"

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

@@ -12,11 +12,12 @@ module Idml
     # the source's TextRange. Precise per-range rects require deeper
     # integration with the text engine — see TODO 78.
     class HyperlinkEmitter
-      def initialize(writer:, package:, page_height:)
+      def initialize(writer:, package:, page_height:, layer_filter: nil)
         @writer = writer
         @package = package
         @resolver = HyperlinkResolver.new(package)
         @page_height = page_height
+        @layer_filter = layer_filter
       end
 
       def emit_for(spread, page_index)
@@ -29,7 +30,10 @@ module Idml
 
       def each_text_frame_on(spread)
         spread.each_page_item do |item|
-          yield item if item.is_a?(Idml::Elements::TextFrame)
+          next unless item.is_a?(Idml::Elements::TextFrame)
+          next if @layer_filter && !@layer_filter.visible?(item)
+
+          yield item
         end
       end
 

data/lib/idml/render/metadata_builder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Idml
+  module Render
+    # Builds the PDF Info-dict metadata hash by merging XMP-extracted
+    # values from `META-INF/metadata.xml` over sensible defaults.
+    # Extracted from `Pipeline` for SRP — Pipeline orchestrates
+    # rendering, this module owns metadata assembly.
+    class MetadataBuilder
+      XMP_PATH = "META-INF/metadata.xml"
+
+      def initialize(package)
+        @package = package
+      end
+
+      # Returns a hash with Producer/CreationDate defaults, overridden
+      # by any XMP-supplied fields (Title, Author, Subject, Keywords,
+      # Creator, CreationDate, ModDate). XMP dates are converted from
+      # ISO 8601 to PDF `D:YYYYMMDDHHmmss` format.
+      def build
+        defaults.merge(xmp_fields) { |_key, default, xmp| xmp || default }
+      end
+
+      private
+
+      def defaults
+        {
+          Producer: "idml gem v#{Idml::VERSION}",
+          CreationDate: pdf_date(Time.now.utc),
+        }
+      end
+
+      def xmp_fields
+        return {} unless xmp_packet
+
+        {
+          Title: xmp_packet.title,
+          Author: xmp_packet.author,
+          Subject: xmp_packet.description,
+          Keywords: xmp_packet.keywords,
+          Creator: xmp_packet.creator_tool,
+          CreationDate: pdf_date_string(xmp_packet.create_date),
+          ModDate: pdf_date_string(xmp_packet.modify_date),
+        }.compact
+      end
+
+      def xmp_packet
+        return nil unless @package.has_part?(XMP_PATH)
+
+        @xmp_packet ||= begin
+          xml = @package.read_part(XMP_PATH)
+          Parts::XmpMeta.from_xml(xml).rdf
+        rescue StandardError
+          nil
+        end
+      end
+
+      def pdf_date_string(iso8601)
+        return nil unless iso8601
+
+        pdf_date(Time.iso8601(iso8601))
+      rescue ArgumentError
+        nil
+      end
+
+      def pdf_date(time)
+        time.strftime("D:%Y%m%d%H%M%S+00'00'")
+      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
@@ -21,26 +28,24 @@ module Idml
 
       def call
         writer = PdfrbWriter.new
-        metadata = combined_metadata
+        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)
         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, page_index)
         end
 
         structure.flush(writer)
@@ -53,7 +58,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 +73,24 @@ 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, 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)
         current = page_offset
 
         pages.each do |page|
@@ -95,20 +101,22 @@ module Idml
                                           page_height: dims[:height],
                                           image_refs: image_refs,
                                           page_index: current)
-          emit_hyperlinks(writer, spread, current)
+          emit_hyperlinks(writer, spread, current, layer_filter)
         end
         current
       end
 
-      def emit_hyperlinks(writer, spread, page_index)
+      def emit_hyperlinks(writer, spread, page_index, layer_filter)
         HyperlinkEmitter.new(writer: writer, package: @package,
-                             page_height: DEFAULT_HEIGHT).emit_for(spread, page_index)
+                             page_height: DEFAULT_HEIGHT,
+                             layer_filter: layer_filter)
+          .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)
         SpreadRenderer.new(
           font_metrics: font_metrics,
           font_ps_name: font_resource,
@@ -123,104 +131,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
-
-      def combined_metadata
-        defaults = default_metadata
-        xmp_metadata.each do |key, value|
-          next if value.nil? || value.empty?
-
-          defaults[key] = value
-        end
-        defaults
-      end
-
-      def xmp_metadata
-        return {} unless @package.has_part?(XMP_PATH)
-
-        xml = @package.read_part(XMP_PATH)
-        meta = Parts::XmpMeta.from_xml(xml)
-        rdf = meta.rdf
-        return {} unless rdf
-
-        {
-          Title: rdf.title,
-          Author: rdf.author,
-          Subject: rdf.description,
-          Keywords: rdf.keywords,
-          Creator: rdf.creator_tool,
-          CreationDate: pdf_date_string(rdf.create_date),
-          ModDate: pdf_date_string(rdf.modify_date),
-        }
-      rescue StandardError
-        {}
-      end
-
-      def pdf_date_string(iso8601)
-        return nil unless iso8601
-
-        time = Time.iso8601(iso8601)
-        pdf_date(time)
-      rescue ArgumentError
-        nil
-      end
-
-      def default_metadata
-        {
-          Producer: "idml gem v#{Idml::VERSION}",
-          CreationDate: pdf_date(Time.now.utc),
-        }
-      end
-
-      def pdf_date(time)
-        time.strftime("D:%Y%m%d%H%M%S+00'00'")
-      end
-
-      XMP_PATH = "META-INF/metadata.xml"
-      private_constant :XMP_PATH
     end
   end
 end

data/lib/idml/render.rb

@@ -23,6 +23,8 @@ module Idml
     autoload :BookmarkResolver,    "#{__dir__}/render/bookmark_resolver"
     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 :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.0"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Ribose
@@ -209,6 +209,10 @@ files:
 - TODO.pdf/80-paragraph-alignment.md
 - 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
@@ -255,6 +259,7 @@ files:
 - lib/idml/elements/group.rb
 - lib/idml/elements/hyperlink.rb
 - lib/idml/elements/hyperlink_page_destination.rb
+- lib/idml/elements/hyperlink_text_source.rb
 - lib/idml/elements/hyperlink_url_destination.rb
 - lib/idml/elements/image.rb
 - lib/idml/elements/ink.rb
@@ -383,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
@@ -390,6 +396,7 @@ files:
 - lib/idml/render/image.rb
 - lib/idml/render/image_collector.rb
 - lib/idml/render/layer_filter.rb
+- lib/idml/render/metadata_builder.rb
 - lib/idml/render/page_item_renderer.rb
 - lib/idml/render/pdfa_packet.rb
 - lib/idml/render/pdfrb_writer.rb