idml 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d870be70e870df44bf1b0fcd658e5d5cc04b877e00d195f40666027c4a64b12
-  data.tar.gz: f3b5e9f8ea4e3eb181f66795746a090d4994c5ce7ea32cbf210b8366c9d801fa
+  metadata.gz: 02ab670c36492471dd8dd986380fd180826e9ce250d5e22dde6fb5fda18b9bd3
+  data.tar.gz: 73d2c392dee732f12b1551a445f5e1a866a551885742adf3552d81abe0c3e9d4
 SHA512:
-  metadata.gz: 2bbbd17c0ef7958732c45ffc848f4e0ad89ac27406f79f42af769d49ce9f5dc88584b5e7b45e462a77d85c663b383113c11b8cd824942320de7baa57bf3ec77d
-  data.tar.gz: b6e86c5e3d233aa80ea12302db92781dac9d08e6cc55c28aa83858bc73b18875f78f7bebdf67e077c9c7fa462d617e8401763b421cf45a9c7e21d0663516eb8a
+  metadata.gz: b5c44e670ba295c964c6b58f6cecab0dcde43b579d4e4eb282e2d5b66cf567df34f943377a84510df7edd84d831892b3f3d6e13d7a4b13eb5311058377b94494
+  data.tar.gz: d1692d7d0ed411358d2ed877497abe2838fe25d2a1aa6a9fc534561b116743fd0a4e279819ea0206b8dfb5ecaf29c8f806e4341cca941267a2c2dc71193dbd9e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    idml (0.2.5)
+    idml (0.2.6)
       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.5)
+  idml (0.2.6)
   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/40-font-ps-name-resolution.md

@@ -1,30 +1,42 @@
 # TODO PDF 40: Font PS name resolution from Fonts.xml
 
-## Goal
-
-Connect the IDML document's Fonts.xml (FontFamily/Font entries with
-PostScriptName) to the FontResolver so text rendering uses the correct
-font, not the hardcoded "Helvetica" default.
-
-## Status: PARTIALLY DONE
-
-## What was done
-
-- Verified `Parts::Fonts` typed model parses FontFamily → Font entries.
-- `FontFamily` and `Font` element models exist and expose PostScriptName.
-- The FontResolver can find fonts by family name + style.
-
-## What remains
-
-- Map CharacterStyleRange#applied_font → FontFamily/Font → PostScriptName
-  → FontResolver search.
-- Add PostScriptName-based search to FontResolver (current search is
-  family-name based).
-- Pipeline: pass document font references to the font resolver.
-- When a document font can't be found on disk, log a warning and fall
-  back to the default font.
-
-## Dependencies
-
-- TODO 29 (StyleResolver for applied_font extraction).
-- TODO 33 (font resolution from IDML).
+## Status: DONE
+
+## What was implemented
+
+The pipeline now resolves document fonts from `Resources/Fonts.xml` via
+PostScriptName lookup, falling back to the default font when the file
+isn't found on disk:
+
+1. `Idml::TextEngine::FontResolver#resolve_by_ps_name(ps_name)`
+   walks system font directories and matches on each candidate font's
+   internal PostScript name (read by Fontisan).
+2. `Idml::Render::Pipeline#resolve_document_font_path` iterates
+   `Parts::Fonts#font_family` → `FontFamily#font`, skips entries with
+   `Status="Missing"`, and returns the first match.
+3. `Pipeline#register_font` rescues any resolver failure and returns
+   `Render::DEFAULT_FONT` (`"Helvetica"`) so rendering never crashes
+   when a font file is absent.
+4. The chosen font name is threaded through `RenderContext` to every
+   renderer via `font_ps_name`.
+
+## Verification
+
+- `lib/idml/render/pipeline.rb:170` — `resolve_document_font_path`
+- `lib/idml/render/pipeline.rb:185` — `resolve_by_ps_name` call
+- `lib/idml/text_engine/font_resolver.rb:38` — PS-name search
+
+## Acceptance criteria
+
+- [x] Parts::Fonts typed model parses FontFamily → Font entries.
+- [x] FontFamily and Font element models expose PostScriptName.
+- [x] PostScriptName-based search added to FontResolver.
+- [x] Pipeline passes document font references to the resolver.
+- [x] Falls back to default font when document font can't be found.
+
+## Out of scope
+
+Per-run font selection (each `CharacterStyleRange#applied_font`
+mapped to its own registered font) requires TODO 67's multi-font
+`text_rich` integration and is tracked there. This TODO covers the
+document-default font, which is what every renderer uses today.

