idml 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fcb60002b6973119b04d5aef70ec4ae5541c2da5da1d6fb42fcb19288fec86d
-  data.tar.gz: 86fb08cdace467cf97fedd0cd82bd65820ca1977da5a83255db40ba239273799
+  metadata.gz: e9833da9d4a8ddda74890980eab76f2a47b03cdb99977730fb1dee5d8809dd68
+  data.tar.gz: 1d771cc2775f1071329d2b2dbab681cc46197546be27681fcba39ee9313f9a2b
 SHA512:
-  metadata.gz: 38cab95250785926124189618d16e7d63190ffa63824296530292c8c264bc8913fe6038ed39fbd85ca84925252399cdf609cfda54b64530f20d77bb3ac6c7fed
-  data.tar.gz: bed359cf5365c4a2658f379c7d2a84213c545688993cbe86406bcbf88609b59a992ee46cc96eb21c77ec9142036e7b57bd2c561356502051d2cb15bd71c94b78
+  metadata.gz: e3dfbfc1c8ccdccdcd53070ff9aaf8de3f150699e524c3b6b4668c9a2d266cfb530ed5d8fb1e5b515be6da145df17e60832d9f9f60c0c9b2c106092adf716dfd
+  data.tar.gz: 437d8bcdc82e87f999b916ea9fc10486f2f4b8ae57965b9753fae465ab8f570684f4b2ea7eb8ae81fbc40fdf6a66288387429d265053562cf2dc4581101473be

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.2.7)
+    idml (0.2.8)
       bigdecimal
       fontisan
       lutaml-model (~> 0.8.18)
@@ -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.7)
+  idml (0.2.8)
   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/52-font-subsetting.md

@@ -1,52 +1,45 @@
 # TODO PDF 52: Font subsetting via pdfrb
 
-## Status: BLOCKED (pdfrb has no subsetting API)
-
-## Goal
-
-Subset embedded TrueType fonts to include only the glyphs actually used
-in the document. This dramatically reduces PDF file size (from full font
-~500KB to subset ~5-20KB per font).
-
-## Blocker
-
-pdfrb 0.4.0 exposes no subsetting API:
-
-- `Pdfrb::Document::Fonts#add` accepts `**opts` but ignores `subset:`.
-- No `used_codepoints` collector.
-- `glyph_width` returns stub 500 for TrueType — the per-glyph data
-  needed to build a subset is unavailable.
-
-Without per-glyph metrics, subsetting cannot be implemented in the
-caller either. This is also the same blocker that blocks TODO 63
-(replace FontMetrics with pdfrb).
-
-## Path forward
-
-Either:
-
-1. pdfrb adds a subsetting API that consumes a `used_codepoints:` set
-   and emits a subsetted FontFile2 at write time, OR
-2. pdfrb grows real TTF table parsing (head/hmtx/cmap) so the caller
-   can collect used codepoints, build the subset, and pass the bytes
-   back to `Fonts#add` as pre-subsetted data.
-
-Once pdfrb unblocks, the idml side needs to:
-
-1. Pipeline collects all Unicode codepoints across all stories.
-2. Pipeline passes `used_codepoints: set` to `Fonts#add(subset: true, ...)`.
-3. Spec renders text with known characters and verifies the embedded
-   font only contains those glyphs.
-
-## Acceptance criteria (after pdfrb unblocks)
-
-- [ ] Pipeline collects all Unicode codepoints used across all stories.
-- [ ] For each embedded font, only the used glyphs are included.
-- [ ] FontFile2 contains a subsetted font table (not the full font).
-- [ ] PDF file size significantly reduced vs full-font embedding.
-- [ ] Spec: render text with known characters, verify embedded font
-      contains only those glyphs.
-
-## Dependencies
-
-- pdfrb subsetting API (NOT YET AVAILABLE in 0.4.0).
+## Status: DONE
+
+## What was implemented
+
+Pipeline now subsets embedded TrueType fonts via pdfrb 0.4.0's
+`Fonts#subset_fonts!`. The flow:
+
+1. Every `canvas.text` / `canvas.text_lines` call auto-populates
+   `document.fonts.used_codepoints(resource)` per font.
+2. `Pipeline#call` invokes `writer.subset_fonts!` after rendering all
+   spreads and before `writer.write`.
+3. `PdfrbWriter#subset_fonts!` delegates to
+   `document.fonts.subset_fonts!`, which rewrites each registered
+   font's FontFile2 with a subset containing only the used glyphs
+   (plus glyph 0 / notdef).
+4. Subsetting uses `Pdfrb::Font::TrueType::Subsetter`, which rebuilds
+   glyf/loca/cmap/hmtx/hhea/maxp/head tables and resolves composite
+   glyph references.
+
+## Opting out
+
+`Idml::Render.render(..., subset_fonts: false)` skips the call.
+The CLI exposes `--no-subset` for the same effect. Useful when a
+downstream consumer needs the full font table (e.g. searchable PDFs
+with a specific glyph set).
+
+## Verification
+
+- `lib/idml/render/pdfrb_writer.rb:48` — `subset_fonts!` delegation.
+- `lib/idml/render/pipeline.rb:38` — `subset_fonts!` call site.
+- `spec/idml/render/render_pdfrb_writer_spec.rb:120` — subsetting
+  produces a sub-15KB PDF for "Hello" in Arial.
+
+## Acceptance criteria
+
+- [x] Pipeline collects used codepoints automatically via pdfrb's
+      `encode_text` hook.
+- [x] Each embedded font's FontFile2 is rewritten with a subset
+      containing only used glyphs.
+- [x] PDF file size significantly reduced vs full-font embedding.
+- [x] Spec renders text with known characters and verifies the
+      output PDF is small.
+- [x] `subset_fonts: false` skips subsetting.

