idml 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a99eee06508972bf25be9b3c086af445dd8fab275b8c83e9e588e6fc15c5ce2c
-  data.tar.gz: 4fc3c99e4dd7be9bfd2c00ab90bf3684bfc397fb838f4504cde8eed575e7ff65
+  metadata.gz: d6cd95e24b0c6610673ad2c95308314a391471fa3912d28a660b8381d46f7b81
+  data.tar.gz: f33fdd9480345a9de8f8fa0e60536b87423978a09732031ab7a4587b99fae59e
 SHA512:
-  metadata.gz: ef32e1d3a418e26d020638aeb955a4296a5f2574c7ae2d75bc105c345b170bcf4497c3f8fc4e7201dbf159302fcb9c4f2881d6da26355e4f1027973f88ed5140
-  data.tar.gz: fb60042f7b9c4fec7cb619a7c2d747daf64229136997cd35d043ee02546facd2003f4cf6a9d52f6444549b4fa7a700371732566722dbd84a6cdac7cb10993a2b
+  metadata.gz: 26f80da839299b0fad35c4380511bca3c91d61aabb29c8699f82a50ee7f7a02d5a9ae314643d596a5e0847f91dcbd7782da2bf73892004995578f8d129c52521
+  data.tar.gz: d416cb234f968d95ed9a5f23fecf7ddbe19a171986e58a98f8eee1483a09db4588496a674bfbcfe52be077c2c8c117978b35314ff335e5498e6cc70367dc11de

data/Gemfile.lock

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

data/lib/idml/render/hyperlink_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Resolves IDML hyperlink definitions to URL destinations. Looks
+    # up `Hyperlink#source` → `Hyperlink#destination` →
+    # `HyperlinkURLDestination#destination_url` from the designmap.
+    #
+    # The renderer is responsible for mapping source Self IDs to
+    # page-item rectangles; this resolver only handles the
+    # destination lookup.
+    class HyperlinkResolver
+      def initialize(package)
+        @package = package
+      end
+
+      # Returns the URL for the given hyperlink-source Self, or nil.
+      def url_for_source(source_self)
+        return nil unless source_self
+
+        hyperlink = hyperlink_by_source(source_self)
+        return nil unless hyperlink
+
+        url_destination_by_self(hyperlink.destination)&.destination_url
+      end
+
+      # Yields [source_self, url] for every visible hyperlink whose
+      # destination chain resolves to a URL.
+      def each_visible
+        return enum_for(:each_visible) unless block_given?
+
+        hyperlinks.each do |hyperlink|
+          entry = visible_entry(hyperlink)
+          yield(*entry) if entry
+        end
+      end
+
+      private
+
+      def visible_entry(hyperlink)
+        return nil if hyperlink.visible == false || hyperlink.hidden == true
+
+        url = url_destination_by_self(hyperlink.destination)&.destination_url
+        return nil unless url
+
+        [hyperlink.source, url]
+      end
+
+      def hyperlinks
+        @package&.designmap&.hyperlink || []
+      end
+
+      def hyperlink_by_source(source_self)
+        hyperlinks.find { |h| h.source == source_self }
+      end
+
+      def url_destination_by_self(self_attr)
+        return nil unless self_attr
+
+        url_destinations.find { |d| d.self_attr == self_attr }
+      end
+
+      def url_destinations
+        @package&.designmap&.hyperlink_url_destination || []
+      end
+    end
+  end
+end

