idml 0.2.7 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fcb60002b6973119b04d5aef70ec4ae5541c2da5da1d6fb42fcb19288fec86d
-  data.tar.gz: 86fb08cdace467cf97fedd0cd82bd65820ca1977da5a83255db40ba239273799
+  metadata.gz: 192799dde8a7c36a34473f5903934fa17a08c8ea05ae444797099ada2b03ff7c
+  data.tar.gz: 9b7659bb74cda7f6d8f9f47df07e2123605baa9df584138d3ef382934f999f60
 SHA512:
-  metadata.gz: 38cab95250785926124189618d16e7d63190ffa63824296530292c8c264bc8913fe6038ed39fbd85ca84925252399cdf609cfda54b64530f20d77bb3ac6c7fed
-  data.tar.gz: bed359cf5365c4a2658f379c7d2a84213c545688993cbe86406bcbf88609b59a992ee46cc96eb21c77ec9142036e7b57bd2c561356502051d2cb15bd71c94b78
+  metadata.gz: c113cb7d7a44f198c4c6746cde61f2301733f7f61f2ed5bfe6a3afd145e4446a2e144790916a5bad8106440e0f83b2901dff52e6ff2adf52dedbbe7fb8fcf655
+  data.tar.gz: 7960cfe58d64292369cfb23c87a5bcaeec495a7e20f3bbf8c87592040ec04d57630d61ecf7fe2916b1706c142d53c7561d3229c5563216eaf015119d28148a48

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.2.7)
+    idml (0.2.9)
       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.9)
   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,65 @@
