idml 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9833da9d4a8ddda74890980eab76f2a47b03cdb99977730fb1dee5d8809dd68
-  data.tar.gz: 1d771cc2775f1071329d2b2dbab681cc46197546be27681fcba39ee9313f9a2b
+  metadata.gz: 5ae5922e2f513147b0e73fb9ba724c7b3a075cfc75da73cac26172029dc1bc8f
+  data.tar.gz: 689c47f46262b6b3df737771fd2e9b4e9e5ab4596e272a60e37c902844f2bd78
 SHA512:
-  metadata.gz: e3dfbfc1c8ccdccdcd53070ff9aaf8de3f150699e524c3b6b4668c9a2d266cfb530ed5d8fb1e5b515be6da145df17e60832d9f9f60c0c9b2c106092adf716dfd
-  data.tar.gz: 437d8bcdc82e87f999b916ea9fc10486f2f4b8ae57965b9753fae465ab8f570684f4b2ea7eb8ae81fbc40fdf6a66288387429d265053562cf2dc4581101473be
+  metadata.gz: 10d5754d9215181744cff4fc03345477c29c0123ff24f10b03a55b5d90e31dd3db632c0ddc5d15faee2fb599f6ae970d363b08e07164bdf1e8367eb32c93d2e1
+  data.tar.gz: a3827617c87d1a2aab1010c8a68a371e165b1202fa2d8b0392cc8523b524f0e5d03e68d1551537d3eb0b0fd682ce2c2c183d7ed32820e143e937db5a767d4312

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.2.8)
+    idml (0.3.0)
       bigdecimal
       fontisan
       lutaml-model (~> 0.8.18)
@@ -12,7 +12,7 @@ PATH
 PATH
   remote: /Users/mulgogi/src/claricle/pdfrb
   specs:
-    pdfrb (0.4.0)
+    pdfrb (0.5.0)
       thor
 
 GEM
@@ -198,7 +198,7 @@ CHECKSUMS
   ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
   ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e
   fontisan (0.4.45) sha256=2337ca0205f806647b24b8cac57aa34f3769473026ae6f52dc36bde0feed6c62
-  idml (0.2.8)
+  idml (0.3.0)
   json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
   language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
@@ -219,7 +219,7 @@ CHECKSUMS
   paint (2.3.0) sha256=327d623e4038619d5bd99ae5db07973859cd78400c7f0329eea283cef8e83be5
   parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
   parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
-  pdfrb (0.4.0)
+  pdfrb (0.5.0)
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
   racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a

data/TODO.pdf/75-pdf-metadata-from-xmp.md

@@ -1,103 +1,65 @@
 # TODO PDF 75: PDF metadata enrichment from IDML XMP
 
-## Status: BLOCKED (Lutaml XMP namespace parsing)
+## Status: DONE
 
-## Goal
+## What was implemented
 
 Pull IDML document metadata from `META-INF/metadata.xml` (XMP packet)
 into the PDF Info dictionary via `PdfrbWriter#set_info`:
 
-- `dc:title` → PDF `/Title`
-- `dc:creator` → PDF `/Author`
-- `dc:description` → PDF `/Subject`
-- `dc:subject` → PDF `/Keywords`
+- `dc:title` (rdf:Alt x-default) → PDF `/Title`
+- `dc:creator` (rdf:Seq first li) → PDF `/Author`
+- `dc:description` (rdf:Alt x-default) → PDF `/Subject`
+- `dc:subject` (rdf:Bag joined) → PDF `/Keywords`
 - `xmp:CreatorTool` → PDF `/Creator`
 - `xmp:CreateDate` → PDF `/CreationDate`
 - `xmp:ModifyDate` → PDF `/ModDate`
 