data/TODO.pdf/52-font-subsetting.md

@@ -1,12 +1,44 @@
 # 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).
 
-## Acceptance criteria
+## 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.
@@ -17,6 +49,4 @@ in the document. This dramatically reduces PDF file size (from full font
 
 ## Dependencies
 
-- pdfrb font embedding support (partial — font registration works,
-  FontFile2 embedding may require pdfrb enhancement).
-- TODO 27 (text engine for glyph collection).
+- pdfrb subsetting API (NOT YET AVAILABLE in 0.4.0).

data/TODO.pdf/55-dead-code-deprecation.md

@@ -1,30 +1,24 @@
 # TODO PDF 55: Dead code deprecation markers
 
-## Goal
+## Status: DONE (modules already removed)
 
-Mark old hand-rolled modules as deprecated. These modules are
-superseded by pdfrb but cannot be deleted per the project's
-"never delete source files" policy. Add deprecation comments and
-update autoloads to lazy-load only when explicitly referenced.
+## What was done
 
-## Modules to deprecate
+The old hand-rolled modules have already been deleted from the codebase
+during the pdfrb migration (TODO 51 + TODO 62). No `Idml::Render::PdfWriter`,
+`Idml::Render::FontEmbedder`, `Idml::Render::Color`, `Idml::Render::Path`,
+or `Idml::Render::Text` references remain in `lib/` or `spec/`.
 
-- `Idml::Render::PdfWriter` — replaced by `PdfrbWriter`
-- `Idml::Render::FontEmbedder` — replaced by `PdfrbWriter.register_font`
-- `Idml::Render::Color` — replaced by `ColorHelper` + Canvas fill_color
-- `Idml::Render::Path` — replaced by Canvas drawing methods
-- `Idml::Render::Text` — replaced by Canvas text method
+The original goal — deprecation comments on dead modules — is moot:
+there are no dead modules to deprecate. This TODO is closed without
+further work.
 
-## Acceptance criteria
+## Verification
 
-- [ ] Each deprecated module has a `# DEPRECATED` header comment pointing
-      to its pdfrb replacement.
-- [ ] No active code path (Pipeline, SpreadRenderer, renderers) references
-      deprecated modules.
-- [ ] Tests for deprecated modules are tagged with `:deprecated` or
-      moved to a separate spec file.
-- [ ] `render.rb` autoloads keep the old modules for backward compatibility.
+`grep -rn "PdfWriter|FontEmbedder|Render::Color\b|Render::Path\b|Render::Text\b" lib/ spec/`
+returns zero matches.
 
-## Dependencies
+## Acceptance criteria
 
-- pdfrb migration (DONE).
+- [x] No live code references the old hand-rolled modules.
+- [x] `bundle exec rake` is green (2314 examples, 0 failures).

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

@@ -1,31 +1,73 @@
 # TODO PDF 63: Replace FontMetrics with pdfrb measurement API
 
+## Status: BLOCKED (pdfrb measurement APIs are stubs)
+
 ## Goal
 
 Replace `Idml::TextEngine::FontMetrics` (200+ lines of TTF binary parsing
-via Fontisan) with pdfrb 0.15.0's native `Fonts#measure_text` and
-`Fonts#metrics_for`. Eliminates the Fontisan dependency for text layout.
+via Fontisan) with pdfrb's native `Fonts#measure_text`, `#glyph_width`,
+and `#metrics_for`. Eliminates the Fontisan dependency for text layout.
+
+## Blocker
+
+pdfrb 0.4.0 ships the API surface but the implementations are stubs
+that return constant values, not real per-glyph widths:
+
+`/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
+end
+
+def glyph_width(_char, _resource)
+  500
+end
+
+def metrics_for(_resource)
+  nil
+end
+```
+
+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.
+
+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
 