data/TODO.pdf/63-replace-fontmetrics-with-pdfrb.md

@@ -1,73 +1,60 @@
 # TODO PDF 63: Replace FontMetrics with pdfrb measurement API
 
-## Status: BLOCKED (pdfrb measurement APIs are stubs)
+## Status: PARTIALLY UNBLOCKED (subsetting works; measurement still AFM-only)
 
 ## Goal
 
 Replace `Idml::TextEngine::FontMetrics` (200+ lines of TTF binary parsing
 via Fontisan) with pdfrb's native `Fonts#measure_text`, `#glyph_width`,
-and `#metrics_for`. Eliminates the Fontisan dependency for text layout.
+and `#metrics_for`.
 
-## Blocker
+## What pdfrb 0.4.0 provides
 
-pdfrb 0.4.0 ships the API surface but the implementations are stubs
-that return constant values, not real per-glyph widths:
+- `Pdfrb::Font::TrueType::File` — real TTF parser with Head, Hhea,
+  Cmap, Hmtx, OS2 tables.
+- `Pdfrb::Font::TrueType::Subsetter` — real subsetting (TODO 52 uses
+  this — DONE).
+- `Fonts#glyph_width(char, resource)` — uses AFM metrics (Standard 14)
+  only; returns `DEFAULT_WIDTH = 500` for TTF.
+- `Fonts#measure_text(text, font:, size:)` — same: AFM or stub
+  (`length * 0.5 * size`).
+- `Fonts#metrics_for(resource)` — AFM metrics only.
 
-`/Users/mulgogi/src/claricle/pdfrb/lib/pdfrb/document/fonts.rb`:
+## What still needs pdfrb work
 
-```ruby
-def measure_text(text, font:, size:)
-  return 0 unless text
-  # TODO: use font metrics for per-glyph width lookup
-  text.to_s.length * (size || 0).to_f * 0.5
-end
+pdfrb's TTF parser exists but is not wired to the measurement API.
+`Fonts#glyph_width` reads `@afm_metrics[resource]`, which is only
+populated for Standard 14 AFM fonts (Helvetica, Times, Courier,
+Symbol, ZapfDingbats). For every other font (any TTF/OTF), it falls
+back to the stub.
 
