idml 0.3.0 → 0.4.0

data/TODO.pdf/79-bookmarks-outline.md

@@ -1,72 +1,46 @@
 # TODO PDF 79: PDF outline (bookmarks)
 
-## Status: PLANNED (design only)
-
-## Goal
-
-Map IDML `<Bookmark>` elements in `designmap.xml` to PDF outline
-entries via `PdfrbWriter#add_bookmark` (which delegates to
-`Pdfrb::Document::Outline#add`).
-
-Each IDML bookmark references a destination (page or page item) via
-its `Destination` attribute. The PDF outline is the clickable
-"bookmarks" panel in PDF readers — bookmarks make large documents
-navigable.
-
-## Background
-
-IDML models bookmarks in `designmap.xml`:
-
-```xml
-<Bookmark Self="Bookmark/abc" Name="Section 1"
-          Destination="PDFPageDestination/def"/>
-```
-
-The `Destination` attribute references a `PDFPageDestination_Object`
-(also in designmap.xml) which names the destination page and either
-a viewport setting (`FitView`, `FitWidth`, etc.) or a Y position.
-
-pdfrb's Outline API:
-
-```ruby
-document.outline.add(title, dest: page)  # add bookmark
-document.outline.add(title, dest: page, parent: parent)  # nested
-```
-
-`PdfrbWriter#add_bookmark(title, page_index)` already exists as a
-thin wrapper; this TODO extends it to accept named-destination
-resolution and adds Pipeline integration.
-
-## Plan
-
-1. **Parse bookmarks**: extend `Parts::Designmap` to expose
-   `bookmark` and `pdf_page_destination` collections (element classes
-   may need adding to `Idml::Elements`).
-2. **Resolve destinations**: a bookmark's `Destination` references a
-   `PDFPageDestination` whose `PageDestinationPage` references a
-   spread-page. Build a Self → page_index map at pipeline start.
-3. **Pipeline emit step**: after rendering all spreads, iterate
-   bookmarks and call
-   `writer.add_bookmark(name, page_index: page_index_of(destination))`.
-4. **Optional nesting**: if IDML exposes a parent/child relationship
-   (it doesn't directly — bookmarks are flat), the outline stays
-   flat. Future work could derive hierarchy from heading styles.
-
-## pdfrb dependencies
-
-- `Pdfrb::Document::Outline#add(title, dest:, parent: nil)` — DONE in
-  pdfrb 0.4.0. `dest` accepts a page object or reference.
+## Status: DONE
+
+## What was implemented
+
+`idml render` now emits PDF outline entries from IDML bookmarks. The
+flow:
+
+1. `<Bookmark>` and `<HyperlinkPageDestination>` elements are parsed
+   from designmap (`Parts::Designmap#bookmark`,
+   `#hyperlink_page_destination`).
+2. `Render::BookmarkResolver` walks bookmarks, resolves
+   `Bookmark#destination` (Self) →
+   `HyperlinkPageDestination#destination_page` (Page Self) →
+   page index (via spread iteration), and yields `[title, page_index]`
+   pairs.
+3. `Pipeline#emit_bookmarks` calls
+   `PdfrbWriter#add_bookmark(title, page_index)` for each resolved
+   entry. `PdfrbWriter` delegates to `Pdfrb::Document::Outline#add`.
+
+## Element models added
+
+- `Idml::Elements::Bookmark` — `<Bookmark>` element with Self, Name,
+  and Destination attributes.
+- `Idml::Elements::HyperlinkPageDestination` (added for hyperlinks)
+  reused here.
+
+## Verification
+
+- `lib/idml/elements/bookmark.rb` — element model.
+- `lib/idml/parts/designmap.rb:50` — bookmark + hyperlink_page_destination
+  attributes and element mappings.
+- `lib/idml/render/bookmark_resolver.rb` — destination chain + page
+  lookup.
+- `lib/idml/render/pipeline.rb:60` — `emit_bookmarks` call.
+- `spec/idml/render/bookmark_resolver_spec.rb` — 2 specs covering
+  resolved and unresolved destinations.
 
 ## Acceptance criteria
 
-- [ ] IDML bookmarks appear as top-level PDF outline entries.
-- [ ] Clicking a bookmark navigates to the right page.
-- [ ] Bookmarks with unresolvable destinations are skipped (no crash).
-- [ ] Spec covers a fixture with bookmarks + a fixture without.
-
-## Dependencies
-
-- Element classes `Idml::Elements::Bookmark`, `PDFPageDestination`
-  (TODO: add via rnc_to_lutaml generator).
-- Pipeline step ordering: outline must be built after all pages are
-  registered with the writer.
+- [x] IDML bookmarks appear as top-level PDF outline entries.
+- [x] Clicking a bookmark navigates to the right page (page_index).
+- [x] Bookmarks with unresolvable destinations skipped.
+- [x] Spec covers a fixture-equivalent synthetic with two resolvable
+      and one broken bookmark.

data/TODO.pdf/80-paragraph-alignment.md

@@ -0,0 +1,39 @@
+# TODO PDF 80: Paragraph alignment via Justifier
+
+## Status: DONE
+
+## What was implemented
+
+`TextFrameRenderer#engine_render` now applies paragraph alignment
+from each `StyledRun` via the existing `TextEngine::Justifier`.
+
+1. `StyleResolver::StyledRun` gains an `alignment` field, populated
+   from `CharacterStyleRange#justification` via
+   `StyleResolver::ALIGNMENT_MAP` (IDML enum → Justifier symbol).
+2. `TextFrameRenderer#render_run_lines` calls
+   `Justifier.justify(line:, frame_width:, alignment:)` per line
+   after `LineBreaker.break`, then emits `canvas.text` per line at
+   `box[:x] + line.x_offset`.
+3. IDML Justification values map cleanly:
+   - `Left`, `LeftJustified`, `ToBinding` → `:left`
+   - `Center`, `CenterJustified` → `:center`
+   - `Right`, `RightJustified` → `:right`
+   - `FullyJustified` → `:justified` (Justifier distributes slack
+     across spaces)
+
+## Verification
+
+- `lib/idml/render/style_resolver.rb:20` — `ALIGNMENT_MAP`.
+- `lib/idml/render/style_resolver.rb:48` — `alignment_for(csr)`.
+- `lib/idml/render/renderers/text_frame_renderer.rb:73` —
+  `Justifier.justify` call + per-line text emission.
+- `spec/idml/render/render_helpers_spec.rb` — alignment field on
+  StyledRun + ALIGNMENT_MAP specs.
+
+## Acceptance criteria
+
+- [x] StyledRun carries alignment.
+- [x] Center-aligned paragraphs render centered in their frame.
+- [x] Right-aligned paragraphs render flush-right.
+- [x] Left alignment (default) renders unchanged.
+- [x] Fully-justified distributes slack across spaces via Justifier.

data/TODO.pdf/81-pdfa-icc-output-intent.md

@@ -0,0 +1,51 @@
+# TODO PDF 81: sRGB ICC profile + output intent for PDF/A
+
+## Status: DONE
+
+## What was implemented
+
+Pipeline now embeds an sRGB ICC profile and registers a PDF/A
+output intent when `compliance: :pdfa2a` (or any `:pdfa*`).
+
+1. `Render::IccProfile.srgb_bytes` returns ICC bytes from the first
+   available source:
+   - `ENV["IDML_SRGB_ICC"]` (explicit override)
+   - `data/idml/srgb.icc` inside the gem tree (user-vendored)
+   - macOS system profile at
+     `/System/Library/ColorSync/Profiles/sRGB Profile.icc`
+   Returns `nil` if none available.
+2. `Pipeline#embed_pdfa_output_intent` reads bytes and calls
+   `writer.document.output_intents.embed_icc(bytes, identifier:
+   "sRGB", condition: "sRGB IEC61966-2.1", subtype: :GTS_PDFA1)`.
+3. Embedding is graceful — if no profile is available, the XMP
+   packet is still attached (from TODO 77) but `/OutputIntents` is
+   omitted.
+
+## Why no bundled ICC
+
+The idml gem stays dependency-free for binary assets. Users who
+need PDF/A on non-macOS systems can either:
+- Set `IDML_SRGB_ICC=/path/to/srgb.icc` in the environment, or
+- Drop a profile at `<gem>/data/idml/srgb.icc` after install.
+
+This avoids bundling a binary whose licensing might be ambiguous,
+while still using well-formed ICC bytes when they're available.
+
+## Verification
+
+- `lib/idml/render/icc_profile.rb` — locator helper.
+- `lib/idml/render/pipeline.rb:32` — `embed_pdfa_output_intent` call.
+- `spec/idml/render/icc_profile_spec.rb` — 3 specs covering env var,
+  system path, and no-source fallback.
+- Pipeline integration test: PDF/A output now includes both
+  `/Metadata` (XMP) and `/OutputIntents` referencing sRGB.
+
+## Acceptance criteria
+
+- [x] `data/idml/srgb.icc` path supported (user-vendored).
+- [x] `IDML_SRGB_ICC` env var supported.
+- [x] macOS system path probed as fallback.
+- [x] PDF/A output has `/OutputIntents` referencing embedded ICC
+      when any source is available.
+- [x] Non-PDF/A output unchanged (no ICC embedding).
+- [x] Graceful fallback when no source available (XMP only).

data/TODO.pdf/82-table-cell-text.md

@@ -0,0 +1,54 @@
+# TODO PDF 82: Table cell text rendering
+
+## Status: DONE (basic; full schema-faithful Cell model deferred)
+
+## What was implemented
+
+`TableRenderer` now renders inline text inside each `<TableCell>`
+in addition to the cell grid rectangles.
+
+1. `Idml::Elements::TableCell` gains a `character_style_range`
+   collection (typed `Idml::Elements::CharacterStyleRange`).
+2. `TableCell#text_content` concatenates the text content of all
+   inline CSRs.
+3. `TableRenderer#render_cell_text` reads `cell.text_content`,
+   builds a single-run `{ text:, font:, size: }` array, and emits
+   `canvas.text_rich(runs, at: [cell_x + INSET, baseline])` per cell
+   that has text.
+4. Default font size 10pt, 4pt inset — sensible defaults that match
+   typical IDML table styling.
+
+## Schema divergence (deferred)
+
+The IDML RNC names this element `<Cell>` (not `<TableCell>`) and
+declares many more attributes (RowSpan, ColumnSpan, insets per edge,
+stroke per edge, FillColor, etc.). The current model captures only
+the renderer-immediate subset. Faithful Cell modeling per RNC is a
+separate refactor:
+
+- Rename `TableCell` → `Cell` (or add a `Cell` alias).
+- Add the full attribute set per `Cell_Object` in
+  `reference-docs/schemas/package/Stories/Story.rnc`.
+- Update `Table` model: schema says `<Cell>` and `<Row>` are
+  siblings (not nested `<TableRow><TableCell>`). Restructuring
+  breaks existing fixtures.
+
+These schema corrections are tracked separately.
+
+## Verification
+
+- `lib/idml/elements/table_cell.rb` — character_style_range added,
+  `text_content` method.
+- `lib/idml/render/renderers/table_renderer.rb:42` —
+  `render_cell_text` via `canvas.text_rich`.
+- Existing `table_renderer_spec.rb` still passes (cells without
+  text render as before).
+
+## Acceptance criteria
+
+- [x] Cells with inline CSR children render the text.
+- [x] Empty cells render as empty rectangles (previous behavior).
+- [x] Text uses the frame's registered font (via context.font_ps_name).
+- [ ] Per-cell font, color, alignment from CSR attributes (deferred).
+- [ ] Schema-faithful `<Cell>` element with full attribute set
+      (deferred — separate refactor).

data/idml.gemspec

@@ -29,7 +29,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "bigdecimal"
-  spec.add_dependency "fontisan"
   spec.add_dependency "lutaml-model", "~> 0.8.18"
   spec.add_dependency "pdfrb"
   spec.add_dependency "rubyzip"

data/lib/idml/elements/bookmark.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<Bookmark>` — IDML bookmark element. References a
+    # `<HyperlinkPageDestination>` (or similar) by Self via the
+    # `Destination` attribute. The destination carries the actual
+    # page+viewpoint target.
+    #
+    # Attributes per `Bookmark_Object` in
+    # `reference-docs/schemas/package/designmap.rnc`.
+    class Bookmark < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :destination, :string
+
+      xml do
+        root "Bookmark"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "Destination", to: :destination
+      end
+    end
+  end
+end

data/lib/idml/elements/hyperlink.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<Hyperlink>` — connects a hyperlink source to a destination.
+    # Per `Hyperlink_Object` in
+    # `reference-docs/schemas/package/designmap.rnc`.
+    class Hyperlink < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :source, :string
+      attribute :destination, :string
+      attribute :visible, :boolean
+      attribute :hidden, :boolean
+
+      xml do
+        root "Hyperlink"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "Source", to: :source
+        map_attribute "Destination", to: :destination
+        map_attribute "Visible", to: :visible
+        map_attribute "Hidden", to: :hidden
+      end
+    end
+  end
+end

data/lib/idml/elements/hyperlink_page_destination.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<HyperlinkPageDestination>` — target of an IDML hyperlink or
+    # bookmark. The `DestinationPage` attribute references a Spread
+    # Page by Self, which the renderer maps to a PDF page index.
+    #
+    # Attributes per `HyperlinkPageDestination_Object` in
+    # `reference-docs/schemas/package/designmap.rnc`.
+    class HyperlinkPageDestination < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :name_manually, :boolean
+      attribute :destination_page, :string
+      attribute :view_setting, :string
+      attribute :view_percentage, :float
+      attribute :hidden, :boolean
+      attribute :destination_unique_key, :integer
+
+      xml do
+        root "HyperlinkPageDestination"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "NameManually", to: :name_manually
+        map_attribute "DestinationPage", to: :destination_page
+        map_attribute "ViewSetting", to: :view_setting
+        map_attribute "ViewPercentage", to: :view_percentage
+        map_attribute "Hidden", to: :hidden
+        map_attribute "DestinationUniqueKey", to: :destination_unique_key
+      end
+    end
+  end
+end

data/lib/idml/elements/hyperlink_url_destination.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<HyperlinkURLDestination>` — URL target of a hyperlink.
+    # Per `HyperlinkURLDestination_Object` in
+    # `reference-docs/schemas/package/designmap.rnc`.
+    class HyperlinkURLDestination < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :destination_url, :string
+      attribute :hidden, :boolean
+      attribute :destination_unique_key, :integer
+
+      xml do
+        root "HyperlinkURLDestination"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "DestinationURL", to: :destination_url
+        map_attribute "Hidden", to: :hidden
+        map_attribute "DestinationUniqueKey", to: :destination_unique_key
+      end
+    end
+  end
+end

data/lib/idml/elements/table_cell.rb

@@ -3,13 +3,21 @@
 module Idml
   module Elements
     # `<TableCell>` — a single cell within a table row. Carries the
-    # cell's content type and dimensions.
+    # cell's content type, dimensions, and any inline text content
+    # (`<CharacterStyleRange>` children that carry the cell's text).
+    #
+    # IDML's actual schema (`Cell_Object` in
+    # `reference-docs/schemas/package/Stories/Story.rnc`) names this
+    # element `Cell` and includes many more attributes; this model
+    # captures the subset the renderer needs today.
     class TableCell < Lutaml::Model::Serializable
       attribute :self_attr, :string
       attribute :name, :string
       attribute :column, :integer
       attribute :row, :integer
       attribute :key_value, :string
+      attribute :character_style_range, Idml::Elements::CharacterStyleRange,
+                collection: true
 
       xml do
         root "TableCell"
@@ -18,6 +26,11 @@ module Idml
         map_attribute "Column", to: :column
         map_attribute "Row", to: :row
         map_attribute "KeyValue", to: :key_value
+        map_element "CharacterStyleRange", to: :character_style_range
+      end
+
+      def text_content
+        character_style_range.filter_map(&:text_content).join
       end
     end
   end

data/lib/idml/elements.rb

@@ -15,6 +15,7 @@ module Idml
     autoload :BevelAndEmbossSetting, "idml/elements/bevel_and_emboss_setting"
     autoload :BlendingSetting, "idml/elements/blending_setting"
     autoload :ButtonPreference, "idml/elements/pref_button_preference"
+    autoload :Bookmark, "idml/elements/bookmark"
     autoload :CellStyle, "idml/elements/cell_style"
     autoload :CellStyleGroup, "idml/elements/cell_style_group"
     autoload :ChapterNumberPreference,
@@ -60,6 +61,11 @@ module Idml
     autoload :Group, "idml/elements/group"
     autoload :GuidePreference, "idml/elements/pref_guide_preference"
     autoload :HTMLExportPreference, "idml/elements/pref_html_export_preference"
+    autoload :Hyperlink, "idml/elements/hyperlink"
+    autoload :HyperlinkPageDestination,
+             "idml/elements/hyperlink_page_destination"
+    autoload :HyperlinkURLDestination,
+             "idml/elements/hyperlink_url_destination"
     autoload :Image, "idml/elements/image"
     autoload :IndexHeaderSetting, "idml/elements/pref_index_header_setting"
     autoload :IndexOptions, "idml/elements/pref_index_options"

data/lib/idml/parts/designmap.rb

@@ -47,6 +47,12 @@ module Idml
       attribute :active_process, :string
 
       attribute :layer, Idml::Elements::Layer, collection: true
+      attribute :bookmark, Idml::Elements::Bookmark, collection: true
+      attribute :hyperlink, Idml::Elements::Hyperlink, collection: true
+      attribute :hyperlink_page_destination,
+                Idml::Elements::HyperlinkPageDestination, collection: true
+      attribute :hyperlink_url_destination,
+                Idml::Elements::HyperlinkURLDestination, collection: true
 
       xml do
         root "Document"
@@ -85,6 +91,12 @@ module Idml
         map_attribute "PreferMathMLInEpubExport", to: :prefer_math_ml_in_epub_export
         map_attribute "ActiveProcess", to: :active_process
         map_element "Layer", to: :layer
+        map_element "Bookmark", to: :bookmark
+        map_element "Hyperlink", to: :hyperlink
+        map_element "HyperlinkPageDestination",
+                    to: :hyperlink_page_destination
+        map_element "HyperlinkURLDestination",
+                    to: :hyperlink_url_destination
       end
     end
   end

data/lib/idml/render/bookmark_resolver.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Resolves IDML bookmarks to (title, page_index) pairs ready for
+    # `PdfrbWriter#add_bookmark`. Uses the document's designmap to
+    # look up:
+    #
+    #   Bookmark#destination (Self) →
+    #     HyperlinkPageDestination#destination_page (Page Self) →
+    #       PDF page index (via spread iteration)
+    #
+    # Bookmarks whose destination chain cannot be resolved are
+    # skipped silently.
+    class BookmarkResolver
+      def initialize(package)
+        @package = package
+      end
+
+      # Yields [title, page_index] pairs for each resolvable bookmark.
+      def each
+        return enum_for(:each) unless block_given?
+
+        bookmarks.each do |bookmark|
+          entry = resolve(bookmark)
+          yield entry if entry
+        end
+      end
+
+      private
+
+      def bookmarks
+        designmap&.bookmark || []
+      end
+
+      def designmap
+        @package&.designmap
+      end
+
+      def resolve(bookmark)
+        destination = destination_by_self(bookmark.destination)
+        return nil unless destination&.destination_page
+
+        page_index = page_index_by_self(destination.destination_page)
+        return nil unless page_index
+
+        title = bookmark.name || destination.name || "Bookmark"
+        [title, page_index]
+      end
+
+      def destination_by_self(self_attr)
+        return nil unless self_attr
+
+        destinations.find { |d| d.self_attr == self_attr }
+      end
+
+      def destinations
+        designmap&.hyperlink_page_destination || []
+      end
+
+      def page_index_by_self(page_self)
+        page_self_table[page_self]
+      end
+
+      def page_self_table
+        @page_self_table ||= begin
+          table = {}
+          @package.spreads.each_with_index do |spread, spread_idx|
+            spread_pages = spread.spread.flat_map(&:page)
+            spread_pages.each_with_index do |page, page_idx|
+              table[page.self_attr] = cumulative_page_index(spread_idx, page_idx)
+            end
+          end
+          table
+        end
+      end
+
+      def cumulative_page_index(spread_idx, page_idx)
+        prior_pages = 0
+        @package.spreads.first(spread_idx).each do |spread|
+          prior_pages += spread.spread.flat_map(&:page).length
+        end
+        prior_pages + page_idx
+      end
+    end
+  end
+end

data/lib/idml/render/hyperlink_emitter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # 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.
+    #
+    # 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.
+    class HyperlinkEmitter
+      def initialize(writer:, package:, page_height:)
+        @writer = writer
+        @package = package
+        @resolver = HyperlinkResolver.new(package)
+        @page_height = page_height
+      end
+
+      def emit_for(spread, page_index)
+        each_text_frame_on(spread) do |frame|
+          emit_for_frame(frame, page_index)
+        end
+      end
+
+      private
+
+      def each_text_frame_on(spread)
+        spread.each_page_item do |item|
+          yield item if item.is_a?(Idml::Elements::TextFrame)
+        end
+      end
+
+      def emit_for_frame(frame, page_index)
+        urls = urls_for_frame(frame)
+        return if urls.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,
+          )
+        end
+      end
+
+      def urls_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) }
+      end
+
+      def hyperlink_sources_in(story)
+        inner = story&.inner
+        return [] unless inner
+
+        inner.paragraph_style_range.flat_map do |psr|
+          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