-## Motivation
+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.
 
-pdfrb 0.15.0 now provides:
-- `document.fonts.measure_text(text, font:, size:)` → width in points
-- `document.fonts.metrics_for(font)` → { ascent:, descent:, cap_height:, ... }
+Once that proposal lands:
 
-The idml gem's FontMetrics class duplicates this by parsing TTF tables
-(head, hhea, hmtx, cmap) via Fontisan. The text engine (Shaper,
-LineBreaker) could use pdfrb's measurement instead.
+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`.
 
-## Plan
+## Acceptance criteria (after pdfrb unblocks)
 
-1. Create a `PdfrbFontMetrics` adapter that implements the FontMetrics
-   interface (`glyph_width`, `measure_text`, `units_per_em`, etc.) using
-   pdfrb's `Fonts#measure_text` and `#metrics_for`.
-2. Update `FontResolver` to return `PdfrbFontMetrics` instances.
-3. Remove `fontisan` from gemspec dependencies.
-4. Remove `text_engine/font_metrics.rb` (200+ lines).
+- [ ] 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.
 
 ## Dependencies
 
-- pdfrb 0.15.0 (DONE — has measure_text and metrics_for)
-- TODO 62 (pdfrb 0.15.0 migration — DONE)
+- pdfrb 0.4.0's `Fonts#measure_text`/`#glyph_width`/`#metrics_for`
+  with real implementations OR
+- pdfrb accepts the external-metrics proposal linked above.

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

@@ -1,29 +1,29 @@
 # TODO PDF 65: pdfrb 0.19.0 feature integration
 
-## Status: PARTIALLY DONE
+## Status: PARTIALLY DONE (remainder blocked)
 
 ## What was implemented
 
-1. **Canvas#text_lines**: TextFrameRenderer uses `canvas.text_lines`
+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.
 
-## What remains (pdfrb bugs)
+## What remains
 