-def glyph_width(_char, _resource)
-  500
-end
+The per-glyph-width proposal asked for "Look up glyph ID from cmap,
+then width from hmtx." The infrastructure is there (Cmap, Hmtx) but
+the integration with `Fonts#glyph_width` is pending.
 
-def metrics_for(_resource)
-  nil
-end
-```
+Until pdfrb's measurement API wires the TTF parser, the idml gem's
+Shaper and LineBreaker must keep using Fontisan-based FontMetrics
+for accurate per-glyph widths.
 
-The Shaper and LineBreaker depend on accurate per-glyph widths for
-correct word-wrap. With stub data, line breaks land at the wrong
-positions and run advance (needed for TODO 67's `text_rich`) is wrong.
+## Plan (after pdfrb unblocks)
 
-Fontisan correctly parses head/hhea/hmtx/cmap tables for any TTF/OTF
-and exposes per-glyph advance widths. Until pdfrb either grows real
-TTF parsing or accepts externally-provided metrics (see
-`/Users/mulgogi/src/claricle/pdfrb/PROPOSAL.external-font-metrics.md`),
-Fontisan stays.
-
-## Path forward
-
-Proposal at `~/src/claricle/pdfrb/PROPOSAL.external-font-metrics.md`
-suggests letting `Fonts#add` accept `widths:`/`metrics:`/`encoding:`
-hashes from the caller, so pdfrb does not need to parse TTF tables
-itself. The idml gem would then build those hashes from FontMetrics
-and pass them in — keeping Fontisan as the parser while pdfrb handles
-only PDF assembly. This is the Unix-philosophy split.
-
-Once that proposal lands:
-
-1. `PdfrbWriter#register_font_with_metrics(path, widths:, metrics:, ...)`.
-2. Pipeline resolves fonts via FontResolver (Fontisan) and passes the
-   resulting metrics to pdfrb.
-3. Internal `FontMetrics` may still exist as the Fontisan adapter, but
-   Shaper/LineBreaker no longer need to read it — they go through
-   `pdfrb.measure_text`.
+1. `PdfrbWriter#register_font(path)` records the TTF bytes for
+   later parsing.
+2. New `PdfrbFontMetrics` adapter implements FontMetrics' interface
+   by calling `pdfrb.fonts.glyph_width(font_resource, codepoint)`.
+3. `FontResolver` returns `PdfrbFontMetrics` for resolved fonts.
+4. Remove `text_engine/font_metrics.rb` (200+ lines).
 
 ## Acceptance criteria (after pdfrb unblocks)
 
-- [ ] Pipeline registers fonts with externally-provided metrics.
-- [ ] Shaper/LineBreaker call pdfrb's measurement API, not FontMetrics.
-- [ ] `fontisan` remains a dependency for parsing, but no longer feeds
-      Shaper/LineBreaker directly.
+- [ ] Pipeline registers fonts via `pdfrb.fonts.add(path)`.
+- [ ] Shaper/LineBreaker call pdfrb's measurement API, not
+      FontMetrics.
+- [ ] `fontisan` removed from gemspec dependencies.
+- [ ] Spec renders text and verifies line breaks land at correct
+      positions for TTF fonts.
 
 ## Dependencies
 
-- pdfrb 0.4.0's `Fonts#measure_text`/`#glyph_width`/`#metrics_for`
-  with real implementations OR
-- pdfrb accepts the external-metrics proposal linked above.
+- pdfrb `Fonts#glyph_width` uses parsed TTF tables, not AFM-only.
+- pdfrb `Fonts#measure_text` uses parsed TTF tables.

data/TODO.pdf/65-pdfrb-019-integration.md

@@ -1,29 +1,39 @@
-# TODO PDF 65: pdfrb 0.19.0 feature integration
+# TODO PDF 65: pdfrb feature integration
 
 ## Status: PARTIALLY DONE (remainder blocked)
 
 ## What was implemented
 
 1. **Canvas#text_lines**: `TextFrameRenderer` uses `canvas.text_lines`