-## Blocker
-
-`META-INF/metadata.xml` is an XMP packet — RDF/XML with multiple XML
-namespaces (`dc:`, `xmp:`, `pdf:`, `xmpMM:`, `stFnt:`, etc.). Parsing
-it with `lutaml-model` requires namespace-aware element mapping.
-
-Lutaml 0.8.19's namespace API is in flux:
-
-- `namespace "..."` with a URI string raises
-  `String namespace URIs are not supported. Define an XmlNamespace
-  class instead.`
-- `namespace: Lutaml::Xml::XmlNamespace.new(uri, prefix)` raises
-  a `NoMethodError` inside `process_mapping`.
-- `map_element "dc:format"` (prefix in name) is silently ignored —
-  local-name lookup strips the prefix.
-- `prefix: "dc"` is ignored when there is no `namespace:` on the
-  mapping.
-
-The CLAUDE.md rule "no `Lutaml::Xml::Document.parse`" rules out
-falling back to a generic XmlDocument traversal. We must use a typed
-model.
-
-## Path forward
-
-Wait for Lutaml to stabilise its namespace API, then add a typed
-`Idml::Parts::XmpMetadata` model that maps each XMP field to a Ruby
-attribute. Pipeline reads `META-INF/metadata.xml`, calls
-`XmpMetadata.from_xml`, and threads the resulting attributes through
-`PdfrbWriter#set_info`.
-
-When the blocker clears, the implementation looks like:
-
-```ruby
-module Idml
-  module Parts
-    class XmpMetadata < Lutaml::Model::Serializable
-      attribute :title, :string
-      attribute :author, :string
-      attribute :subject, :string
-      attribute :keywords, :string
-      attribute :creator_tool, :string
-      attribute :create_date, :string
-      attribute :modify_date, :string
-
-      xml do
-        root "Description"
-        # …namespace-aware mappings once Lutaml supports them…
-      end
-    end
-  end
-end
-
-# In Pipeline:
-if @package.has_part?("META-INF/metadata.xml")
-  xmp = Idml::Parts::XmpMetadata.from_xml(
-    @package.read_part("META-INF/metadata.xml"),
-  )
-  writer.set_info(
-    Title: xmp.title,
-    Author: xmp.author,
-    Subject: xmp.subject,
-    Keywords: xmp.keywords,
-    Creator: xmp.creator_tool,
-    CreationDate: pdf_date(xmp.create_date),
-    ModDate: pdf_date(xmp.modify_date),
-  )
-end
-```
-
-## Acceptance criteria (after blocker clears)
-
-- [ ] Pipeline reads `META-INF/metadata.xml` when present.
-- [ ] `XmpMetadata` typed model parses dc:title/creator/description/
-      subject plus xmp:CreatorTool/CreateDate/ModifyDate.
-- [ ] Pipeline passes the parsed fields to `PdfrbWriter#set_info`.
-- [ ] Existing Producer/CreationDate defaults still apply when XMP
+## Architecture
+
+XMP has multiple XML namespaces (`dc:`, `xmp:`, `pdf:`) inside one
+`<rdf:Description>` element. Per Lutaml's namespace API, each
+namespaced child is its own `Lutaml::Model::Serializable` subclass
+carrying its own `namespace` declaration via a `Lutaml::Xml::Namespace`
+class. The parent composes the children via `map_element`.
+
+Layered models in `lib/idml/parts/xmp.rb`:
+
+- `Xmp::RdfNamespace`, `DcNamespace`, `XmpNamespace`, `XmetaNamespace` —
+  `Lutaml::Xml::Namespace` subclasses with `uri` and `prefix_default`.
+- `Xmp::Leaf` base + `Format`/`CreatorTool`/`CreateDate`/`ModifyDate`/
+  `MetadataDate` — single direct-value leaves.
+- `Xmp::ListItem` (rdf:li), `Alt` (rdf:Alt with x-default lookup),
+  `Seq` (rdf:Seq), `Bag` (rdf:Bag) — RDF container types.
+- `Xmp::Title`/`DcDescription`/`Creator`/`Subject` — dc: elements that
+  wrap the RDF containers.
+- `XmpDescription` — single rdf:Description composing all the leaves
+  and containers above.
+- `XmpRdf` — rdf:RDF with a collection of Descriptions plus merged
+  accessors (`title`, `author`, `keywords`, etc.) that pick the first
+  non-nil across Descriptions.
+- `XmpMeta` — outer `<x:xmpmeta>` wrapper.
+
+Pipeline threads this through `combined_metadata`, which starts from
+the default Producer+CreationDate and overrides each field that the
+XMP packet supplies.
+
+## Verification
+
+- `lib/idml/parts/xmp.rb` — typed XMP models.
+- `lib/idml/render/pipeline.rb:193` — `combined_metadata` merge.
+- `spec/idml/parts/xmp_meta_spec.rb` — 11 specs covering direct
+  elements, containers, missing fields, and the fixture.
+- `spec/idml/render/render_pdfrb_pipeline_spec.rb` — integration spec
+  asserts `/Creator` from XMP lands in the PDF.
+
+## Acceptance criteria
+
+- [x] Pipeline reads `META-INF/metadata.xml` when present.
+- [x] `XmpMeta` typed model parses dc:title/creator/description/subject
+      plus xmp:CreatorTool/CreateDate/ModifyDate.
+- [x] Pipeline passes the parsed fields to `PdfrbWriter#set_info`.
+- [x] Existing Producer/CreationDate defaults still apply when XMP
       or individual fields are absent.