data/lib/idml/render/icc_profile.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Locates an sRGB ICC profile for PDF/A output intent embedding.
+    # The idml gem does not bundle a binary ICC asset; instead, this
+    # helper probes a small set of well-known locations in priority
+    # order and returns the first match as raw bytes.
+    #
+    # Priority:
+    #   1. `ENV["IDML_SRGB_ICC"]` — explicit user override.
+    #   2. `data/idml/srgb.icc` inside the gem tree (user-vendored).
+    #   3. macOS system profile at
+    #      `/System/Library/ColorSync/Profiles/sRGB Profile.icc`.
+    #
+    # Returns `nil` when no profile is available — callers (Pipeline)
+    # should skip ICC embedding in that case rather than raising.
+    module IccProfile
+      GEM_DATA_PATH = File.expand_path("../../../data/idml/srgb.icc", __dir__)
+      MACOS_SYSTEM_PATH = "/System/Library/ColorSync/Profiles/sRGB Profile.icc"
+
+      def self.srgb_bytes
+        candidate_paths.each do |path|
+          bytes = read_if_present(path)
+          return bytes if bytes
+        end
+        nil
+      end
+
+      def self.candidate_paths
+        [
+          ENV.fetch("IDML_SRGB_ICC", nil),
+          GEM_DATA_PATH,
+          MACOS_SYSTEM_PATH,
+        ].compact
+      end
+      private_class_method :candidate_paths
+
+      def self.read_if_present(path)
+        return nil unless path && !path.empty?
+        return nil unless File.exist?(path)
+
+        File.binread(path)
+      rescue StandardError
+        nil
+      end
+      private_class_method :read_if_present
+    end
+  end
+end

data/lib/idml/render/pdfrb_writer.rb

@@ -83,6 +83,16 @@ module Idml
                                               page: page, mcid: mcid)
       end
 
+      def add_uri_link_annotation(page_index:, rect:, url:)
+        page = @document.pages[page_index]
+        action = @document.add({ S: :URI, URI: url },
+                               type: Pdfrb::Model::Cos::Dictionary)
+        action_ref = Pdfrb::Model::Reference.new(action.oid, action.gen)
+        annot = @document.annotations.add(page, subtype: :Link, rect: rect)
+        annot.value[:A] = action_ref
+        annot
+      end
+
       def build_structure
         @document.structure.build!
       end

data/lib/idml/render/pipeline.rb

@@ -24,7 +24,10 @@ module Idml
         metadata = combined_metadata
         writer.set_info(metadata)
         writer.enable_tagged if @tagged
-        PdfaPacket.attach(writer.document, metadata) if pdfa_requested?
+        if pdfa_requested?
+          PdfaPacket.attach(writer.document, metadata)
+          embed_pdfa_output_intent(writer)
+        end
         structure = StructureTracker.new(enabled: @tagged)
         layer_filter = LayerFilter.from_designmap(@package.designmap)
         font_ref_resolver = FontReferenceResolver.build(@package)
@@ -42,6 +45,7 @@ module Idml
 
         structure.flush(writer)
         writer.build_structure if @tagged
+        emit_bookmarks(writer)
         writer.subset_fonts! if @subset_fonts
         writer.write(@output_path)
         @output_path
@@ -49,6 +53,26 @@ module Idml
 
       private
 
+      def embed_pdfa_output_intent(writer)
+        bytes = IccProfile.srgb_bytes
+        return unless bytes
+
+        writer.document.output_intents.embed_icc(
+          bytes,
+          identifier: "sRGB",
+          condition: "sRGB IEC61966-2.1",
+          subtype: :GTS_PDFA1,
+        )
+      rescue StandardError
+        nil
+      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
@@ -71,10 +95,18 @@ module Idml
                                           page_height: dims[:height],
                                           image_refs: image_refs,
                                           page_index: current)
+          emit_hyperlinks(writer, spread, current)
         end
         current
       end
 