+# TODO PDF 75: PDF metadata enrichment from IDML XMP
+
+## Status: DONE
+
+## 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` (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`
+
+## 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.
+- [x] Spec covers a synthetic XMP packet with all fields populated,
+      plus the no-metadata fallback.

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/parts/xmp.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Idml
+  module Parts
+    # XMP (Extensible Metadata Platform) parser for IDML's
+    # `META-INF/metadata.xml`. The packet is RDF/XML with multiple
+    # namespaces (`dc:`, `xmp:`, `pdf:`, `xmpMM:`, etc.).
+    #
+    # Per Lutaml's namespace API, each namespaced element is a
+    # separate `Serializable` subclass that carries its own
+    # `namespace`. The parent `<rdf:Description>` composes the
+    # children via `map_element`, with the namespace binding handled
+    # on each child class.
+    module Xmp
+      class RdfNamespace < Lutaml::Xml::Namespace
+        uri "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+        prefix_default "rdf"
+      end
+
+      class DcNamespace < Lutaml::Xml::Namespace
+        uri "http://purl.org/dc/elements/1.1/"
+        prefix_default "dc"
+      end
+
+      class XmpNamespace < Lutaml::Xml::Namespace
+        uri "http://ns.adobe.com/xap/1.0/"
+        prefix_default "xmp"
+      end
+
+      class XmetaNamespace < Lutaml::Xml::Namespace
+        uri "adobe:ns:meta/"
+        prefix_default "x"
+      end
+
+      # Single direct-value element. Subclasses set the element name
+      # and namespace.
+      class Leaf < Lutaml::Model::Serializable
+        attribute :value, :string
+      end
+
+      class Format < Leaf
+        xml do
+          root "format"
+          namespace DcNamespace
+          map_content to: :value
+        end
+      end
+
+      class CreatorTool < Leaf
+        xml do
+          root "CreatorTool"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      class CreateDate < Leaf
+        xml do
+          root "CreateDate"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      class ModifyDate < Leaf
+        xml do
+          root "ModifyDate"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      class MetadataDate < Leaf
+        xml do
+          root "MetadataDate"
+          namespace XmpNamespace
+          map_content to: :value
+        end
+      end
+
+      # rdf:li element inside rdf:Alt / rdf:Seq / rdf:Bag containers.
+      class ListItem < Lutaml::Model::Serializable
+        attribute :lang, :string
+        attribute :value, :string
+
+        xml do
+          root "li"
+          namespace RdfNamespace
+          map_attribute "lang", to: :lang
+          map_content to: :value
+        end
+      end
+
+      # rdf:Alt — alternative-language values. Used for dc:title and
+      # dc:description.
+      class Alt < Lutaml::Model::Serializable
+        attribute :items, ListItem, collection: true
+
+        xml do
+          root "Alt"
+          namespace RdfNamespace
+          map_element "li", to: :items
+        end
+
+        def default_value
+          x_default = items.find { |i| i.lang == "x-default" }
+          (x_default || items.first)&.value
+        end
+      end
+
+      # rdf:Seq — ordered sequence. Used for dc:creator.
+      class Seq < Lutaml::Model::Serializable
+        attribute :items, ListItem, collection: true
+
+        xml do
+          root "Seq"
+          namespace RdfNamespace
+          map_element "li", to: :items
+        end
+
+        def values
+          items.filter_map(&:value)
+        end
+      end
+
+      # rdf:Bag — unordered set. Used for dc:subject.
+      class Bag < Lutaml::Model::Serializable
+        attribute :items, ListItem, collection: true
+
+        xml do
+          root "Bag"
+          namespace RdfNamespace
+          map_element "li", to: :items
+        end
+
+        def values
+          items.filter_map(&:value)
+        end
+      end
+
+      # Container-wrapped dc elements.
+      class Title < Lutaml::Model::Serializable
+        attribute :alt, Alt
+
+        xml do
+          root "title"
+          namespace DcNamespace
+          map_element "Alt", to: :alt
+        end
+
+        def value
+          alt&.default_value
+        end
+      end
+
+      class DcDescription < Lutaml::Model::Serializable
+        attribute :alt, Alt
+
+        xml do
+          root "description"
+          namespace DcNamespace
+          map_element "Alt", to: :alt
+        end
+
+        def value
+          alt&.default_value
+        end
+      end
+
+      class Creator < Lutaml::Model::Serializable
+        attribute :seq, Seq
+
+        xml do
+          root "creator"
+          namespace DcNamespace
+          map_element "Seq", to: :seq
+        end
+
+        def values
+          seq&.values || []
+        end
+      end
+
+      class Subject < Lutaml::Model::Serializable
+        attribute :bag, Bag
+
+        xml do
+          root "subject"
+          namespace DcNamespace
+          map_element "Bag", to: :bag
+        end
+
+        def values
+          bag&.values || []
+        end
+      end
+    end
+
+    # Single `<rdf:Description>` element from an XMP packet. Combines
+    # children from multiple namespaces (`dc:`, `xmp:`) by composing
+    # nested `Serializable` models — each child carries its own
+    # `namespace` declaration per Lutaml's namespace API.
+    class XmpDescription < Lutaml::Model::Serializable
+      attribute :format, Xmp::Format
+      attribute :title, Xmp::Title
+      attribute :creator, Xmp::Creator
+      attribute :description, Xmp::DcDescription
+      attribute :subject, Xmp::Subject
+      attribute :creator_tool, Xmp::CreatorTool
+      attribute :create_date, Xmp::CreateDate
+      attribute :modify_date, Xmp::ModifyDate
+      attribute :metadata_date, Xmp::MetadataDate
+
+      xml do
+        root "Description"
+        namespace Xmp::RdfNamespace
+        map_element "format", to: :format
+        map_element "title", to: :title
+        map_element "creator", to: :creator
+        map_element "description", to: :description
+        map_element "subject", to: :subject
+        map_element "CreatorTool", to: :creator_tool
+        map_element "CreateDate", to: :create_date
+        map_element "ModifyDate", to: :modify_date
+        map_element "MetadataDate", to: :metadata_date
+      end
+
+      def author
+        creator&.values&.first
+      end
+
+      def keywords
+        subject&.values&.join(", ")
+      end
+    end
+
+    # `<rdf:RDF>` — collection of `<rdf:Description>` siblings inside
+    # an XMP packet. Per IDML's META-INF/metadata.xml, there is
+    # typically one Description per schema group.
+    class XmpRdf < Lutaml::Model::Serializable
+      attribute :descriptions, XmpDescription, collection: true
+
+      xml do
+        root "RDF"
+        namespace Xmp::RdfNamespace
+        map_element "Description", to: :descriptions
+      end
+
+      # Merged view across all Descriptions. Each attribute returns
+      # the first non-nil value across the descriptions.
+      def first_description
+        descriptions.first
+      end
+
+      def title
+        descriptions.map(&:title).find(&:itself)&.value
+      end
+
+      def author
+        descriptions.filter_map(&:author).first
+      end
+
+      def subject
+        descriptions.filter_map(&:subject).find(&:itself)&.values
+      end
+
+      def keywords
+        subject&.join(", ")
+      end
+
+      def description
+        descriptions.map(&:description).find(&:itself)&.value
+      end
+
+      def creator_tool
+        descriptions.filter_map(&:creator_tool).first&.value
+      end
+
+      def create_date
+        descriptions.filter_map(&:create_date).first&.value
+      end
+
+      def modify_date
+        descriptions.filter_map(&:modify_date).first&.value
+      end
+    end
+
+    # `<x:xmpmeta>` — outer wrapper of an XMP packet.
+    class XmpMeta < Lutaml::Model::Serializable
+      attribute :rdf, XmpRdf
+
+      xml do
+        root "xmpmeta"
+        namespace Xmp::XmetaNamespace
+        map_element "RDF", to: :rdf
+      end
+
+      def description
+        rdf&.first_description
+      end
+    end
+  end
+end