-2. **glyph_width for TTF**: pdfrb 0.19.0 has `Fonts#glyph_width` but
-   returns 0 for TrueType fonts (bug: "undefined method glyph_id_for
-   for String"). Standard 14 Type1 fonts work correctly. Cannot
-   replace FontMetrics/Fontisan until this is fixed.
+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:
 
-3. **Pdfrb::FontResolver**: Returns nil for common fonts (Helvetica.ttc
-   on macOS). Cannot replace Fontisan-based resolver yet.
-
-4. **Font subsetting**: `Fonts#add` accepts `**opts` but `subset: true`
-   behavior unverified. Standard 14 fonts don't need FontFile embedding.
+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.
 
 ## Acceptance criteria
 
-- [x] TextFrameRenderer uses canvas.text_lines
-- [ ] FontMetrics replaced with pdfrb glyph_width (blocked by TTF bug)
-- [ ] FontResolver replaced with Pdfrb::FontResolver (blocked by .ttc)
-- [ ] Font subsetting verified
+- [x] TextFrameRenderer uses `canvas.text_lines`
+- [ ] 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

@@ -0,0 +1,51 @@
+# TODO PDF 67: Multi-run text batching via Canvas#text_rich
+
+## Status: BLOCKED (pdfrb measure_text is a stub)
+
+## Goal
+
+Replace the per-run `Canvas#text` calls in `TextFrameRenderer#simple_render`
+with a single `Canvas#text_rich` call per text frame. `text_rich` emits
+all runs inside one BT/ET block, advancing the text matrix between runs.
+
+## Motivation
+
+`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.
+
+## Blocker
+
+`/Users/mulgogi/src/claricle/pdfrb/lib/pdfrb/document/fonts.rb:65`:
+
+```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
+```
+
+`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.
+
+## 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])`.
+3. Verify rendered PDF: runs no longer overwrite, multi-color lines work.
+
+## Acceptance criteria
+
+- [ ] `TextFrameRenderer#simple_render` uses `canvas.text_rich`.
+- [ ] Render spec verifies a multi-run line has correct horizontal advance.
+- [ ] Single BT/ET block per frame (assertion on PDF content stream).
+
+## Dependencies
+
+- pdfrb 0.4.0 `Fonts#measure_text` returns real per-glyph widths.
+- pdfrb 0.4.0 `Fonts#glyph_width` not returning stub 500.

data/TODO.pdf/68-radial-gradient-shadings.md

@@ -0,0 +1,36 @@
+# TODO PDF 68: Radial gradient shadings via pdfrb 0.4.0
+
+## Goal
+
+RectangleRenderer routes gradient fills to either `Shadings#add_axial`
+(linear) or `Shadings#add_radial` (radial) based on the IDML
+`Gradient.type` attribute (`"Linear"` vs `"Radial"`).
+
+## Background
+
+IDML `<Gradient Type="...">` supports two gradient shapes:
+- `"Linear"` (default) — colour stops along a straight axis
+- `"Radial"` — colour stops along a radius from a centre point
+
+pdfrb 0.4.0 exposes both:
+- `document.shadings.add_axial(from:, to:, stops:, extend:)`
+- `document.shadings.add_radial(from:, to:, stops:, extend:)`
+
+Before this TODO, every gradient was rendered as axial regardless of the
+declared type, producing incorrect output for radial swatches.
+
+## Implementation
+
+1. Read `Gradient#type` (already modelled on `Elements::Gradient`).
+2. In `RectangleRenderer.render_gradient_fill`, dispatch:
+   - `type == "Radial"` → `add_radial` with centre-to-edge coords.
+   - otherwise → `add_axial` (existing behaviour).
+3. Radial coordinates use the box centre as both `from` and the
+   near corner of `to` so the shading fills the rectangle.
+
+## Acceptance criteria
+
+- [x] `Gradient.type == "Radial"` produces a pdfrb radial shading.
+- [x] `Gradient.type == "Linear"` (or nil) keeps producing an axial shading.
+- [x] Spec covers both branches.
+- [x] All existing specs still pass.

data/TODO.pdf/69-transparency-blend-modes.md

@@ -0,0 +1,84 @@
+# TODO PDF 69: Transparency and blend modes via pdfrb 0.4.0
+
+## Goal
+
+Honor IDML `<BlendingSetting BlendMode="..." Opacity="..."/>` on page
+items by routing through pdfrb's `Canvas#with_transparency` and
+`Canvas#blend_mode=`. Applies to Rectangle, Polygon, GraphicLine, and
+TextFrame fill+stroke paths.
+
+## Background
+
+IDML models transparency as nested elements under each page item:
+
+```xml
+<Rectangle ...>
+  <TransparencySetting>
+    <BlendingSetting BlendMode="Multiply" Opacity="0.5"
+                     KnockoutGroup="true" IsolateBlending="false"/>
+    <DropShadowSetting .../>   <!-- not handled here -->
+  </TransparencySetting>
+</Rectangle>
+```
+
+`TransparencySetting` lives as a child of the page item (sibling of
+`Properties`). Its first `BlendingSetting` child carries the blend mode
+and opacity that apply to the item's entire drawing.
+
+pdfrb 0.4.0 exposes the matching primitives:
+
+- `Canvas#opacity=` — sets alpha for both fill and stroke (ExtGState `ca`/`CA`).
+- `Canvas#blend_mode=` — sets BM name.
+- `Canvas#with_transparency(opacity:, blend_mode:) { ... }` — saves graphics state, applies both, restores on exit.
+
+## IDML → PDF blend-mode mapping
+
+IDML's `BlendMode` enumeration maps to PDF's `BM` names where they line
+up; PDF does not have equivalents for every IDML mode. Initial mapping:
+
+| IDML               | PDF           |
+|--------------------|---------------|
+| `Normal`           | `Normal`      |
+| `Multiply`         | `Multiply`    |
+| `Screen`           | `Screen`      |
+| `Overlay`          | `Overlay`     |
+| `SoftLight`        | `SoftLight`   |
+| `HardLight`        | `HardLight`   |
+| `Darken`           | `Darken`      |
+| `Lighten`          | `Lighten`     |
+| `ColorDodge`       | `ColorDodge`  |
+| `ColorBurn`        | `ColorBurn`   |
+| `Difference`       | `Difference`  |
+| `Exclusion`        | `Exclusion`   |
+| `Hue`              | `Hue`         |
+| `Saturation`       | `Saturation`  |
+| `Color`            | `Color`       |
+| `Luminosity`       | `Luminosity`  |
+
+Unknown modes fall back to `Normal`.
+
+## Implementation
+
+1. Add `transparency_setting` attribute to `Rectangle`, `Polygon`,
+   `GraphicLine`, `TextFrame`, `Group` (RNC lists it on every page item).
+2. Model `TransparencySetting` with a `blending_setting` child.
+3. New helper `Render::Blending` that maps an `Elements::BlendingSetting`
+   to a `{ opacity:, blend_mode: }` hash.
+4. In each renderer, wrap the existing fill/stroke block in
+   `canvas.with_transparency(**blending_args) { ... }` when a setting is
+   present.
+5. Reuse the existing `save_graphics_state` block — `with_transparency`
+   already saves/restores, so renderers call it in place of the plain
+   save block when blending applies.
+
+## Acceptance criteria
+
+- [ ] IDML `<BlendingSetting Opacity="0.5"/>` halves the item's alpha in the output PDF.
+- [ ] IDML `<BlendingSetting BlendMode="Multiply"/>` sets `/BM /Multiply` in ExtGState.
+- [ ] Items without BlendingSetting render exactly as before (no ExtGState emitted).
+- [ ] Spec covers opacity, blend_mode, and pass-through cases.
+
+## Dependencies
+
+- pdfrb 0.4.0 `Canvas#with_transparency` (DONE — confirmed in pdfrb 0.4.0).
+- pdfrb 0.4.0 `Canvas#blend_mode=` (DONE).

data/TODO.pdf/70-stroke-styling.md

@@ -0,0 +1,60 @@
+# TODO PDF 70: Stroke styling — line cap, join, dash patterns
+
+## Status: PLANNED (not started)
+
+## Goal
+
+Honor IDML stroke styling attributes by routing through pdfrb 0.4.0's
+stroke-style Canvas setters:
+
+- `line_width=` (already used — TODO 31)
+- `line_cap=` — RoundButt/RoundJoin cap shape
+- `line_join=` — miter/round/bevel corner joining
+- `miter_limit=` — clamps spikes on sharp angles
+- `dash_pattern=` — dashed/dotted stroke styles
+
+## Background
+
+pdfrb 0.4.0 exposes the full PDF graphics-state stroke suite. IDML
+exposes the matching attributes through `<DashedStrokeStyle>` and
+`<DottedStrokeStyle>` elements in `Resources/Graphic.xml`, plus
+per-item `StrokeColor`/`StrokeWeight` (already handled).
+
+IDML → PDF stroke mapping:
+
+| IDML                                | PDF                       |
+|-------------------------------------|---------------------------|
+| `EndCap="RoundCap"`                 | `line_cap = 1` (Round)    |
+| `EndCap="ButtCap"`                  | `line_cap = 0` (Butt)     |
+| `EndCap="ProjectingCap"`            | `line_cap = 2` (Square)   |
+| `Join="RoundJoin"`                  | `line_join = 1`           |
+| `Join="MiterJoin"`                  | `line_join = 0`           |
+| `Join="BevelJoin"`                  | `line_join = 2`           |
+| `<DashedStrokeStyle DashArray="...">` | `dash_pattern = [arr, 0]` |
+| `<DottedStrokeStyle DotArray="...">`  | `dash_pattern = [arr, 0]` (dots are short dashes) |
+
+## Plan
+
+1. `Parts::Graphic` already exposes `dashed_stroke_style` and
+   `dotted_stroke_style` collections — add accessors on the renderer
+   context.
+2. New `Render::StrokeStyle` helper that resolves an
+   `Elements::DashedStrokeStyle` / `DottedStrokeStyle` (or stroke-style
+   self-id reference on the item) to a `{ line_cap:, line_join:,
+   miter_limit:, dash_pattern: }` hash.
+3. Each stroke renderer (Rectangle, Polygon, GraphicLine) calls
+   `StrokeStyle.apply(canvas, item, context)` before `canvas.stroke`.
+
+## Acceptance criteria
+
+- [ ] Dashed strokes render with correct dash array.
+- [ ] Dotted strokes render as zero-length dashes with round caps.
+- [ ] Round/miter/bevel joins produce matching PDF output.
+- [ ] Plain strokes (no style) render exactly as before.
+- [ ] Spec covers dashed, dotted, round-join, and pass-through cases.
+
+## Dependencies
+
+- pdfrb 0.4.0 `line_cap=`, `line_join=`, `miter_limit=`, `dash_pattern=`
+  (DONE — all confirmed in pdfrb 0.4.0).
+- IDML element models for stroke styles (DONE — already generated from RNC).

data/lib/idml/elements/graphic_line.rb

@@ -13,6 +13,7 @@ module Idml
       attribute :visible, :boolean
       attribute :item_layer, :string
       attribute :properties, Idml::Elements::Properties, collection: true
+      attribute :transparency_setting, Idml::Elements::TransparencySetting
 
       xml do
         root "GraphicLine"
@@ -24,6 +25,7 @@ module Idml
         map_attribute "Visible", to: :visible
         map_attribute "ItemLayer", to: :item_layer
         map_element "Properties", to: :properties
+        map_element "TransparencySetting", to: :transparency_setting
       end
 
       def geometric_bounds

data/lib/idml/elements/polygon.rb

@@ -15,6 +15,7 @@ module Idml
       attribute :visible, :boolean
       attribute :item_layer, :string
       attribute :properties, Idml::Elements::Properties, collection: true
+      attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :image, Idml::Elements::Image, collection: true
 
       xml do
@@ -29,6 +30,7 @@ module Idml
         map_attribute "Visible", to: :visible
         map_attribute "ItemLayer", to: :item_layer
         map_element "Properties", to: :properties
+        map_element "TransparencySetting", to: :transparency_setting
         map_element "Image", to: :image
       end
 

data/lib/idml/elements/rectangle.rb

@@ -19,6 +19,7 @@ module Idml
       attribute :name, :string
       attribute :item_layer, :string
       attribute :properties, Idml::Elements::Properties, collection: true
+      attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :image, Idml::Elements::Image, collection: true
 
       xml do
@@ -36,6 +37,7 @@ module Idml
         map_attribute "Name", to: :name
         map_attribute "ItemLayer", to: :item_layer
         map_element "Properties", to: :properties
+        map_element "TransparencySetting", to: :transparency_setting
         map_element "Image", to: :image
       end
 

data/lib/idml/elements/text_frame.rb

@@ -20,6 +20,7 @@ module Idml
       attribute :name, :string
       attribute :item_layer, :string
       attribute :properties, Idml::Elements::Properties, collection: true
+      attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :text_frame_preference, Idml::Elements::TextFramePreference,
                 collection: true
 
@@ -39,6 +40,7 @@ module Idml
         map_attribute "Name", to: :name
         map_attribute "ItemLayer", to: :item_layer
         map_element "Properties", to: :properties
+        map_element "TransparencySetting", to: :transparency_setting
         map_element "TextFramePreference", to: :text_frame_preference
       end
 

data/lib/idml/elements/transparency_setting.rb

@@ -7,8 +7,33 @@ module Idml
     # `reference-docs/schemas/package/Resources/Styles.rnc` is declared (0 attributes),
     # generated by `scripts/rnc_to_lutaml.rb`.
     class TransparencySetting < Lutaml::Model::Serializable
+      attribute :blending_setting, Idml::Elements::BlendingSetting
+      attribute :drop_shadow_setting, Idml::Elements::DropShadowSetting
+      attribute :feather_setting, Idml::Elements::FeatherSetting
+      attribute :inner_shadow_setting, Idml::Elements::InnerShadowSetting
+      attribute :outer_glow_setting, Idml::Elements::OuterGlowSetting
+      attribute :inner_glow_setting, Idml::Elements::InnerGlowSetting
+      attribute :bevel_and_emboss_setting, Idml::Elements::BevelAndEmbossSetting
+      attribute :satin_setting, Idml::Elements::SatinSetting
+      attribute :directional_feather_setting,
+                Idml::Elements::DirectionalFeatherSetting
+      attribute :gradient_feather_setting,
+                Idml::Elements::GradientFeatherSetting
+
       xml do
         root "TransparencySetting"
+        map_element "BlendingSetting", to: :blending_setting
+        map_element "DropShadowSetting", to: :drop_shadow_setting
+        map_element "FeatherSetting", to: :feather_setting
+        map_element "InnerShadowSetting", to: :inner_shadow_setting
+        map_element "OuterGlowSetting", to: :outer_glow_setting
+        map_element "InnerGlowSetting", to: :inner_glow_setting
+        map_element "BevelAndEmbossSetting", to: :bevel_and_emboss_setting
+        map_element "SatinSetting", to: :satin_setting
+        map_element "DirectionalFeatherSetting",
+                    to: :directional_feather_setting
+        map_element "GradientFeatherSetting",
+                    to: :gradient_feather_setting
       end
     end
   end

data/lib/idml/render/blending.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Maps an `Elements::BlendingSetting` to the keyword arguments that
+    # `Pdfrb::Content::Canvas#with_transparency` expects. IDML stores
+    # opacity as 0–100 (percentage); pdfrb wants 0.0–1.0 alpha. Blend
+    # mode names line up directly with PDF `BM` names; unknown modes
+    # fall back to `Normal`.
+    module Blending
+      PDF_BLEND_MODES = %w[
+        Normal Multiply Screen Overlay SoftLight HardLight Darken Lighten
+        ColorDodge ColorBurn Difference Exclusion Hue Saturation Color
+        Luminosity
+      ].freeze
+
+      def self.args_for(setting)
+        return nil unless setting&.blending_setting
+
+        build_args(setting.blending_setting)
+      end
+
+      def self.build_args(blending)
+        opacity = normalize_opacity(blending.opacity)
+        mode = normalize_mode(blending.blend_mode)
+        return nil unless opacity || mode
+
+        { opacity: opacity || 1.0, blend_mode: mode || "Normal" }
+      end
+      private_class_method :build_args
+
+      # Wraps the given block in `Canvas#with_transparency` when the
+      # page item has a BlendingSetting, otherwise yields directly.
+      def self.wrap(canvas, setting, &)
+        args = args_for(setting)
+        if args
+          canvas.with_transparency(**args, &)
+        else
+          yield
+        end
+      end
+
+      def self.normalize_opacity(raw)
+        return nil if raw.nil?
+
+        (raw.to_f / 100.0).clamp(0.0, 1.0)
+      end
+      private_class_method :normalize_opacity
+
+      def self.normalize_mode(raw)
+        return nil if raw.nil? || raw == "Normal"
+
+        camel = raw.to_s.dup
+        camel[0] = camel[0].upcase
+        PDF_BLEND_MODES.include?(camel) ? camel : nil
+      end
+      private_class_method :normalize_mode
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Idml
           box = RectangleRenderer.placement_box(line, context.page_height)
           return unless box
 
-          canvas.save_graphics_state do
+          Blending.wrap(canvas, line.transparency_setting) do
             canvas.stroke_color(ColorHelper.to_canvas(color))
             canvas.line_width = line.stroke_weight
             canvas.move_to(box[:x], box[:y] + box[:height])

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

@@ -11,7 +11,7 @@ module Idml
           box = RectangleRenderer.placement_box(poly, context.page_height)
           return unless box
 
-          canvas.save_graphics_state do
+          Blending.wrap(canvas, poly.transparency_setting) do
             render_fill(canvas, poly, context, box)
             render_stroke(canvas, poly, context, box)
           end

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

@@ -12,7 +12,7 @@ module Idml
           box = placement_box(rect, context.page_height)
           return unless box
 
-          canvas.save_graphics_state do
+          Blending.wrap(canvas, rect.transparency_setting) do
             render_fill(canvas, rect, context, box)
             render_stroke(canvas, rect, context, box)
           end
@@ -44,32 +44,51 @@ module Idml
         private_class_method :render_fill
 
         def self.render_gradient_fill(canvas, rect, context, box)
-          stops = gradient_stops_for(rect, context)
-          return unless stops&.length&.>=(2)
+          gradient = gradient_for(rect, context)
+          return unless gradient
+          return unless gradient.gradient_stop.length >= 2
+
+          stops = gradient_stops(gradient, context)
+          return unless stops.length >= 2
+
+          shading = if gradient.type == "Radial"
+                      radial_shading(canvas, box, stops)
+                    else
+                      axial_shading(canvas, box, stops)
+                    end
+          canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
+          canvas.fill_shading(shading)
+        end
+        private_class_method :render_gradient_fill
 
-          shading = canvas.document.shadings.add_axial(
+        def self.axial_shading(canvas, box, stops)
+          canvas.document.shadings.add_axial(
             from: [box[:x], box[:y] + box[:height]],
             to: [box[:x] + box[:width], box[:y]],
             stops: stops,
           )
-          canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
-          canvas.fill_shading(shading)
         end
-        private_class_method :render_gradient_fill
+        private_class_method :axial_shading
+
+        def self.radial_shading(canvas, box, stops)
+          cx = box[:x] + (box[:width] / 2.0)
+          cy = box[:y] + (box[:height] / 2.0)
+          radius = [box[:width], box[:height]].max / 2.0
+          canvas.document.shadings.add_radial(
+            from: [cx, cy, 0.0],
+            to: [cx, cy, radius],
+            stops: stops,
+          )
+        end
+        private_class_method :radial_shading
 
-        def self.gradient_stops_for(rect, context)
+        def self.gradient_for(rect, context)
           graphic = context.package&.graphic
           return nil unless graphic
 
-          gradient = graphic.gradient.find do |g|
-            g.self_attr == rect.fill_color
-          end
-          return nil unless gradient
-          return nil unless gradient.gradient_stop.length >= 2
-
-          gradient_stops(gradient, context)
+          graphic.gradient.find { |g| g.self_attr == rect.fill_color }
         end
-        private_class_method :gradient_stops_for
+        private_class_method :gradient_for
 
         def self.gradient_stops(gradient, context)
           gradient.gradient_stop.filter_map do |stop|

data/lib/idml/render.rb

@@ -11,6 +11,7 @@ module Idml
     autoload :FontReferenceResolver,
              "#{__dir__}/render/font_reference_resolver"
     autoload :GradientResolver,    "#{__dir__}/render/gradient_resolver"
+    autoload :Blending,            "#{__dir__}/render/blending"
     autoload :LayerFilter,         "#{__dir__}/render/layer_filter"
     autoload :StoryThreader,       "#{__dir__}/render/story_threader"
     autoload :PdfrbWriter, "#{__dir__}/render/pdfrb_writer"

data/lib/idml/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Ribose
@@ -207,6 +207,10 @@ files:
 - TODO.pdf/64-pipeline-cli-optimizations.md
 - TODO.pdf/65-pdfrb-019-integration.md
 - TODO.pdf/66-gradient-shadings-pdfrb.md
+- TODO.pdf/67-text-rich-multi-run.md
+- TODO.pdf/68-radial-gradient-shadings.md
+- TODO.pdf/69-transparency-blend-modes.md
+- TODO.pdf/70-stroke-styling.md
 - TODO.pdf/README.md
 - exe/idml
 - idml.gemspec
@@ -371,6 +375,7 @@ files:
 - lib/idml/parts/style_mapping.rb
 - lib/idml/parts/tags.rb
 - lib/idml/render.rb
+- lib/idml/render/blending.rb
 - lib/idml/render/color_helper.rb
 - lib/idml/render/color_resolver.rb
 - lib/idml/render/font_reference_resolver.rb