+      def emit_hyperlinks(writer, spread, page_index)
+        HyperlinkEmitter.new(writer: writer, package: @package,
+                             page_height: DEFAULT_HEIGHT).emit_for(spread, page_index)
+      rescue StandardError
+        nil
+      end
+
       def build_renderer(layer_filter, font_ref_resolver, font_resource,
                          font_metrics, structure:)
         SpreadRenderer.new(

data/lib/idml/render/renderers/table_renderer.rb

@@ -3,7 +3,14 @@
 module Idml
   module Render
     module Renderers
+      # Renders an IDML Table. Draws the cell grid via rectangle ops,
+      # then renders inline `<CharacterStyleRange>` text in each cell
+      # via `canvas.text_rich`. Cells with no text render as empty
+      # rectangles.
       class TableRenderer
+        DEFAULT_SIZE = 10.0
+        INSET = 4.0
+
         def self.render(canvas, context)
           table = context.item
           return if table.visible == false
@@ -17,24 +24,41 @@ module Idml
 
           canvas.save_graphics_state do
             table.table_row.each_with_index do |row, row_index|
-              render_row(canvas, row, row_index, row_count, box, row_height)
+              render_row(canvas, row, row_index, row_count, box, row_height,
+                         context)
             end
           end
         end
 
-        def self.render_row(canvas, row, row_index, row_count, box, row_height)
+        def self.render_row(canvas, row, row_index, row_count, box, row_height,
+                            context)
           row_y = box[:y] + ((row_count - 1 - row_index) * row_height)
           cell_count = row.table_cell.length
           return unless cell_count.positive?
 
           cell_width = box[:width] / cell_count
-          row.table_cell.each_with_index do |_cell, cell_index|
+          row.table_cell.each_with_index do |cell, cell_index|
             cell_x = box[:x] + (cell_index * cell_width)
             canvas.rectangle(cell_x, row_y, cell_width, row_height)
             canvas.stroke
+            render_cell_text(canvas, cell, cell_x, row_y, row_height, context)
           end
         end
         private_class_method :render_row
+
+        def self.render_cell_text(canvas, cell, x, y, height, context)
+          text = cell.text_content
+          return if text.nil? || text.empty?
+
+          runs = [{
+            text: text,
+            font: context.font_ps_name,
+            size: DEFAULT_SIZE,
+          }]
+          baseline = y + (height / 2)
+          canvas.text_rich(runs, at: [x + INSET, baseline])
+        end
+        private_class_method :render_cell_text
       end
     end
   end

data/lib/idml/render/renderers/text_frame_renderer.rb

@@ -58,8 +58,10 @@ module Idml
         end
         private_class_method :engine_render
 
-        # Emits one `canvas.text_lines` call per run, after shaping
-        # and line-breaking with real font metrics. Lines that fall
+        # Emits one `canvas.text` call per line, after shaping and
+        # line-breaking with real font metrics. Applies paragraph
+        # alignment via `Justifier` so each line is offset within
+        # the frame box per IDML `Justification`. Lines that fall
         # below the frame's bottom edge are clipped.
         def self.render_run_lines(canvas, run, context, box, font, baseline_y)
           size = run.point_size
@@ -69,26 +71,30 @@ module Idml
           lines = TextEngine::LineBreaker.break(
             glyphs: glyphs, frame_width: box[:width],
           )
-
-          line_texts = []
-          lines.each do |line|
-            break if baseline_y < box[:y]
-
-            line_texts << line.glyphs.map { |g| [g.codepoint].pack("U") }.join
-            baseline_y -= size * LEADING_FACTOR
-          end
-
-          if line_texts.any?
-            canvas.text_lines(line_texts,
-                              font: context.font_ps_name,
-                              size: size,
-                              at: [box[:x], box[:y] + box[:height] - size],
-                              leading: size * LEADING_FACTOR)
+          alignment = run.alignment || :left
+          start_y = box[:y] + box[:height] - size
+
+          lines.each_with_index do |line, idx|
+            line_y = start_y - (idx * size * LEADING_FACTOR)
+            break if line_y < box[:y]
+
+            TextEngine::Justifier.justify(line: line,
+                                          frame_width: box[:width],
+                                          alignment: alignment)
+            canvas.text(line_text(line),
+                        at: [box[:x] + line.x_offset, line_y],
+                        font: context.font_ps_name,
+                        size: size)
           end
           baseline_y
         end
         private_class_method :render_run_lines
 
+        def self.line_text(line)
+          line.glyphs.map { |g| [g.codepoint].pack("U") }.join
+        end
+        private_class_method :line_text
+
         # Fallback when no metrics are available: emit all runs as
         # one `text_rich` block, letting pdfrb measure advance widths.
         # Uses pdfrb's measurement API directly (no Fontisan).

data/lib/idml/render/style_resolver.rb

@@ -4,15 +4,30 @@ module Idml
   module Render
     # Extracts styled text runs from an IDML Story. Each run carries the
     # text content plus the CharacterStyleRange attributes that affect
-    # rendering (font style, size, fill color, applied font reference).
+    # rendering (font style, size, fill color, applied font reference,
+    # paragraph alignment).
     class StyleResolver
       StyledRun = Struct.new(
         :text, :font_style, :point_size,
-        :fill_color, :fill_tint, :applied_font, keyword_init: true
+        :fill_color, :fill_tint, :applied_font, :alignment,
+        keyword_init: true
       )
 
       DEFAULT_POINT_SIZE = 12.0
 
+      # IDML `Justification` enum → Justifier symbol. Full justify
+      # and binding-side variants defer to :left for now (TODO 80).
+      ALIGNMENT_MAP = {
+        "Left" => :left,
+        "Center" => :center,
+        "Right" => :right,
+        "LeftJustified" => :left,
+        "RightJustified" => :right,
+        "CenterJustified" => :center,
+        "FullyJustified" => :justified,
+        "ToBinding" => :left,
+      }.freeze
+
       def self.extract_runs(story)
         return [] unless story&.inner
 
@@ -33,11 +48,17 @@ module Idml
             fill_color: csr.fill_color,
             fill_tint: csr.fill_tint,
             applied_font: csr.applied_font,
+            alignment: alignment_for(csr),
           )
         end
       end
       private_class_method :csr_runs
 