-   instead of N separate `canvas.text` calls per line. Single batch
-   call for all lines within a run.
+   for batched single-font multi-line text (TODO 27).
+2. **Real PDF gradient shadings**: `RectangleRenderer` uses pdfrb's
+   `Shadings#add_axial` and `Shadings#add_radial` (TODOs 49, 66, 68).
+3. **Canvas#with_transparency**: `Blending.wrap` applies IDML
+   `BlendingSetting` opacity + blend modes (TODO 69).
+4. **Stroke-style setters**: `StrokeStyle.apply` calls
+   `line_cap=`/`line_join=`/`miter_limit=`/`dash_pattern=` from
+   IDML `EndCap`/`EndJoin`/`MiterLimit`/`StrokeDashAndGap` (TODO 70/72).
+5. **Font subsetting**: `Pipeline` calls `Fonts#subset_fonts!` before
+   write (TODO 52).
+6. **Placement module**: shared `Render::Placement.box` (TODO 71).
 
 ## What remains
 
-Blocked by pdfrb 0.4.0 stubs in `Fonts#measure_text` (returns
-`length * 0.5 * size`) and `#glyph_width` (returns 500). Until real
-per-glyph widths land:
+Blocked by pdfrb 0.4.0's TTF measurement still being AFM-only:
 
-2. **`text_rich` for multi-run text**: tracked in TODO 67. Cannot
-   advance between runs without real measurement.
-3. **Replace FontMetrics with pdfrb measurement**: tracked in TODO 63.
-4. **Font subsetting**: tracked in TODO 52. `Fonts#add` accepts `**opts`
-   but `subset:` has no effect.
+7. **`text_rich` for multi-run text** (TODO 67): multi-run batching
+   depends on accurate per-run advance, which `Fonts#measure_text`
+   cannot provide for TTF.
+8. **Replace FontMetrics with pdfrb measurement** (TODO 63): same
+   blocker.
 
 ## Acceptance criteria
 
 - [x] TextFrameRenderer uses `canvas.text_lines`
+- [x] Real PDF gradient shadings via pdfrb
+- [x] Transparency and blend modes
+- [x] Stroke styling
+- [x] Font subsetting
+- [x] Shared Placement module
 - [ ] FontMetrics replaced with pdfrb `glyph_width` (blocked — TODO 63)
-- [ ] FontResolver replaced with `Pdfrb::FontResolver` (blocked — TODO 63)
-- [ ] Font subsetting verified (blocked — TODO 52)
 - [ ] `text_rich` used for multi-run frames (blocked — TODO 67)

data/TODO.pdf/67-text-rich-multi-run.md

@@ -1,6 +1,6 @@
 # TODO PDF 67: Multi-run text batching via Canvas#text_rich
 
-## Status: BLOCKED (pdfrb measure_text is a stub)
+## Status: BLOCKED (pdfrb measure_text is stub for TTF)
 
 ## Goal
 
@@ -12,32 +12,35 @@ all runs inside one BT/ET block, advancing the text matrix between runs.
 
 `text_rich` is the right primitive for multi-run text — one begin/end
 text block per frame instead of N. But its run-advance relies on
-`Pdfrb::Document::Fonts#measure_text`, which in pdfrb 0.4.0 returns a
-stub `length * 0.5 * size`. Without accurate advance, runs overwrite
-each other on the line.
+`Pdfrb::Document::Fonts#measure_text`, which in pdfrb 0.4.0 still
+returns the stub `length * 0.5 * size` for TTF/OTF fonts (only
+Standard 14 AFM fonts get real measurement). Without accurate advance,
+runs overwrite each other on the line.
 
 ## Blocker
 
