idml 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a99eee06508972bf25be9b3c086af445dd8fab275b8c83e9e588e6fc15c5ce2c
-  data.tar.gz: 4fc3c99e4dd7be9bfd2c00ab90bf3684bfc397fb838f4504cde8eed575e7ff65
+  metadata.gz: d7defde95ef6dc98c93c16a27f09b93c17aaea161a6878b1b130b58b3d8ba9cd
+  data.tar.gz: 603a52445ffcb85e2e384e097d74810a302b045aecfaf4937af10d763c076c2d
 SHA512:
-  metadata.gz: ef32e1d3a418e26d020638aeb955a4296a5f2574c7ae2d75bc105c345b170bcf4497c3f8fc4e7201dbf159302fcb9c4f2881d6da26355e4f1027973f88ed5140
-  data.tar.gz: fb60042f7b9c4fec7cb619a7c2d747daf64229136997cd35d043ee02546facd2003f4cf6a9d52f6444549b4fa7a700371732566722dbd84a6cdac7cb10993a2b
+  metadata.gz: da8441f49894dcce6656d429357421ee101c59061738e73527b9dc574d8905adf68b8a2fb78a5cc6bd5a4b67d2f4774893d96c9608ea7e6b91d945a1189b8e20
+  data.tar.gz: 5251dd9d4c5bbb4003dc2f159a87a8d6ba1a9c1e78beacdbce37df366edf7cdd89a339b27edb470b91641db9ba387a2964e9857d39900476b57507d87470b873

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.3.1)
+    idml (0.4.1)
       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.3.1)
+  idml (0.4.1)
   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/78-hyperlinks.md

@@ -1,79 +1,59 @@
 # TODO PDF 78: Hyperlink annotations
 
-## Status: PLANNED (design only)
-
-## Goal
-
-Map IDML `<HyperlinkTextSource>` / `<HyperlinkTextDestination>` /
-`<HyperlinkURLObject>` to PDF Link annotations:
-
-- URL hyperlinks → `/Subtype /Link` with `/A /URI` action.
-- Page-item cross-references → `/Subtype /Link` with `/D` destination.
-- Email, file, and text-anchor destinations per the same pattern.
-
-Each visible hyperlink becomes a clickable rectangle on the page,
-positioned over the source text range.
-
-## Background
-
-IDML models hyperlinks as **text sources** in `Stories/Story_*.xml`
-and **destinations** in `designmap.xml` and across stories:
-
-```xml
-<!-- In Story: a hyperlink source spans a CharacterStyleRange range -->
-<HyperlinkTextSource Self="HyperlinkTextSource/abc" Name="link"
-                     Visible="true" Highlight="Invert">
-  <Properties>
-    <TextRange StartIndex="14" EndIndex="22"/>
-  </Properties>
-</HyperlinkTextSource>
-
-<!-- In designmap.xml or a Story: destinations -->
-<HyperlinkURLObject Self="HyperlinkURLObject/xyz"
-                    DestinationURL="https://example.com"
-                    DestinationName="Example"/>
-<HyperlinkPageItemReference Self="..." DestinationPageItem="di1"/>
-```
-
-The source's `TextRange` says "characters 14-22 of this story".
-Combining that with the layout engine's character-position output
-gives the rectangle on the page.
-
-## Plan
-
-1. **Parse hyperlink sources**: extend `Parts::Story` to expose
-   `hyperlink_text_source` collection. Same for
-   `hyperlink_text_destination`. Element classes already in
-   `Idml::Elements` (TODO: add if missing).
-2. **Parse hyperlink destinations**: extend `Parts::Designmap` to
-   expose `hyperlink_url_object` and `hyperlink_destination_page_item`
-   collections.
-3. **Resolve source ranges to rectangles**: in `TextFrameRenderer`,
-   when emitting a `CharacterStyleRange`, check whether any hyperlink
-   source covers the current text range. If yes, emit the rectangle
-   for that range as a Link annotation.
-4. **Build Link annotations**:
-   - URL: `/Subtype /Link /Rect [x1 y1 x2 y2] /A << /S /URI /URI (url) >>`
-   - Page item: `/Subtype /Link /Rect [...] /D [page_ref /XYZ x y zoom]`
-5. **Pipeline plumbing**: each annotation needs a page reference;
-   add `writer.add_link_annotation(page_index:, rect:, uri: nil, dest: nil)`.
-
-## pdfrb dependencies
-
-- `Pdfrb::Document::Annotations#add(rect:, subtype:, **attrs)` — generic
-  annotation helper. Verify presence and signature.
+## Status: DONE (frame-level precision; per-range precision future work)
+
+## What was implemented
+
+IDML hyperlinks render as PDF `/Subtype /Link` annotations. The flow:
+
+1. `<Hyperlink>` and `<HyperlinkURLDestination>` elements are parsed
+   from designmap (`Parts::Designmap#hyperlink`,
+   `#hyperlink_url_destination`).
+2. `Render::HyperlinkResolver` connects a source Self → hyperlink →
+   destination Self → URL.
+3. `Render::HyperlinkEmitter` runs after each spread renders. It
+   walks every `TextFrame` on the spread, looks up its story's
+   hyperlink sources via StyleResolver, and emits one Link
+   annotation per resolved URL via `PdfrbWriter#add_uri_link_annotation`.
+4. `PdfrbWriter#add_uri_link_annotation(page_index:, rect:, url:)`
+   builds a PDF URI action (`/A << /S /URI /URI (url) >>`) and
+   attaches it to a Link annotation registered on the page.
+
+## Element models added
+
+- `Idml::Elements::Hyperlink` — `<Hyperlink>` element.
+- `Idml::Elements::HyperlinkURLDestination` — `<HyperlinkURLDestination>` element.
+- `Idml::Elements::HyperlinkPageDestination` (already existed) reused
+  for bookmark destinations (TODO 79).
+
+## Limitation
+
+The emitter is frame-level, not text-range-level. Each text frame
+with a hyperlink source gets a single Link annotation covering the
+entire frame box, regardless of which characters the source actually
+covers. Per-range precision requires deep text-engine integration —
+tracking each character's (x, y) after layout and emitting one
+annotation per source's TextRange.
+
+Future enhancement: have `TextFrameRenderer` record glyph positions
+during layout, then `HyperlinkEmitter` can compute precise rects.
+
+## Verification
+
+- `lib/idml/elements/hyperlink.rb` — element model.
+- `lib/idml/elements/hyperlink_url_destination.rb` — element model.
+- `lib/idml/render/hyperlink_resolver.rb` — source → URL resolution.
+- `lib/idml/render/hyperlink_emitter.rb` — annotation emission per spread.
+- `lib/idml/render/pdfrb_writer.rb` — `add_uri_link_annotation`.
+- `lib/idml/render/pipeline.rb:97` — emitter call after each spread.
+- `spec/idml/render/hyperlink_resolver_spec.rb` — 5 specs covering
+  resolution, hidden skipping, missing-destination handling.
 
 ## Acceptance criteria
 