+      def self.alignment_for(csr)
+        ALIGNMENT_MAP[csr.justification] || :left
+      end
+      private_class_method :alignment_for
+
       # Concatenate runs into a single block. Used when the renderer
       # can't handle per-run styling (e.g., no font metrics available).
       def self.concatenate(runs)

data/lib/idml/render.rb

@@ -19,6 +19,10 @@ module Idml
     autoload :StructureTracker,    "#{__dir__}/render/structure_tracker"
     autoload :StructureMapper,     "#{__dir__}/render/structure_mapper"
     autoload :PdfaPacket,          "#{__dir__}/render/pdfa_packet"
+    autoload :IccProfile,          "#{__dir__}/render/icc_profile"
+    autoload :BookmarkResolver,    "#{__dir__}/render/bookmark_resolver"
+    autoload :HyperlinkResolver,   "#{__dir__}/render/hyperlink_resolver"
+    autoload :HyperlinkEmitter,    "#{__dir__}/render/hyperlink_emitter"
     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.3.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Ribose
@@ -206,6 +206,9 @@ files:
 - TODO.pdf/77-pdfa-xmp-output-intent.md
 - TODO.pdf/78-hyperlinks.md
 - TODO.pdf/79-bookmarks-outline.md
+- TODO.pdf/80-paragraph-alignment.md
+- TODO.pdf/81-pdfa-icc-output-intent.md
+- TODO.pdf/82-table-cell-text.md
 - TODO.pdf/README.md
 - exe/idml
 - idml.gemspec
@@ -223,6 +226,7 @@ files:
 - lib/idml/elements/baseline_frame_grid_option.rb
 - lib/idml/elements/bevel_and_emboss_setting.rb
 - lib/idml/elements/blending_setting.rb
+- lib/idml/elements/bookmark.rb
 - lib/idml/elements/cell_style.rb
 - lib/idml/elements/cell_style_group.rb
 - lib/idml/elements/character_style.rb
@@ -249,6 +253,9 @@ files:
 - lib/idml/elements/gradient_stop.rb
 - lib/idml/elements/graphic_line.rb
 - lib/idml/elements/group.rb
+- lib/idml/elements/hyperlink.rb
+- lib/idml/elements/hyperlink_page_destination.rb
+- lib/idml/elements/hyperlink_url_destination.rb
 - lib/idml/elements/image.rb
 - lib/idml/elements/ink.rb
 - lib/idml/elements/inner_glow_setting.rb
@@ -372,10 +379,14 @@ files:
 - lib/idml/parts/xmp.rb
 - lib/idml/render.rb
 - lib/idml/render/blending.rb
+- lib/idml/render/bookmark_resolver.rb
 - lib/idml/render/color_helper.rb
 - lib/idml/render/color_resolver.rb
 - lib/idml/render/font_reference_resolver.rb
 - lib/idml/render/gradient_resolver.rb
+- lib/idml/render/hyperlink_emitter.rb
+- lib/idml/render/hyperlink_resolver.rb
+- lib/idml/render/icc_profile.rb
 - lib/idml/render/image.rb
 - lib/idml/render/image_collector.rb
 - lib/idml/render/layer_filter.rb