-`/Users/mulgogi/src/claricle/pdfrb/lib/pdfrb/document/fonts.rb:65`:
+`/Users/mulgogi/src/claricle/pdfrb/lib/pdfrb/document/fonts.rb`:
 
 ```ruby
 def measure_text(text, font:, size:)
-  return 0 unless text
-  # TODO: use font metrics for per-glyph width lookup
-  text.to_s.length * (size || 0).to_f * 0.5
+  return 0 unless text && size
+  metrics = @afm_metrics[font]
+  return text.to_s.length * size.to_f * 0.5 unless metrics  # STUB
+  ...
 end
 ```
 
-`glyph_width` (line 79) is also a stub returning 500, and `metrics_for`
-(line 87) returns nil. These need real Fontisan-backed implementations
-before text_rich produces correct output.
+`@afm_metrics` is only populated for Standard 14 fonts. pdfrb has
+the TTF parsing infrastructure (`Pdfrb::Font::TrueType::File` with
+Cmap, Hmtx) but the integration with `Fonts#glyph_width` /
+`measure_text` is pending.
 
 ## Plan (after pdfrb unblocks)
 
 1. Build `runs` array of `{ text:, font:, size:, color: }` per line.
-2. Replace `simple_render` body with `canvas.text_lines(..., rich: true)`
-   or `canvas.text_rich(runs, at: [x, y])`.
+2. Replace `simple_render` body with `canvas.text_rich(runs, at: [x, y])`.
 3. Verify rendered PDF: runs no longer overwrite, multi-color lines work.
+4. Combine with TODO 63 to drop Fontisan for measurement.
 
 ## Acceptance criteria
 
@@ -47,5 +50,5 @@ before text_rich produces correct output.
 
 ## Dependencies
 
-- pdfrb 0.4.0 `Fonts#measure_text` returns real per-glyph widths.
-- pdfrb 0.4.0 `Fonts#glyph_width` not returning stub 500.
+- pdfrb `Fonts#measure_text` returns real per-glyph widths for TTF
+  fonts (currently stub — see TODO 63).

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

@@ -0,0 +1,103 @@
+# TODO PDF 75: PDF metadata enrichment from IDML XMP
+
+## Status: BLOCKED (Lutaml XMP namespace parsing)
+
+## Goal
+
+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`
+- `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
+      or individual fields are absent.
+- [ ] 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

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

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

@@ -0,0 +1,74 @@
+# TODO PDF 77: PDF/A XMP metadata and output intent
+
+## Status: PLANNED (design only)
+
+## Goal
+
+Emit PDF/A-compliant XMP metadata so the rendered PDF passes
+veraPDF/A validation. PDF/A requires:
+
+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).
+
+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.
+
+## Background
+
+pdfrb 0.4.0 ships the primitives:
+
+- `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.
+
+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:
+
+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).
+
+## Plan
+
+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`.
+
+## 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.
+
+## Dependencies
+
+- 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.

data/lib/idml/cli.rb

@@ -67,6 +67,8 @@ module Idml
                           desc: "Produce PDF/A-2a compliant output"
     method_option :tagged, type: :boolean, default: false,
                            desc: "Produce tagged PDF (PDF/UA)"
+    method_option :no_subset, type: :boolean, default: false,
+                              desc: "Skip font subsetting (larger PDF)"
     method_option :verbose, aliases: "-v", type: :boolean, default: false,
                             desc: "Print progress"
     def render(path)
@@ -97,6 +99,7 @@ module Idml
         font_search_paths: font_search_paths,
         compliance: options[:pdf_a] ? :pdfa2a : nil,
         tagged: options[:tagged],
+        subset_fonts: !options[:no_subset],
       }
     end
 

data/lib/idml/render/pdfrb_writer.rb

@@ -6,14 +6,26 @@ module Idml
     # Delegates all PDF assembly to pdfrb (no hand-rolled PDF code).
     # The adapter provides a consistent interface for the Pipeline
     # (add_page → returns Canvas, add_image → name, register_font → name,
-    # set_info, add_bookmark) while letting pdfrb handle xref, trailer,
-    # object streams, and operator emission.
+    # set_info, add_bookmark, subset_fonts!) while letting pdfrb handle
+    # xref, trailer, object streams, and operator emission.
     class PdfrbWriter
       DEFAULT_WIDTH = 612
       DEFAULT_HEIGHT = 792
 