data/lib/idml/parts.rb

@@ -15,6 +15,10 @@ module Idml
     autoload :Preferences,  "idml/parts/preferences"
     autoload :Tags,         "idml/parts/tags"
     autoload :Mapping,      "idml/parts/mapping"
+    autoload :Xmp,            "idml/parts/xmp"
+    autoload :XmpDescription, "idml/parts/xmp"
+    autoload :XmpRdf,         "idml/parts/xmp"
+    autoload :XmpMeta,        "idml/parts/xmp"
 
     @registry = {}
 

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,17 +10,18 @@ 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
         writer = PdfrbWriter.new
-        writer.set_info(default_metadata)
+        writer.set_info(combined_metadata)
         writer.enable_tagged if @tagged
         layer_filter = LayerFilter.from_designmap(@package.designmap)
         font_ref_resolver = FontReferenceResolver.build(@package)
@@ -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
@@ -188,6 +190,46 @@ module Idml
         nil
       end
 
+      def combined_metadata
+        defaults = default_metadata
+        xmp_metadata.each do |key, value|
+          next if value.nil? || value.empty?
+
+          defaults[key] = value
+        end
+        defaults
+      end
+
+      def xmp_metadata
+        return {} unless @package.has_part?(XMP_PATH)
+
+        xml = @package.read_part(XMP_PATH)
+        meta = Parts::XmpMeta.from_xml(xml)
+        rdf = meta.rdf
+        return {} unless rdf
+
+        {
+          Title: rdf.title,
+          Author: rdf.author,
+          Subject: rdf.description,
+          Keywords: rdf.keywords,
+          Creator: rdf.creator_tool,
+          CreationDate: pdf_date_string(rdf.create_date),
+          ModDate: pdf_date_string(rdf.modify_date),
+        }
+      rescue StandardError
+        {}
+      end
+
+      def pdf_date_string(iso8601)
+        return nil unless iso8601
+
+        time = Time.iso8601(iso8601)
+        pdf_date(time)
+      rescue ArgumentError
+        nil
+      end
+
       def default_metadata
         {
           Producer: "idml gem v#{Idml::VERSION}",
@@ -198,6 +240,9 @@ module Idml
       def pdf_date(time)
         time.strftime("D:%Y%m%d%H%M%S+00'00'")
       end
+
+      XMP_PATH = "META-INF/metadata.xml"
+      private_constant :XMP_PATH
     end
   end
 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.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.9
 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
@@ -378,6 +381,7 @@ files:
 - lib/idml/parts/style.rb
 - lib/idml/parts/style_mapping.rb
 - lib/idml/parts/tags.rb
+- lib/idml/parts/xmp.rb
 - lib/idml/render.rb
 - lib/idml/render/blending.rb
 - lib/idml/render/color_helper.rb