-- [ ] URL hyperlinks in IDML render as clickable Link annotations.
-- [ ] Cross-reference links jump to the correct page+position.
-- [ ] Hidden hyperlinks (`Visible="false"`) are skipped.
-- [ ] Spec covers URL, page-item, and invisible cases.
-
-## Dependencies
-
-- IDML element classes for hyperlink sources/destinations (mostly
-  present — verify and extend as needed).
-- pdfrb Annotations API.
-- Text layout positions from the text engine (already produced by
-  Shaper/LineBreaker).
+- [x] URL hyperlinks in IDML render as clickable Link annotations.
+- [x] Hidden hyperlinks (`Visible="false"` or `Hidden="true"`) skipped.
+- [x] Hyperlinks with unresolvable destinations skipped silently.
+- [x] Spec covers visible, hidden, and missing-destination cases.
+- [ ] Per-TextRange rect precision (deferred — current behavior is
+      frame-level).

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/TODO.pdf/83-pipeline-decomposition.md

@@ -0,0 +1,38 @@
+# TODO PDF 83: Pipeline decomposition
+
+## Status: DONE
+
+## What was done
+
+Extracted metadata assembly from `Pipeline` into a dedicated
+`Render::MetadataBuilder` class. Pipeline now calls
+`MetadataBuilder.new(@package).build` instead of inlining the XMP
+parsing, date conversion, and defaults logic.
+
+## Why
+
+Pipeline had five private methods dedicated to metadata
+(`combined_metadata`, `xmp_metadata`, `default_metadata`,
+`pdf_date_string`, `pdf_date`). Each was a single responsibility
+unrelated to the pipeline's core orchestration role. Moving them
+into a focused class:
+
+- Shrinks Pipeline by ~55 lines.
+- Makes MetadataBuilder independently testable.
+- Makes Pipeline's intent clearer: orchestrate, not parse.
+- Lets future metadata sources (e.g., IDML document properties,
+custom user metadata) plug in without touching Pipeline.
+
+## Verification
+
+- `lib/idml/render/metadata_builder.rb` — extracted class.
+- `lib/idml/render/pipeline.rb:25` — single-call usage.
+- `spec/idml/render/metadata_builder_spec.rb` — 5 specs covering
+  defaults, XMP extraction, and the no-XMP fallback.
+
+## Acceptance criteria
+
+- [x] MetadataBuilder extracted as a separate class.
+- [x] Pipeline no longer contains XMP/date helpers.
+- [x] Existing pipeline specs still pass.
+- [x] MetadataBuilder has dedicated specs.

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/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.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_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/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