+      META_SETTERS = {
+        Title: :title=,
+        Author: :author=,
+        Subject: :subject=,
+        Keywords: :keywords=,
+        Creator: :creator=,
+        Producer: :producer=,
+        CreationDate: :creationdate=,
+        ModDate: :moddate=,
+      }.freeze
+
       def initialize
         @document = Pdfrb::Document.new
+        @image_cache = {}
       end
 
       def add_page(width: DEFAULT_WIDTH, height: DEFAULT_HEIGHT)
@@ -39,20 +51,25 @@ module Idml
         meta = @document.metadata
         hash.each do |key, value|
           setter = META_SETTERS[key.to_sym]
-          meta.public_send(setter, value.to_s) if setter
+          next unless setter
+
+          meta.public_send(setter, value.to_s)
         end
       end
 
+      def subset_fonts!
+        @document.fonts.subset_fonts!
+      end
+
       def write(path)
         @document.write(path)
       end
 
       def image_name_for(uri)
-        @image_cache&.key?(uri) ? @image_cache[uri] : nil
+        @image_cache[uri]
       end
 
       def register_image_name(uri, name)
-        @image_cache ||= {}
         @image_cache[uri] = name
       end
 
@@ -72,17 +89,6 @@ module Idml
       def document
         @document
       end
-
-      META_SETTERS = {
-        Title: :title=,
-        Author: :author=,
-        Subject: :subject=,
-        Keywords: :keywords=,
-        Creator: :creator=,
-        Producer: :producer=,
-        CreationDate: :creationdate=,
-        ModDate: :moddate=,
-      }.freeze
     end
   end
 end

data/lib/idml/render/pipeline.rb

@@ -10,12 +10,13 @@ module Idml
       DEFAULT_HEIGHT = 792
 
       def initialize(package, output_path, font_search_paths = nil,
-                     compliance: nil, tagged: false)
+                     compliance: nil, tagged: false, subset_fonts: true)
         @package = package
         @output_path = output_path
         @font_resolver = build_font_resolver(font_search_paths)
         @compliance = compliance
         @tagged = tagged
+        @subset_fonts = subset_fonts
       end
 
       def call
@@ -33,6 +34,7 @@ module Idml
         end
 
         writer.build_structure if @tagged
+        writer.subset_fonts! if @subset_fonts
         writer.write(@output_path)
         @output_path
       end

data/lib/idml/render.rb

@@ -25,11 +25,16 @@ module Idml
 
     DEFAULT_FONT = "Helvetica"
 
+    # Render an IDML package to a PDF file. All options except
+    # `package:` and `to:` are keyword-only and optional.
+    # rubocop:disable Metrics/ParameterLists
     def self.render(package:, to:, font_search_paths: nil, compliance: nil,
-                   tagged: false)
-      Pipeline.new(package, to, font_search_paths, compliance: compliance,
-                                                   tagged: tagged).call
+                   tagged: false, subset_fonts: true)
+      Pipeline.new(package, to, font_search_paths,
+                   compliance: compliance, tagged: tagged,
+                   subset_fonts: subset_fonts).call
     end
+    # rubocop:enable Metrics/ParameterLists
   end
 end
 

data/lib/idml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Idml
-  VERSION = "0.2.7"
+  VERSION = "0.2.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - Ribose
@@ -215,6 +215,9 @@ files:
 - TODO.pdf/72-stroke-styling.md
 - TODO.pdf/73-gradient-resolver-cleanup.md
 - TODO.pdf/74-renderer-spec-coverage.md
+- TODO.pdf/75-pdf-metadata-from-xmp.md
+- TODO.pdf/76-tagged-pdf-structure.md
+- TODO.pdf/77-pdfa-xmp-output-intent.md
 - TODO.pdf/README.md
 - exe/idml
 - idml.gemspec