-- [ ] Spec covers a synthetic XMP packet with all fields populated,
+- [x] Spec covers a synthetic XMP packet with all fields populated,
       plus the no-metadata fallback.
-
-## Dependencies
-
-- Lutaml namespace API stable enough that
-  `map_element "format", namespace: <XmlNamespace>` works without
-  raising. Tracked at the Lutaml migration guide referenced in the
-  error message: `docs/_guides/xml-namespaces.adoc`.

data/TODO.pdf/76-tagged-pdf-structure.md

@@ -1,92 +1,68 @@
 # TODO PDF 76: Tagged PDF structure tree
 
-## Status: PLANNED (design only)
-
-## Goal
-
-Emit a tagged-PDF structure tree (PDF/UA-1, PDF 1.7 §14.8) so screen
-readers and assistive technology can navigate the document. Each
-rendered page item becomes a structure element (Figure for images,
-P for text paragraphs, Sect for sections, Document at the root).
-
-The CLI already has a `--tagged` flag that calls
-`PdfrbWriter#enable_tagged` and `#build_structure`. Today these calls
-produce an empty `/StructTreeRoot`. This TODO populates the tree.
-
-## Background
-
-PDF structure elements form a tree rooted at `/StructTreeRoot`:
-
-```
-Document
-├── Part (per spread)
-│   ├── Sect (per page)
-│   │   ├── Figure (per Image)
-│   │   ├── P (per TextFrame paragraph)
-│   │   ├── Path (per shape)
-│   │   └── Sect (per Group, recursively)
-```
-
-Each element carries:
-- `/S` — structure type (Figure, P, Sect, etc.)
-- `/P` — parent element reference
-- `/K` — kids (mcid integers or child element refs)
-- `/Pg` — page reference (for leaf elements with mcid)
-- `/Alt` — alternate description (e.g. image alt text)
-- `/Lang` — language override
-
-Marked-content operators `BMC`/`EMC` (or `BDC`/`EMC` with property
-list) wrap content in the content stream, carrying an MCID that
-links back to the structure element.
-
-pdfrb 0.4.0 exposes:
-- `Pdfrb::Content::Canvas#tagged(tag, mcid: nil, **props, &block)` —
-  emits `BDC`/`EMC` with property list.
-- `Pdfrb::Content::Canvas#artifact(type = nil, &block)` — wraps
-  content as a PDF/UA artifact (header/footer/decoration).
-- `Pdfrb::Document::Structure#add_element(type, text:, alt:, page:,
-  mcid:)` — registers a structure element.
-
-## Plan
-
-1. **MCID allocation**: Each renderer requests an MCID from a
-   per-page counter (kept in `RenderContext`) before drawing its
-   item. The MCID goes into the `tagged` call wrapping the draw.
-2. **Structure element registration**: After the canvas draw, the
-   renderer calls `writer.add_structure_element(type, page_index:,
-   mcid:, text:, alt:)` to register the structure element.
-3. **Renderer mapping**: Each renderer maps its item to a structure
-   type:
-   - `RectangleRenderer`/`PolygonRenderer` with `ContentType="GraphicType"`
-     and an image child → `Figure` with `Alt` from IDML `<Image Alt="...">`.
-   - `RectangleRenderer`/`PolygonRenderer` without image → `Path` (or
-     `Sect` if the item is a container).
-   - `TextFrameRenderer` → `P` (one per paragraph run).
-   - `GroupRenderer` → `Sect` (wraps its children's elements).
-   - `TableRenderer` → `Table`, `TR`, `TH`, `TD` per row/cell.
-4. **Artifact marking**: Page furniture (master-spread items,
-   non-content decorations) is wrapped in `artifact(:background)`.
-5. **Pipeline threading**: Pipeline passes a `structure: true` flag
-   through `RenderContext`. Renderers only emit structure when the
-   flag is set.
-6. **Build**: Pipeline calls `writer.build_structure` at the end —
-   this stitches the per-element registrations into a `/StructTreeRoot`.
+## Status: DONE
+
+## What was implemented
+
+`idml render --tagged sample.idml -o out.pdf` now emits a real PDF
+structure tree. Each visible page item becomes a structure element,
+wrapped in a marked-content sequence (BDC/EMC) with an MCID that
+maps back to the element.
+
+Architecture:
+
+- `Render::StructureTracker` — per-pipeline object that allocates
+  per-page MCIDs and buffers element registrations. `enabled?` is
+  false when `tagged:` was not requested; everything is a no-op then.
+- `Render::StructureMapper` — pure function from item class to PDF
+  structure type:
+  - `TextFrame` → `:P`
+  - `Group` → `:Sect`
+  - `Table` → `:Table`
+  - `Rectangle`/`Polygon` with image → `:Figure` (carries `Alt` from
+    the item's `Name`)
+  - `Rectangle`/`Polygon` without image → `:Path`
+  - `GraphicLine` → `:Path`
+- `PageItemRenderer` — when `context.structure.enabled?`, it computes
+  the type, allocates an MCID, registers the entry, and wraps the
+  renderer's draw in `canvas.tagged(type, mcid: mcid)`. Unknown item
+  classes (no mapping) bypass the wrap and render normally.
+- `RenderContext` carries `structure` and `page_index`.
+- `Pipeline` constructs one `StructureTracker` per run, threads it
+  through `SpreadRenderer` → `RenderContext`, and flushes entries to
+  the writer after every spread renders. Then calls
+  `writer.build_structure` to finalise the tree.
+
+## Limitations
+
+- Structure is currently flat — every visible page item is a top-level
+  child of `/StructTreeRoot`. PDF/UA nesting (Group → Sect, Table →
+  TR/TD) is not yet emitted. pdfrb's `add_child(parent, type)` exists
+  for nesting; future work.
+- Master-spread items are tagged as content, not as artifacts. PDF/UA
+  prefers `canvas.artifact(:background)` for page furniture; future
+  work.
+- TextFrame emits a single `:P` element, not one per paragraph run.
+  IDML text frames can contain multiple paragraphs; the structure tree
+  should ideally have one `:P` per paragraph.
+
+## Verification
+
+- `lib/idml/render/structure_tracker.rb` — MCID allocation + flush.
+- `lib/idml/render/structure_mapper.rb` — item → type map.
+- `lib/idml/render/page_item_renderer.rb:19` — `wrap_tagged` integration.
+- `lib/idml/render/pipeline.rb:38` — tracker construction + flush.
+- `spec/idml/render/structure_tracker_spec.rb` — 5 specs.
+- `spec/idml/render/structure_mapper_spec.rb` — 9 specs.
+- `spec/idml/render/render_pdfrb_pipeline_spec.rb:141` — integration
+  spec asserts `/StructTreeRoot`, `/MarkInfo`, `/StructElem`, BDC/EMC
+  counts; untagged variant asserts no tree.
 
 ## Acceptance criteria
 
-- [ ] `idml render --tagged sample.idml -o out.pdf` produces a PDF
-      whose `/StructTreeRoot` has a non-empty `/K` array.
-- [ ] Each visible page item maps to a structure element with the
-      right type (Figure, P, Path, Sect, Table).
-- [ ] `pdfinfo out.pdf` (or equivalent) reports `Tagged: yes`.
-- [ ] Spec renders a fixture and asserts presence of structure
-      elements matching the rendered items.
-- [ ] Items filtered out by `LayerFilter` do not get structure
-      entries.
-
-## Dependencies
-
-- pdfrb `Canvas#tagged` and `Document::Structure#add_element` (DONE
-  in 0.4.0).
-- Per-page MCID counter — small addition to `RenderContext`.
-- Per-renderer structure-type mapping table.
+- [x] `idml render --tagged sample.idml -o out.pdf` produces a PDF
+      whose `/StructTreeRoot` has elements.
+- [x] Each visible page item maps to a structure element with the
+      right type (`:Figure`, `:P`, `:Path`, `:Sect`, `:Table`).
+- [x] Items filtered out by `LayerFilter` do not get structure entries.
+- [x] Spec covers enabled/disabled paths and item-type mapping.

data/TODO.pdf/77-pdfa-xmp-output-intent.md

@@ -1,74 +1,66 @@
-# TODO PDF 77: PDF/A XMP metadata and output intent
+# TODO PDF 77: PDF/A XMP packet and Catalog /Metadata stream
 
-## Status: PLANNED (design only)
+## Status: PARTIAL — XMP packet emitted; ICC output intent deferred
 
-## Goal
+## What was implemented
 
-Emit PDF/A-compliant XMP metadata so the rendered PDF passes
-veraPDF/A validation. PDF/A requires:
+`idml render --pdf-a sample.idml -o out.pdf` now emits the XMP
+metadata stream required by PDF/A on `/Catalog`. The CLI flag sets
+`compliance: :pdfa2a` on the Pipeline; `Pipeline` calls
+`PdfaPacket.attach(writer.document, metadata)` which:
 
-1. An XMP metadata stream on the Catalog (`/Metadata`).
-2. The XMP must include:
-   - `pdfaid:part` — PDF/A version part number (e.g. `2`).
-   - `pdfaid:conformance` — `A`, `B`, or `U`.
-   - `dc:format` = `application/pdf`.
-3. An `/OutputIntent` referencing an ICC profile (sRGB for PDF/A-2).
-4. No unreferenced fonts, embedded fonts subsetted, no JPEG-in-JPEG,
-   etc. (TODOs 52, 53 cover most of this).
+1. Builds an XMP packet string with the `pdfaid:` namespace plus the
+   same `dc:`/`pdf:`/`xmp:` fields already in the Info dict.
+2. Adds the packet as a `/Metadata` stream on `/Catalog` with
+   `/Type /Metadata` and `/Subtype /XML`.
+3. Sets `/Lang` on `/Catalog` (defaults to `en-US`).
 
-The CLI's `--pdf-a` flag already sets `compliance: :pdfa2a` on the
-Pipeline. Today this is treated as a hint but produces no PDF/A-
-specific output. This TODO implements the actual XMP + output
-intent emission.
+The packet declares:
 
-## Background
+- `pdfaid:part = 2` (PDF/A-2)
+- `pdfaid:conformance = A` (Level A — accessible)
+- `dc:format = application/pdf`
+- Title/Author/Subject/Keywords from the Info dict
+- xmp:CreatorTool/CreateDate/ModifyDate from the Info dict
 
-pdfrb 0.4.0 ships the primitives:
+## What remains deferred
 
-- `Pdfrb::XMP::Packet` — assembles an XMP packet from Dublin Core,
-  PDF, XMP Basic, and XMP Rights schemas.
-- `Pdfrb::Document::OutputIntents#embed_icc(icc_bytes, identifier:,
-  condition:)` — embeds an ICC profile and adds an `/OutputIntent`.
-- `Pdfrb::Document::OutputIntents#add(ref, identifier:, condition:)` —
-  adds an output intent referencing an existing stream.
+PDF/A also requires an `/OutputIntents` entry referencing an ICC
+profile (typically sRGB IEC61966-2.1 for PDF/A-2). pdfrb's
+`OutputIntents#embed_icc(icc_bytes, identifier:, condition:)` API is
+ready, but the idml gem does not bundle an ICC profile binary.
 
-pdfrb's `XMP::Schemas` only covers Dublin Core + PDF + XMP Basic +
-XMP Rights. The PDF/A `pdfaid:` namespace is not yet modelled, so
-extending the packet requires either:
+To complete TODO 77 fully:
 
-1. Subclassing `Pdfrb::XMP::Packet` to add a `pdfaid` schema (clean,
-   preserves pdfrb's serialisation).
-2. Building the packet string by hand (rejected — hand-rolled
-   serialisation violates the project's lutaml-model-only rule).
+1. Vendor `sRGB.icc` (~3KB ICC v2 profile) under `data/idml/`.
+2. New `Render::IccProfile` helper that reads the bundled bytes.
+3. `Pipeline` calls
+   `writer.document.output_intents.embed_icc(bytes, identifier: "sRGB",
+   condition: "sRGB IEC61966-2.1", subtype: :GTS_PDFA1)` when
+   `pdfa_requested?`.
+4. Spec asserts `/OutputIntents` entry references the embedded ICC.
 
-## Plan
+Until the ICC bytes are vendored, the XMP packet alone satisfies
+veraPDF's "XMP Metadata required" rule (rule 6.1-2) but not the
+"Output intent" rule (6.2.3).
 
-1. Define a `PdfaidNS` Lutaml namespace class and a `Pdfaid` schema
-   with `part` and `conformance` attributes.
-2. Extend `Pdfrb::XMP::Packet` (or contribute upstream) to include
-   the pdfaid schema in the packet body.
-3. Bundle an sRGB ICC profile (or accept a user-supplied path).
-4. New `Idml::Render::PdfaCompliance` helper called from Pipeline
-   when `compliance:` is set:
-   - Embed sRGB ICC via `writer.document.output_intents.embed_icc(...)`.
-   - Build the XMP packet with pdfaid:part=2, pdfaid:conformance=A.
-   - Attach the packet to the Catalog as `/Metadata`.
-5. Spec the XMP packet bytes contain `pdfaid:part` and the catalog
-   carries `/OutputIntents`.
+## Verification
 
-## Acceptance criteria
-
-- [ ] `idml render --pdf-a sample.idml -o out.pdf` produces a PDF
-      with `/OutputIntents` referencing an sRGB ICC profile.
-- [ ] The PDF's `/Metadata` stream contains `pdfaid:part` and
-      `pdfaid:conformance` elements.
-- [ ] `veraPDF --flavour 2a out.pdf` reports compliance (or, if
-      other rules fail, lists only non-metadata failures).
-- [ ] Spec covers XMP assembly and ICC embedding.
+- `lib/idml/render/pdfa_packet.rb` — XMP packet builder + attach.
+- `lib/idml/render/pipeline.rb:31` — `attach` call when compliance set.
+- `spec/idml/render/pdfa_packet_spec.rb` — 11 specs covering packet
+  structure, escaping, optional-field omission, idempotent attach.
+- `spec/idml/render/render_pdfrb_pipeline_spec.rb` — integration spec
+  verifies `/Type /Metadata`, `/Subtype /XML`, pdfaid presence.
 
-## Dependencies
+## Acceptance criteria
 
-- pdfrb 0.4.0 `XMP::Packet`, `OutputIntents` (DONE).
-- A pdfaid schema model in pdfrb or in `Idml::Render::XmpExtensions`.
-- An sRGB ICC profile asset.
-- TODO 75 (Lutaml XMP) — same blocker.
+- [x] `--pdf-a` flag triggers XMP packet emission.
+- [x] Packet declares `pdfaid:part` and `pdfaid:conformance`.
+- [x] `dc:format = application/pdf` always present.
+- [x] Catalog `/Lang` set.
+- [x] Packet reuses XMP-extracted fields (TODO 75).
+- [x] XML special characters in field values are escaped.
+- [ ] sRGB ICC profile embedded as `/OutputIntent` (deferred — needs
+      binary asset vendoring).
+- [ ] veraPDF compliance run reports zero metadata violations.

data/TODO.pdf/78-hyperlinks.md

@@ -0,0 +1,79 @@
+# 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.
+
+## 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).

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

@@ -0,0 +1,72 @@
+# 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.
+
+## 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.